
An active Player in the game of technology


Brian Baliach

Building production-grade AI agents is tricky. In a landscape shifting rapidly, betting your entire architecture on a single provider's raw SDK allows for quick starts but leads to brittle vendor lock-in. This is where Google’s Agent Development Kit (ADK) shines. It acts as a crucial abstraction layer, providing a standardized common interface for defining tools (similar to LiteLLM which Google ADK actually uses internally), events, and agent orchestration. This means you aren't locked solely into Gemini; you can design systems that utilize different models from various providers — even using them as fallbacks for one another — without rewriting your core business logic.

However, if you’ve tried taking the ADK into production with TypeScript, you’ve likely hit a significant reality gap. While the Python documentation is comprehensive, the TypeScript side is remarkably thin, steering devs toward "ADK Devtools" which, while fine for local prototyping, simply don't cut it for a hardened production stack.

Before we fix that, let's briefly strip away the jargon and define how the ADK actually works under the hood. It relies on three core concepts:

1. **The Runner (Event Loop):** Think of this as the engine room. It’s an asynchronous loop that takes an incoming signal (an event), processes it through your agent’s logic (calling the LLM, executing tools), and determines the next step (updating state in the process).
2. **State:** This is the "short-term memory" of the active conversation. It’s mutable data representing where the user is *right now* in a flow (e.g., `{ step: 'collecting_address', attempt: 2 }`).
3. **Context:** The environment the runner operates in. This is the static stuff the agent needs to do its job but doesn't change turn-by-turn. Think database connections, user IDs, or API keys.

**Here is the crucial part for production:** Events in the ADK aren't just passive text messages. They carry their own state payload representing a "delta" or in simple layman terms, change. The Runner uses this specific event state to update the overall session state before beginning the next turn (handled by the session service).

You can read more about the Google ADK architecture here: https://google.github.io/adk-docs/get-started/about/

In a real-world environment, you can't let that critical state live in volatile, in-memory storage. You need true persistence so agents retain context across server restarts and container scaling. Furthermore, if you’re running a modern TypeScript stack with ESM, the currently shipped `@google/adk` package suffers from dependency conflicts that break standard builds.

Today, we’re going to fix this. We'll walk through patching the ADK to bridge the ESM/CommonJS gap and implementing custom PostgreSQL-backed session and memory services to ensure that state is saved durably. It’s a deep dive, but essential for anyone moving beyond the "Hello World" phase.

Here's the GitHub repo with complete code examples you can refer from: [tutorial repository](https://github.com/TylerMutai/google-adk-tutorial.git)

### The Current Limitations

For production TypeScript applications, the current ADK falls short in three key areas:

1. **Lack of Persistence:** The provided examples use in-memory services. Server restarts mean lost user context.
2. **ESM/CJS Conflicts:** The published package's CommonJS build incorrectly imports the ESM-only `lodash-es` package, rather than standard `lodash`, breaking many build pipelines.
3. **Missing Infrastructure:** Unlike the Python SDK, the TypeScript version lacks built-in persistent session services (like VertexAI) out of the box.

We will resolve these issues using **NestJS**, **TypeORM** (PostgreSQL), and **pnpm package manager**  for patching.

---

## Hands-On: Building a Persistent ADK Agent

We are going to implement a `CloudSqlSessionService` and a `CloudSqlMemoryService`. This ensures your agent's state and long-term memories live safely in your Postgres database rather than ephemeral RAM.

### 1. Patching @google/adk

The first step is stabilizing the dependency tree. As mentioned, the `@google/adk` package currently ships a CommonJS build that incorrectly imports `lodash-es`. We need to patch this to get it running in a modern environment.

