@vibesdotdev/storage 0.0.1

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

@@ -0,0 +1,314 @@
+/**
+ * Storage Table Interface
+ *
+ * Defines the interface for CRUD operations on a single table within a schema.
+ * This is what gets returned when you access a table from a StorageSchema.
+ *
+ * @example
+ * ```typescript
+ * const schema = await runtime
+ *   .query('storage/schema')
+ *   .withId('session')
+ *   .resolve();
+ *
+ * const todosTable = schema.table('todos');
+ *
+ * // Create
+ * const todo = await todosTable.create({
+ *   sessionId: 'session-123',
+ *   title: 'Implement storage',
+ *   status: 'in_progress'
+ * });
+ *
+ * // List with relations to other tables in the schema
+ * const todos = await todosTable.list({
+ *   where: { sessionId: 'session-123' },
+ *   include: { session: true, parent: true }
+ * });
+ * ```
+ */
+
+import type { z } from 'zod/v4';
+import type { StorageRelation } from '../../schemas/record';
+import type {
+	WhereFilter,
+	QueryOptions,
+	QueryResult,
+	CreateInput,
+	CreateManyOptions,
+	UpdateInput,
+	UpdateOptions,
+	UpdateResult,
+	DeleteOptions,
+	DeleteResult,
+	AggregationOptions,
+	AggregationResult,
+	StreamOptions
+} from '../record';
+
+/**
+ * Storage Table Interface
+ *
+ * Provides CRUD operations on a single table within a schema.
+ * Similar to StorageRecordInterface but scoped to a schema context.
+ */
+export interface StorageTableInterface<
+	T = unknown,
+	R extends Record<string, StorageRelation> = Record<string, StorageRelation>
+> {
+	// METADATA
+
+	/** Table name */
+	readonly tableName: string;
+
+	/** Primary key field */
+	readonly primaryKey: string;
+
+	/** Zod schema for validation */
+	readonly schema: z.ZodType<T>;
+
+	/** Available relations to other tables in the schema */
+	readonly relations: R;
+
+	// CREATE
+
+	/**
+	 * Create a new record
+	 *
+	 * @param data - Record data
+	 * @returns Created record
+	 */
+	create(data: CreateInput<T>): Promise<T>;
+
+	/**
+	 * Create multiple records
+	 *
+	 * @param data - Array of record data
+	 * @param options - Create many options
+	 * @returns Created records
+	 */
+	createMany(data: CreateInput<T>[], options?: CreateManyOptions): Promise<T[]>;
+
+	// READ
+
+	/**
+	 * Get a single record by ID
+	 *
+	 * @param id - Record ID
+	 * @param options - Query options (include relations, select fields)
+	 * @returns Record or null if not found
+	 */
+	get(
+		id: string,
+		options?: Pick<QueryOptions<T, string & keyof R>, 'include' | 'select'>
+	): Promise<T | null>;
+
+	/**
+	 * Get a single record or throw if not found
+	 *
+	 * @param id - Record ID
+	 * @param options - Query options
+	 * @returns Record
+	 * @throws Error if record not found
+	 */
+	getOrThrow(
+		id: string,
+		options?: Pick<QueryOptions<T, string & keyof R>, 'include' | 'select'>
+	): Promise<T>;
+
+	/**
+	 * Get many records by IDs
+	 *
+	 * @param ids - Record IDs
+	 * @param options - Query options
+	 * @returns Records (may be fewer than requested if some not found)
+	 */
+	getMany(
+		ids: string[],
+		options?: Pick<QueryOptions<T, string & keyof R>, 'include' | 'select'>
+	): Promise<T[]>;
+
+	/**
+	 * List records with filtering, pagination, and relations
+	 *
+	 * @param options - Query options
+	 * @returns Query result with items and pagination metadata
+	 */
+	list(options?: QueryOptions<T, string & keyof R>): Promise<QueryResult<T>>;
+
+	/**
+	 * Find first record matching conditions
+	 *
+	 * @param options - Query options
+	 * @returns First matching record or null
+	 */
+	findFirst(options?: QueryOptions<T, string & keyof R>): Promise<T | null>;
+
+	/**
+	 * Find first record or throw if not found
+	 *
+	 * @param options - Query options
+	 * @returns First matching record
+	 * @throws Error if no record found
+	 */
+	findFirstOrThrow(options?: QueryOptions<T, string & keyof R>): Promise<T>;
+
+	/**
+	 * Check if record exists
+	 *
+	 * @param id - Record ID
+	 * @returns True if record exists
+	 */
+	exists(id: string): Promise<boolean>;
+
+	/**
+	 * Count records matching conditions
+	 *
+	 * @param where - Filter conditions
+	 * @returns Number of matching records
+	 */
+	count(where?: WhereFilter<T>): Promise<number>;
+
+	// UPDATE
+
+	/**
+	 * Update a record by ID
+	 *
+	 * @param id - Record ID
+	 * @param data - Update data
+	 * @param options - Update options
+	 * @returns Updated record
+	 * @throws Error if record not found
+	 */
+	update(id: string, data: UpdateInput<T>, options?: UpdateOptions): Promise<T>;
+
+	/**
+	 * Update many records matching conditions
+	 *
+	 * @param where - Filter conditions
+	 * @param data - Update data
+	 * @param options - Update options
+	 * @returns Update result with count
+	 */
+	updateMany(
+		where: WhereFilter<T>,
+		data: UpdateInput<T>,
+		options?: UpdateOptions
+	): Promise<UpdateResult>;
+
+	/**
+	 * Update or create a record
+	 *
+	 * @param id - Record ID
+	 * @param create - Data to use if creating
+	 * @param update - Data to use if updating
+	 * @returns Created or updated record
+	 */
+	upsert(id: string, create: CreateInput<T>, update: UpdateInput<T>): Promise<T>;
+
+	// DELETE
+
+	/**
+	 * Delete a record by ID
+	 *
+	 * @param id - Record ID
+	 * @param options - Delete options
+	 * @returns Delete result
+	 */
+	delete(id: string, options?: DeleteOptions): Promise<DeleteResult>;
+
+	/**
+	 * Delete many records matching conditions
+	 *
+	 * @param where - Filter conditions
+	 * @param options - Delete options
+	 * @returns Delete result with count
+	 */
+	deleteMany(where: WhereFilter<T>, options?: DeleteOptions): Promise<DeleteResult>;
+
+	/**
+	 * Restore a soft-deleted record
+	 *
+	 * @param id - Record ID
+	 * @returns Restored record
+	 * @throws Error if record not found or not soft-deleted
+	 */
+	restore(id: string): Promise<T>;
+
+	// AGGREGATION
+
+	/**
+	 * Count records
+	 *
+	 * @param options - Aggregation options
+	 * @returns Aggregation results
+	 */
+	aggregate(options: AggregationOptions<T> & { function: 'count' }): Promise<AggregationResult[]>;
+
+	/**
+	 * Sum field values
+	 *
+	 * @param options - Aggregation options
+	 * @returns Aggregation results
+	 */
+	aggregate(
+		options: AggregationOptions<T> & { function: 'sum'; field: keyof T }
+	): Promise<AggregationResult[]>;
+
+	/**
+	 * Average field values
+	 *
+	 * @param options - Aggregation options
+	 * @returns Aggregation results
+	 */
+	aggregate(
+		options: AggregationOptions<T> & { function: 'avg'; field: keyof T }
+	): Promise<AggregationResult[]>;
+
+	/**
+	 * Get minimum field value
+	 *
+	 * @param options - Aggregation options
+	 * @returns Aggregation results
+	 */
+	aggregate(
+		options: AggregationOptions<T> & { function: 'min'; field: keyof T }
+	): Promise<AggregationResult[]>;
+
+	/**
+	 * Get maximum field value
+	 *
+	 * @param options - Aggregation options
+	 * @returns Aggregation results
+	 */
+	aggregate(
+		options: AggregationOptions<T> & { function: 'max'; field: keyof T }
+	): Promise<AggregationResult[]>;
+
+	// STREAMING
+
+	/**
+	 * Stream records as async iterable
+	 *
+	 * @param options - Stream options
+	 * @returns Async iterable of records
+	 */
+	stream(options?: StreamOptions<T>): AsyncIterable<T>;
+
+	// UTILITIES
+
+	/**
+	 * Validate record data against schema
+	 *
+	 * @param data - Record data
+	 * @returns Validation result
+	 */
+	validate(data: unknown): Promise<{ success: boolean; data?: T; errors?: z.ZodError }>;
+
+	/**
+	 * Get database adapter being used
+	 *
+	 * @returns Adapter ID
+	 */
+	getAdapterId(): string;
+}

