@vibesdotdev/storage 0.0.1

package/src/interfaces/schema/schema-interface.ts

@@ -0,0 +1,586 @@
+/**
+ * Storage Schema Interface
+ *
+ * Defines the interface for multi-table schemas with relations.
+ * This is what gets resolved when you query for a storage/schema descriptor.
+ *
+ * @example
+ * ```typescript
+ * const schema = await runtime
+ *   .query('storage/schema')
+ *   .withId('session')
+ *   .resolve();
+ *
+ * // Access individual tables
+ * const sessions = schema.table('sessions');
+ * const todos = schema.table('todos');
+ *
+ * // Cross-table operations
+ * const sessionWithTodos = await schema.getTransaction(async (tx) => {
+ *   const session = await sessions.create({ ... });
+ *   await todos.create({ sessionId: session.id, title: 'First todo' });
+ *   return session;
+ * });
+ *
+ * // Schema-level operations
+ * await schema.migrate();
+ * await schema.backup();
+ * ```
+ */
+
+import type { z } from 'zod/v4';
+import type { StorageRelation } from '../../schemas/record';
+import type { StorageTableDefinition } from '../../schemas/schema';
+import type { StorageTableInterface } from './table-interface';
+import type { TransactionFn, TransactionContext } from '../record';
+
+// MIGRATION TYPES
+
+/**
+ * Migration status
+ */
+export interface MigrationStatus {
+	/** Current schema version */
+	currentVersion: number;
+	/** Latest available version */
+	latestVersion: number;
+	/** Whether migrations are pending */
+	pending: boolean;
+	/** List of applied migrations */
+	applied: Array<{
+		version: number;
+		name?: string;
+		appliedAt: Date;
+	}>;
+	/** List of pending migrations */
+	pendingMigrations: Array<{
+		version: number;
+		name?: string;
+	}>;
+}
+
+/**
+ * Migration options
+ */
+export interface MigrationOptions {
+	/** Target version (default: latest) */
+	targetVersion?: number;
+	/** Dry run (don't actually apply migrations) */
+	dryRun?: boolean;
+	/** Skip migrations that fail */
+	skipFailures?: boolean;
+	/** Force apply even if already applied */
+	force?: boolean;
+}
+
+/**
+ * Migration result
+ */
+export interface MigrationResult {
+	/** Whether migration was successful */
+	success: boolean;
+	/** Applied migrations */
+	applied: Array<{
+		version: number;
+		name?: string;
+		duration: number;
+	}>;
+	/** Failed migrations */
+	failed: Array<{
+		version: number;
+		name?: string;
+		error: Error;
+	}>;
+	/** Total duration */
+	duration: number;
+}
+
+// BACKUP TYPES
+
+/**
+ * Backup options
+ */
+export interface BackupOptions {
+	/** Backup name/identifier */
+	name?: string;
+	/** Tables to include (default: all) */
+	tables?: string[];
+	/** Tables to exclude */
+	excludeTables?: string[];
+	/** Include schema definition */
+	includeSchema?: boolean;
+	/** Compression algorithm */
+	compression?: 'none' | 'gzip' | 'brotli';
+	/** Output path */
+	path?: string;
+}
+
+/**
+ * Backup result
+ */
+export interface BackupResult {
+	/** Backup ID */
+	id: string;
+	/** Backup name */
+	name: string;
+	/** Backup path */
+	path: string;
+	/** Backup size in bytes */
+	size: number;
+	/** Tables included */
+	tables: string[];
+	/** Backup timestamp */
+	createdAt: Date;
+	/** Checksum for verification */
+	checksum: string;
+}
+
+/**
+ * Restore options
+ */
+export interface RestoreOptions {
+	/** Backup ID or path */
+	backup: string;
+	/** Tables to restore (default: all in backup) */
+	tables?: string[];
+	/** Drop existing tables before restore */
+	dropExisting?: boolean;
+	/** Verify checksum before restore */
+	verifyChecksum?: boolean;
+	/** Continue on errors */
+	continueOnError?: boolean;
+}
+
+/**
+ * Restore result
+ */
+export interface RestoreResult {
+	/** Whether restore was successful */
+	success: boolean;
+	/** Restored tables */
+	tables: string[];
+	/** Number of records restored per table */
+	recordCounts: Record<string, number>;
+	/** Errors encountered */
+	errors: Array<{ table: string; error: Error }>;
+	/** Duration in milliseconds */
+	duration: number;
+}
+
+// SYNC TYPES
+
+/**
+ * Sync status
+ */
+export interface SyncStatus {
+	/** Whether sync is enabled */
+	enabled: boolean;
+	/** Last sync time */
+	lastSync?: Date;
+	/** Sync direction */
+	direction: 'bidirectional' | 'to-cloud' | 'from-cloud';
+	/** Whether sync is in progress */
+	inProgress: boolean;
+	/** Number of pending changes */
+	pendingChanges: number;
+	/** Sync errors */
+	errors: Array<{ table: string; error: Error; timestamp: Date }>;
+}
+
+/**
+ * Sync options
+ */
+export interface SyncOptions {
+	/** Force sync even if already in progress */
+	force?: boolean;
+	/** Tables to sync (default: all) */
+	tables?: string[];
+	/** Direction override */
+	direction?: 'bidirectional' | 'to-cloud' | 'from-cloud';
+	/** Dry run (don't actually sync) */
+	dryRun?: boolean;
+}
+
+/**
+ * Sync result
+ */
+export interface SyncResult {
+	/** Whether sync was successful */
+	success: boolean;
+	/** Number of changes pushed */
+	pushed: number;
+	/** Number of changes pulled */
+	pulled: number;
+	/** Conflicts detected */
+	conflicts: Array<{
+		table: string;
+		id: string;
+		local: unknown;
+		remote: unknown;
+	}>;
+	/** Duration in milliseconds */
+	duration: number;
+}
+
+// QUERY TYPES
+
+/**
+ * Cross-table query options
+ */
+export interface CrossTableQueryOptions {
+	/** Tables to include */
+	tables: string[];
+	/** Join conditions */
+	joins: Array<{
+		from: { table: string; field: string };
+		to: { table: string; field: string };
+		type?: 'inner' | 'left' | 'right' | 'full';
+	}>;
+	/** Filter conditions */
+	where?: Record<string, unknown>;
+	/** Order by */
+	orderBy?: Array<{ table: string; field: string; direction: 'asc' | 'desc' }>;
+	/** Limit */
+	limit?: number;
+	/** Offset */
+	offset?: number;
+}
+
+// SCHEMA METADATA
+
+/**
+ * Schema statistics
+ */
+export interface SchemaStatistics {
+	/** Table statistics */
+	tables: Record<
+		string,
+		{
+			/** Number of records */
+			recordCount: number;
+			/** Table size in bytes */
+			size: number;
+			/** Index size in bytes */
+			indexSize: number;
+			/** Last modified */
+			lastModified?: Date;
+		}
+	>;
+	/** Total database size */
+	totalSize: number;
+	/** Database file path */
+	path: string;
+}
+
+/**
+ * Schema health status
+ */
+export interface SchemaHealthStatus {
+	/** Whether schema is healthy */
+	healthy: boolean;
+	/** Database connection status */
+	connected: boolean;
+	/** Migration status */
+	migrations: MigrationStatus;
+	/** Integrity check result */
+	integrity: {
+		valid: boolean;
+		errors: string[];
+	};
+	/** Performance metrics */
+	performance: {
+		averageQueryTime: number;
+		slowQueries: number;
+		cacheHitRate: number;
+	};
+}
+
+// STORAGE SCHEMA INTERFACE
+
+/**
+ * Storage Schema Interface
+ *
+ * Provides access to multiple tables with cross-table operations.
+ */
+export interface StorageSchemaInterface<
+	TTables extends Record<string, StorageTableDefinition> = Record<string, StorageTableDefinition>
+> {
+	// METADATA
+
+	/** Schema ID */
+	readonly id: string;
+
+	/** Schema name */
+	readonly name: string;
+
+	/** Database name */
+	readonly dbName: string;
+
+	/** Available table names */
+	readonly tableNames: Extract<keyof TTables, string>[];
+
+	/** Zod schemas for all tables */
+	readonly schemas: { [K in keyof TTables]: z.ZodType };
+
+	/** Relations between tables */
+	readonly relations: Record<string, Record<string, StorageRelation>>;
+
+	// TABLE ACCESS
+
+	/**
+	 * Get a table interface for operations
+	 *
+	 * @param tableName - Table name
+	 * @returns Table interface
+	 */
+	table<K extends Extract<keyof TTables, string>>(
+		tableName: K
+	): StorageTableInterface<
+		z.infer<TTables[K]['schema']>,
+		TTables[K]['relations'] extends Record<string, StorageRelation>
+			? TTables[K]['relations']
+			: Record<string, StorageRelation>
+	>;
+
+	/**
+	 * Check if table exists
+	 *
+	 * @param tableName - Table name
+	 * @returns True if table exists
+	 */
+	hasTable(tableName: string): boolean;
+
+	/**
+	 * Get all table interfaces
+	 *
+	 * @returns Map of table name to interface
+	 */
+	getTables(): Map<string, StorageTableInterface>;
+
+	// TRANSACTIONS
+
+	/**
+	 * Execute operations in a transaction
+	 *
+	 * @param fn - Transaction function
+	 * @returns Transaction result
+	 */
+	transaction<T>(fn: TransactionFn<T>): Promise<T>;
+
+	/**
+	 * Begin a transaction explicitly
+	 *
+	 * @returns Transaction context
+	 */
+	beginTransaction(): Promise<TransactionContext>;
+
+	/**
+	 * Commit a transaction
+	 *
+	 * @param tx - Transaction context
+	 */
+	commitTransaction(tx: TransactionContext): Promise<void>;
+
+	/**
+	 * Rollback a transaction
+	 *
+	 * @param tx - Transaction context
+	 */
+	rollbackTransaction(tx: TransactionContext): Promise<void>;
+
+	// CROSS-TABLE OPERATIONS
+
+	/**
+	 * Execute a cross-table query with joins
+	 *
+	 * @param options - Query options
+	 * @returns Query results
+	 */
+	query(options: CrossTableQueryOptions): Promise<Record<string, unknown>[]>;
+
+	/**
+	 * Batch operations across multiple tables
+	 *
+	 * @param operations - Array of operations
+	 * @returns Array of results
+	 */
+	batch(
+		operations: Array<{
+			table: string;
+			operation: 'create' | 'update' | 'delete';
+			data?: unknown;
+			id?: string;
+		}>
+	): Promise<unknown[]>;
+
+	/**
+	 * Truncate multiple tables
+	 *
+	 * @param tables - Table names (default: all tables)
+	 * @param options - Truncate options
+	 */
+	truncate(
+		tables?: string[],
+		options?: { restartIdentity?: boolean; cascade?: boolean }
+	): Promise<void>;
+
+	// MIGRATIONS
+
+	/**
+	 * Run migrations
+	 *
+	 * @param options - Migration options
+	 * @returns Migration result
+	 */
+	migrate(options?: MigrationOptions): Promise<MigrationResult>;
+
+	/**
+	 * Rollback migrations
+	 *
+	 * @param steps - Number of migrations to rollback (default: 1)
+	 * @returns Migration result
+	 */
+	rollback(steps?: number): Promise<MigrationResult>;
+
+	/**
+	 * Get migration status
+	 *
+	 * @returns Migration status
+	 */
+	getMigrationStatus(): Promise<MigrationStatus>;
+
+	/**
+	 * Reset schema (drop all tables and re-run migrations)
+	 *
+	 * @param options - Reset options
+	 */
+	reset(options?: { seed?: boolean }): Promise<void>;
+
+	// BACKUP & RESTORE
+
+	/**
+	 * Create a backup
+	 *
+	 * @param options - Backup options
+	 * @returns Backup result
+	 */
+	backup(options?: BackupOptions): Promise<BackupResult>;
+
+	/**
+	 * Restore from a backup
+	 *
+	 * @param options - Restore options
+	 * @returns Restore result
+	 */
+	restore(options: RestoreOptions): Promise<RestoreResult>;
+
+	/**
+	 * List available backups
+	 *
+	 * @returns List of backups
+	 */
+	listBackups(): Promise<
+		Array<{
+			id: string;
+			name: string;
+			createdAt: Date;
+			size: number;
+			tables: string[];
+		}>
+	>;
+
+	/**
+	 * Delete a backup
+	 *
+	 * @param backupId - Backup ID
+	 */
+	deleteBackup(backupId: string): Promise<void>;
+
+	// SYNC & REPLICATION
+
+	/**
+	 * Sync with remote storage
+	 *
+	 * @param options - Sync options
+	 * @returns Sync result
+	 */
+	sync(options?: SyncOptions): Promise<SyncResult>;
+
+	/**
+	 * Get sync status
+	 *
+	 * @returns Sync status
+	 */
+	getSyncStatus(): Promise<SyncStatus>;
+
+	/**
+	 * Enable sync
+	 */
+	enableSync(): Promise<void>;
+
+	/**
+	 * Disable sync
+	 */
+	disableSync(): Promise<void>;
+
+	// STATISTICS & MONITORING
+
+	/**
+	 * Get schema statistics
+	 *
+	 * @returns Schema statistics
+	 */
+	getStatistics(): Promise<SchemaStatistics>;
+
+	/**
+	 * Get health status
+	 *
+	 * @returns Health status
+	 */
+	getHealth(): Promise<SchemaHealthStatus>;
+
+	/**
+	 * Check database integrity
+	 *
+	 * @returns Integrity check result
+	 */
+	checkIntegrity(): Promise<{ valid: boolean; errors: string[] }>;
+
+	/**
+	 * Optimize database (vacuum, analyze, etc.)
+	 */
+	optimize(): Promise<void>;
+
+	// UTILITIES
+
+	/**
+	 * Get adapter ID
+	 *
+	 * @returns Adapter ID
+	 */
+	getAdapterId(): string;
+
+	/**
+	 * Export schema definition
+	 *
+	 * @returns Schema definition
+	 */
+	exportSchema(): Record<string, unknown>;
+
+	/**
+	 * Validate data against table schema
+	 *
+	 * @param tableName - Table name
+	 * @param data - Data to validate
+	 * @returns Validation result
+	 */
+	validate<K extends Extract<keyof TTables, string>>(
+		tableName: K,
+		data: unknown
+	): Promise<{ success: boolean; data?: unknown; errors?: z.ZodError }>;
+
+	/**
+	 * Close all connections and cleanup
+	 */
+	close(): Promise<void>;
+}