@langgraph-js/pure-graph 1.0.2 → 1.2.0

package/src/adapter/zod.ts

@@ -0,0 +1,135 @@
+import z from 'zod';
+
+export const AssistantConfigurable = z
+    .object({
+        thread_id: z.string().optional(),
+        thread_ts: z.string().optional(),
+    })
+    .catchall(z.unknown());
+
+export const AssistantConfig = z
+    .object({
+        tags: z.array(z.string()).optional(),
+        recursion_limit: z.number().int().optional(),
+        configurable: AssistantConfigurable.optional(),
+    })
+    .catchall(z.unknown())
+    .describe('The configuration of an assistant.');
+
+export const Assistant = z.object({
+    assistant_id: z.string().uuid(),
+    graph_id: z.string(),
+    config: AssistantConfig,
+    created_at: z.string(),
+    updated_at: z.string(),
+    metadata: z.object({}).catchall(z.any()),
+});
+
+export const MetadataSchema = z
+    .object({
+        source: z.union([z.literal('input'), z.literal('loop'), z.literal('update'), z.string()]).optional(),
+        step: z.number().optional(),
+        writes: z.record(z.unknown()).nullable().optional(),
+        parents: z.record(z.string()).optional(),
+    })
+    .catchall(z.unknown());
+
+export const SendSchema = z.object({
+    node: z.string(),
+    input: z.unknown().nullable(),
+});
+
+export const CommandSchema = z.object({
+    update: z
+        .union([z.record(z.unknown()), z.array(z.tuple([z.string(), z.unknown()]))])
+        .nullable()
+        .optional(),
+    resume: z.unknown().optional(),
+    goto: z.union([SendSchema, z.array(SendSchema), z.string(), z.array(z.string())]).optional(),
+});
+
+// 公共的查询参数验证 schema
+export const PaginationQuerySchema = z.object({
+    limit: z.number().int().optional(),
+    offset: z.number().int().optional(),
+});
+
+export const ThreadIdParamSchema = z.object({
+    thread_id: z.string().uuid(),
+});
+
+export const RunIdParamSchema = z.object({
+    thread_id: z.string().uuid(),
+    run_id: z.string().uuid(),
+});
+
+// Assistants 相关的 schema
+export const AssistantsSearchSchema = z.object({
+    graph_id: z.string().optional(),
+    metadata: MetadataSchema.optional(),
+    limit: z.number().int().optional(),
+    offset: z.number().int().optional(),
+});
+
+export const AssistantGraphQuerySchema = z.object({
+    xray: z.string().optional(),
+});
+
+// Runs 相关的 schema
+export const RunStreamPayloadSchema = z
+    .object({
+        assistant_id: z.union([z.string().uuid(), z.string()]),
+        checkpoint_id: z.string().optional(),
+        input: z.any().optional(),
+        command: CommandSchema.optional(),
+        metadata: MetadataSchema.optional(),
+        config: AssistantConfig.optional(),
+        webhook: z.string().optional(),
+        interrupt_before: z.union([z.literal('*'), z.array(z.string())]).optional(),
+        interrupt_after: z.union([z.literal('*'), z.array(z.string())]).optional(),
+        on_disconnect: z.enum(['cancel', 'continue']).optional().default('continue'),
+        multitask_strategy: z.enum(['reject', 'rollback', 'interrupt', 'enqueue']).optional(),
+        stream_mode: z
+            .array(z.enum(['values', 'messages', 'messages-tuple', 'updates', 'events', 'debug', 'custom']))
+            .optional(),
+        stream_subgraphs: z.boolean().optional(),
+        stream_resumable: z.boolean().optional(),
+        after_seconds: z.number().optional(),
+        if_not_exists: z.enum(['create', 'reject']).optional(),
+        on_completion: z.enum(['complete', 'continue']).optional(),
+        feedback_keys: z.array(z.string()).optional(),
+        langsmith_tracer: z.unknown().optional(),
+    })
+    .describe('Payload for creating a stateful run.');
+
+export const RunListQuerySchema = z.object({
+    limit: z.coerce.number().int().optional(),
+    offset: z.coerce.number().int().optional(),
+    status: z.enum(['pending', 'running', 'error', 'success', 'timeout', 'interrupted']).optional(),
+});
+
+export const RunCancelQuerySchema = z.object({
+    wait: z.coerce.boolean().optional().default(false),
+    action: z.enum(['interrupt', 'rollback']).optional().default('interrupt'),
+});
+
+// Threads 相关的 schema
+export const ThreadCreatePayloadSchema = z
+    .object({
+        thread_id: z.string().uuid().describe('The ID of the thread. If not provided, an ID is generated.').optional(),
+        metadata: MetadataSchema.optional(),
+        if_exists: z.union([z.literal('raise'), z.literal('do_nothing')]).optional(),
+    })
+    .describe('Payload for creating a thread.');
+
+export const ThreadSearchPayloadSchema = z
+    .object({
+        metadata: z.record(z.unknown()).describe('Metadata to search for.').optional(),
+        status: z.enum(['idle', 'busy', 'interrupted', 'error']).describe('Filter by thread status.').optional(),
+        values: z.record(z.unknown()).describe('Filter by thread values.').optional(),
+        limit: z.number().int().gte(1).lte(1000).describe('Maximum number to return.').optional(),
+        offset: z.number().int().gte(0).describe('Offset to start from.').optional(),
+        sort_by: z.enum(['thread_id', 'status', 'created_at', 'updated_at']).describe('Sort by field.').optional(),
+        sort_order: z.enum(['asc', 'desc']).describe('Sort order.').optional(),
+    })
+    .describe('Payload for listing threads.');

