@dexto/storage 1.6.0 → 1.6.2

package/dist/index.d.cts

@@ -1,24 +1,503 @@
-export { StorageConfig, StorageSchema, ValidatedStorageConfig } from './schemas.cjs';
-export { CacheFactory } from './cache/factory.cjs';
-export { inMemoryCacheFactory } from './cache/factories/memory.cjs';
-export { redisCacheFactory } from './cache/factories/redis.cjs';
-export { CACHE_TYPES, CacheConfig, CacheConfigSchema, CacheType, InMemoryCacheConfig, RedisCacheConfig } from './cache/schemas.cjs';
-export { MemoryCacheStore } from './cache/memory-cache-store.cjs';
-export { RedisStore } from './cache/redis-store.cjs';
-export { DatabaseFactory } from './database/factory.cjs';
-export { inMemoryDatabaseFactory } from './database/factories/memory.cjs';
-export { sqliteDatabaseFactory } from './database/factories/sqlite.cjs';
-export { postgresDatabaseFactory } from './database/factories/postgres.cjs';
-export { DATABASE_TYPES, DatabaseConfig, DatabaseConfigSchema, DatabaseType, InMemoryDatabaseConfig, PostgresDatabaseConfig, SqliteDatabaseConfig } from './database/schemas.cjs';
-export { MemoryDatabaseStore } from './database/memory-database-store.cjs';
-export { SQLiteStore } from './database/sqlite-store.cjs';
-export { PostgresStore } from './database/postgres-store.cjs';
-export { BlobStoreFactory } from './blob/factory.cjs';
-export { localBlobStoreFactory } from './blob/factories/local.cjs';
-export { inMemoryBlobStoreFactory } from './blob/factories/memory.cjs';
-export { BLOB_STORE_TYPES, BlobStoreConfig, BlobStoreConfigSchema, BlobStoreType, InMemoryBlobStoreConfig, InMemoryBlobStoreConfigInput, InMemoryBlobStoreSchema, LocalBlobStoreConfig, LocalBlobStoreConfigInput, LocalBlobStoreSchema } from './blob/schemas.cjs';
-export { LocalBlobStore } from './blob/local-blob-store.cjs';
-export { MemoryBlobStore } from './blob/memory-blob-store.cjs';
-import 'zod';
-import '@dexto/core';
-import 'pg';
+import { InMemoryCacheConfig, RedisCacheConfig, InMemoryDatabaseConfig, SqliteDatabaseConfig, PostgresDatabaseConfig, LocalBlobStoreConfig, InMemoryBlobStoreConfig, InMemoryBlobStoreConfigInput } from './schemas.cjs';
+export { BLOB_STORE_TYPES, BlobStoreConfig, BlobStoreConfigSchema, BlobStoreType, CACHE_TYPES, CacheConfig, CacheConfigSchema, CacheType, DATABASE_TYPES, DatabaseConfig, DatabaseConfigSchema, DatabaseType, InMemoryBlobStoreSchema, LocalBlobStoreConfigInput, LocalBlobStoreSchema, StorageConfig, StorageSchema, ValidatedStorageConfig } from './schemas.cjs';
+import { Logger, Cache, Database, BlobStore, BlobInput, BlobMetadata, BlobReference, BlobData, BlobStats } from '@dexto/core';
+import { z } from 'zod';
+import { PoolClient } from 'pg';
+
+/**
+ * Factory interface for creating cache instances.
+ *
+ * Factories are plain exports (no global registries). Images decide which factories are
+ * available by including them in `image.storage.cache`.
+ */
+interface CacheFactory<TConfig = unknown> {
+    /**
+     * Zod schema for validating factory-specific configuration.
+     * The schema must output the `TConfig` type.
+     */
+    configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>;
+    /**
+     * Factory function to create a Cache instance.
+     *
+     * Cache factories may return a Promise to support lazy loading of optional
+     * dependencies (e.g., `ioredis`).
+     *
+     * @param config - Validated configuration specific to this backend
+     * @param logger - Logger instance for the cache
+     * @returns A Cache implementation (or Promise for async backends)
+     */
+    create(config: TConfig, logger: Logger): Cache | Promise<Cache>;
+    /**
+     * Optional metadata for documentation, UIs, and discovery.
+     */
+    metadata?: {
+        /** Human-readable name (e.g., "Redis", "Memcached") */
+        displayName: string;
+        /** Brief description of this cache backend */
+        description: string;
+        /** Whether this backend requires network connectivity */
+        requiresNetwork?: boolean;
+        /** Whether this backend supports TTL (time-to-live) */
+        supportsTTL?: boolean;
+    };
+}
+
+/**
+ * Factory for in-memory cache storage.
+ *
+ * This factory stores data in RAM and is ideal for development,
+ * testing, and ephemeral use cases where persistence is not required.
+ *
+ * Features:
+ * - Zero external dependencies
+ * - Fast in-memory operations
+ * - TTL support for automatic expiration
+ * - No network required
+ * - Data is lost on restart
+ */
+declare const inMemoryCacheFactory: CacheFactory<InMemoryCacheConfig>;
+
+/**
+ * Factory for Redis cache storage.
+ *
+ * This factory stores data in a Redis server using the ioredis package.
+ * It's ideal for production deployments requiring scalability, persistence,
+ * and multi-machine access.
+ *
+ * Features:
+ * - Native TTL support
+ * - Connection pooling
+ * - Pub/sub capabilities (via additional methods)
+ * - Suitable for distributed deployments
+ *
+ * Note: ioredis is an optional dependency. Install it with:
+ * npm install ioredis
+ */
+declare const redisCacheFactory: CacheFactory<RedisCacheConfig>;
+
+/**
+ * In-memory cache store for development and testing.
+ * Supports TTL for automatic cleanup of temporary data.
+ * Data is lost when the process restarts.
+ */
+declare class MemoryCacheStore implements Cache {
+    private data;
+    private ttls;
+    private connected;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    private checkConnection;
+    private checkTTL;
+    clear(): Promise<void>;
+    dump(): Promise<{
+        data: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * Redis cache store for production cache operations.
+ * Implements the Cache interface with connection pooling and optimizations.
+ * EXPERIMENTAL - NOT FULLY TESTED YET
+ */
+declare class RedisStore implements Cache {
+    private config;
+    private redis;
+    private connected;
+    private logger;
+    constructor(config: RedisCacheConfig, logger: Logger);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    mget<T>(keys: string[]): Promise<(T | undefined)[]>;
+    mset<T>(entries: [string, T][]): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    expire(key: string, ttlSeconds: number): Promise<void>;
+    increment(key: string, by?: number): Promise<number>;
+    decrement(key: string, by?: number): Promise<number>;
+    private checkConnection;
+    flushdb(): Promise<void>;
+    info(): Promise<string>;
+}
+
+/**
+ * Factory interface for creating database instances.
+ *
+ * Factories are plain exports (no global registries). Images decide which factories are
+ * available by including them in `image.storage.database`.
+ */
+interface DatabaseFactory<TConfig = unknown> {
+    /**
+     * Zod schema for validating factory-specific configuration.
+     * The schema must output the `TConfig` type.
+     */
+    configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>;
+    /**
+     * Factory function to create a Database instance.
+     *
+     * Database factories may return a Promise to support lazy loading of optional
+     * dependencies (e.g., `better-sqlite3`, `pg`).
+     *
+     * @param config - Validated configuration specific to this backend
+     * @param logger - Logger instance for the database
+     * @returns A Database implementation (or Promise for async backends)
+     */
+    create(config: TConfig, logger: Logger): Database | Promise<Database>;
+    /**
+     * Optional metadata for documentation, UIs, and discovery.
+     */
+    metadata?: {
+        /** Human-readable name (e.g., "SQLite", "PostgreSQL") */
+        displayName: string;
+        /** Brief description of this storage backend */
+        description: string;
+        /** Whether this backend requires network connectivity */
+        requiresNetwork?: boolean;
+        /** Whether this backend supports list operations (append/getRange) */
+        supportsListOperations?: boolean;
+    };
+}
+
+/**
+ * Factory for in-memory database storage.
+ *
+ * This factory stores data in RAM and is ideal for development,
+ * testing, and ephemeral use cases where persistence is not required.
+ *
+ * Features:
+ * - Zero external dependencies
+ * - Fast in-memory operations
+ * - No network required
+ * - Data is lost on restart
+ */
+declare const inMemoryDatabaseFactory: DatabaseFactory<InMemoryDatabaseConfig>;
+
+/**
+ * Factory for SQLite database storage.
+ *
+ * This factory stores data in a local SQLite database file using better-sqlite3.
+ * It's ideal for single-machine deployments and development scenarios where
+ * persistence is required without the overhead of a database server.
+ *
+ * Features:
+ * - Uses better-sqlite3 for synchronous, fast operations
+ * - WAL mode enabled for better concurrency
+ * - No external server required
+ * - Persistent storage survives restarts
+ *
+ * Note: better-sqlite3 is an optional dependency. Install it with:
+ * npm install better-sqlite3
+ */
+declare const sqliteDatabaseFactory: DatabaseFactory<SqliteDatabaseConfig>;
+
+/**
+ * Factory for PostgreSQL database storage.
+ *
+ * This factory stores data in a PostgreSQL database server using the pg package.
+ * It's ideal for production deployments requiring scalability and multi-machine access.
+ *
+ * Features:
+ * - Connection pooling for efficient resource usage
+ * - JSONB storage for flexible data types
+ * - Transaction support
+ * - Suitable for distributed deployments
+ *
+ * Note: pg is an optional dependency. Install it with:
+ * npm install pg
+ */
+declare const postgresDatabaseFactory: DatabaseFactory<PostgresDatabaseConfig>;
+
+/**
+ * In-memory database store for development and testing.
+ * Supports list operations for message history and enumeration for settings.
+ * Data is lost when the process restarts.
+ */
+declare class MemoryDatabaseStore implements Database {
+    private data;
+    private lists;
+    private connected;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    append<T>(key: string, item: T): Promise<void>;
+    getRange<T>(key: string, start: number, count: number): Promise<T[]>;
+    private checkConnection;
+    clear(): Promise<void>;
+    dump(): Promise<{
+        data: Record<string, unknown>;
+        lists: Record<string, unknown[]>;
+    }>;
+}
+
+/**
+ * SQLite database store for local development and production.
+ * Implements the Database interface with proper schema and connection handling.
+ */
+declare class SQLiteStore implements Database {
+    private db;
+    private dbPath;
+    private config;
+    private logger;
+    constructor(config: SqliteDatabaseConfig, logger: Logger);
+    private initializeTables;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    append<T>(key: string, item: T): Promise<void>;
+    getRange<T>(key: string, start: number, count: number): Promise<T[]>;
+    private checkConnection;
+    vacuum(): Promise<void>;
+    getStats(): Promise<{
+        kvCount: number;
+        listCount: number;
+        dbSize: number;
+    }>;
+}
+
+/**
+ * PostgreSQL database store for production database operations.
+ * Implements the Database interface with connection pooling and JSONB support.
+ * EXPERIMENTAL - NOT FULLY TESTED YET
+ */
+declare class PostgresStore implements Database {
+    private config;
+    private pool;
+    private connected;
+    private logger;
+    constructor(config: PostgresDatabaseConfig, logger: Logger);
+    connect(): Promise<void>;
+    /**
+     * Creates a PostgreSQL schema if it doesn't exist.
+     */
+    private createSchema;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    append<T>(key: string, item: T): Promise<void>;
+    getRange<T>(key: string, start: number, count: number): Promise<T[]>;
+    private createTables;
+    private checkConnection;
+    /**
+     * Check if an error is a connection error that should trigger a retry.
+     * Common with serverless databases (Neon) where connections go stale.
+     */
+    private isConnectionError;
+    /**
+     * Execute a database operation with automatic retry on connection errors.
+     * Handles serverless DB connection issues (Neon cold starts, stale connections).
+     */
+    private withRetry;
+    /**
+     * Execute a callback within a database transaction.
+     * Note: On connection failure, the entire callback will be retried on a new connection.
+     * Ensure callback operations are idempotent or use this only for read operations.
+     */
+    transaction<T>(callback: (client: PoolClient) => Promise<T>): Promise<T>;
+    getStats(): Promise<{
+        kvCount: number;
+        listCount: number;
+        totalSize: string;
+    }>;
+    vacuum(): Promise<void>;
+}
+
+/**
+ * Factory interface for creating blob store instances.
+ *
+ * Factories are plain exports (no global registries). Images decide which factories are
+ * available by including them in `image.storage.blob`.
+ */
+interface BlobStoreFactory<TConfig = unknown> {
+    /**
+     * Zod schema for validating factory-specific configuration.
+     * The schema must output the `TConfig` type.
+     */
+    configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>;
+    /**
+     * Factory function to create a BlobStore instance.
+     * @param config - Validated configuration specific to this backend
+     * @param logger - Logger instance for the blob store
+     * @returns A BlobStore implementation
+     */
+    create(config: TConfig, logger: Logger): BlobStore | Promise<BlobStore>;
+    /**
+     * Optional metadata for documentation, UIs, and discovery.
+     */
+    metadata?: {
+        /** Human-readable name (e.g., "Local Filesystem", "Amazon S3") */
+        displayName: string;
+        /** Brief description of this storage backend */
+        description: string;
+        /** Whether this backend requires network connectivity */
+        requiresNetwork?: boolean;
+    };
+}
+
+/**
+ * Factory for local filesystem blob storage.
+ *
+ * This factory stores blobs on the local filesystem with content-based
+ * deduplication and metadata tracking. It's ideal for development and
+ * single-machine deployments.
+ *
+ * Features:
+ * - Zero external dependencies (uses Node.js fs module)
+ * - Content-based deduplication (same hash = same blob)
+ * - Automatic cleanup of old blobs
+ * - No network required
+ */
+declare const localBlobStoreFactory: BlobStoreFactory<LocalBlobStoreConfig>;
+
+/**
+ * Factory for in-memory blob storage.
+ *
+ * This factory stores blobs in RAM, making it ideal for testing and
+ * development. All data is lost when the process exits.
+ *
+ * Features:
+ * - Zero dependencies
+ * - Extremely fast (no I/O)
+ * - Configurable size limits
+ * - No network required
+ * - Perfect for unit tests
+ */
+declare const inMemoryBlobStoreFactory: BlobStoreFactory<InMemoryBlobStoreConfig>;
+
+/**
+ * Local filesystem blob store implementation.
+ *
+ * Stores blobs on the local filesystem with content-based deduplication
+ * and metadata tracking. This is the default store for development
+ * and single-machine deployments.
+ */
+declare class LocalBlobStore implements BlobStore {
+    private config;
+    private storePath;
+    private connected;
+    private statsCache;
+    private statsCachePromise;
+    private lastStatsRefresh;
+    private logger;
+    private static readonly STATS_REFRESH_INTERVAL_MS;
+    constructor(config: LocalBlobStoreConfig, logger: Logger);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    store(input: BlobInput, metadata?: BlobMetadata): Promise<BlobReference>;
+    retrieve(reference: string, format?: 'base64' | 'buffer' | 'path' | 'stream' | 'url'): Promise<BlobData>;
+    exists(reference: string): Promise<boolean>;
+    delete(reference: string): Promise<void>;
+    cleanup(olderThan?: Date): Promise<number>;
+    getStats(): Promise<BlobStats>;
+    getStoragePath(): string | undefined;
+    listBlobs(): Promise<BlobReference[]>;
+    private ensureStatsCache;
+    private refreshStatsCache;
+    private updateStatsCacheAfterStore;
+    private updateStatsCacheAfterDelete;
+    /**
+     * Convert various input types to Buffer
+     */
+    private inputToBuffer;
+    /**
+     * Parse blob reference to extract ID
+     */
+    private parseReference;
+    /**
+     * Detect MIME type from buffer content and/or filename
+     */
+    private detectMimeType;
+    /**
+     * Check if buffer contains text content
+     */
+    private isTextBuffer;
+}
+
+/**
+ * In-memory blob store implementation.
+ *
+ * Stores blobs in memory with content-based deduplication and size limits.
+ * Suitable for development, testing, and scenarios where blob persistence
+ * across restarts is not required.
+ *
+ * Features:
+ * - Content-based deduplication (same as LocalBlobStore)
+ * - Configurable size limits (per-blob and total)
+ * - Automatic cleanup of old blobs
+ * - MIME type detection
+ * - Multi-format retrieval (base64, buffer, stream, data URI)
+ *
+ * Limitations:
+ * - Data lost on restart (no persistence)
+ * - Path format not supported (no filesystem)
+ * - Memory usage proportional to blob size
+ */
+type MemoryBlobStoreOptions = Omit<InMemoryBlobStoreConfigInput, 'type'>;
+declare class MemoryBlobStore implements BlobStore {
+    private config;
+    private blobs;
+    private connected;
+    private logger;
+    constructor(options: MemoryBlobStoreOptions, logger: Logger);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    store(input: BlobInput, metadata?: BlobMetadata): Promise<BlobReference>;
+    retrieve(reference: string, format?: 'base64' | 'buffer' | 'path' | 'stream' | 'url'): Promise<BlobData>;
+    exists(reference: string): Promise<boolean>;
+    delete(reference: string): Promise<void>;
+    cleanup(olderThan?: Date): Promise<number>;
+    getStats(): Promise<BlobStats>;
+    listBlobs(): Promise<BlobReference[]>;
+    getStoragePath(): string | undefined;
+    /**
+     * Calculate total size of all blobs in memory
+     */
+    private getTotalSize;
+    /**
+     * Convert various input types to Buffer.
+     * Copied from LocalBlobStore with minor adaptations.
+     */
+    private inputToBuffer;
+    /**
+     * Parse blob reference to extract ID.
+     * Copied from LocalBlobStore.
+     */
+    private parseReference;
+    /**
+     * Detect MIME type from buffer content and/or filename.
+     * Copied from LocalBlobStore.
+     */
+    private detectMimeType;
+    /**
+     * Check if buffer contains text content.
+     * Copied from LocalBlobStore.
+     */
+    private isTextBuffer;
+}
+
+export { type BlobStoreFactory, type CacheFactory, type DatabaseFactory, InMemoryBlobStoreConfig, InMemoryBlobStoreConfigInput, InMemoryCacheConfig, InMemoryDatabaseConfig, LocalBlobStore, LocalBlobStoreConfig, MemoryBlobStore, MemoryCacheStore, MemoryDatabaseStore, PostgresDatabaseConfig, PostgresStore, RedisCacheConfig, RedisStore, SQLiteStore, SqliteDatabaseConfig, inMemoryBlobStoreFactory, inMemoryCacheFactory, inMemoryDatabaseFactory, localBlobStoreFactory, postgresDatabaseFactory, redisCacheFactory, sqliteDatabaseFactory };