@langgraph-js/pure-graph 1.4.0 → 1.4.1

package/README.md

@@ -27,6 +27,25 @@ yarn add @langgraph-js/pure-graph
 
 ### Next.js Example
 
+```text
+my-nextjs-app/
+├── app/
+│   ├── api/
+│   │   └── langgraph/
+│   │       └── [...path]/
+│   │           └── route.ts      # LangGraph API endpoint
+│   ├── layout.tsx                # Root layout
+│   └── page.tsx                  # Your page
+├── agent/
+│   └── graph-name/
+│       ├── graph.ts              # Main graph implementation
+│       ├── state.ts              # Graph state definitions
+│       └── prompt.ts             # Prompt templates
+├── .env.local                    # Environment variables
+├── package.json                  # Dependencies and scripts
+└── tsconfig.json                 # TypeScript configuration
+```
+
 To integrate Pure Graph into a Next.js project, follow these steps:
 
 1. **Create a Route Handler**
@@ -37,7 +56,7 @@ To integrate Pure Graph into a Next.js project, follow these steps:
     // app/api/langgraph/[...path]/route.ts
     import { GET, POST, DELETE } from '@langgraph-js/pure-graph/dist/adapter/nextjs/router.js';
     import { registerGraph } from '@langgraph-js/pure-graph';
-    import { graph } from './path/to/your/graph'; // Replace with your graph implementation
+    import { graph } from '../../../agent/graph-name/graph';
 
     registerGraph('test', graph);
 
