@vibesdotdev/storage 0.0.1 → 1.0.0-rc.3

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

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