@vibesdotdev/storage 0.0.2 → 1.0.0-rc.3

package/src/interfaces/record/interface.ts

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