Ensure you have [pnpm installed](https://pnpm.io/installation), then run (I assume here that you already have this dependency included in your project):
`pnpm patch @google/adk`

Open the temporary directory pnpm provides (it'll be printed out in your terminal) and make two changes:

1. In `package.json`, add the standard `lodash` (CommonJS) to dependencies, matching the version of the existing `lodash-es` entry.
2. In `dist/cjs/index.js`, do a find-and-replace: change all instances of `'lodash-es'` to `'lodash'`.

Here's my package.json example:

```json
{
  "dependencies": {
    "@google/genai": "^1.37.0",
    "@modelcontextprotocol/sdk": "^1.24.0",
    "google-auth-library": "^10.3.0",
    "lodash-es": "^4.17.22",
    "lodash": "^4.17.22", <----- This change here. Also ensure version numbers match for lodash-es (above) and lodash.
    "zod": "3.25.76"
  }
```

Apply the fix:
`pnpm patch-commit <path-to-temp-dir>`

> **Note:** You can find the already-patched version in the [tutorial repository](https://github.com/TylerMutai/google-adk-tutorial.git) if you want to skip this step.

### 2. The Webpack Shim (For NX/Webpack users)

If you are using Webpack (or NX), you need to configure it to handle mixed module types. Since your project is likely ESM, but the patched ADK package is CJS, your `webpack.config.cjs` (you should have a `webpack.config.js` file if your project is commonjs) needs explicit handling for output formatting to ensure Node runs it correctly.

```javascript
// Key configuration: Save output as .cjs to run as a CommonJS module while maintaining TS paths (if your project is esm), otherwise, use .js
config.output = {
  ...config.output,
  // ensure the output is treated as commonjs
  filename: '[name].cjs',
  chunkFilename: '[name].chunk.cjs',
};

```

### 3. Implementing Persistent Sessions

Before we go to the actual meat of the implementation, I'll briefly explain the database entities and how they map to Google ADK types (feel free to skip this section if this is of no interest to you).
#### The Persistence Schema: Mapping ADK to PostgreSQL

You'll need a database schema that mirrors the ADK's internal logic. Using **TypeORM**, we define three primary entities: **Sessions**, **Events**, and **Memories**.

#### The Session Entity

The `SessionEntity` acts as the root. It tracks the overall `state` (the short-term memory) and metadata like `appName` and `userId`. This ensures that even if your server instances cycle, the agent knows exactly where it left off with a specific user.

```typescript
import { BaseEntity } from '@app/common/lib/entities/base.entity.mjs';
import { Column, Entity, OneToMany, Index } from 'typeorm';
import { EventEntity } from './event.entity.mjs';

@Entity('adk_sessions')
export class SessionEntity extends BaseEntity {
  @Column({ type: 'varchar', length: 100 })
  @Index({ unique: true })
  sessionId: string; // The ADK session identifier (e.g. phone_YYYY-MM-DD)

  @Column({ type: 'varchar', length: 255 })
  appName: string;

  @Column({ type: 'varchar', length: 255 })
  userId: string; // The phone number identifier

  @Column({ type: 'jsonb', default: {} })
  state: Record<string, unknown>;

  @Column({ type: 'bigint' })
  lastUpdateTime: number;

  @Column({ type: 'boolean', default: false })
  isSummarized: boolean; // To avoid re-summarizing already summarized sessions.

  @OneToMany(() => EventEntity, (event: EventEntity) => event.session, { cascade: true })
  events: EventEntity[];
}
```

#### The Event Entity

Every interaction, whether it’s a user message, an agent response, or a tool execution, is an event. Notice the `actions` and `content` columns are `jsonb`. This is because ADK events are complex objects; storing them as JSON allows us to preserve the full payload without creating dozens of narrow columns.

```typescript
import { Column, Entity, JoinColumn, ManyToOne, type Relation } from 'typeorm';
import { SessionEntity } from './session.entity.mjs';
import { BaseEntity } from '@app/common/lib/entities/base.entity.mjs';

@Entity('adk_events')
export class EventEntity extends BaseEntity {
  @Column({ type: 'varchar', length: 150, unique: true })
  eventId: string; // Global Event ID provided by ADK

  @ManyToOne(() => SessionEntity, (session) => session.events, { onDelete: 'CASCADE' })
  @JoinColumn()
  session: Relation<SessionEntity>;

  @Column({ type: 'jsonb' })
  actions: Record<string, unknown>; // Stores the full ADK Event object

  @Column({ type: 'varchar', length: 255 })
  invocationId: string;

  /**
   * Represents the entity that generated the event.
   * "user" - for input from the human user
   * "Agent Name" - (e.g. "General Agent") for output from a specific AI agent
   */
  @Column({ type: 'varchar', length: 255, nullable: true })
  author: string;

  @Column({ type: 'bigint' })
  timestamp: number;

  @Column({ type: 'varchar', length: 255, nullable: true })
  branch: string;

  @Column({ type: 'jsonb' })
  content: Record<string, unknown>; // Stores the full ADK Event object
}
```

#### The Memory Entity

Finally, the `MemoryEntity` handles long-term persistence. The key column here is `embedding`, which uses the `vector` type. This is what allows your agent to perform semantic searches over thousands of past interactions to find relevant historical context.

```typescript
import { Column, Entity, Index } from 'typeorm';
import type { Content } from '@google/genai';
import { BaseEntity } from '@app/common/lib/entities/base.entity.mjs';

@Entity('adk_memories')
export class MemoryEntity extends BaseEntity {
  @Column({ type: 'varchar', length: 255 })
  @Index()
  userId: string;

  @Column({ type: 'varchar', length: 255 })
  @Index()
  appName: string;

  @Column({ type: 'jsonb' })
  content: Content;

  @Column({ type: 'varchar', length: 255, nullable: true })
  author: string;

  @Column({ type: 'bigint' })
  timestamp: number;

  @Column({ type: 'vector', length: 768, nullable: true })
  embedding: number[];
}
```

#### Actual Implementation: The Services Layer
We need a custom `SessionService` that persists state to PostgreSQL via TypeORM.

**Critical Implementation Detail:** When overriding the `appendEvent` method in your custom service, you **must** call `super.appendEvent({ session, event })` first.
This call registers the incoming event with the ADK framework's current in-memory execution context for the active "turn." If you omit this, the framework won't recognize that an event occurred, even if you successfully save it to your database.

Here's a code snippet of my implementation (you can find the full code example in the project repo):
```typescript
export class CloudSqlSessionService extends BaseSessionService {
  override async appendEvent({ session, event }: AppendEventRequest): Promise<Event> {
    // 1. Essential: Tell the ADK framework something happened in this turn
    await super.appendEvent({ session, event });

    // 2. Fetch current session state from DB
    const sessionEntity = await this.sessionsRepository.findOne({
      where: { sessionId: session.id },
    });

    // 3. Create event entity
    const eventEntity = this.eventsRepository.create({
      /* ... mapping logic ... */
    });

    await this.eventsRepository.save(eventEntity);
    
    // 4. Persist the updated state delta to Postgres
    await this.sessionsRepository.update(sessionEntity.id, {
      state: updatedState,
      lastUpdateTime: Date.now(),
    });

    return event;
  }
}

```

### 4. Long-Term Memory (Vector Search)

For long-term recall across different sessions, we implement a `CloudSqlMemoryService`. This utilizes **pgvector** within PostgreSQL for similarity search and Gemini’s `text-embedding-004` model for generating embeddings.
**Important**: You MUST enable the pgvector extension in postgres. Refer to this link on how to install this extension: [installation instructions](https://github.com/pgvector/pgvector), then enable it by running this command:

```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

Here's the code example for saving and searching your long term memory (again, the full code example is available in the project repo):
```typescript
export class CloudSqlSessionService extends BaseSessionService {
  async addSessionToMemory(session: Session): Promise<void> {
    console.info(`------------- Adding session ${session.id} events (total events: ${session.events.length}) to memory for user ${session.userId} -------------`);

    for (const event of session.events) {
      console.log('event: ', event);
      console.log('event.content: ', event.content);
      const textContent = stringifyContent(event).trim();
      console.log('textContent: ', textContent, '\n\n');
      if (!textContent) {
        continue;
      }

      try {
        const embedding = await this.generateEmbedding(textContent);

        const memory = this.memoryRepository.create({
          userId: session.userId,
          appName: session.appName,
          content: event.content,
          author: event.author || 'unknown',
          timestamp: event.timestamp,
          embedding: embedding,
        });

        await this.memoryRepository.save(memory);
      } catch (e) {
        console.error(`Failed to generate embedding for event in session ${session.id}: ${e.message}`, e);
      }
    }
  }

  /**
   * Searches for relevant memories using vector similarity.
   */
  async searchMemory(request: SearchMemoryRequest): Promise<SearchMemoryResponse> {
    const { appName, userId, query } = request;

    try {
      const queryEmbedding = await this.generateEmbedding(query);
      const vectorStr = `[${queryEmbedding.join(',')}]`;

      // Use pgvector's cosine distance operator <=>
      const results = await this.dataSource.query(
        `SELECT id, content, author, timestamp
         FROM adk_memories
         WHERE "userId" = $1
           AND "appName" = $2
         ORDER BY embedding <=> $3
           LIMIT 5`,
        [userId, appName, vectorStr],
      );

      const memories: MemoryEntry[] = results.map(r => ({
        content: r.content,
        author: r.author,
        timestamp: r.timestamp,
      }));

      return { memories };
    } catch (error) {
      console.error(`Failed to search memory: ${error.message}`, error);
      return { memories: [] };
    }
  }

  /**
   * Generates an embedding for the given text.
   */
  private async generateEmbedding(text: string): Promise<number[]> {
    const response = await this._genAI.models.embedContent({
      model: 'text-embedding-004',
      contents: [text],
    });
    if (!response.embeddings || response.embeddings.length === 0) {
      throw new Error('No embeddings returned from API');
    }
    return response.embeddings[0].values!;
  }
}

```

---
### 5) Giving the Agent a "Memory" Tool

With your `CloudSqlMemoryService` in place, you need a way for the agent to actually trigger a search. In the ADK, this is done by defining a `FunctionTool`. This tool acts as the bridge between the LLM’s reasoning and your vector database.

When the agent realizes it lacks specific historical context (e.g., "What did we discuss about the project architecture last month?"), it will call this `load_memory` tool.

```typescript
import { FunctionTool } from '@google/adk';
import { z } from 'zod';

/**
 * A built-in tool that allows agents to load relevant long-term memories.
 */
const loadMemoryTool = new FunctionTool({
  name: 'load_memory',
  description: 'Loads relevant long-term memories for the current user based on a query.',
  parameters: z.object({
    query: z.string().describe('The search query for memory.'),
  }),
  execute: async ({ query }, toolContext) => {
    if (!toolContext) {
      throw new Error('Tool context is missing');
    }
    // The ADK passes the active MemoryService via toolContext
    return await toolContext.searchMemory(query);
  },
});

export default loadMemoryTool;

```

#### Why `toolContext` is Key

Notice that we don't import the memory service directly into the tool. Instead, we pull it from the `toolContext`. This is an architectural win: it keeps your tools decoupled from specific database implementations and ensures that the search is automatically scoped to the correct `userId` and `appName` currently active in the session.

---

### 6) Orchestrating the Agent (The "General Agent" Factory)

Now that we have our persistent services and our `load_memory` tool, we need to wire them into the agent. In a production NestJS or Express environment, you’ll often want to pass external dependencies (like database connections or configurations) into your agent definition.

A clean way to do this is by using a **factory function**. This allows you to inject your `MainContext` directly into the agent and its sub-agents.

```typescript
import { LlmAgent } from '@google/adk';
import loadMemoryTool from '../load-memory.tool.mjs';

// Factory function to inject context and dependencies
export default function generalAgent(context: MainContext) {
  return new LlmAgent({
    name: 'general_agent',
    model: 'gemini-1.5-pro', // Use your preferred model constant
    instruction: `
  **Identity:**
  You are SkyCast, a helpful weather assistant. 
  **Current Date and Time:** {current_datetime}
  
  **Long-term Memory:** You can access the user's favorite locations and past queries by calling the \`load_memory\` tool.
  
  **User profile:** {user:profile?} 
  Use this to identify the user's home city or preferred units.

  **Core Responsibilities:**
  1. **Triage & Routing:** Route users to specific sub-agents (user, forecast, or alerts).
  2. **Memory Retrieval:** Proactively check memory for saved preferences if the user is vague.
  `,
    tools: [loadMemoryTool],
    // Sub-agents receive the same context for consistent behavior
    subAgents: [userAgent(context), forecastAgent(context), alertsAgent(context)],
  });
}

```

---

#### Why This Structure Wins

* **Recursive Context:** By passing `context` into `subAgents`, every agent in the hierarchy shares the same understanding of the user's session and database connection.
* **Dynamic Instructions:** Notice the placeholders like `{current_datetime}` and `{user:profile?}`. The ADK fills these in at runtime, giving the LLM immediate "short-term" context before it even decides to call the "long-term" `load_memory` tool.
* **Agent Handoffs:** The `subAgents` array defines the "routing" capabilities. If the user asks to register, the General Agent handles the handoff to the `user_agent` automatically based on your routing rules.

---

## Architectural Benefits

By moving off the default in-memory implementations and using a factory pattern for orchestration, we gain several production advantages:

* **Stateless Application Tier:** Offloading state to PostgreSQL means your application containers can scale horizontally without losing track of a user's progress.
* **Session Durability:** User context survives deployments, crashes, or server restarts.
* **Complex Multi-Agent Logic:** The factory pattern allows you to build a sophisticated "brain" that delegates specialized tasks (like weather alerts or billing) while maintaining a single source of truth for user memory.

### Wrapping Up

By patching the ADK's module issues, implementing database-backed services, and orchestrating your agents through a clean factory pattern, you move from a prototype to a production-ready system. The result is a robust backend that handles state correctly, regardless of infrastructure churn.


Moving beyond devtools: How to implement persistent sessions and memory in Google’s Agent Development Kit using PostgreSQL and TypeORM.

Patching the Gaps: A Production-Ready Guide to Google’s ADK with TypeScript


We recently started partnering (where I currently work) with some of our customers to co-create content, and as a result we needed a way to stream files from the client to the server, through GraphQL. This added an extra layer of complexity, which took us some time to effectively hash-out, and hence the inspiration for this blog.

In this blog, I'll be walking you through (with code snippets included) how to enhance your GraphQL set up, to allow for file uploads. I intend this tutorial to be an in-depth one, that goes full circle starting with the server set up, and implementation (using Apollo Server), and going all the way to the client set up and implementation (using Apollo Client). 
The tech-stack specifications for the client will be Apollo client (and I'll try and generalize the config as much as possible since there's a gazillion javascript frontend frameworks and I can't possibly touch on all of them. **There'll be probably another new javascript frontend framework by the time you are reading this lol**).
For the server, the set-up is mostly inclined towards NestJS, but can be co-adopted to other frameworks as well.

---

### 1. Spinning Up the Backend: Dependencies & Configuration

So for starters, create a nestjs project (if you don't have one already). You can skip this step if you have your own set-up that isn't nestjs-related.

```bash
nest new project-name
```

Secondly, install necessary dependencies (I'm using TypeScript, which should - at the risk of breaking the one forbidden software rule of having an opinion - be your default at this point. If you are writing server-side code without static types, then you must be the one-true master, and I'd love to learn your ways). Skip the nestjs apollo dependencies if you have a different backend set up:


```bash
npm i @nestjs/graphql @nestjs/apollo @apollo/server@^4.11.2 graphql graphql-upload-ts
```

Next, we need to configure our graphql set-up. 

#### For the nestjs category:
Open `app.module.ts` and make sure your graphql config matches mine (especially since v10 of Apollo Server removed it's built-in upload handler):

```typescript
// ...other imports
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
import { ApolloServerPluginLandingPageLocalDefault } from '@apollo/server/plugin/landingPage/default';
// ...other imports
GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  playground: false, // Let's get fancy with an alternative playground.
  plugins: [
    ApolloServerPluginLandingPageLocalDefault({
      embed: true,
    }),
  ],
  uploads: false, // Disable Apollo’s default upload handling if on NestJS 9+ (and Apollo Server version 10 and above).
  autoSchemaFile: 'src/schema.gql', // Adjust if your path differs!
  sortSchema: true,
  introspection: true,
  context: ({ req, res }) => ({ req, res }),
})
// ...other imports
```

Then configure the `graphqlUploadExpress` middleware within the same `app.module.ts` file:

```typescript
export class GraphQLAppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(
      // apply the upload middleware, setting reasonable defaults.
        graphqlUploadExpress({
          maxFieldSize:100 * 1024 * 1024, // 100MB
          maxFileSize: 100 * 1024 * 1024, // 100MB
          maxFiles: 10, // 10 files per request
        })
      )
      .forRoutes('graphql');
  }
}
```

#### for the bare-metal express server category:
```typescript
const express = require('express');
const expressGraphql = require('express-graphql');
const { graphqlUploadExpress } = require('graphql-upload-ts');