@@ -65,7 +84,7 @@ To integrate Pure Graph into a Hono.js project, follow these steps:
     ```js
     // app.js
     import { registerGraph } from '@langgraph-js/pure-graph';
-    import { graph } from './path/to/your/graph'; // Replace with your graph implementation
+    import { graph } from './agent/graph-name/graph';
     import { Hono } from 'hono';
     import LangGraphApp from '@langgraph-js/pure-graph/dist/adapter/hono/index';
 
@@ -93,9 +112,146 @@ Here are the environment variables you need to configure:
 
 -   `SQLITE_DATABASE_URI`: Path to your SQLite database (e.g., `./.langgraph_api/chat.db`).
 -   `DATABASE_URL`: PostgreSQL connection string (required for PostgreSQL checkpoint storage).
+-   `DATABASE_INIT`: Set to `true` for initial PostgreSQL database setup (required only on first run with PostgreSQL).
 -   `CHECKPOINT_TYPE`: Type of checkpoint storage (optional, defaults to memory; options: `postgres`, `redis`, `shallow/redis`).
 -   `REDIS_URL`: URL for Redis (required if using Redis checkpoint or message queue).
 
+## Persistence Configuration
+
+Pure Graph supports multiple storage backends for persisting graph state, checkpoints, and thread data. Choose the appropriate storage type based on your requirements for scalability, persistence, and performance.
+
+### Memory Storage (Default)
+
+**Best for**: Development, testing, or stateless applications.
+
+**Configuration**:
+
+```bash
+# No additional configuration required - this is the default
+```
+
+**Characteristics**:
+
+-   Fastest performance
+-   No persistence across restarts
+-   Data is lost when the application stops
+-   Suitable for development and testing
+
+### SQLite Storage
+
+**Best for**: Single-server applications, development, or small-scale production.
+
+**Configuration**:
+
+```bash
+SQLITE_DATABASE_URI=./.langgraph_api/chat.db
+```
+
+**Setup**:
+
+```bash
+# Create the database directory
+mkdir -p .langgraph_api
+
+# The database file will be created automatically on first run
+```
+
+**Characteristics**:
+
+-   File-based database
+-   Good performance for moderate workloads
+-   ACID compliant
+-   Single-writer limitation
+
+### PostgreSQL Storage
+
+**Best for**: Production applications requiring high reliability and scalability.
+
+**Configuration**:
+
+```bash
+DATABASE_URL=postgresql://username:password@localhost:5432/langgraph_db
+DATABASE_INIT=true  # Only needed for initial setup
+CHECKPOINT_TYPE=postgres
+```
+
+**Setup**:
+
+```bash
+# First run with DATABASE_INIT=true to create tables
+export DATABASE_INIT=true
+# Run your application once to initialize the database
+
+# Remove DATABASE_INIT for subsequent runs
+unset DATABASE_INIT
+```
+
+**Characteristics**:
+
+-   Full ACID compliance
+-   Concurrent access support
+-   Scalable for high-throughput applications
+-   Requires PostgreSQL server setup
+
+### Redis Storage
+
+Pure Graph supports two Redis checkpoint modes:
+
+#### Full Redis Checkpoint
+
+**Best for**: High-performance caching with full persistence.
+
+**Configuration**:
+
+```bash
+REDIS_URL=redis://localhost:6379
+CHECKPOINT_TYPE=redis
+```
+
+#### Shallow Redis Checkpoint
+
+**Best for**: Memory-efficient Redis usage with lighter persistence.
+
+**Configuration**:
+
+```bash
+REDIS_URL=redis://localhost:6379
+CHECKPOINT_TYPE=shallow/redis
+```
+
+**Characteristics**:
+
+-   High performance
+-   TTL-based automatic cleanup
+-   Distributed caching capabilities
+-   Requires Redis server setup
+
+### Redis Message Queue
+
+When using Redis, message queues are automatically enabled for better performance:
+
+**Configuration**:
+
+```bash
+REDIS_URL=redis://localhost:6379
+# Message queues will use Redis automatically when REDIS_URL is set
+```
+
+**Characteristics**:
+
+-   Automatic TTL management (300 seconds)
+-   Improved streaming performance
+-   Better resource utilization
+
+### Configuration Priority
+
+Storage backends are selected in this priority order:
+
+1. **Redis** (if `REDIS_URL` set and `CHECKPOINT_TYPE` matches)
+2. **PostgreSQL** (if `DATABASE_URL` set)
+3. **SQLite** (if `SQLITE_DATABASE_URI` set)
+4. **Memory** (fallback default)
+
 ## API Endpoints
 
 ### Assistants

package/dist/global.d.ts

@@ -2,6 +2,6 @@ import type { SqliteSaver } from './storage/sqlite/checkpoint.js';
 import type { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
 export declare class LangGraphGlobal {
     static globalMessageQueue: import("./queue/stream_queue.js").StreamQueueManager<import("./queue/stream_queue.js").BaseStreamQueueInterface>;
-    static globalCheckPointer: import("@langchain/langgraph-checkpoint-redis").RedisSaver | import("@langchain/langgraph-checkpoint-redis/shallow").ShallowRedisSaver | PostgresSaver | SqliteSaver | import("@langchain/langgraph-checkpoint").MemorySaver;
+    static globalCheckPointer: SqliteSaver | PostgresSaver | import("@langchain/langgraph-checkpoint-redis").RedisSaver | import("@langchain/langgraph-checkpoint-redis/shallow").ShallowRedisSaver | import("@langchain/langgraph-checkpoint").MemorySaver;
     static globalThreadsManager: import("./storage/pg/threads.js").PostgresThreadsManager<unknown> | import("./storage/sqlite/threads.js").SQLiteThreadsManager<unknown> | import("./storage/memory/threads.js").MemoryThreadsManager<unknown>;
 }

package/dist/global.js

@@ -1,8 +1,11 @@
 import { createCheckPointer, createMessageQueue, createThreadManager } from './storage/index.js';
 const [globalMessageQueue, globalCheckPointer] = await Promise.all([createMessageQueue(), createCheckPointer()]);
+console.debug('LG | checkpointer created');
 const globalThreadsManager = await createThreadManager({
     checkpointer: globalCheckPointer,
 });
+console.debug('LG | threads manager created');
+console.debug('LG | global init done');
 export class LangGraphGlobal {
     static globalMessageQueue = globalMessageQueue;
     static globalCheckPointer = globalCheckPointer;

package/dist/storage/index.d.ts

@@ -4,7 +4,7 @@ import { MemoryThreadsManager } from './memory/threads';
 import type { SqliteSaver as SqliteSaverType } from './sqlite/checkpoint';
 import type { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
 import { SQLiteThreadsManager } from './sqlite/threads';
-export declare const createCheckPointer: () => Promise<import("@langchain/langgraph-checkpoint-redis").RedisSaver | import("@langchain/langgraph-checkpoint-redis/shallow").ShallowRedisSaver | PostgresSaver | SqliteSaverType | MemorySaver>;
+export declare const createCheckPointer: () => Promise<SqliteSaverType | PostgresSaver | import("@langchain/langgraph-checkpoint-redis").RedisSaver | import("@langchain/langgraph-checkpoint-redis/shallow").ShallowRedisSaver | MemorySaver>;
 export declare const createMessageQueue: () => Promise<StreamQueueManager<BaseStreamQueueInterface>>;
 export declare const createThreadManager: (config: {
     checkpointer?: SqliteSaverType | PostgresSaver;

package/dist/storage/index.js

@@ -8,7 +8,7 @@ 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') {
-            console.log('Using redis as checkpoint');
+            console.debug('LG | Using redis as checkpoint');
             const { RedisSaver } = await import('@langchain/langgraph-checkpoint-redis');
             return await RedisSaver.fromUrl(process.env.REDIS_URL, {
                 defaultTTL: 60, // TTL in minutes
@@ -16,18 +16,18 @@ export const createCheckPointer = async () => {
             });
         }
         if (process.env.CHECKPOINT_TYPE === 'shallow/redis') {
-            console.log('Using shallow redis as checkpoint');
+            console.debug('LG | Using shallow redis as checkpoint');
             const { ShallowRedisSaver } = await import('@langchain/langgraph-checkpoint-redis/shallow');
             return await ShallowRedisSaver.fromUrl(process.env.REDIS_URL);
         }
     }
     if (process.env.DATABASE_URL) {
-        console.log('Using postgres as checkpoint');
+        console.debug('LG | Using postgres as checkpoint');
         const { createPGCheckpoint } = await import('./pg/checkpoint');
         return createPGCheckpoint();
     }
     if (process.env.SQLITE_DATABASE_URI) {
-        console.log('Using sqlite as checkpoint');
+        console.debug('LG | Using sqlite as checkpoint');
         const { SqliteSaver } = await import('./sqlite/checkpoint');
         const db = SqliteSaver.fromConnString(process.env.SQLITE_DATABASE_URI);
         return db;
@@ -37,7 +37,7 @@ export const createCheckPointer = async () => {
 export const createMessageQueue = async () => {
     let q;
     if (process.env.REDIS_URL) {
-        console.log('Using redis as stream queue');
+        console.debug('LG | Using redis as stream queue');
         const { RedisStreamQueue } = await import('./redis/queue');
         q = RedisStreamQueue;
     }
@@ -49,10 +49,16 @@ export const createMessageQueue = async () => {
 export const createThreadManager = async (config) => {
     if (process.env.DATABASE_URL && config.checkpointer) {
         const { PostgresThreadsManager } = await import('./pg/threads');
-        return new PostgresThreadsManager(config.checkpointer);
+        const threadsManager = new PostgresThreadsManager(config.checkpointer);
+        if (process.env.DATABASE_INIT === 'true') {
+            await threadsManager.setup();
+        }
+        return threadsManager;
     }
     if (process.env.SQLITE_DATABASE_URI && config.checkpointer) {
-        return new SQLiteThreadsManager(config.checkpointer);
+        const threadsManager = new SQLiteThreadsManager(config.checkpointer);
+        await threadsManager.setup();
+        return threadsManager;
     }
     return new MemoryThreadsManager();
 };

package/dist/storage/memory/threads.d.ts

@@ -2,6 +2,7 @@ import { BaseThreadsManager } from '../../threads/index.js';
 import { Command, Config, Metadata, OnConflictBehavior, Run, RunStatus, SortOrder, Thread, ThreadSortBy, ThreadStatus } from '@langgraph-js/sdk';
 export declare class MemoryThreadsManager<ValuesType = unknown> implements BaseThreadsManager<ValuesType> {
     private threads;
+    setup(): Promise<void>;
     create(payload?: {
         metadata?: Metadata;
         threadId?: string;

package/dist/storage/memory/threads.js

@@ -2,6 +2,9 @@ import { getGraph } from '../../utils/getGraph.js';
 import { serialiseAsDict } from '../../graph/stream.js';
 export class MemoryThreadsManager {
     threads = [];
+    async setup() {
+        return;
+    }
     async create(payload) {
         const threadId = payload?.threadId || crypto.randomUUID();
         if (payload?.ifExists === 'raise' && this.threads.some((t) => t.thread_id === threadId)) {

package/dist/storage/pg/checkpoint.js

@@ -2,7 +2,7 @@ import { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
 export const createPGCheckpoint = async () => {
     const checkpointer = PostgresSaver.fromConnString(process.env.DATABASE_URL);
     if (process.env.DATABASE_INIT === 'true') {
-        console.log('Initializing postgres checkpoint');
+        console.debug('LG | Initializing postgres checkpoint');
         await checkpointer.setup();
     }
     return checkpointer;

package/dist/storage/pg/threads.d.ts

@@ -5,7 +5,7 @@ export declare class PostgresThreadsManager<ValuesType = unknown> implements Bas
     private pool;
     private isSetup;
     constructor(checkpointer: PostgresSaver);
-    private setup;
+    setup(): Promise<void>;
     create(payload?: {
         metadata?: Metadata;
         threadId?: string;

package/dist/storage/pg/threads.js

@@ -6,7 +6,6 @@ export class PostgresThreadsManager {
     constructor(checkpointer) {
         // 访问 PostgresSaver 的 pool 属性（虽然是 private，但在运行时可以访问）
         this.pool = checkpointer.pool;
-        this.setup();
     }
     async setup() {
         if (this.isSetup) {

package/dist/storage/sqlite/DB.js

@@ -1,7 +1,7 @@
 let Database;
 /** @ts-ignore */
 if (globalThis.Bun) {
-    console.log('Using Bun Sqlite, pid:', process.pid);
+    console.debug('LG | Using Bun Sqlite, pid:', process.pid);
     const BunSqlite = await import('bun:sqlite');
     /** @ts-ignore */
     Database = BunSqlite.default;

package/dist/storage/sqlite/threads.d.ts

@@ -6,7 +6,7 @@ export declare class SQLiteThreadsManager<ValuesType = unknown> implements BaseT
     db: DatabaseType;
     private isSetup;
     constructor(checkpointer: SqliteSaver);
-    private setup;
+    setup(): Promise<void>;
     create(payload?: {
         metadata?: Metadata;
         threadId?: string;

package/dist/storage/sqlite/threads.js

@@ -5,9 +5,8 @@ export class SQLiteThreadsManager {
     isSetup = false;
     constructor(checkpointer) {
         this.db = checkpointer.db;
-        this.setup();
     }
-    setup() {
+    async setup() {
         if (this.isSetup) {
             return;
         }

package/dist/threads/index.d.ts

@@ -1,5 +1,6 @@
 import { Command, Config, Metadata, OnConflictBehavior, Run, RunStatus, SortOrder, Thread, ThreadSortBy, ThreadStatus } from '@langgraph-js/sdk';
 export interface BaseThreadsManager<ValuesType = unknown> {
+    setup(): Promise<void>;
     create(payload?: {
         metadata?: Metadata;
         threadId?: string;