@mdxui/terminal 2.0.0

package/src/data/types.ts

@@ -0,0 +1,660 @@
+/**
+ * @mdxui/terminal Data Layer Types
+ *
+ * Type definitions for the TanStack DB-like integration.
+ * Provides a type-safe, reactive in-memory database with Zod validation,
+ * filtering, sorting, pagination, and optimistic updates.
+ */
+
+import type { ZodSchema, ZodRawShape, z } from 'zod'
+
+// ============================================================================
+// Query Filter Types
+// ============================================================================
+
+/**
+ * Comparison operators for filtering database queries
+ *
+ * @template T - The type of the field being compared
+ *
+ * @example
+ * ```typescript
+ * // Using comparison operators in a where clause
+ * {
+ *   $eq: 5,           // Equal to 5
+ *   $ne: 10,          // Not equal to 10
+ *   $gt: 3,           // Greater than 3
+ *   $gte: 3,          // Greater than or equal to 3
+ *   $lt: 100,         // Less than 100
+ *   $lte: 100,        // Less than or equal to 100
+ *   $in: [1, 2, 3],   // In array [1, 2, 3]
+ *   $nin: [1, 2, 3],  // Not in array [1, 2, 3]
+ * }
+ * ```
+ */
+export interface ComparisonOperators<T> {
+  /** Equality match */
+  $eq?: T
+  /** Not equal to */
+  $ne?: T
+  /** Greater than */
+  $gt?: T
+  /** Greater than or equal to */
+  $gte?: T
+  /** Less than */
+  $lt?: T
+  /** Less than or equal to */
+  $lte?: T
+  /** Value is in array */
+  $in?: T[]
+  /** Value is not in array */
+  $nin?: T[]
+}
+
+/**
+ * Field filter - either a direct value for equality or comparison operators
+ *
+ * @template T - The type of the field
+ *
+ * @example
+ * ```typescript
+ * // Direct equality
+ * type Filter = FieldFilter<number>  // number
+ * const filter: Filter = 5
+ *
+ * // With operators
+ * const filter: Filter = { $gt: 5 }
+ * ```
+ */
+export type FieldFilter<T> = T | ComparisonOperators<T>
+
+/**
+ * Where clause for filtering - supports equality, comparison operators, and $or
+ *
+ * @template T - The document type being queried
+ *
+ * @remarks
+ * - Uses AND logic for multiple field conditions
+ * - `$or` is an array of alternative conditions (OR logic)
+ * - Can combine $or with other fields (fields AND ($or[...]))
+ *
+ * @example
+ * ```typescript
+ * // Simple equality
+ * const where: WhereClause<User> = { role: 'admin' }
+ *
+ * // With comparison operators
+ * const where: WhereClause<User> = { age: { $gte: 18 } }
+ *
+ * // Multiple conditions (AND)
+ * const where: WhereClause<User> = {
+ *   role: 'admin',
+ *   age: { $gte: 18 }
+ * }
+ *
+ * // OR conditions
+ * const where: WhereClause<User> = {
+ *   $or: [
+ *     { role: 'admin' },
+ *     { role: 'moderator' }
+ *   ]
+ * }
+ *
+ * // Combined AND/OR
+ * const where: WhereClause<User> = {
+ *   status: 'active',
+ *   $or: [
+ *     { role: 'admin' },
+ *     { role: 'moderator' }
+ *   ]
+ * }
+ * ```
+ */
+export type WhereClause<T> = {
+  [K in keyof T]?: FieldFilter<T[K]>
+} & {
+  $or?: Array<WhereClause<T>>
+}
+
+/**
+ * Sort direction for ordering results
+ *
+ * @example
+ * ```typescript
+ * type Direction = OrderDirection
+ * const ascending: Direction = 'asc'
+ * const descending: Direction = 'desc'
+ * ```
+ */
+export type OrderDirection = 'asc' | 'desc'
+
+/**
+ * Order by clause for sorting results
+ *
+ * @template T - The document type being sorted
+ *
+ * @remarks
+ * Maps field names to sort directions (asc/desc)
+ *
+ * @example
+ * ```typescript
+ * // Sort by age ascending
+ * const orderBy: OrderByClause<User> = { age: 'asc' }
+ *
+ * // Sort by multiple fields
+ * const orderByArray: OrderByClause<User>[] = [
+ *   { role: 'asc' },
+ *   { age: 'desc' }
+ * ]
+ * ```
+ */
+export type OrderByClause<T> = {
+  [K in keyof T]?: OrderDirection
+}
+
+// ============================================================================
+// Collection Types
+// ============================================================================
+
+/**
+ * Configuration for creating a collection
+ *
+ * @template T - The Zod schema shape for the collection
+ *
+ * @example
+ * ```typescript
+ * const config: CollectionConfig<typeof UserSchema.shape> = {
+ *   name: 'users',
+ *   schema: UserSchema,
+ *   primaryKey: 'id',
+ *   indexes: ['email', 'role']
+ * }
+ * ```
+ */
+export interface CollectionConfig<T extends ZodRawShape> {
+  /** Collection name - used to reference in queries */
+  name: string
+  /** Zod schema for automatic validation on insert/update */
+  schema: ZodSchema<z.infer<z.ZodObject<T>>>
+  /** Primary key field (defaults to 'id'). Used for duplicate detection */
+  primaryKey?: keyof z.infer<z.ZodObject<T>>
+  /** Fields to index for faster queries (metadata only, used for optimization hints) */
+  indexes?: Array<keyof z.infer<z.ZodObject<T>>>
+}
+
+/**
+ * A typed in-memory collection with CRUD operations, filtering, sorting, and reactive subscriptions
+ *
+ * @template T - The document type stored in this collection
+ *
+ * @remarks
+ * - All documents are validated against the schema on insert/update
+ * - Provides reactive subscriptions for real-time updates
+ * - Supports filtering with where clauses and comparison operators
+ * - Supports sorting with orderBy and multiple sort fields
+ * - Supports pagination with limit and offset
+ *
+ * @example
+ * ```typescript
+ * const collection = createCollection<User>({
+ *   name: 'users',
+ *   schema: UserSchema
+ * })
+ *
+ * // CRUD operations
+ * const user = await collection.insert({ id: '1', name: 'Alice', ... })
+ * const updated = await collection.update({ id: '1' }, { name: 'Alicia' })
+ * const found = await collection.findOne({ id: '1' })
+ * const all = await collection.findMany()
+ * await collection.delete({ id: '1' })
+ *
+ * // Subscribe to changes
+ * const unsubscribe = collection.subscribe((data) => {
+ *   console.log('Collection changed:', data)
+ * })
+ * ```
+ */
+export interface Collection<T> {
+  /** Collection name - used to reference in queries */
+  name: string
+  /** Zod schema for validation */
+  schema: ZodSchema<T>
+  /** Primary key field name */
+  primaryKey: string
+  /** Indexed field names */
+  indexes: string[]
+
+  /**
+   * Insert a new document into the collection
+   *
+   * @param data - Document to insert (must match schema)
+   * @returns The validated document
+   * @throws If document fails schema validation or primary key already exists
+   */
+  insert(data: T): Promise<T>
+
+  /**
+   * Update one or more documents matching the filter
+   *
+   * @param filter - Documents matching this filter will be updated
+   * @param data - Partial updates to apply (merged with existing data)
+   * @returns Array of updated documents
+   * @throws If updated documents fail schema validation
+   */
+  update(filter: Partial<T>, data: Partial<T>): Promise<T[]>
+
+  /**
+   * Delete one or more documents matching the filter
+   *
+   * @param filter - Documents matching this filter will be deleted
+   * @returns void
+   */
+  delete(filter: Partial<T>): Promise<void>
+
+  /**
+   * Find a single document matching the filter
+   *
+   * @param filter - Equality filter conditions
+   * @returns First matching document or null if not found
+   */
+  findOne(filter: Partial<T>): Promise<T | null>
+
+  /**
+   * Find multiple documents with optional filtering, sorting, and pagination
+   *
+   * @param options - Query options (where, orderBy, limit, offset)
+   * @returns Array of matching documents
+   *
+   * @example
+   * ```typescript
+   * // Get all
+   * const all = await collection.findMany()
+   *
+   * // With filter
+   * const admins = await collection.findMany({
+   *   where: { role: 'admin' }
+   * })
+   *
+   * // With sorting and pagination
+   * const page = await collection.findMany({
+   *   where: { status: 'active' },
+   *   orderBy: { createdAt: 'desc' },
+   *   limit: 20,
+   *   offset: 0
+   * })
+   * ```
+   */
+  findMany(options?: FindManyOptions<T>): Promise<T[]>
+
+  /**
+   * Subscribe to collection changes
+   *
+   * @param callback - Called whenever data changes with current full collection state
+   * @returns Unsubscribe function to remove listener
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = collection.subscribe((data) => {
+   *   console.log('Collection now contains:', data)
+   * })
+   *
+   * // Later: stop listening
+   * unsubscribe()
+   * ```
+   */
+  subscribe(callback: (data: T[]) => void): () => void
+
+  /** Internal: notify all subscribers of changes */
+  _notify(): void
+}
+
+// ============================================================================
+// Database Types
+// ============================================================================
+
+/**
+ * Sync adapter interface for remote synchronization
+ *
+ * @remarks
+ * Implement this interface to add custom sync behavior (WebSockets, server polling, etc.)
+ * The database automatically calls these methods when mutations occur (if optimistic mode enabled)
+ *
+ * @example
+ * ```typescript
+ * const syncAdapter: SyncAdapter = {
+ *   async push(changes) {
+ *     // Send to server
+ *     await fetch('/api/sync', { method: 'POST', body: JSON.stringify(changes) })
+ *   },
+ *   async pull() {
+ *     // Get from server
+ *     const res = await fetch('/api/sync')
+ *     return res.json()
+ *   },
+ *   subscribe(callback) {
+ *     // Listen for remote changes
+ *     const ws = new WebSocket('wss://...')
+ *     ws.onmessage = (e) => callback(e.data)
+ *     return () => ws.close()
+ *   }
+ * }
+ * ```
+ */
+export interface SyncAdapter {
+  /**
+   * Push local changes to remote
+   *
+   * @param changes - Array of change objects to send to remote
+   * @throws Error if push fails - mutation will be rolled back if optimistic
+   */
+  push(changes: unknown[]): Promise<void>
+
+  /**
+   * Pull remote changes
+   *
+   * @returns Array of changes from remote
+   */
+  pull(): Promise<unknown[]>
+
+  /**
+   * Subscribe to remote changes
+   *
+   * @param callback - Called with remote changes
+   * @returns Unsubscribe function
+   */
+  subscribe(callback: (changes: unknown[]) => void): () => void
+}
+
+/**
+ * Database configuration for creating a DB instance
+ *
+ * @example
+ * ```typescript
+ * const config: DBConfig = {
+ *   collections: [usersCollection, todosCollection],
+ *   sync: customSyncAdapter
+ * }
+ * ```
+ */
+export interface DBConfig {
+  /** Collections to register in the database */
+  collections?: Collection<any>[]
+  /** Optional sync adapter for remote synchronization */
+  sync?: SyncAdapter
+}
+
+/**
+ * Database instance - main entry point for accessing collections and syncing
+ *
+ * @remarks
+ * - Collections are accessed by name via `db.collections[name]`
+ * - Provides centralized management of all collections
+ * - Optional sync adapter for remote data synchronization
+ *
+ * @example
+ * ```typescript
+ * const db = createDB({
+ *   collections: [usersCollection, todosCollection],
+ *   sync: syncAdapter
+ * })
+ *
+ * // Access collections
+ * const users = await db.collections.users.findMany()
+ *
+ * // Clear all data
+ * await db.clear()
+ *
+ * // Close resources
+ * db.close()
+ * ```
+ */
+export interface DB {
+  /** Registered collections by name - access with `db.collections[collectionName]` */
+  collections: Record<string, Collection<any>>
+  /** Optional sync adapter if configured */
+  sync?: SyncAdapter
+
+  /**
+   * Close the database connection and clean up resources
+   */
+  close(): void
+
+  /**
+   * Clear all data from all collections
+   *
+   * @returns Promise that resolves when all data is cleared
+   */
+  clear(): Promise<void>
+}
+
+// ============================================================================
+// Hook Types
+// ============================================================================
+
+/**
+ * Options for collection.findMany() - internal collection query
+ *
+ * @template T - The document type
+ *
+ * @remarks
+ * Unlike `QueryOptions`, this doesn't include `from` since it's called on a collection directly
+ *
+ * @example
+ * ```typescript
+ * const options: FindManyOptions<User> = {
+ *   where: { role: 'admin' },
+ *   orderBy: { name: 'asc' },
+ *   limit: 10,
+ *   offset: 0
+ * }
+ * const users = await collection.findMany(options)
+ * ```
+ */
+export interface FindManyOptions<T> {
+  /** Filter conditions using WhereClause syntax */
+  where?: WhereClause<T>
+  /** Sort order - single field or array of fields with directions */
+  orderBy?: OrderByClause<T> | OrderByClause<T>[]
+  /** Maximum number of results to return */
+  limit?: number
+  /** Number of results to skip (for pagination) */
+  offset?: number
+}
+
+/**
+ * Options for useQuery hook - React hook query interface
+ *
+ * @template T - The document type being queried
+ *
+ * @remarks
+ * Extends `FindManyOptions` with `from` to specify which collection to query.
+ * Called within a `DBProvider` context.
+ *
+ * @example
+ * ```typescript
+ * const { data, isLoading, error } = useQuery<User>({
+ *   from: 'users',
+ *   where: { role: 'admin', age: { $gte: 18 } },
+ *   orderBy: { name: 'asc' },
+ *   limit: 20
+ * })
+ * ```
+ */
+export interface QueryOptions<T> extends FindManyOptions<T> {
+  /** Collection name to query from */
+  from: string
+}
+
+/**
+ * Result of useQuery hook - reactive query state and refetch control
+ *
+ * @template T - The document type
+ *
+ * @remarks
+ * - `data` starts as undefined while loading
+ * - `isLoading` is true until first query completes
+ * - Automatically updates when collection changes (reactive)
+ * - Subscribe callbacks automatically re-apply filters and sorting
+ *
+ * @example
+ * ```typescript
+ * const { data, isLoading, error, refetch } = useQuery<User>({
+ *   from: 'users'
+ * })
+ *
+ * if (isLoading) return <Spinner />
+ * if (error) return <Error message={error.message} />
+ *
+ * return (
+ *   <div>
+ *     {data?.map(user => (
+ *       <UserCard key={user.id} user={user} />
+ *     ))}
+ *     <button onClick={refetch}>Refresh</button>
+ *   </div>
+ * )
+ * ```
+ */
+export interface QueryResult<T> {
+  /** Query results - undefined while loading, array when loaded */
+  data: T[] | undefined
+  /** True while initial query is executing */
+  isLoading: boolean
+  /** Error object if query failed, undefined if successful */
+  error: Error | undefined
+  /** Function to manually refetch the query */
+  refetch: () => void
+}
+
+/**
+ * Type of mutation operation
+ *
+ * @example
+ * ```typescript
+ * type Op = MutationOperation
+ * const operation: Op = 'insert'
+ * ```
+ */
+export type MutationOperation = 'insert' | 'update' | 'delete'
+
+/**
+ * Options for useMutation hook
+ *
+ * @remarks
+ * - `insert`: Creates new document
+ * - `update`: Updates existing documents matching filter
+ * - `delete`: Removes documents matching filter
+ * - `optimistic`: If true, updates UI immediately before server confirmation
+ *   (on error, automatically rolls back)
+ *
+ * @example
+ * ```typescript
+ * const { mutate, isPending, error } = useMutation({
+ *   collection: 'users',
+ *   operation: 'insert',
+ *   optimistic: true
+ * })
+ * ```
+ */
+export interface MutationOptions {
+  /** Collection name to mutate */
+  collection: string
+  /** Type of operation: insert, update, or delete */
+  operation: MutationOperation
+  /** Enable optimistic updates (show change immediately, rollback on error) */
+  optimistic?: boolean
+}
+
+/**
+ * Data format for update mutations
+ *
+ * @template T - The document type
+ *
+ * @example
+ * ```typescript
+ * const updateData: UpdateMutationData<User> = {
+ *   where: { id: '1' },
+ *   data: { name: 'Updated Name' }
+ * }
+ * ```
+ */
+export interface UpdateMutationData<T> {
+  /** Filter to select which documents to update */
+  where: Partial<T>
+  /** Partial updates to apply to matching documents */
+  data: Partial<T>
+}
+
+/**
+ * Data format for delete mutations
+ *
+ * @template T - The document type (generic for flexibility)
+ *
+ * @example
+ * ```typescript
+ * const deleteData: DeleteMutationData<User> = {
+ *   id: 'user-123'
+ * }
+ * ```
+ */
+export interface DeleteMutationData<T> {
+  /** ID of document to delete */
+  id: string
+}
+
+/**
+ * Result of useMutation hook - mutation execution and state control
+ *
+ * @template T - The document type
+ *
+ * @remarks
+ * - Call `mutate()` with data to execute the operation
+ * - `isPending` is true while mutation is executing
+ * - On error, `error` contains the Error object
+ * - Use `reset()` to clear error state after handling
+ * - For optimistic updates, local UI updates immediately
+ *   (automatic rollback if sync fails)
+ *
+ * @example
+ * ```typescript
+ * const { mutate, isPending, error, reset } = useMutation<User>({
+ *   collection: 'users',
+ *   operation: 'insert'
+ * })
+ *
+ * const handleCreate = async () => {
+ *   try {
+ *     await mutate({
+ *       id: '2',
+ *       name: 'Bob',
+ *       email: 'bob@example.com',
+ *       role: 'user'
+ *     })
+ *   } catch (err) {
+ *     console.error('Failed:', err)
+ *   }
+ * }
+ *
+ * return (
+ *   <form onSubmit={handleCreate}>
+ *     <button disabled={isPending}>
+ *       {isPending ? 'Creating...' : 'Create'}
+ *     </button>
+ *     {error && <Error message={error.message} onDismiss={reset} />}
+ *   </form>
+ * )
+ * ```
+ */
+export interface MutationResult<T> {
+  /**
+   * Execute the mutation with data
+   * Data format depends on operation: T for insert, UpdateMutationData<T> for update, DeleteMutationData<T> for delete
+   */
+  mutate: (data: T | UpdateMutationData<T> | DeleteMutationData<T>) => Promise<void>
+  /** True while mutation is being executed */
+  isPending: boolean
+  /** Error object if mutation failed, undefined if successful */
+  error: Error | undefined
+  /** Reset mutation state (clears error and pending flags) */
+  reset: () => void
+}