express()
  .use(
    '/graphql',
    // apply the upload middleware, setting reasonable defaults.
    graphqlUploadExpress({
      maxFieldSize:100 * 1024 * 1024, // 100MB
      maxFileSize: 100 * 1024 * 1024, // 100MB
      maxFiles: 10, // 10 files per request
    }),
    // Replace with your schema path
    expressGraphql({ schema: require('./schema.gql') })
  )
  .listen(3000);
```
---

### 2. Server Models, DTOs, & Resolvers: Building Your Upload Endpoint

Next, we'll define our model, which we'll call `BigFileDataModel`.
For nestjs users, I'm using the code-first approach. For the rest of the readers, I'll also include a snippet of the resulting schema to include in your schema files.

The typescript definition:

```typescript
import { Field, InputType } from '@nestjs/graphql';
import { FileUpload, GraphQLUpload } from 'graphql-upload-ts';
import { IsIn, IsNotEmpty } from 'class-validator';

@InputType()
export class BigFileDataModel {
  @Field()
  @IsNotEmpty()
  @IsIn(['mp4', 'mov', 'avi', 'mkv', 'webp', 'jpeg', 'jpg', 'png'])
  fileType: string;

  @Field(() => GraphQLUpload)
  contents: Promise<FileUpload>;
}
```

The equivalent schema:

```graphql
"""The `Upload` scalar type represents a file upload."""
scalar Upload