package/src/createEndpoint.ts

@@ -2,8 +2,7 @@ import { StreamEvent } from '@langchain/core/tracers/log_stream';
 import { streamState } from './graph/stream.js';
 import { Assistant, Run, StreamMode, Metadata, AssistantGraph } from '@langchain/langgraph-sdk';
 import { getGraph, GRAPHS } from './utils/getGraph.js';
-import { BaseThreadsManager } from './threads/index.js';
-import { globalMessageQueue } from './global.js';
+import { LangGraphGlobal } from './global.js';
 import { AssistantSortBy, CancelAction, ILangGraphClient, RunStatus, SortOrder, StreamInputData } from './types.js';
 export { registerGraph } from './utils/getGraph.js';
 
@@ -57,16 +56,24 @@ export const AssistantEndpoint: ILangGraphClient['assistants'] = {
     },
 };
 
-export const createEndpoint = (threads: BaseThreadsManager): ILangGraphClient => {
+export const createEndpoint = (): ILangGraphClient => {
+    const threads = LangGraphGlobal.globalThreadsManager;
     return {
         assistants: AssistantEndpoint,
         threads,
         runs: {
-            list(threadId: string, options?: { limit?: number; offset?: number; status?: RunStatus }): Promise<Run[]> {
+            list(
+                threadId: string,
+                options?: {
+                    limit?: number;
+                    offset?: number;
+                    status?: RunStatus;
+                },
+            ): Promise<Run[]> {
                 return threads.listRuns(threadId, options);
             },
             async cancel(threadId: string, runId: string, wait?: boolean, action?: CancelAction): Promise<void> {
-                return globalMessageQueue.cancelQueue(runId);
+                return LangGraphGlobal.globalMessageQueue.cancelQueue(runId);
             },
             async *stream(threadId: string, assistantId: string, payload: StreamInputData) {
                 if (!payload.config) {

package/src/e.d.ts

@@ -0,0 +1,3 @@
+declare module 'bun:sqlite' {
+    export * from 'better-sqlite3';
+}

package/src/global.ts

@@ -1,6 +1,11 @@
-import { createCheckPointer, createMessageQueue } from './storage/index.js';
-
-/** 全局队列管理器 */
-export const globalMessageQueue = createMessageQueue();
-/** 全局 Checkpointer */
-export const globalCheckPointer = createCheckPointer();
+import { createCheckPointer, createMessageQueue, createThreadManager } from './storage/index.js';
+import type { SqliteSaver } from './storage/sqlite/checkpoint.js';
+const [globalMessageQueue, globalCheckPointer] = await Promise.all([createMessageQueue(), createCheckPointer()]);
+const globalThreadsManager = await createThreadManager({
+    checkpointer: globalCheckPointer as SqliteSaver,
+});
+export class LangGraphGlobal {
+    static globalMessageQueue = globalMessageQueue;
+    static globalCheckPointer = globalCheckPointer;
+    static globalThreadsManager = globalThreadsManager;
+}

package/src/graph/stream.ts

@@ -4,7 +4,7 @@ import type { Pregel } from '@langchain/langgraph/pregel';
 import { getLangGraphCommand } from '../utils/getLangGraphCommand.js';
 import type { BaseStreamQueueInterface } from '../queue/stream_queue.js';
 
-import { globalMessageQueue } from '../global.js';
+import { LangGraphGlobal } from '../global.js';
 import { Run } from '@langgraph-js/sdk';
 import { EventMessage, StreamErrorEventMessage, StreamEndEventMessage } from '../queue/event_message.js';
 
@@ -54,7 +54,13 @@ export async function streamStateWithQueue(
         libStreamMode.add('values');
     }
 
-    await queue.push(new EventMessage('metadata', { run_id: run.run_id, attempt: options.attempt, graph_id: graphId }));
+    await queue.push(
+        new EventMessage('metadata', {
+            run_id: run.run_id,
+            attempt: options.attempt,
+            graph_id: graphId,
+        }),
+    );
 
     const metadata = {
         ...payload.config?.metadata,
@@ -107,7 +113,9 @@ export async function streamStateWithQueue(
                     }
                 }
                 if (mode === 'values') {
-                    await threads.set(run.thread_id, { values: JSON.parse(serialiseAsDict(data)) });
+                    await threads.set(run.thread_id, {
+                        values: data ? JSON.parse(serialiseAsDict(data)) : '',
+                    });
                 }
             } else if (userStreamMode.includes('events')) {
                 await queue.push(new EventMessage('events', event));
@@ -151,7 +159,9 @@ export async function streamStateWithQueue(
                     if (messages[message.id] == null) {
                         messages[message.id] = message;
                         await queue.push(
-                            new EventMessage('messages/metadata', { [message.id]: { metadata: event.metadata } }),
+                            new EventMessage('messages/metadata', {
+                                [message.id]: { metadata: event.metadata },
+                            }),
                         );
                     } else {
                         messages[message.id] = messages[message.id].concat(message);
@@ -174,11 +184,11 @@ export async function streamStateWithQueue(
  * @returns 数据流生成器
  */
 export async function* createStreamFromQueue(queueId: string): AsyncGenerator<{ event: string; data: unknown }> {
-    const queue = globalMessageQueue.getQueue(queueId);
+    const queue = LangGraphGlobal.globalMessageQueue.getQueue(queueId);
     return queue.onDataReceive();
 }
 
-export const serialiseAsDict = (obj: unknown) => {
+export const serialiseAsDict = (obj: unknown, indent = 2) => {
     return JSON.stringify(
         obj,
         function (key: string | number, value: unknown) {
@@ -196,7 +206,7 @@ export const serialiseAsDict = (obj: unknown) => {
 
             return value;
         },
-        2,
+        indent,
     );
 };
 /**
@@ -227,12 +237,12 @@ export async function* streamState(
         // 启动队列推送任务（在后台异步执行）
         await threads.set(threadId, { status: 'busy' });
         await threads.updateRun(run.run_id, { status: 'running' });
-        const queue = globalMessageQueue.createQueue(queueId);
+        const queue = LangGraphGlobal.globalMessageQueue.createQueue(queueId);
         const state = queue.onDataReceive();
         streamStateWithQueue(threads, run, queue, payload, options).catch((error) => {
             console.error('Queue task error:', error);
             // 如果生产者出错，向队列推送错误信号
-            globalMessageQueue.pushToQueue(queueId, new StreamErrorEventMessage(error));
+            LangGraphGlobal.globalMessageQueue.pushToQueue(queueId, new StreamErrorEventMessage(error));
             // TODO 不知道这里需不需要错误处理
         });
         for await (const data of state) {
@@ -248,6 +258,6 @@ export async function* streamState(
     } finally {
         // 在完成后清理队列
         await threads.set(threadId, { status: 'idle' });
-        globalMessageQueue.removeQueue(queueId);
+        LangGraphGlobal.globalMessageQueue.removeQueue(queueId);
     }
 }

package/src/index.ts

@@ -3,3 +3,4 @@ export * from './types';
 export * from './global';
 
 export * from './threads/index';
+export * from './utils/createEntrypointGraph';

package/src/queue/stream_queue.ts

@@ -26,7 +26,7 @@ export class BaseStreamQueue extends EventEmitter<StreamQueueEvents<EventMessage
      * Constructor
      * @param compressMessages 是否压缩消息 / Whether to compress messages
      */
-    constructor(readonly compressMessages: boolean = true) {
+    constructor(readonly id: string, readonly compressMessages: boolean = true) {
         super();
     }
 
@@ -58,6 +58,7 @@ export class BaseStreamQueue extends EventEmitter<StreamQueueEvents<EventMessage
  * Base stream queue interface
  */
 export interface BaseStreamQueueInterface {
+    id: string;
     /** 是否压缩消息 / Whether to compress messages */
     compressMessages: boolean;
     /**
@@ -76,7 +77,7 @@ export interface BaseStreamQueueInterface {
      * @param listener 数据变化监听器 / Data change listener
      * @returns 取消监听函数 / Unsubscribe function
      */
-    onDataChange(listener: (data: EventMessage) => void): () => void;
+    onDataReceive(): AsyncGenerator<EventMessage, void, unknown>;
     /** 取消信号控制器 / Cancel signal controller */
     cancelSignal: AbortController;
     /** 取消操作 / Cancel operation */
@@ -93,7 +94,7 @@ export class StreamQueueManager<Q extends BaseStreamQueueInterface> {
     /** 默认是否压缩消息 / Default compress messages setting */
     private defaultCompressMessages: boolean;
     /** 队列构造函数 / Queue constructor */
-    private queueConstructor: new (compressMessages: boolean) => Q;
+    private queueConstructor: new (queueId: string) => Q;
 
     /**
      * 构造函数
@@ -102,7 +103,7 @@ export class StreamQueueManager<Q extends BaseStreamQueueInterface> {
      * @param options 配置选项 / Configuration options
      */
     constructor(
-        queueConstructor: new (compressMessages: boolean) => Q,
+        queueConstructor: new (id: string) => Q,
         options: {
             /** 默认是否压缩消息 / Default compress messages setting */
             defaultCompressMessages?: boolean;
@@ -121,7 +122,7 @@ export class StreamQueueManager<Q extends BaseStreamQueueInterface> {
      */
     createQueue(id: string, compressMessages?: boolean): Q {
         const compress = compressMessages ?? this.defaultCompressMessages;
-        this.queues.set(id, new this.queueConstructor(compress));
+        this.queues.set(id, new this.queueConstructor(id));
         return this.queues.get(id)!;
     }
 

package/src/storage/index.ts

@@ -1,14 +1,52 @@
-import { StreamQueueManager } from '../queue/stream_queue';
+import { BaseStreamQueueInterface, StreamQueueManager } from '../queue/stream_queue';
 import { MemorySaver } from './memory/checkpoint';
 import { MemoryStreamQueue } from './memory/queue';
+import { MemoryThreadsManager } from './memory/threads';
+import type { SqliteSaver as SqliteSaverType } from './sqlite/checkpoint';
+import { SQLiteThreadsManager } from './sqlite/threads';
 
 // 所有的适配实现，都请写到这里，通过环境变量进行判断使用哪种方式进行适配
 
-export const createCheckPointer = () => {
+export const createCheckPointer = async () => {
+    if (
+        (process.env.REDIS_URL && process.env.CHECKPOINT_TYPE === 'redis') ||
+        process.env.CHECKPOINT_TYPE === 'shallow/redis'
+    ) {
+        if (process.env.CHECKPOINT_TYPE === 'redis') {
+            const { RedisSaver } = await import('@langchain/langgraph-checkpoint-redis');
+            return await RedisSaver.fromUrl(process.env.REDIS_URL!, {
+                defaultTTL: 60, // TTL in minutes
+                refreshOnRead: true,
+            });
+        }
+        if (process.env.CHECKPOINT_TYPE === 'shallow/redis') {
+            const { ShallowRedisSaver } = await import('@langchain/langgraph-checkpoint-redis/shallow');
+            return await ShallowRedisSaver.fromUrl(process.env.REDIS_URL!);
+        }
+    }
+    if (process.env.SQLITE_DATABASE_URI) {
+        const { SqliteSaver } = await import('./sqlite/checkpoint');
+        const db = SqliteSaver.fromConnString(process.env.SQLITE_DATABASE_URI);
+        return db;
+    }
     return new MemorySaver();
 };
 
-export const createMessageQueue = () => {
-    const q: new (compressMessages: boolean) => MemoryStreamQueue = MemoryStreamQueue;
+export const createMessageQueue = async () => {
+    let q: new (id: string) => BaseStreamQueueInterface;
+    if (process.env.REDIS_URL) {
+        console.log('Using redis as stream queue');
+        const { RedisStreamQueue } = await import('./redis/queue');
+        q = RedisStreamQueue;
+    } else {
+        q = MemoryStreamQueue;
+    }
     return new StreamQueueManager(q);
 };
+
+export const createThreadManager = (config: { checkpointer?: SqliteSaverType }) => {
+    if (process.env.SQLITE_DATABASE_URI && config.checkpointer) {
+        return new SQLiteThreadsManager(config.checkpointer);
+    }
+    return new MemoryThreadsManager();
+};

package/src/storage/redis/queue.ts

@@ -0,0 +1,148 @@
+import { CancelEventMessage, EventMessage } from '../../queue/event_message.js';
+import { BaseStreamQueue } from '../../queue/stream_queue.js';
+import { BaseStreamQueueInterface } from '../../queue/stream_queue.js';
+import { createClient, RedisClientType } from 'redis';
+
+/**
+ * Redis 实现的消息队列，用于存储消息
+ */
+export class RedisStreamQueue extends BaseStreamQueue implements BaseStreamQueueInterface {
+    static redis: RedisClientType = createClient({ url: process.env.REDIS_URL! });
+    static subscriberRedis: RedisClientType = createClient({ url: process.env.REDIS_URL! });
+    private redis: RedisClientType;
+    private subscriberRedis: RedisClientType;
+    private queueKey: string;
+    private channelKey: string;
+    private isConnected = false;
+    public cancelSignal: AbortController;
+
+    constructor(readonly id: string = 'default') {
+        super(id, true);
+        this.queueKey = `queue:${this.id}`;
+        this.channelKey = `channel:${this.id}`;
+        this.redis = RedisStreamQueue.redis;
+        this.subscriberRedis = RedisStreamQueue.subscriberRedis;
+        this.cancelSignal = new AbortController();
+
+        // 连接 Redis 客户端
+        this.redis.connect();
+        this.subscriberRedis.connect();
+        this.isConnected = true;
+    }
+
+    /**
+     * 推送消息到 Redis 队列
+     */
+    async push(item: EventMessage): Promise<void> {
+        const data = await this.encodeData(item);
+        const serializedData = Buffer.from(data);
+
+        // 推送到队列
+        await this.redis.lPush(this.queueKey, serializedData);
+
+        // 设置队列 TTL 为 300 秒
+        await this.redis.expire(this.queueKey, 300);
+
+        // 发布到频道通知有新数据
+        await this.redis.publish(this.channelKey, serializedData);
+
+        this.emit('dataChange', data);
+    }
+
+    /**
+     * 异步生成器：支持 for await...of 方式消费队列数据
+     */
+    async *onDataReceive(): AsyncGenerator<EventMessage, void, unknown> {
+        let queue: EventMessage[] = [];
+        let pendingResolve: (() => void) | null = null;
+        let isStreamEnded = false;
+        const handleMessage = async (message: string) => {
+            const data = (await this.decodeData(message)) as EventMessage;
+            queue.push(data);
+            // 检查是否为流结束或错误信号
+            if (
+                data.event === '__stream_end__' ||
+                data.event === '__stream_error__' ||
+                data.event === '__stream_cancel__'
+            ) {
+                setTimeout(() => {
+                    isStreamEnded = true;
+                    if (pendingResolve) {
+                        pendingResolve();
+                        pendingResolve = null;
+                    }
+                }, 300);
+
+                if (data.event === '__stream_cancel__') {
+                    this.cancel();
+                }
+            }
+
+            if (pendingResolve) {
+                pendingResolve();
+                pendingResolve = null;
+            }
+        };
+
+        // 订阅 Redis 频道
+        await this.subscriberRedis.subscribe(this.channelKey, (message) => {
+            handleMessage(message);
+        });
+
+        try {
+            while (!isStreamEnded) {
+                if (queue.length > 0) {
+                    for (const item of queue) {
+                        yield item;
+                    }
+                    queue = [];
+                } else {
+                    await new Promise((resolve) => {
+                        pendingResolve = resolve as () => void;
+                    });
+                }
+            }
+        } finally {
+            await this.subscriberRedis.unsubscribe(this.channelKey);
+        }
+    }
+
+    /**
+     * 获取队列中的所有数据
+     */
+    async getAll(): Promise<EventMessage[]> {
+        const data = await this.redis.lRange(this.queueKey, 0, -1);
+
+        if (!data || data.length === 0) {
+            return [];
+        }
+
+        if (this.compressMessages) {
+            return (await Promise.all(
+                data.map(async (item: string) => {
+                    const parsed = JSON.parse(item) as EventMessage;
+                    return (await this.decodeData(parsed as any)) as EventMessage;
+                }),
+            )) as EventMessage[];
+        } else {
+            return data.map((item: string) => JSON.parse(item) as EventMessage);
+        }
+    }
+
+    /**
+     * 清空队列
+     */
+    clear(): void {
+        if (this.isConnected) {
+            this.redis.del(this.queueKey);
+        }
+    }
+
+    /**
+     * 取消操作
+     */
+    cancel(): void {
+        this.push(new CancelEventMessage());
+        this.cancelSignal.abort('user cancel this run');
+    }
+}

package/src/storage/sqlite/DB.ts

@@ -0,0 +1,16 @@
+import { DatabaseType } from './type';
+
+let Database: new (uri: string) => DatabaseType;
+/** @ts-ignore */
+if (globalThis.Bun) {
+    console.log('Using Bun Sqlite, pid:', process.pid);
+    const BunSqlite = await import('bun:sqlite');
+    /** @ts-ignore */
+    Database = BunSqlite.default;
+} else {
+    /** @ts-ignore */
+    const CommonSqlite = await import('better-sqlite3');
+    Database = CommonSqlite.default;
+}
+
+export { Database };