@vibesdotdev/storage 0.0.1 → 1.0.0-rc.3

package/src/interfaces/adapter.ts

@@ -1,451 +0,0 @@
-/**
- * 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
-
-/**
- * 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;
-}
-
-// PROTOCOLS & CAPABILITIES
-
-/**
- * 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 ADAPTER INTERFACE
-
-/**
- * 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;
-
-	// Document Store (single-doc storage)
-
-	/**
-	 * 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>;
-
-	// Key-Value Store (pair-schema storage)
-
-	/**
-	 * 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>;
-
-	// Repository (structured records - legacy pattern)
-
-	/**
-	 * 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>;
-
-	// Record (new descriptor-driven pattern)
-
-	/**
-	 * 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>;
-
-	// Browse (optional — adapters declaring `browse` capability implement these)
-
-	/**
-	 * 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[]>;
-
-	// Database Access
-
-	/**
-	 * 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;
-
-	// Lifecycle
-
-	/**
-	 * 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 STATUS
-
-/**
- * Health check result
- */
-export interface StorageHealthStatus {
-	healthy: boolean;
-	latencyMs?: number;
-	error?: string;
-	details?: Record<string, unknown>;
-}
-
-// ADAPTER DESCRIPTOR EXTENSION
-
-/**
- * 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 TYPES FOR COMMON ADAPTERS
-
-/**
- * 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;
-	};
-}

package/src/interfaces/document-store.ts

@@ -1,74 +0,0 @@
-/**
- * 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>;

package/src/interfaces/index.ts

@@ -1,117 +0,0 @@
-/**
- * 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 {
-	type StorageAdapterInterface,
-	type StorageAdapterCapabilities,
-	type StorageAdapterDescriptorFields,
-	type StorageProtocol,
-	type StorageHealthStatus,
-	type CloudSettingsClient,
-	// Config types
-	type FileBasedAdapterConfig,
-	type LocalDBAdapterConfig,
-	type JSONAdapterConfig,
-	type MemoryAdapterConfig,
-	type CloudDirectAdapterConfig,
-	type CloudAPIAdapterConfig,
-	type EncryptedAdapterConfig
-} from './adapter';
-
-// Document store interface
-export { type StorageDocumentStoreInterface, type DocumentStoreFactory } from './document-store';
-
-// Key-value interface
-export {
-	type StorageKeyValueInterface,
-	type KeyValueSetOptions,
-	type KeyValueStoreFactory
-} from './key-value';
-
-// Repository interface
-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';
-
-// Storage record interface (single table CRUD)
-export {
-	// Query types
-	type WhereFilter,
-	type OrderBy,
-	type IncludeRelations,
-	type PaginationOptions,
-	type QueryOptions,
-	type QueryResult,
-	// Create types
-	type CreateInput,
-	type CreateManyOptions,
-	// Update types
-	type UpdateInput,
-	type UpdateOptions,
-	type UpdateResult,
-	// Delete types
-	type DeleteOptions,
-	type DeleteResult,
-	// Relation types
-	type LoadedRelation,
-	type RecordWithRelations,
-	// Transaction types
-	type TransactionContext,
-	type TransactionFn,
-	// Aggregation types
-	type AggregationFunction,
-	type AggregationOptions,
-	type AggregationResult,
-	// Stream types
-	type StreamOptions,
-	// Main interface
-	type StorageRecordInterface
-} from './record';
-
-// Query-builder database interface (Drizzle-ORM-compatible)
-export { type QueryBuilderDatabase } from './query-builder';
-
-// Storage schema interface (multi-table schemas)
-export {
-	// Table interface
-	type StorageTableInterface,
-	// Main interface
-	type StorageSchemaInterface,
-	// Migration types
-	type MigrationStatus,
-	type MigrationOptions,
-	type MigrationResult,
-	// Backup types
-	type BackupOptions,
-	type BackupResult,
-	type RestoreOptions,
-	type RestoreResult,
-	// Sync types
-	type SyncStatus,
-	type SyncOptions,
-	type SyncResult,
-	// Query types
-	type CrossTableQueryOptions,
-	// Metadata types
-	type SchemaStatistics,
-	type SchemaHealthStatus
-} from './schema';