input BigFileDataModel {
  contents: Upload!
  fileType: String!
}
```

Our `BigFileDataModel` has a file `type` and `contents`. The fileType is the file extension (so `.png`, `.jpg` and so on), and the contents is the binary file itself.

__A quick thing to note: Make sure the data types match the typescript example if you are using schema-first approach, specifically the contents (which will be the file being streamed), which returns a promise when all the file bytes have finished transmitting.__



#### Request & Response DTOs

Next, we'll create our DTOs that will be used by a resolver (which we'll create in a future step).
The DTOs will be basically a request and response DTO (Data Transfer Object).
For nestjs readers using the code-first approach, here's the TypeScript definitions.

Our `Request` DTO:
**Request DTO:**
```typescript
import { ArgsType, Field } from '@nestjs/graphql';

@ArgsType()
export class UploadFileRequest {
  @Field(() => BigFileDataModel)
  file: BigFileDataModel;
}
```

**Response DTO:**
```typescript
import { Field, ObjectType } from '@nestjs/graphql';

@ObjectType()
export class _UploadFileResponse {
  @Field({ nullable: true })
  file: string;
}

// Use your preferred base response structure, here I'm assuming inheritance/mixins:
@ObjectType()
export class UploadFileResponse extends StandardGraphQLResponse(_UploadFileResponse) {}
```

For our schema-first readers, here's the equivalent schema:
```graphql
"""The `Upload` scalar type represents a file upload."""
scalar Upload

