@vibesdotdev/storage 0.0.1

package/src/interfaces/repository.ts

@@ -0,0 +1,300 @@
+/**
+ * Storage Repository Interface
+ *
+ * Repository pattern for structured record storage with queries.
+ * Supports CRUD operations, filtering, sorting, pagination.
+ */
+
+import type { z } from 'zod/v4';
+
+/**
+ * Repository for structured record storage
+ *
+ * @example
+ * ```ts
+ * const repo = adapter.repository('providers', providerSchema);
+ * const provider = await repo.create({ name: 'OpenAI', ... });
+ * const all = await repo.list({ limit: 10 });
+ * const found = await repo.find({ where: { type: 'cloud' } });
+ * ```
+ */
+export interface StorageRepositoryInterface<T> {
+	// Create
+
+	/**
+	 * Create a new record
+	 * @param data The record data (id auto-generated if not provided)
+	 * @returns The created record with id
+	 */
+	create(data: RepositoryCreateInput<T>): Promise<T>;
+
+	/**
+	 * Create multiple records
+	 * @param data Array of record data
+	 * @returns The created records
+	 */
+	createMany(data: RepositoryCreateInput<T>[]): Promise<T[]>;
+
+	// Read
+
+	/**
+	 * Get a record by id
+	 * @param id The record id
+	 * @returns The record or null if not found
+	 */
+	get(id: string): Promise<T | null>;
+
+	/**
+	 * Get a record by id or throw
+	 * @param id The record id
+	 * @throws Error if not found
+	 */
+	getOrThrow(id: string): Promise<T>;
+
+	/**
+	 * Get multiple records by ids
+	 * @param ids The record ids
+	 * @returns Map of id to record (missing ids omitted)
+	 */
+	getMany(ids: string[]): Promise<Map<string, T>>;
+
+	/**
+	 * List records with pagination
+	 * @param options List options
+	 */
+	list(options?: RepositoryListOptions<T>): Promise<RepositoryPage<T>>;
+
+	/**
+	 * Find records matching a query
+	 * @param query The query
+	 * @param options Additional options
+	 */
+	find(query: RepositoryQuery<T>, options?: RepositoryFindOptions<T>): Promise<T[]>;
+
+	/**
+	 * Find first record matching a query
+	 * @param query The query
+	 */
+	findOne(query: RepositoryQuery<T>): Promise<T | null>;
+
+	/**
+	 * Count records matching a query
+	 * @param query The query (optional, counts all if omitted)
+	 */
+	count(query?: RepositoryQuery<T>): Promise<number>;
+
+	/**
+	 * Check if a record exists
+	 * @param id The record id
+	 */
+	exists(id: string): Promise<boolean>;
+
+	/**
+	 * Check if any record matches a query
+	 * @param query The query
+	 */
+	existsWhere(query: RepositoryQuery<T>): Promise<boolean>;
+
+	// Update
+
+	/**
+	 * Update a record
+	 * @param id The record id
+	 * @param data The fields to update
+	 * @returns The updated record or null if not found
+	 */
+	update(id: string, data: RepositoryUpdateInput<T>): Promise<T | null>;
+
+	/**
+	 * Update a record or throw
+	 * @param id The record id
+	 * @param data The fields to update
+	 * @throws Error if not found
+	 */
+	updateOrThrow(id: string, data: RepositoryUpdateInput<T>): Promise<T>;
+
+	/**
+	 * Update multiple records matching a query
+	 * @param query The query to match
+	 * @param data The fields to update
+	 * @returns Number of records updated
+	 */
+	updateMany(query: RepositoryQuery<T>, data: RepositoryUpdateInput<T>): Promise<number>;
+
+	/**
+	 * Upsert a record (create or update)
+	 * @param data The record data
+	 * @param uniqueKey The field to match for update (defaults to 'id')
+	 * @returns The upserted record
+	 */
+	upsert(data: RepositoryCreateInput<T>, uniqueKey?: keyof T): Promise<T>;
+
+	// Delete
+
+	/**
+	 * Delete a record by id
+	 * @param id The record id
+	 * @returns true if deleted, false if not found
+	 */
+	delete(id: string): Promise<boolean>;
+
+	/**
+	 * Delete multiple records by ids
+	 * @param ids The record ids
+	 * @returns Number of records deleted
+	 */
+	deleteMany(ids: string[]): Promise<number>;
+
+	/**
+	 * Delete records matching a query
+	 * @param query The query
+	 * @returns Number of records deleted
+	 */
+	deleteWhere(query: RepositoryQuery<T>): Promise<number>;
+
+	// Metadata
+
+	/**
+	 * Get repository metadata
+	 */
+	meta(): RepositoryMeta<T>;
+}
+
+// Input Types
+
+/**
+ * Input for creating a record
+ * All fields except auto-generated ones (id, createdAt, updatedAt)
+ */
+export type RepositoryCreateInput<T> = Omit<T, 'id' | 'createdAt' | 'updatedAt'> & {
+	id?: string;
+};
+
+/**
+ * Input for updating a record
+ * Partial fields (id cannot be updated)
+ */
+export type RepositoryUpdateInput<T> = Partial<Omit<T, 'id' | 'createdAt' | 'updatedAt'>>;
+
+// Query Types
+
+/**
+ * Query for finding records
+ */
+export interface RepositoryQuery<T> {
+	/** Field conditions (AND) */
+	where?: Partial<Record<keyof T, QueryCondition<T[keyof T]>>>;
+	/** OR conditions */
+	or?: RepositoryQuery<T>[];
+	/** AND conditions */
+	and?: RepositoryQuery<T>[];
+}
+
+/**
+ * Condition for a field
+ */
+export type QueryCondition<TField> =
+	| TField // Equals
+	| { eq: TField }
+	| { ne: TField }
+	| { gt: TField }
+	| { gte: TField }
+	| { lt: TField }
+	| { lte: TField }
+	| { in: TField[] }
+	| { notIn: TField[] }
+	| { like: string }
+	| { ilike: string }
+	| { isNull: boolean }
+	| { contains: string }
+	| { startsWith: string }
+	| { endsWith: string };
+
+// Options Types
+
+/**
+ * Options for list operations
+ */
+export interface RepositoryListOptions<T> {
+	/** Maximum records to return */
+	limit?: number;
+	/** Records to skip */
+	offset?: number;
+	/** Cursor for pagination (alternative to offset) */
+	cursor?: string;
+	/** Sort order */
+	orderBy?: RepositoryOrderBy<T>;
+}
+
+/**
+ * Options for find operations
+ */
+export interface RepositoryFindOptions<T> extends RepositoryListOptions<T> {
+	/** Fields to select (default: all) */
+	select?: (keyof T)[];
+}
+
+/**
+ * Sort specification
+ */
+export type RepositoryOrderBy<T> =
+	| keyof T
+	| { field: keyof T; direction: 'asc' | 'desc' }
+	| Array<keyof T | { field: keyof T; direction: 'asc' | 'desc' }>;
+
+// Result Types
+
+/**
+ * Paginated result
+ */
+export interface RepositoryPage<T> {
+	/** Records in this page */
+	data: T[];
+	/** Total count (if available) */
+	total?: number;
+	/** Cursor for next page (if using cursor pagination) */
+	nextCursor?: string;
+	/** Whether more records exist */
+	hasMore: boolean;
+}
+
+/**
+ * Repository metadata
+ */
+export interface RepositoryMeta<T> {
+	/** Table/collection name */
+	tableName: string;
+	/** Zod schema */
+	schema: z.ZodType<T>;
+	/** Primary key field */
+	primaryKey: string;
+	/** Auto-generated fields */
+	autoFields: {
+		id: boolean;
+		createdAt: boolean;
+		updatedAt: boolean;
+	};
+}
+
+// Factory Type
+
+/**
+ * Factory type for creating repositories
+ */
+export type RepositoryFactory<T> = (
+	tableName: string,
+	schema: z.ZodType<T>,
+	options?: RepositoryOptions
+) => StorageRepositoryInterface<T>;
+
+/**
+ * Options for repository creation
+ */
+export interface RepositoryOptions {
+	/** Custom primary key field (default: 'id') */
+	primaryKey?: string;
+	/** Whether to auto-generate id (default: true) */
+	autoId?: boolean;
+	/** Whether to auto-manage createdAt/updatedAt (default: true) */
+	autoTimestamps?: boolean;
+}

package/src/interfaces/schema/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Storage Schema Interface Exports
+ *
+ * Exports all types and interfaces for storage/schema operations.
+ */
+
+// Table interface
+export { type StorageTableInterface } from './table-interface';
+
+// Schema interface and types
+export {
+	// 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-interface';