package/src/interfaces/storage-consumer-fs.ts

@@ -0,0 +1,66 @@
+/**
+ * Storage Consumer File System Abstraction
+ *
+ * Consumer-scoped: provides access to host fs, crypto, and path primitives.
+ * Injected at runtime to avoid universal core importing Node.js built-ins.
+ *
+ * This enables `cli/context.consumer.ts` to operate in consumer hardware scope
+ * without polluting the universal core with Node.js imports.
+ *
+ * Usage:
+ * ```ts
+ * import { getConsumerFs } from './storage-consumer-fs';
+ *
+ * const fs = getConsumerFs();
+ * const data = await fs.readFile('/path/to/file', 'utf8');
+ * ```
+ */
+
+export interface ConsumerFileSystem {
+	existsSync(path: string): boolean;
+	mkdirSync(path: string, options?: { recursive: boolean }): void;
+	watch(
+		dir: string,
+		listener: (eventType: string, filename: string | Buffer | null) => void
+	): { close(): void } | null;
+	readFile(path: string, encoding: BufferEncoding): Promise<string>;
+	writeFile(
+		path: string,
+		content: string | Uint8Array,
+		options?: BufferEncoding | { encoding?: BufferEncoding; mode?: number; flag?: string }
+	): Promise<void>;
+	rename(oldPath: string, newPath: string): Promise<void>;
+	dirname(path: string): string;
+	basename(path: string, ext?: string): string;
+	join(...paths: string[]): string;
+	resolve(...paths: string[]): string;
+	randomUUID(): string;
+}
+
+let _consumerFs: ConsumerFileSystem | null = null;
+
+export async function getConsumerFs(): Promise<ConsumerFileSystem> {
+	if (_consumerFs) return _consumerFs;
+
+	const [fs, crypto, path] = await Promise.all([
+		import('node:fs'),
+		import('node:crypto'),
+		import('node:path')
+	]);
+
+	_consumerFs = {
+		existsSync: fs.existsSync,
+		mkdirSync: fs.mkdirSync,
+		watch: fs.watch.bind(fs),
+		readFile: (path: string, encoding: BufferEncoding) => fs.promises.readFile(path, encoding),
+		writeFile: (path: string, content: string | Uint8Array, options?: BufferEncoding | { encoding?: BufferEncoding; mode?: number; flag?: string }) => fs.promises.writeFile(path, content, options),
+		rename: fs.promises.rename,
+		dirname: path.dirname,
+		basename: path.basename,
+		join: path.join,
+		resolve: path.resolve,
+		randomUUID: crypto.randomUUID
+	};
+
+	return _consumerFs;
+}