input BigFileDataModel {
  contents: Upload!
  fileType: String!
}

"""The section above has been included from a previous step for consistency """

type UploadFileResponse {
  file: String!
}

type Mutation {
  uploadFile(file: BigFileDataModel!): UploadFileResponse!
}

```
The request DTO basically takes an argument `file` which specifies the file properties we are sending from the client.

#### Our Resolver and FileUploadService class
At this point I don't think I need a 'nestjs code-first approach users' and 'schema-first users'. I assume you'll be smart enough to deduce which code snippet is for you moving forward.

Our typescript resolver (feel free to adapt this without the annotations to your resolver definition):
```typescript
import { Resolver, Mutation, Args } from '@nestjs/graphql';

@Resolver('FileUploadResolver')
export class FileUploadResolver {
  constructor(private readonly fileUploadService: FileUploadService) {}

  @Mutation(() => UploadFileResponse)
  async uploadFile(@Args() req: UploadFileRequest) {
    const res = await this.fileUploadService.uploadToFirebase({
      file: req.file.contents,
      fileType: req.file.fileType,
    });
    return { file: res };
  }
}
```
The resolver basically calls our file upload service (which uploads the binary file to Google Storage, and returns a string representing the public url).

Here's the definition of our `FileUploadService.ts`, which you can feel free to re-use in your personal services requiring file upload.
```typescript
import { Injectable } from '@nestjs/common';
import { Readable } from 'stream';
import { FileUpload } from 'graphql-upload-ts';

