@limo-labs/deity 0.1.1-alpha.2 → 0.1.1-alpha.4

package/dist/adapter-C9dvN_7c.d.cts

@@ -0,0 +1,696 @@
+/**
+ * State checkpoint types and utilities.
+ * Supports semantic versioning and explicit save points.
+ */
+/**
+ * State checkpoint record.
+ * Represents a single save point in workflow execution.
+ */
+interface StateCheckpoint {
+    /** Unique checkpoint ID (developer-defined) */
+    id: string;
+    /** Semantic version (major.minor.patch) */
+    version: string;
+    /** Checkpoint label (e.g., "after-planning", "analysis-complete") */
+    label: string;
+    /** Arbitrary state data */
+    state: Record<string, unknown>;
+    /** Stage outputs captured at this point */
+    outputs: Record<string, unknown>;
+    /** Creation timestamp (ISO 8601) */
+    timestamp: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Checkpoint store interface.
+ * Manages persistence of state checkpoints.
+ */
+interface CheckpointStore {
+    /**
+     * Save a checkpoint.
+     */
+    save(checkpoint: StateCheckpoint): Promise<void>;
+    /**
+     * Load a checkpoint by ID.
+     */
+    load(checkpointId: string): Promise<StateCheckpoint | undefined>;
+    /**
+     * List all available checkpoints.
+     */
+    list(): Promise<StateCheckpoint[]>;
+    /**
+     * Get the latest checkpoint.
+     */
+    getLatest(): Promise<StateCheckpoint | undefined>;
+    /**
+     * Delete a checkpoint by ID.
+     */
+    delete(checkpointId: string): Promise<void>;
+    /**
+     * Clear all checkpoints.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Semantic version utilities.
+ */
+/**
+ * Parse a semantic version string into components.
+ */
+declare function parseVersion(version: string): {
+    major: number;
+    minor: number;
+    patch: number;
+};
+/**
+ * Check if a checkpoint version is compatible with the current version.
+ * Only major version changes break compatibility.
+ */
+declare function isCompatible(checkpointVersion: string, currentVersion: string): boolean;
+/**
+ * Compare two semantic versions.
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b
+ */
+declare function compareVersions(a: string, b: string): number;
+/**
+ * Validate a semantic version string.
+ */
+declare function isValidVersion(version: string): boolean;
+
+/**
+ * Simplified state store interface for basic use cases.
+ *
+ * This interface provides a minimal API for simple key-value storage,
+ * reducing complexity for users who don't need advanced checkpoint features.
+ *
+ * ## Design Philosophy
+ *
+ * - **Minimal**: Only 4 essential methods (get, set, delete, has)
+ * - **Async-first**: All methods return Promises for I/O flexibility
+ * - **Type-safe**: Full TypeScript support with unknown type safety
+ * - **Framework-agnostic**: Can be used standalone or with Deity workflow
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { SimpleStateStore } from '@limo-labs/deity/state';
+ *
+ * // Implement your own store
+ * class MyStore implements SimpleStateStore {
+ *   async get(key: string) { ... }
+ *   async set(key: string, value: unknown) { ... }
+ *   async delete(key: string) { ... }
+ *   async has(key: string) { ... }
+ * }
+ *
+ * // Or use built-in implementations
+ * import { createInMemoryStore, createFileStore } from '@limo-labs/deity/helpers';
+ *
+ * const memStore = createInMemoryStore();
+ * const fileStore = createFileStore('./data');
+ * ```
+ *
+ * ## When to Use
+ *
+ * **Use SimpleStateStore when:**
+ * - You need basic key-value storage
+ * - You don't need checkpoint versioning
+ * - You want minimal implementation overhead
+ * - You're prototyping or testing
+ *
+ * **Use full StateStore/CheckpointStore when:**
+ * - You need semantic versioning
+ * - You need event sourcing
+ * - You need workflow checkpoint/resume
+ * - You need time-travel debugging
+ *
+ * @module state/simple-store
+ * @since 3.0.0
+ */
+/**
+ * Simplified state store interface.
+ *
+ * Provides minimal key-value storage without checkpoint metadata.
+ * All values are serializable (JSON-compatible).
+ *
+ * @example
+ * ```typescript
+ * const store: SimpleStateStore = createInMemoryStore();
+ *
+ * // Set a value
+ * await store.set('user:123', { name: 'Alice', age: 30 });
+ *
+ * // Get a value
+ * const user = await store.get('user:123');
+ *
+ * // Check existence
+ * if (await store.has('user:123')) {
+ *   console.log('User exists');
+ * }
+ *
+ * // Delete a value
+ * await store.delete('user:123');
+ * ```
+ */
+interface SimpleStateStore {
+    /**
+     * Get a value by key.
+     *
+     * @param key - The key to retrieve
+     * @returns The stored value, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const data = await store.get('my-key');
+     * if (data) {
+     *   console.log('Found:', data);
+     * }
+     * ```
+     */
+    get(key: string): Promise<unknown | undefined>;
+    /**
+     * Set a value for a key.
+     *
+     * @param key - The key to store under
+     * @param value - The value to store (must be JSON-serializable)
+     *
+     * @example
+     * ```typescript
+     * await store.set('config', { theme: 'dark', lang: 'en' });
+     * ```
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /**
+     * Delete a value by key.
+     *
+     * @param key - The key to delete
+     *
+     * @example
+     * ```typescript
+     * await store.delete('temp-data');
+     * ```
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a key exists.
+     *
+     * @param key - The key to check
+     * @returns True if the key exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (await store.has('cache:results')) {
+     *   const results = await store.get('cache:results');
+     * }
+     * ```
+     */
+    has(key: string): Promise<boolean>;
+}
+/**
+ * Extended simple store interface with optional clear operation.
+ *
+ * Some implementations may support bulk delete operations.
+ */
+interface SimpleStateStoreWithClear extends SimpleStateStore {
+    /**
+     * Clear all stored values.
+     * Optional - not all implementations support this.
+     */
+    clear?(): Promise<void>;
+}
+
+/**
+ * In-memory implementation of SimpleStateStore.
+ *
+ * Fast, lightweight key-value store using a Map.
+ * Supports optional TTL (time-to-live) and size limits.
+ *
+ * ## Features
+ *
+ * - **Fast**: O(1) get/set/delete operations
+ * - **TTL support**: Auto-expire entries after timeout
+ * - **Size limits**: Prevent unbounded memory growth
+ * - **LRU eviction**: When size limit reached, evict oldest entries
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { InMemoryStateStore } from '@limo-labs/deity/state';
+ *
+ * // Basic usage
+ * const store = new InMemoryStateStore();
+ *
+ * // With TTL (entries expire after 1 hour)
+ * const cacheStore = new InMemoryStateStore({
+ *   ttl: 3600000  // 1 hour in ms
+ * });
+ *
+ * // With size limit (max 1000 entries)
+ * const limitedStore = new InMemoryStateStore({
+ *   maxSize: 1000
+ * });
+ * ```
+ *
+ * @module state/memory-store
+ * @since 3.0.0
+ */
+
+/**
+ * In-memory state store configuration.
+ */
+interface InMemoryStateStoreOptions {
+    /**
+     * Time-to-live in milliseconds.
+     * Entries older than this will be automatically deleted.
+     * Default: undefined (no expiration)
+     */
+    ttl?: number;
+    /**
+     * Maximum number of entries.
+     * When limit is reached, oldest entries are evicted (LRU).
+     * Default: undefined (no limit)
+     */
+    maxSize?: number;
+    /**
+     * Enable automatic cleanup of expired entries.
+     * When enabled, runs a cleanup check every cleanupInterval ms.
+     * Default: true
+     */
+    autoCleanup?: boolean;
+    /**
+     * Cleanup interval in milliseconds.
+     * Only used when autoCleanup is enabled.
+     * Default: 60000 (1 minute)
+     */
+    cleanupInterval?: number;
+}
+/**
+ * In-memory state store implementation.
+ *
+ * Stores data in a Map with optional TTL and size limits.
+ * All operations are synchronous but wrapped in Promises for API consistency.
+ *
+ * @example
+ * ```typescript
+ * // Create store with 5-minute TTL
+ * const store = new InMemoryStateStore({
+ *   ttl: 5 * 60 * 1000,
+ *   maxSize: 500
+ * });
+ *
+ * // Use like any SimpleStateStore
+ * await store.set('session:abc', { userId: 123 });
+ * const session = await store.get('session:abc');
+ *
+ * // Entries expire after 5 minutes
+ * await new Promise(resolve => setTimeout(resolve, 5 * 60 * 1000 + 100));
+ * const expired = await store.get('session:abc'); // undefined
+ * ```
+ */
+declare class InMemoryStateStore implements SimpleStateStore {
+    private data;
+    private options;
+    private cleanupTimer?;
+    constructor(options?: InMemoryStateStoreOptions);
+    /**
+     * Get a value by key.
+     * Returns undefined if key doesn't exist or has expired.
+     */
+    get(key: string): Promise<unknown | undefined>;
+    /**
+     * Set a value for a key.
+     * Evicts old entries if size limit is reached.
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /**
+     * Delete a value by key.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a key exists and is not expired.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clear all stored values.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the current number of stored entries (including expired).
+     */
+    get size(): number;
+    /**
+     * Get statistics about the store.
+     */
+    getStats(): {
+        totalEntries: number;
+        activeEntries: number;
+        expiredEntries: number;
+        oldestEntry?: number;
+        newestEntry?: number;
+    };
+    /**
+     * Manually clean up expired entries.
+     * Returns the number of entries removed.
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Stop auto-cleanup timer.
+     */
+    destroy(): void;
+    /**
+     * Check if an entry has expired.
+     */
+    private isExpired;
+    /**
+     * Evict the oldest entry (LRU).
+     */
+    private evictOldest;
+    /**
+     * Start automatic cleanup timer.
+     */
+    private startAutoCleanup;
+}
+/**
+ * Create an in-memory state store with default options.
+ *
+ * @param options - Store configuration options
+ * @returns A new InMemoryStateStore instance
+ *
+ * @example
+ * ```typescript
+ * // Simple cache with 10-minute TTL
+ * const cache = createInMemoryStore({
+ *   ttl: 10 * 60 * 1000,
+ *   maxSize: 100
+ * });
+ * ```
+ */
+declare function createInMemoryStore(options?: InMemoryStateStoreOptions): InMemoryStateStore;
+
+/**
+ * File system implementation of SimpleStateStore.
+ *
+ * Stores each key-value pair as a separate JSON file.
+ * Provides durable storage with atomic write guarantees.
+ *
+ * ## Features
+ *
+ * - **Durable**: Data persists across process restarts
+ * - **Atomic writes**: Uses write-then-rename for safety
+ * - **One file per key**: Simple directory structure
+ * - **Safe concurrent access**: Atomic filesystem operations
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { FileSystemStateStore } from '@limo-labs/deity/state';
+ *
+ * const store = new FileSystemStateStore('./my-data');
+ * await store.set('config', { version: '1.0' });
+ * const config = await store.get('config');
+ * ```
+ *
+ * ## Directory Structure
+ *
+ * ```
+ * ./my-data/
+ *   ├── state-config.json
+ *   ├── state-user-123.json
+ *   └── state-session-abc.json
+ * ```
+ *
+ * @module state/file-store
+ * @since 3.0.0
+ */
+
+/**
+ * File system state store configuration.
+ */
+interface FileSystemStateStoreOptions {
+    /**
+     * Pretty-print JSON files.
+     * Makes files human-readable but slightly larger.
+     * Default: false
+     */
+    prettyPrint?: boolean;
+    /**
+     * File name prefix for state files.
+     * Default: "state-"
+     */
+    filePrefix?: string;
+    /**
+     * File extension for state files.
+     * Default: ".json"
+     */
+    fileExtension?: string;
+    /**
+     * Use atomic writes (write to temp file, then rename).
+     * Safer but slightly slower.
+     * Default: true
+     */
+    atomicWrites?: boolean;
+}
+/**
+ * File system state store implementation.
+ *
+ * Stores each key as a separate JSON file in a directory.
+ * Provides durable, crash-safe storage.
+ *
+ * @example
+ * ```typescript
+ * // Create store in './data' directory
+ * const store = new FileSystemStateStore('./data');
+ *
+ * // Store some data
+ * await store.set('user:alice', {
+ *   name: 'Alice',
+ *   email: 'alice@example.com'
+ * });
+ *
+ * // Retrieve data
+ * const user = await store.get('user:alice');
+ *
+ * // Data persists across restarts
+ * ```
+ */
+declare class FileSystemStateStore implements SimpleStateStore {
+    private directory;
+    private options;
+    constructor(directory: string, options?: FileSystemStateStoreOptions);
+    /**
+     * Get a value by key.
+     */
+    get(key: string): Promise<unknown | undefined>;
+    /**
+     * Set a value for a key.
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /**
+     * Delete a value by key.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a key exists.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clear all stored values.
+     */
+    clear(): Promise<void>;
+    /**
+     * List all keys in the store.
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Get statistics about the store.
+     */
+    getStats(): Promise<{
+        totalKeys: number;
+        totalSize: number;
+        directory: string;
+    }>;
+    /**
+     * Ensure the storage directory exists.
+     */
+    private ensureDirectory;
+    /**
+     * Get the file path for a key.
+     */
+    private getFilePath;
+    /**
+     * Get a temporary file path for atomic writes.
+     */
+    private getTempFilePath;
+    /**
+     * Sanitize a key to be filesystem-safe.
+     * Replaces special characters with dashes and hashes long keys.
+     */
+    private sanitizeKey;
+    /**
+     * Extract the original key from a file name.
+     */
+    private keyFromFileName;
+}
+/**
+ * Create a file system state store.
+ *
+ * @param directory - Directory to store state files
+ * @param options - Store configuration options
+ * @returns A new FileSystemStateStore instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const store = createFileStore('./data');
+ *
+ * // With pretty-printed JSON
+ * const prettyStore = createFileStore('./data', {
+ *   prettyPrint: true
+ * });
+ * ```
+ */
+declare function createFileStore(directory: string, options?: FileSystemStateStoreOptions): FileSystemStateStore;
+
+/**
+ * Adapter for using SimpleStateStore with the full CheckpointStore interface.
+ *
+ * This adapter wraps a SimpleStateStore and provides the full CheckpointStore
+ * API, including checkpoint versioning, metadata, and listing.
+ *
+ * ## Purpose
+ *
+ * Allows simple key-value stores to be used with Deity's checkpoint system
+ * without implementing the full CheckpointStore interface.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { createStateStoreAdapter } from '@limo-labs/deity/state';
+ * import { createInMemoryStore } from '@limo-labs/deity/helpers';
+ *
+ * // Create simple store
+ * const simpleStore = createInMemoryStore();
+ *
+ * // Wrap with adapter
+ * const checkpointStore = createStateStoreAdapter(simpleStore);
+ *
+ * // Use as CheckpointStore
+ * await checkpointStore.save({
+ *   id: 'checkpoint-1',
+ *   version: '1.0.0',
+ *   label: 'After analysis',
+ *   state: {},
+ *   outputs: { result: 42 },
+ *   timestamp: new Date().toISOString()
+ * });
+ * ```
+ *
+ * @module state/adapter
+ * @since 3.0.0
+ */
+
+/**
+ * State store adapter implementation.
+ *
+ * Wraps a SimpleStateStore and implements CheckpointStore by:
+ * - Storing checkpoints with a prefix
+ * - Maintaining an index of all checkpoints
+ * - Providing list/query operations
+ *
+ * @example
+ * ```typescript
+ * const simpleStore = createInMemoryStore();
+ * const adapter = new StateStoreAdapter(simpleStore);
+ *
+ * await adapter.save({
+ *   id: 'cp1',
+ *   version: '1.0.0',
+ *   label: 'Start',
+ *   state: {},
+ *   outputs: {},
+ *   timestamp: new Date().toISOString()
+ * });
+ *
+ * const checkpoints = await adapter.list();
+ * console.log(checkpoints); // [{ id: 'cp1', ... }]
+ * ```
+ */
+declare class StateStoreAdapter implements CheckpointStore {
+    private store;
+    constructor(store: SimpleStateStore);
+    /**
+     * Save a checkpoint.
+     */
+    save(checkpoint: StateCheckpoint): Promise<void>;
+    /**
+     * Load a checkpoint by ID.
+     */
+    load(checkpointId: string): Promise<StateCheckpoint | undefined>;
+    /**
+     * List all available checkpoints.
+     * Returns checkpoints sorted by timestamp (oldest first).
+     */
+    list(): Promise<StateCheckpoint[]>;
+    /**
+     * Get the latest checkpoint (most recent).
+     */
+    getLatest(): Promise<StateCheckpoint | undefined>;
+    /**
+     * Delete a checkpoint by ID.
+     */
+    delete(checkpointId: string): Promise<void>;
+    /**
+     * Clear all checkpoints.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the storage key for a checkpoint.
+     */
+    private getCheckpointKey;
+    /**
+     * Load the checkpoint index.
+     */
+    private loadIndex;
+    /**
+     * Save the checkpoint index.
+     */
+    private saveIndex;
+    /**
+     * Update the index with a new checkpoint.
+     */
+    private updateIndex;
+    /**
+     * Remove a checkpoint from the index.
+     */
+    private removeFromIndex;
+}
+/**
+ * Create a CheckpointStore from a SimpleStateStore.
+ *
+ * @param store - The simple store to wrap
+ * @returns A CheckpointStore adapter
+ *
+ * @example
+ * ```typescript
+ * import { createInMemoryStore } from '@limo-labs/deity/helpers';
+ * import { createStateStoreAdapter } from '@limo-labs/deity/state';
+ *
+ * const simpleStore = createInMemoryStore();
+ * const checkpointStore = createStateStoreAdapter(simpleStore);
+ *
+ * // Use with state manager
+ * const stateManager = createStateManager({
+ *   directory: '.deity',
+ *   version: '1.0.0',
+ *   checkpointStore  // Uses the adapted store
+ * });
+ * ```
+ */
+declare function createStateStoreAdapter(store: SimpleStateStore): CheckpointStore;
+/**
+ * Type guard to check if a store is a SimpleStateStore.
+ */
+declare function isSimpleStateStore(store: unknown): store is SimpleStateStore;
+
+export { type CheckpointStore as C, FileSystemStateStore as F, InMemoryStateStore as I, type StateCheckpoint as S, createInMemoryStore as a, createStateStoreAdapter as b, createFileStore as c, type FileSystemStateStoreOptions as d, type InMemoryStateStoreOptions as e, type SimpleStateStore as f, type SimpleStateStoreWithClear as g, StateStoreAdapter as h, compareVersions as i, isCompatible as j, isSimpleStateStore as k, isValidVersion as l, parseVersion as p };