chat-state-filesystem

Filesystem state adapter for Chat SDK. It stores subscriptions, locks, cache values, lists, and queues in a directory of JSON files using an injected minimal filesystem interface.

Installation

bun add chat-state-filesystem

chat is an optional dependency and is only imported as TypeScript types by this package. Your application should install chat when using the adapter with Chat SDK.

Usage

import * as fs from "node:fs/promises";
import { Chat } from "chat";
import { createFileSystemState } from "chat-state-filesystem";

const state = createFileSystemState({
  fs,
  path: ".chat-state",
});

const bot = new Chat({
  adapters: {
    // ...
  },
  state,
  userName: "bot",
});

You can override lock token generation:

const state = createFileSystemState({
  fs,
  generateToken: () => crypto.randomUUID(),
});

Filesystem Interface

The fs option accepts this minimal interface:

export interface FileSystem {
  mkdir(path: string, options?: { recursive?: boolean }): Promise<unknown>;
  readFile(path: string, encoding: "utf8"): Promise<string>;
  rm?(path: string, options?: { force?: boolean }): Promise<unknown>;
  unlink?(path: string): Promise<unknown>;
  writeFile(path: string, data: string, encoding: "utf8"): Promise<unknown>;
}

node:fs/promises satisfies this interface directly.

Storage Layout

By default, state is stored under .chat-state:

.chat-state/
├── subscriptions.json
├── locks/
│   └── {thread-key}.json
├── cache/
│   └── {cache-key}.json
├── lists/
│   └── {list-key}.json
└── queues/
    └── {thread-key}.json

Keys are encoded with encodeURIComponent, and . is encoded as %2E.

Capabilities

| Feature | Supported | |---------|-----------| | Persistence | Yes, JSON files on disk | | Multi-instance | No | | Subscriptions | Yes, filesystem-backed | | Distributed locking | No, single-process file mutation lock only | | Key-value caching | Yes, filesystem-backed with TTL | | Lists | Yes, filesystem-backed with TTL and max length trimming | | Queues | Yes, filesystem-backed with expiry and max size trimming | | Automatic reconnect | Not applicable, no network connection | | Cluster support | No | | Sentinel support | No | | Key prefix namespacing | No, use separate path directories instead |

Notes

This adapter serializes read-modify-write operations in-process per file. It is appropriate for local development, tests, and simple single-process deployments. It is not a replacement for Redis or Postgres when you need robust multi-process or multi-host distributed locking.

Development

bun install
bun test
bun run typecheck
bun run build

Tests write fixtures to .tmp/.chat-state. The .tmp directory is intentionally not removed after the final test run so the generated state can be inspected.

License

MIT