@Injectable()
export class FileUploadService {
  constructor(private readonly folderName: string) {}

  async uploadToFirebase({
    file,
    fileType,
  }: {
    file: Promise<FileUpload>;
    fileType?: string;
  }): Promise<string> {
    const buffer = await this.streamToBuffer((await file).createReadStream());
    const _fileName = `${Date.now()}-${Math.round(Math.random() * 1e9)}.${fileType}`;
    
    // Check the definition for this method below
    return await this.saveFileToStorage(this.folderName, _fileName, buffer);
  }

  private async streamToBuffer(readableStream: Readable): Promise<Buffer> {
    return new Promise((resolve, reject) => {
      const chunks: Buffer[] = [];
      readableStream.on('data', (data) => {
        if (typeof data === 'string') {
          chunks.push(Buffer.from(data, 'utf-8'));
        } else {
          chunks.push(data);
        }
      });
      readableStream.on('end', () => resolve(Buffer.concat(chunks)));
      readableStream.on('error', reject);
    });
  }

  // Stub: wire this up to your favorite storage backend
  private async saveFileToStorage(folder: string, fileName: string, buffer: Buffer): Promise<string> {
    // Implementation left as an exercise for the reader. Feel free to user Google storage/S3/local-fs or your own implementation for this.
    return `https://storage.example.com/${folder}/${fileName}`;
  }
}
```


There you have it - we have our server set up and ready to receive graphql file uploads. You can stop here if you're a just-backend engineer and hate anything to do with HTML/CSS/JavaScript.

For our full-stack engineers (yes, you rank higher than the just-backend engineers) who also want to set up a client, read on.

---

### 3. Client-Side Wizardry: Uploading Files with Apollo Client

Let's face it: JavaScript frontend frameworks multiply like rabbits. As a result, I'll try my best to keep the client implementation as *framework-agnostic* as possible. I'll use Apollo Client as an agnostic toolkit (since it's a separate implementation that does not depend on any frameworks, and is in the blog title).

#### Install necessary dependencies:
```bash
npm install @apollo/client apollo-upload-client
```

#### Setup Apollo Client Setup (with Upload)
Set up your Apollo Client (which you can use in your ApolloProvider in the case of Next.js. For other frameworks, you're on your own here):

```typescript
import { ApolloClient, InMemoryCache } from '@apollo/client';
import { createUploadLink } from 'apollo-upload-client';
import { setContext } from '@apollo/client/link/context';

