@vibesdotdev/storage 0.0.1

package/src/interfaces/record/interface.ts

@@ -0,0 +1,723 @@
+/**
+ * Storage Record Interface
+ *
+ * Defines the interface for CRUD operations on a single table.
+ * This is what gets resolved when you query for a storage/record descriptor.
+ *
+ * @example
+ * ```typescript
+ * const todos = await runtime
+ *   .query('storage/record')
+ *   .withId('session.todos')
+ *   .resolve();
+ *
+ * // Create
+ * const todo = await todos.create({
+ *   sessionId: 'session-123',
+ *   title: 'Implement storage',
+ *   status: 'in_progress'
+ * });
+ *
+ * // Get
+ * const todo = await todos.get('todo-123');
+ *
+ * // List with filters
+ * const todos = await todos.list({
+ *   where: { sessionId: 'session-123', status: 'pending' },
+ *   include: { session: true },
+ *   orderBy: { createdAt: 'desc' },
+ *   limit: 50
+ * });
+ *
+ * // Full-text search
+ * const results = await todos.search('implement storage', {
+ *   where: { sessionId: 'session-123' },
+ *   highlight: true
+ * });
+ *
+ * // Get todo tree
+ * const tree = await todos.getTree({ where: { sessionId: 'session-123' } });
+ *
+ * // Update
+ * await todos.update('todo-123', { status: 'completed' });
+ *
+ * // Delete
+ * await todos.delete('todo-123');
+ * ```
+ */
+
+import type { z } from 'zod/v4';
+import type { StorageRelation } from '../../schemas/record/relation';
+
+// QUERY TYPES
+
+/**
+ * Filter conditions for queries
+ */
+export type WhereFilter<T> = {
+	[P in keyof T]?:
+		| T[P]
+		| {
+				eq?: T[P];
+				ne?: T[P];
+				gt?: T[P];
+				gte?: T[P];
+				lt?: T[P];
+				lte?: T[P];
+				in?: T[P][];
+				notIn?: T[P][];
+				like?: string;
+				ilike?: string;
+				contains?: string;
+				startsWith?: string;
+				endsWith?: string;
+				isNull?: boolean;
+				isNotNull?: boolean;
+				between?: [T[P], T[P]];
+		  };
+};
+
+/**
+ * Order by specification
+ */
+export type OrderBy<T> =
+	| {
+			[P in keyof T]?: 'asc' | 'desc';
+	  }
+	| {
+			field: keyof T;
+			direction: 'asc' | 'desc';
+	  }[];
+
+/**
+ * Relation include specification
+ */
+export type IncludeRelations<R extends string = string> =
+	| R
+	| R[]
+	| { [K in R]?: boolean | IncludeRelations };
+
+/**
+ * Pagination options
+ */
+export interface PaginationOptions {
+	/** Number of items to return */
+	limit?: number;
+	/** Number of items to skip */
+	offset?: number;
+	/** Cursor for cursor-based pagination */
+	cursor?: string;
+	/** Cursor field (default: primaryKey) */
+	cursorField?: string;
+}
+
+/**
+ * Query options for list operations
+ */
+export interface QueryOptions<T, R extends string = string> extends PaginationOptions {
+	/** Filter conditions */
+	where?: WhereFilter<T>;
+	/** Relations to include */
+	include?: IncludeRelations<R>;
+	/** Order by fields */
+	orderBy?: OrderBy<T>;
+	/** Fields to select */
+	select?: (keyof T)[];
+	/** Whether to include soft-deleted records */
+	includeDeleted?: boolean;
+	/** Distinct fields */
+	distinct?: keyof T | (keyof T)[];
+	/** Group by fields */
+	groupBy?: keyof T | (keyof T)[];
+	/** Having conditions (for groupBy) */
+	having?: Record<string, unknown>;
+	/** Include computed fields in results */
+	includeComputed?: (keyof T)[] | boolean;
+}
+
+/**
+ * Query result with pagination metadata
+ */
+export interface QueryResult<T> {
+	/** Result items */
+	items: T[];
+	/** Total count (without pagination) */
+	total?: number;
+	/** Whether there are more items */
+	hasMore?: boolean;
+	/** Next cursor (for cursor-based pagination) */
+	nextCursor?: string;
+	/** Previous cursor (for cursor-based pagination) */
+	prevCursor?: string;
+}
+
+// SEARCH TYPES (FTS)
+
+/**
+ * Full-text search options
+ */
+export interface SearchOptions<T, R extends string = string> extends QueryOptions<T, R> {
+	/** Highlight matches in results */
+	highlight?: boolean;
+	/** Fields to search (default: all fts fields) */
+	fields?: (keyof T)[];
+	/** Rank by relevance score */
+	rankByRelevance?: boolean;
+	/** Minimum relevance score (0-1) */
+	minScore?: number;
+	/** Highlight tag prefix (default: <mark>) */
+	highlightPrefix?: string;
+	/** Highlight tag suffix (default: </mark>) */
+	highlightSuffix?: string;
+}
+
+/**
+ * Search result with relevance score
+ */
+export interface SearchResult<T> extends QueryResult<T> {
+	/** Relevance scores per item */
+	scores?: number[];
+	/** Highlighted snippets per item */
+	highlights?: Map<string, string[]>;
+}
+
+// HIERARCHY TYPES (Recursive CTEs)
+
+/**
+ * Tree node for hierarchical data
+ */
+export interface TreeNode<T> {
+	/** The record data */
+	record: T;
+	/** Child nodes */
+	children: TreeNode<T>[];
+	/** Depth in tree (0 = root) */
+	depth: number;
+	/** Path from root (array of IDs) */
+	path?: string[];
+}
+
+/**
+ * Hierarchy query options
+ */
+export interface HierarchyOptions<T, R extends string = string> extends QueryOptions<T, R> {
+	/** Maximum depth to traverse (default: unlimited) */
+	maxDepth?: number;
+	/** Include depth in results */
+	includeDepth?: boolean;
+	/** Include path from root */
+	includePath?: boolean;
+}
+
+// CREATE TYPES
+
+/**
+ * Create input (excludes auto-managed fields)
+ */
+export type CreateInput<T> = Omit<T, 'id' | 'createdAt' | 'updatedAt'> & {
+	/** Override auto-generated ID */
+	id?: string;
+	/** Override auto-generated createdAt */
+	createdAt?: string | Date;
+	/** Override auto-generated updatedAt */
+	updatedAt?: string | Date;
+	/** Override deletedAt when importing tombstones */
+	deletedAt?: string | Date | null;
+};
+
+/**
+ * Create many options
+ */
+export interface CreateManyOptions {
+	/** Skip duplicate IDs */
+	skipDuplicates?: boolean;
+	/** Batch size for bulk insert */
+	batchSize?: number;
+}
+
+// UPDATE TYPES
+
+/**
+ * Update input (partial with conditions)
+ */
+export type UpdateInput<T> = Partial<Omit<T, 'id' | 'createdAt'>>;
+
+/**
+ * Update options
+ */
+export interface UpdateOptions {
+	/** Update only if conditions match */
+	where?: Record<string, unknown>;
+	/** Increment fields */
+	increment?: Record<string, number>;
+	/** Decrement fields */
+	decrement?: Record<string, number>;
+	/** Set fields to null */
+	unset?: string[];
+	/** Push to array fields */
+	push?: Record<string, unknown | unknown[]>;
+	/** Pull from array fields */
+	pull?: Record<string, unknown | unknown[]>;
+}
+
+/**
+ * Update result
+ */
+export interface UpdateResult {
+	/** Number of records updated */
+	count: number;
+	/** Whether any records were updated */
+	success: boolean;
+}
+
+// DELETE TYPES
+
+/**
+ * Delete options
+ */
+export interface DeleteOptions {
+	/** Force delete (even with soft delete enabled) */
+	force?: boolean;
+	/** Delete only if conditions match */
+	where?: Record<string, unknown>;
+}
+
+/**
+ * Delete result
+ */
+export interface DeleteResult {
+	/** Number of records deleted */
+	count: number;
+	/** Whether any records were deleted */
+	success: boolean;
+}
+
+// RELATION TYPES
+
+/**
+ * Loaded relation data
+ */
+export type LoadedRelation<T, R extends StorageRelation> = R extends {
+	type: 'belongs_to' | 'has_one';
+}
+	? T | null
+	: R extends { type: 'has_many' | 'many_to_many' }
+		? T[]
+		: never;
+
+/**
+ * Record with loaded relations
+ */
+export type RecordWithRelations<T, R extends Record<string, StorageRelation>> = T & {
+	[K in keyof R]?: LoadedRelation<unknown, R[K]>;
+};
+
+// TRANSACTION TYPES
+
+/**
+ * Transaction context
+ */
+export interface TransactionContext {
+	/** Transaction ID */
+	id: string;
+	/** Transaction start time */
+	startTime: number;
+	/** Whether transaction is active */
+	isActive: boolean;
+}
+
+/**
+ * Transaction function
+ */
+export type TransactionFn<T> = (tx: TransactionContext) => Promise<T>;
+
+// AGGREGATION TYPES
+
+/**
+ * Aggregation functions
+ */
+export type AggregationFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
+
+/**
+ * Aggregation options
+ */
+export interface AggregationOptions<T> {
+	/** Field to aggregate (not needed for count) */
+	field?: keyof T;
+	/** Filter conditions */
+	where?: WhereFilter<T>;
+	/** Group by fields */
+	groupBy?: keyof T | (keyof T)[];
+	/** Having conditions */
+	having?: Record<string, unknown>;
+	/** Multiple aggregations in one query */
+	aggregations?: {
+		[alias: string]: {
+			function: AggregationFunction;
+			field?: keyof T;
+		};
+	};
+	/** Include grouped values in result */
+	includeGroups?: boolean;
+}
+
+/**
+ * Aggregation result
+ */
+export interface AggregationResult {
+	/** Aggregation value */
+	value: number;
+	/** Group values (if grouped) */
+	group?: Record<string, unknown>;
+	/** Multiple aggregation values when using aggregations */
+	values?: Record<string, number>;
+}
+
+// STREAM TYPES
+
+/**
+ * Stream options
+ */
+export interface StreamOptions<T> extends QueryOptions<T> {
+	/** Batch size for streaming */
+	batchSize?: number;
+	/** High water mark for backpressure */
+	highWaterMark?: number;
+}
+
+// RAW QUERY TYPES
+
+/**
+ * Raw query options
+ */
+export interface RawQueryOptions<R = unknown> {
+	/** SQL query with placeholders */
+	sql: string;
+	/** Query parameters */
+	params?: unknown[];
+	/** Schema for result validation */
+	schema?: z.ZodType<R>;
+}
+
+// STORAGE RECORD INTERFACE
+
+/**
+ * Storage Record Interface
+ *
+ * Provides CRUD operations on a single table with relations.
+ */
+export interface StorageRecordInterface<
+	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 */
+	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' | 'includeComputed'>
+	): 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' | 'includeComputed'>
+	): 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' | 'includeComputed'>
+	): 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>;
+
+	// FULL-TEXT SEARCH
+
+	/**
+	 * Full-text search on indexed fields
+	 *
+	 * @param query - Search query (FTS5 syntax supported)
+	 * @param options - Search options
+	 * @returns Search results with relevance scores
+	 */
+	search(query: string, options?: SearchOptions<T, string & keyof R>): Promise<SearchResult<T>>;
+
+	// HIERARCHY (Recursive CTEs)
+
+	/**
+	 * Get all descendants of a record
+	 *
+	 * @param id - Root record ID
+	 * @param options - Hierarchy options
+	 * @returns Query result with depth information
+	 */
+	getDescendants(
+		id: string,
+		options?: HierarchyOptions<T, string & keyof R>
+	): Promise<QueryResult<T & { depth: number; path?: string[] }>>;
+
+	/**
+	 * Get all ancestors of a record
+	 *
+	 * @param id - Leaf record ID
+	 * @param options - Query options
+	 * @returns Ancestor records from root to parent
+	 */
+	getAncestors(id: string, options?: QueryOptions<T, string & keyof R>): Promise<T[]>;
+
+	/**
+	 * Get full tree starting from matching roots
+	 *
+	 * @param options - Query options for root selection
+	 * @returns Tree structure with nested children
+	 */
+	getTree(options?: HierarchyOptions<T, string & keyof R>): Promise<TreeNode<T>[]>;
+
+	// 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
+
+	/**
+	 * Aggregate records
+	 *
+	 * @param options - Aggregation options with function
+	 * @returns Aggregation results
+	 */
+	aggregate(
+		options: AggregationOptions<T> & { function: AggregationFunction }
+	): Promise<AggregationResult[]>;
+
+	// TRANSACTIONS
+
+	/**
+	 * Execute operations in a transaction
+	 *
+	 * @param fn - Transaction function
+	 * @returns Transaction result
+	 */
+	transaction<U>(fn: TransactionFn<U>): Promise<U>;
+
+	// STREAMING
+
+	/**
+	 * Stream records as async iterable
+	 *
+	 * @param options - Stream options
+	 * @returns Async iterable of records
+	 */
+	stream(options?: StreamOptions<T>): AsyncIterable<T>;
+
+	// BATCH OPERATIONS
+
+	/**
+	 * Execute multiple operations in batch
+	 *
+	 * @param operations - Array of operations
+	 * @returns Array of results
+	 */
+	batch(
+		operations: Array<{
+			type: 'create' | 'update' | 'delete';
+			data?: unknown;
+			id?: string;
+		}>
+	): Promise<unknown[]>;
+
+	// RAW QUERIES
+
+	/**
+	 * Execute raw SQL query (adapter-specific)
+	 * Use sparingly - breaks adapter portability
+	 *
+	 * @param sql - SQL query with placeholders
+	 * @param params - Query parameters
+	 * @returns Raw result rows
+	 */
+	raw<R = unknown>(sql: string, ...params: unknown[]): Promise<R[]>;
+
+	/**
+	 * Execute raw query with typed result
+	 *
+	 * @param options - Raw query options
+	 * @returns Typed result rows
+	 */
+	queryRaw<R>(options: RawQueryOptions<R>): Promise<R[]>;
+
+	// 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;
+
+	/**
+	 * Close connections and cleanup
+	 */
+	close(): Promise<void>;
+}