@vibesdotdev/storage 0.0.1

package/dist/interfaces/adapter.d.ts

@@ -0,0 +1,382 @@
+/**
+ * Storage Adapter Interface
+ *
+ * Main interface for storage adapters. Adapters provide access to
+ * document stores, key-value stores, repositories, and records.
+ *
+ * Each adapter can specify its own config type and declare which
+ * storage protocols and features it supports.
+ */
+import type { z } from 'zod/v4';
+import type { StorageDocumentStoreInterface } from './document-store';
+import type { StorageKeyValueInterface } from './key-value';
+import type { StorageRepositoryInterface, RepositoryOptions } from './repository';
+import type { StorageRecordInterface } from './record';
+import type { StorageRecordDescriptor } from '../schemas/record';
+import type { StorageCapability, StorageDrive, StorageEntry } from '../schemas/adapter-descriptor';
+/**
+ * Universal SQL database handle interface.
+ *
+ * Abstracts the underlying SQL driver (bun:sqlite, better-sqlite3, postgres, etc.)
+ * to keep storage core universal (no Node/Bun/SQL imports in core).
+ *
+ * Exposes only the surface area that storage core actually uses.
+ */
+export interface SqlDatabaseHandle {
+    exec(sql: string): void;
+    query<T, P extends any[] = unknown[]>(sql: string): SqlStatement<T, P>;
+}
+/**
+ * Prepared SQL statement returned by SqlDatabaseHandle.query()
+ */
+export interface SqlStatement<T, P extends any[] = unknown[]> {
+    all(...params: P): T[];
+    get(...params: P): T | undefined;
+    run(...params: P): void;
+}
+/**
+ * Storage protocols supported by adapters
+ */
+export type StorageProtocol = 'document' | 'keyvalue' | 'repository' | 'record';
+/**
+ * Storage adapter capabilities
+ */
+export interface StorageAdapterCapabilities {
+    /** Supported protocols */
+    protocols: StorageProtocol[];
+    /**
+     * Coarse-grained capability flags mirroring the descriptor's
+     * `capabilities[]`. `browse` indicates `list(driveId, path)` +
+     * `listDrives()` are implemented.
+     */
+    capabilities?: StorageCapability[];
+    /** Whether adapter requires pair schema (key + value) for main storage */
+    requiresPairSchema: boolean;
+    /** Whether adapter supports transactions */
+    supportsTransactions: boolean;
+    /** Whether adapter supports TTL (for caches) */
+    supportsTTL: boolean;
+    /** Whether adapter supports full-text search */
+    supportsFTS: boolean;
+    /** Whether adapter is persistent (survives restarts) */
+    persistent: boolean;
+    /** Whether adapter supports change subscriptions */
+    supportsSubscription: boolean;
+    /** Whether adapter supports hierarchical/recursive queries */
+    supportsHierarchy: boolean;
+    /** Whether adapter supports computed fields (aggregations) */
+    supportsComputedFields: boolean;
+    /** Whether adapter supports cross-table side effects */
+    supportsSideEffects: boolean;
+    /** Whether adapter supports raw SQL queries */
+    supportsRawQueries: boolean;
+}
+/**
+ * Main storage adapter interface
+ *
+ * @typeParam TConfig - Adapter-specific configuration type
+ *
+ * @example
+ * ```ts
+ * // LocalDB adapter (consumer hardware)
+ * interface LocalDBConfig {
+ *   basePath: string;
+ *   dbName?: string;
+ * }
+ *
+ * class LocalDBAdapter implements StorageAdapterInterface<LocalDBConfig> {
+ *   configure(config: LocalDBConfig) { ... }
+ *   documentStore(namespace, schema) { ... }
+ *   repository(tableName, schema) { ... }
+ *   record(descriptor) { ... }
+ * }
+ * ```
+ */
+export interface StorageAdapterInterface<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Unique adapter identifier
+     */
+    readonly id: string;
+    /**
+     * Adapter capabilities
+     */
+    readonly capabilities: StorageAdapterCapabilities;
+    /**
+     * Configure the adapter with adapter-specific options
+     * @param config Adapter-specific configuration
+     */
+    configure(config: TConfig): void;
+    /**
+     * Check if adapter is configured and ready
+     */
+    isConfigured(): boolean;
+    /**
+     * Get a document store for a namespace
+     *
+     * @param namespace Storage namespace (e.g., 'ai.config')
+     * @param schema Zod schema for validation
+     * @param manifest Storage manifest descriptor (contains adapter-specific config)
+     * @returns Document store interface
+     * @throws If adapter doesn't support document protocol
+     *
+     * @example
+     * ```ts
+     * const store = adapter.documentStore('ai.config', aiConfigSchema, manifest);
+     * const config = await store.load();
+     * ```
+     */
+    documentStore<T>(namespace: string, schema: z.ZodType<T>, manifest?: unknown): StorageDocumentStoreInterface<T>;
+    /**
+     * Get a key-value store for a namespace
+     *
+     * @param namespace Storage namespace (e.g., 'cache')
+     * @param keySchema Zod schema for keys
+     * @param valueSchema Zod schema for values
+     * @returns Key-value store interface
+     * @throws If adapter doesn't support keyvalue protocol
+     *
+     * @example
+     * ```ts
+     * const kv = adapter.keyValueStore('cache', z.string(), userSchema);
+     * await kv.set('user:123', userData);
+     * ```
+     */
+    keyValueStore<TKey, TValue>(namespace: string, keySchema: z.ZodType<TKey>, valueSchema: z.ZodType<TValue>): StorageKeyValueInterface<TKey, TValue>;
+    /**
+     * Get a repository for a table/collection
+     *
+     * @param tableName Table or collection name
+     * @param schema Zod schema for records
+     * @param options Repository options
+     * @returns Repository interface
+     * @throws If adapter doesn't support repository protocol
+     *
+     * @example
+     * ```ts
+     * const repo = adapter.repository('providers', providerSchema);
+     * const providers = await repo.list({ limit: 10 });
+     * ```
+     */
+    repository<T>(tableName: string, schema: z.ZodType<T>, options?: RepositoryOptions): StorageRepositoryInterface<T>;
+    /**
+     * Get a storage record interface for CRUD operations on a single table.
+     *
+     * This is the new pattern for storage that uses descriptors to define
+     * schema, relations, indexes, and advanced features.
+     *
+     * @param descriptor - Storage record descriptor
+     * @returns Storage record interface with CRUD and advanced operations
+     *
+     * @example
+     * ```typescript
+     * const todos = adapter.record(todoDescriptor);
+     * await todos.initialize();
+     *
+     * // Basic CRUD
+     * await todos.create({ sessionId: '...', title: '...' });
+     * const allTodos = await todos.list({ where: { sessionId: '...' }});
+     *
+     * // FTS (if adapter supports it)
+     * const results = await todos.search('implement feature');
+     *
+     * // Hierarchy (if adapter supports it)
+     * const tree = await todos.getTree({ where: { sessionId: '...' }});
+     * ```
+     */
+    record<T = unknown>(descriptor: StorageRecordDescriptor): StorageRecordInterface<T>;
+    /**
+     * Enumerate the top-level "drives" exposed by this adapter.
+     *
+     * A drive is the unit of selection before drilling into folders —
+     * for SharePoint, a site; for OneDrive, the user's default drive; etc.
+     *
+     * Only adapters that declare the `browse` capability in their
+     * descriptor are required to implement this method. Adapters that
+     * don't browse omit it.
+     *
+     * @returns Promise resolving to all drives the current credential can see.
+     */
+    listDrives?(): Promise<StorageDrive[]>;
+    /**
+     * Enumerate files + directories inside a drive at the given path.
+     *
+     * Only adapters that declare the `browse` capability are required to
+     * implement this method. Adapters that don't browse omit it.
+     *
+     * @param driveId - Drive identifier from `listDrives()`.
+     * @param path - Path relative to the drive root. Use `''` (or omit
+     *   when calling with two args) for the drive's top level. Segments
+     *   joined with `/`.
+     * @returns Promise resolving to the entries at that path.
+     */
+    list?(driveId: string, path?: string): Promise<StorageEntry[]>;
+    /**
+     * Ensure adapter is fully initialized and database is ready for use.
+     * Unlike initialize(), this also creates the database connection on first access.
+     * Called by StorageRecord before accessing the database.
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Get the underlying database connection.
+     * Must call ensureReady() first.
+     *
+     * @returns The raw database connection (e.g., bun:sqlite Database)
+     * @throws If database is not initialized
+     */
+    getDatabaseConnection(): unknown;
+    /**
+     * Initialize the adapter (create tables, connect, etc.)
+     * Called automatically on first use if not called explicitly.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Close connections and clean up
+     */
+    close(): Promise<void>;
+    /**
+     * Check adapter health
+     */
+    healthCheck(): Promise<StorageHealthStatus>;
+}
+/**
+ * Health check result
+ */
+export interface StorageHealthStatus {
+    healthy: boolean;
+    latencyMs?: number;
+    error?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Extended adapter descriptor for storage adapters
+ * Adds storage-specific fields to the base AdapterDescriptor
+ */
+export interface StorageAdapterDescriptorFields {
+    /** Storage protocols supported */
+    protocols: StorageProtocol[];
+    /** Whether adapter requires pair schema */
+    requiresPairSchema: boolean;
+    /** Additional capability flags */
+    supportsTransactions?: boolean;
+    supportsTTL?: boolean;
+    supportsFTS?: boolean;
+    persistent?: boolean;
+    supportsHierarchy?: boolean;
+    supportsComputedFields?: boolean;
+    supportsSideEffects?: boolean;
+    supportsRawQueries?: boolean;
+}
+/**
+ * Config for file-based adapters (JSON, SQLite)
+ */
+export interface FileBasedAdapterConfig {
+    /** Base path for storage files */
+    basePath: string;
+    /** Index signature for Record<string, unknown> compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Config for LocalDB adapter (SQLite)
+ */
+export interface LocalDBAdapterConfig extends FileBasedAdapterConfig {
+    /** Database file name (default: 'vibes.db') */
+    dbName?: string;
+    /** Workspace root used for scope template resolution */
+    workspacePath?: string;
+    /** WAL mode (default: true) */
+    walMode?: boolean;
+    /** Whether to use custom tables instead of generic vibes_* tables */
+    customTables?: boolean;
+    /** Migration key for custom tables (required if customTables = true) */
+    migrationKey?: string;
+    /** Custom table name for single-table manifests */
+    tableName?: string;
+    /** Manifest ID this config is associated with */
+    manifestId?: string;
+    /** Namespace of the manifest */
+    namespace?: string;
+}
+/**
+ * Config for JSON adapter
+ */
+export interface JSONAdapterConfig extends FileBasedAdapterConfig {
+    /** Optional filename override for document manifests */
+    filename?: string;
+    /** Pretty print JSON (default: false in prod) */
+    prettyPrint?: boolean;
+}
+/**
+ * Config for Memory adapter
+ */
+export interface MemoryAdapterConfig {
+    /** Maximum items per namespace (for cache eviction) */
+    maxItems?: number;
+    /** Default TTL in milliseconds */
+    defaultTTL?: number;
+    /** Index signature for Record<string, unknown> compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Config for Cloud Direct adapter (running ON cloud)
+ */
+export interface CloudDirectAdapterConfig {
+    /** Database connection string */
+    connectionString: string;
+    /** Database schema (for Postgres) */
+    schema?: string;
+    /** Connection pool size */
+    poolSize?: number;
+}
+/**
+ * Config for Cloud API adapter (consumer → cloud bridge)
+ */
+export interface CloudAPIAdapterConfig {
+    /** API endpoint URL (full origin, e.g. `https://ai.vibes.dev`). Optional
+     * when `ownerApp` is set — the adapter then resolves the origin from
+     * `config/environment.apps[ownerApp]` at init time. */
+    apiEndpoint?: string;
+    /** Owning app id (e.g. `'ai'`, `'tools'`, `'platform'`). When set, the
+     * adapter looks up `config/environment.apps[ownerApp]` to determine
+     * the base origin for requests. Lets storage manifests declare which
+     * cloud worker hosts their data without hardcoding origins per
+     * environment. Pairs with the runtime's `config/environment` kind so
+     * the same descriptor works in local / staging / production. */
+    ownerApp?: string;
+    /** API authentication token */
+    apiToken?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Index signature for Record<string, unknown> compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Cloud settings client interface for API-based storage.
+ * Generic methods allow type-safe storage operations.
+ */
+export interface CloudSettingsClient {
+    /** Get settings from cloud */
+    get<T>(namespace: string): Promise<T | null>;
+    /** Set settings in cloud */
+    set<T>(namespace: string, data: T): Promise<void>;
+    /** Reconcile a records collection against its canonical CRUD endpoint */
+    reconcile<T extends Record<string, unknown>>(namespace: string, data: T): Promise<void>;
+    /** Perform a raw request against a configured cloud endpoint */
+    request<T>(path: string, options?: RequestInit): Promise<T | null>;
+    /** Delete settings from cloud */
+    delete(namespace: string): Promise<void>;
+    /** Check if settings exist */
+    exists(namespace: string): Promise<boolean>;
+}
+/**
+ * Config for Encrypted adapter (decorator)
+ */
+export interface EncryptedAdapterConfig extends FileBasedAdapterConfig {
+    /** Encryption key (derived from user secret) */
+    encryptionKey?: string;
+    /** Key derivation parameters */
+    keyDerivation?: {
+        salt?: string;
+        iterations?: number;
+    };
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/interfaces/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/interfaces/adapter.ts"],"names":[],"mappings":"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"}

package/dist/interfaces/adapter.js

@@ -0,0 +1,11 @@
+/**
+ * Storage Adapter Interface
+ *
+ * Main interface for storage adapters. Adapters provide access to
+ * document stores, key-value stores, repositories, and records.
+ *
+ * Each adapter can specify its own config type and declare which
+ * storage protocols and features it supports.
+ */
+export {};
+//# sourceMappingURL=adapter.js.map

package/dist/interfaces/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/interfaces/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/interfaces/document-store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Storage Document Store Interface
+ *
+ * Simple document store for loading/saving single documents.
+ * Schema validation is handled by the adapter.
+ */
+import type { z } from 'zod/v4';
+/**
+ * Callback for change subscriptions
+ */
+export type DocumentChangeCallback<T> = (data: T | null) => void;
+/**
+ * Unsubscribe function returned by subscribe()
+ */
+export type Unsubscribe = () => void;
+/**
+ * Document store for single-document storage
+ *
+ * @example
+ * ```ts
+ * const store = adapter.documentStore('ai.config', aiConfigSchema);
+ * const config = await store.load();
+ * await store.save({ ...config, temperature: 0.7 });
+ * ```
+ */
+export interface StorageDocumentStoreInterface<T> {
+    /**
+     * Load the document
+     * @returns The document or null if not found
+     */
+    load(): Promise<T | null>;
+    /**
+     * Save the document
+     * @param data The document to save
+     */
+    save(data: T): Promise<void>;
+    /**
+     * Check if the document exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Delete the document
+     */
+    delete(): Promise<void>;
+    /**
+     * Get the storage path/location (for debugging)
+     */
+    getPath(): string;
+    /**
+     * Subscribe to changes to this document.
+     * Returns an unsubscribe function.
+     * Only supported if adapter capabilities include supportsSubscription.
+     * @param callback Function called when document changes
+     * @returns Unsubscribe function
+     */
+    subscribe?(callback: DocumentChangeCallback<T>): Unsubscribe;
+}
+/**
+ * Factory type for creating document stores
+ */
+export type DocumentStoreFactory<T> = (namespace: string, schema: z.ZodType<T>) => StorageDocumentStoreInterface<T>;
+//# sourceMappingURL=document-store.d.ts.map

package/dist/interfaces/document-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-store.d.ts","sourceRoot":"","sources":["../../src/interfaces/document-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,WAAW,6BAA6B,CAAC,CAAC;IAC/C;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAE1B;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAE3B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;OAEG;IACH,OAAO,IAAI,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAChB,6BAA6B,CAAC,CAAC,CAAC,CAAC"}

package/dist/interfaces/document-store.js

@@ -0,0 +1,8 @@
+/**
+ * Storage Document Store Interface
+ *
+ * Simple document store for loading/saving single documents.
+ * Schema validation is handled by the adapter.
+ */
+export {};
+//# sourceMappingURL=document-store.js.map

package/dist/interfaces/document-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-store.js","sourceRoot":"","sources":["../../src/interfaces/document-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/interfaces/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Storage Interfaces
+ *
+ * Core interfaces for the storage module:
+ * - StorageAdapterInterface: Main adapter with document, key-value, and repository support
+ * - StorageDocumentStoreInterface: Single-document storage
+ * - StorageKeyValueInterface: Key-value storage (pair schema)
+ * - StorageRepositoryInterface: Structured record storage with queries
+ */
+export { type StorageAdapterInterface, type StorageAdapterCapabilities, type StorageAdapterDescriptorFields, type StorageProtocol, type StorageHealthStatus, type CloudSettingsClient, type FileBasedAdapterConfig, type LocalDBAdapterConfig, type JSONAdapterConfig, type MemoryAdapterConfig, type CloudDirectAdapterConfig, type CloudAPIAdapterConfig, type EncryptedAdapterConfig } from './adapter';
+export { type StorageDocumentStoreInterface, type DocumentStoreFactory } from './document-store';
+export { type StorageKeyValueInterface, type KeyValueSetOptions, type KeyValueStoreFactory } from './key-value';
+export { type StorageRepositoryInterface, type RepositoryCreateInput, type RepositoryUpdateInput, type RepositoryQuery, type QueryCondition, type RepositoryListOptions, type RepositoryFindOptions, type RepositoryOrderBy, type RepositoryPage, type RepositoryMeta, type RepositoryFactory, type RepositoryOptions } from './repository';
+export { type WhereFilter, type OrderBy, type IncludeRelations, type PaginationOptions, type QueryOptions, type QueryResult, type CreateInput, type CreateManyOptions, type UpdateInput, type UpdateOptions, type UpdateResult, type DeleteOptions, type DeleteResult, type LoadedRelation, type RecordWithRelations, type TransactionContext, type TransactionFn, type AggregationFunction, type AggregationOptions, type AggregationResult, type StreamOptions, type StorageRecordInterface } from './record';
+export { type QueryBuilderDatabase } from './query-builder';
+export { type StorageTableInterface, type StorageSchemaInterface, type MigrationStatus, type MigrationOptions, type MigrationResult, type BackupOptions, type BackupResult, type RestoreOptions, type RestoreResult, type SyncStatus, type SyncOptions, type SyncResult, type CrossTableQueryOptions, type SchemaStatistics, type SchemaHealthStatus } from './schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/interfaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interfaces/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACN,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,8BAA8B,EACnC,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EAExB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,KAAK,6BAA6B,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGjG,OAAO,EACN,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACN,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAEN,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,WAAW,EAEhB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EAEtB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EAEjB,KAAK,aAAa,EAClB,KAAK,YAAY,EAEjB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EAExB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAElB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EAEtB,KAAK,aAAa,EAElB,KAAK,sBAAsB,EAC3B,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG5D,OAAO,EAEN,KAAK,qBAAqB,EAE1B,KAAK,sBAAsB,EAE3B,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAEpB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAElB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EAEf,KAAK,sBAAsB,EAE3B,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,MAAM,UAAU,CAAC"}

package/dist/interfaces/index.js

@@ -0,0 +1,24 @@
+/**
+ * Storage Interfaces
+ *
+ * Core interfaces for the storage module:
+ * - StorageAdapterInterface: Main adapter with document, key-value, and repository support
+ * - StorageDocumentStoreInterface: Single-document storage
+ * - StorageKeyValueInterface: Key-value storage (pair schema)
+ * - StorageRepositoryInterface: Structured record storage with queries
+ */
+// Main adapter interface
+export {} from './adapter.js';
+// Document store interface
+export {} from './document-store.js';
+// Key-value interface
+export {} from './key-value.js';
+// Repository interface
+export {} from './repository.js';
+// Storage record interface (single table CRUD)
+export {} from './record';
+// Query-builder database interface (Drizzle-ORM-compatible)
+export {} from './query-builder.js';
+// Storage schema interface (multi-table schemas)
+export {} from './schema';
+//# sourceMappingURL=index.js.map

package/dist/interfaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/interfaces/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,yBAAyB;AACzB,OAAO,EAeN,MAAM,WAAW,CAAC;AAEnB,2BAA2B;AAC3B,OAAO,EAAiE,MAAM,kBAAkB,CAAC;AAEjG,sBAAsB;AACtB,OAAO,EAIN,MAAM,aAAa,CAAC;AAErB,uBAAuB;AACvB,OAAO,EAaN,MAAM,cAAc,CAAC;AAEtB,+CAA+C;AAC/C,OAAO,EAgCN,MAAM,UAAU,CAAC;AAElB,4DAA4D;AAC5D,OAAO,EAA6B,MAAM,iBAAiB,CAAC;AAE5D,iDAAiD;AACjD,OAAO,EAuBN,MAAM,UAAU,CAAC"}

package/dist/interfaces/key-value.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Storage Key-Value Interface
+ *
+ * Key-value store for adapters that require pair schemas (key + value).
+ * Examples: Redis, KV stores, caches.
+ */
+import type { z } from 'zod/v4';
+/**
+ * Key-value store for pair-schema storage
+ *
+ * @example
+ * ```ts
+ * const kv = adapter.keyValueStore('cache', keySchema, valueSchema);
+ * await kv.set('user:123', { name: 'Alice' });
+ * const user = await kv.get('user:123');
+ * ```
+ */
+export interface StorageKeyValueInterface<TKey, TValue> {
+    /**
+     * Get a value by key
+     * @param key The key to look up
+     * @returns The value or null if not found
+     */
+    get(key: TKey): Promise<TValue | null>;
+    /**
+     * Set a value for a key
+     * @param key The key
+     * @param value The value to store
+     * @param options Optional TTL and other settings
+     */
+    set(key: TKey, value: TValue, options?: KeyValueSetOptions): Promise<void>;
+    /**
+     * Delete a key
+     * @param key The key to delete
+     * @returns true if deleted, false if not found
+     */
+    delete(key: TKey): Promise<boolean>;
+    /**
+     * Check if a key exists
+     * @param key The key to check
+     */
+    has(key: TKey): Promise<boolean>;
+    /**
+     * Get multiple values by keys
+     * @param keys The keys to look up
+     * @returns Map of key to value (missing keys omitted)
+     */
+    getMany(keys: TKey[]): Promise<Map<TKey, TValue>>;
+    /**
+     * Set multiple key-value pairs
+     * @param entries The entries to set
+     */
+    setMany(entries: Array<[TKey, TValue]>): Promise<void>;
+    /**
+     * Delete multiple keys
+     * @param keys The keys to delete
+     * @returns Number of keys deleted
+     */
+    deleteMany(keys: TKey[]): Promise<number>;
+    /**
+     * Iterate over all keys
+     * @param pattern Optional pattern to filter keys (adapter-specific)
+     */
+    keys(pattern?: string): AsyncIterable<TKey>;
+    /**
+     * Iterate over all entries
+     * @param pattern Optional pattern to filter keys (adapter-specific)
+     */
+    entries(pattern?: string): AsyncIterable<[TKey, TValue]>;
+    /**
+     * Count keys
+     * @param pattern Optional pattern to filter keys
+     */
+    count(pattern?: string): Promise<number>;
+    /**
+     * Clear all entries in this namespace
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Options for set operations
+ */
+export interface KeyValueSetOptions {
+    /** Time-to-live in milliseconds (for caches) */
+    ttl?: number;
+    /** Only set if key doesn't exist */
+    nx?: boolean;
+    /** Only set if key exists */
+    xx?: boolean;
+}
+/**
+ * Factory type for creating key-value stores
+ */
+export type KeyValueStoreFactory<TKey, TValue> = (namespace: string, keySchema: z.ZodType<TKey>, valueSchema: z.ZodType<TValue>) => StorageKeyValueInterface<TKey, TValue>;
+//# sourceMappingURL=key-value.d.ts.map

package/dist/interfaces/key-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-value.d.ts","sourceRoot":"","sources":["../../src/interfaces/key-value.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB,CAAC,IAAI,EAAE,MAAM;IACrD;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEvC;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3E;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpC;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjC;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAElD;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1C;;;OAGG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAE5C;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAEzD;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,6BAA6B;IAC7B,EAAE,CAAC,EAAE,OAAO,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,IAAI,EAAE,MAAM,IAAI,CAChD,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAC1B,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,KAC1B,wBAAwB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC"}

package/dist/interfaces/key-value.js

@@ -0,0 +1,8 @@
+/**
+ * Storage Key-Value Interface
+ *
+ * Key-value store for adapters that require pair schemas (key + value).
+ * Examples: Redis, KV stores, caches.
+ */
+export {};
+//# sourceMappingURL=key-value.js.map

package/dist/interfaces/key-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-value.js","sourceRoot":"","sources":["../../src/interfaces/key-value.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}