const httpLink = createUploadLink({
  uri: 'http://localhost:4000/graphql', // Plug in your server URL!
});

const headersLink = setContext((_, { headers }) => ({
  headers: {
    ...headers,
    'Apollo-Require-Preflight': 'true', // Enable CORS for file uploads
  },
}));

const apolloClient = new ApolloClient({
  cache: new InMemoryCache(),
  link: headersLink.concat(httpLink),
  ssrMode: typeof window === 'undefined', // Server-side support, if needed
});

export default apolloClient;
```

In the example above, we create two links: one for injecting headers, and the other, a [http terminating link](https://www.apollographql.com/docs/react/api/link/introduction/#the-terminating-link) for file upload, provided by the `apollo-upload-client` package.
Then we include the ` 'Apollo-Require-Preflight': 'true'` header, which is needed for enabling cors. This is outside the scope of this tutorial, but if you'd like to find out more, you [can here](https://www.apollographql.com/docs/apollo-server/security/cors#graphql-upload);

#### The GraphQL Mutation
```graphql
mutation uploadFile($file: BigFileDataModel!) {
  uploadFile(file: $file) {
    file
  }
}
```

#### File Input and Upload Logic

Here’s a barebones React-flavored file uploader. You can adapt this for your front-end framework of choice.

```typescript
import { useMutation } from '@apollo/client';
const MUTATION = /* see mutation above */;

function UploadFile() {
  const [mutate] = useMutation(MUTATION);

  return (
    <input
      type="file"
      required
      onChange={({
        target: {
          validity,
          files: [file],
        },
      }) => {
        if (validity.valid)
          mutate({
            variables: {
              file,
            },
          });
      }}
    />
  );
}
```
I hope the code snippets above are self-explanatory (considering this is applicable to all frontend frameworks). If you run into any issues, always feel free to tag me in the comment section, and I'll respond as soon as I can!
---

### Wrapping Up...
You should now have a working, end-to-end GraphQL file upload system, complete with server, DTOs, middleware, resolvers, upload streaming, Apollo Client, and a front-end implementation.
If there's a framework or storage backend I missed, or you have a better implementation, drop your thoughts in the comments! 
Until next time, happy hacking!
```


An in-depth guide for integrating file uploads with GraphQL, NestJS and Apollo server & client

Showing posts from nestjs tag

Patching the Gaps: A Production-Ready Guide to Google’s ADK with TypeScript

End-to-End GraphQL File Uploads with Apollo Server and Apollo Client: A Comprehensive Guide