@mdxui/terminal 2.0.0

package/src/data/hooks.ts

@@ -0,0 +1,532 @@
+/**
+ * @mdxui/terminal Data Hooks
+ *
+ * React hooks for reactive queries and mutations with optimistic updates.
+ * Provides type-safe hooks for querying and mutating database collections
+ * within a DBProvider context.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react'
+import { useDBContext } from './context'
+import type {
+  QueryOptions,
+  QueryResult,
+  MutationOptions,
+  MutationResult,
+  WhereClause,
+  OrderByClause,
+  UpdateMutationData,
+  DeleteMutationData,
+} from './types'
+
+/**
+ * Check if a value matches a field filter
+ */
+function matchesFilter<T>(value: T, filter: any): boolean {
+  if (filter === null || filter === undefined || typeof filter !== 'object') {
+    return value === filter
+  }
+
+  const ops = filter as Record<string, any>
+
+  if ('$eq' in ops && value !== ops.$eq) return false
+  if ('$ne' in ops && value === ops.$ne) return false
+  if ('$gt' in ops && !(value > ops.$gt)) return false
+  if ('$gte' in ops && !(value >= ops.$gte)) return false
+  if ('$lt' in ops && !(value < ops.$lt)) return false
+  if ('$lte' in ops && !(value <= ops.$lte)) return false
+  if ('$in' in ops && !ops.$in.includes(value)) return false
+  if ('$nin' in ops && ops.$nin.includes(value)) return false
+
+  return true
+}
+
+/**
+ * Check if a document matches a where clause
+ */
+function matchesWhere<T extends Record<string, any>>(doc: T, where: WhereClause<T>): boolean {
+  if ('$or' in where && where.$or) {
+    const orClauses = where.$or as WhereClause<T>[]
+    const matchesOr = orClauses.some(clause => matchesWhere(doc, clause))
+    if (!matchesOr) return false
+
+    const { $or, ...rest } = where
+    if (Object.keys(rest).length === 0) return true
+    return matchesWhere(doc, rest as WhereClause<T>)
+  }
+
+  for (const [key, filter] of Object.entries(where)) {
+    if (key === '$or') continue
+    const value = doc[key]
+    if (!matchesFilter(value, filter)) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Sort documents by orderBy clause
+ */
+function sortDocuments<T extends Record<string, any>>(
+  docs: T[],
+  orderBy: OrderByClause<T> | OrderByClause<T>[]
+): T[] {
+  const orderClauses = Array.isArray(orderBy) ? orderBy : [orderBy]
+
+  return [...docs].sort((a, b) => {
+    for (const clause of orderClauses) {
+      const [field, direction] = Object.entries(clause)[0]
+      const aVal = a[field]
+      const bVal = b[field]
+
+      if (aVal === null || aVal === undefined) {
+        if (bVal !== null && bVal !== undefined) return 1
+        continue
+      }
+      if (bVal === null || bVal === undefined) return -1
+
+      let comparison = 0
+      if (typeof aVal === 'string') {
+        comparison = aVal.localeCompare(bVal)
+      } else if (typeof aVal === 'number') {
+        comparison = aVal - bVal
+      } else if (aVal instanceof Date) {
+        comparison = aVal.getTime() - bVal.getTime()
+      } else {
+        comparison = String(aVal).localeCompare(String(bVal))
+      }
+
+      if (comparison !== 0) {
+        return direction === 'desc' ? -comparison : comparison
+      }
+    }
+    return 0
+  })
+}
+
+/**
+ * React hook for reactive data queries with filtering, sorting, and pagination
+ *
+ * @template T - The document type being queried
+ *
+ * @param options - Query options (collection name, filters, sorting, pagination)
+ * @returns Query result with reactive data, loading/error states, and refetch control
+ *
+ * @remarks
+ * - Must be used within a DBProvider component
+ * - Automatically fetches initial data on mount
+ * - Reactively updates when collection changes (subscriptions)
+ * - Filters, sorting, and pagination are re-applied when data changes
+ * - `data` is undefined while loading, array when loaded
+ * - `isLoading` is true for the initial fetch only
+ * - Manual refetch available via `refetch()` function
+ * - Error state persists until query succeeds
+ *
+ * @example
+ * ```tsx
+ * // Basic query - get all documents
+ * function AllUsers() {
+ *   const { data, isLoading, error } = useQuery({
+ *     from: 'users'
+ *   })
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *   if (error) return <div>Error: {error.message}</div>
+ *
+ *   return (
+ *     <ul>
+ *       {data?.map(user => (
+ *         <li key={user.id}>{user.name}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With filtering
+ * function AdminUsers() {
+ *   const { data } = useQuery({
+ *     from: 'users',
+ *     where: { role: 'admin' }
+ *   })
+ *
+ *   return data?.map(user => <AdminCard key={user.id} user={user} />)
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With sorting and pagination
+ * function UsersPaginated() {
+ *   const { data, refetch } = useQuery({
+ *     from: 'users',
+ *     where: { status: 'active' },
+ *     orderBy: { createdAt: 'desc' },
+ *     limit: 20,
+ *     offset: 0
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <Users data={data} />
+ *       <button onClick={refetch}>Refresh</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With comparison operators
+ * function AdultUsers() {
+ *   const { data } = useQuery({
+ *     from: 'users',
+ *     where: { age: { $gte: 18 } }
+ *   })
+ *
+ *   return data?.map(user => <Card key={user.id} user={user} />)
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With OR conditions
+ * function AdminsOrModerators() {
+ *   const { data } = useQuery({
+ *     from: 'users',
+ *     where: {
+ *       $or: [
+ *         { role: 'admin' },
+ *         { role: 'moderator' }
+ *       ]
+ *     }
+ *   })
+ *
+ *   return data?.map(user => <Card key={user.id} user={user} />)
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With multiple sort fields
+ * function UsersSorted() {
+ *   const { data } = useQuery({
+ *     from: 'users',
+ *     orderBy: [
+ *       { role: 'asc' },
+ *       { name: 'asc' }
+ *     ]
+ *   })
+ *
+ *   return data?.map(user => <Card key={user.id} user={user} />)
+ * }
+ * ```
+ */
+export function useQuery<T extends Record<string, any>>(
+  options: QueryOptions<T>
+): QueryResult<T> {
+  const db = useDBContext()
+  const [data, setData] = useState<T[] | undefined>(undefined)
+  const [isLoading, setIsLoading] = useState(true)
+  const [error, setError] = useState<Error | undefined>(undefined)
+
+  const { from, where, orderBy, limit, offset } = options
+
+  // Get collection
+  const collection = db.collections[from]
+
+  const executeQuery = useCallback(async () => {
+    if (!collection) {
+      setError(new Error(`Collection '${from}' not found`))
+      setIsLoading(false)
+      return
+    }
+
+    try {
+      const result = await collection.findMany({ where, orderBy, limit, offset })
+      setData(result)
+      setError(undefined)
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)))
+    } finally {
+      setIsLoading(false)
+    }
+  }, [collection, from, JSON.stringify(where), JSON.stringify(orderBy), limit, offset])
+
+  // Initial fetch
+  useEffect(() => {
+    executeQuery()
+  }, [executeQuery])
+
+  // Subscribe to collection changes
+  useEffect(() => {
+    if (!collection) return
+
+    const unsubscribe = collection.subscribe((allData: T[]) => {
+      // Re-apply filters when data changes
+      let result = allData
+
+      if (where) {
+        result = result.filter(doc => matchesWhere(doc, where))
+      }
+
+      if (orderBy) {
+        result = sortDocuments(result, orderBy)
+      }
+
+      if (offset !== undefined) {
+        result = result.slice(offset)
+      }
+
+      if (limit !== undefined) {
+        result = result.slice(0, limit)
+      }
+
+      setData(result)
+    })
+
+    return unsubscribe
+  }, [collection, JSON.stringify(where), JSON.stringify(orderBy), limit, offset])
+
+  return {
+    data,
+    isLoading,
+    error,
+    refetch: executeQuery,
+  }
+}
+
+/**
+ * React hook for data mutations (insert, update, delete) with optimistic updates
+ *
+ * @template T - The document type being mutated
+ *
+ * @param options - Mutation options (collection, operation, optimistic mode)
+ * @returns Mutation result with mutate function, pending/error states, and reset
+ *
+ * @remarks
+ * - Must be used within a DBProvider component
+ * - Supports three operations: insert, update, delete
+ * - Optimistic updates: UI updates immediately, rolls back on error
+ * - Manual updates: UI updates only after server confirmation
+ * - `isPending` is true while mutation is executing
+ * - Error state persists until mutation succeeds or `reset()` is called
+ * - Data format depends on operation type:
+ *   - `insert`: T (full document)
+ *   - `update`: UpdateMutationData<T> (where + data)
+ *   - `delete`: DeleteMutationData<T> (id)
+ * - Sync adapter is called when optimistic=true and sync is configured
+ *
+ * @example
+ * ```tsx
+ * // Insert with optimistic update
+ * function CreateUserForm() {
+ *   const { mutate, isPending, error, reset } = useMutation({
+ *     collection: 'users',
+ *     operation: 'insert',
+ *     optimistic: true
+ *   })
+ *
+ *   const handleSubmit = async (formData) => {
+ *     try {
+ *       await mutate({
+ *         id: crypto.randomUUID(),
+ *         name: formData.name,
+ *         email: formData.email,
+ *         role: 'user'
+ *       })
+ *       console.log('User created!')
+ *     } catch (err) {
+ *       console.error('Failed to create user')
+ *     }
+ *   }
+ *
+ *   return (
+ *     <form onSubmit={async (e) => {
+ *       e.preventDefault()
+ *       await handleSubmit(Object.fromEntries(new FormData(e.currentTarget)))
+ *     }}>
+ *       <input name="name" required />
+ *       <input name="email" type="email" required />
+ *       <button disabled={isPending}>
+ *         {isPending ? 'Creating...' : 'Create'}
+ *       </button>
+ *       {error && (
+ *         <div>
+ *           <p>Error: {error.message}</p>
+ *           <button onClick={reset}>Dismiss</button>
+ *         </div>
+ *       )}
+ *     </form>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Update mutation
+ * function EditUserForm({ userId }) {
+ *   const { mutate, isPending } = useMutation({
+ *     collection: 'users',
+ *     operation: 'update'
+ *   })
+ *
+ *   const handleSave = async (updates) => {
+ *     await mutate({
+ *       where: { id: userId },
+ *       data: updates
+ *     })
+ *   }
+ *
+ *   return <Form onSave={handleSave} disabled={isPending} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Delete mutation
+ * function DeleteUserButton({ userId }) {
+ *   const { mutate, isPending } = useMutation({
+ *     collection: 'users',
+ *     operation: 'delete'
+ *   })
+ *
+ *   const handleDelete = async () => {
+ *     if (confirm('Really delete?')) {
+ *       await mutate({ id: userId })
+ *     }
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleDelete} disabled={isPending}>
+ *       {isPending ? 'Deleting...' : 'Delete'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Optimistic vs non-optimistic
+ * function UserActions() {
+ *   // UI updates immediately, auto-rollback on error
+ *   const { mutate: optimisticInsert } = useMutation({
+ *     collection: 'users',
+ *     operation: 'insert',
+ *     optimistic: true  // Default UI update
+ *   })
+ *
+ *   // UI updates only after server confirms
+ *   const { mutate: carefullInsert } = useMutation({
+ *     collection: 'users',
+ *     operation: 'insert',
+ *     optimistic: false  // Wait for server
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => optimisticInsert(newUser)}>
+ *         Quick Add (optimistic)
+ *       </button>
+ *       <button onClick={() => carefullInsert(newUser)}>
+ *         Safe Add (wait for server)
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useMutation<T extends Record<string, any>>(
+  options: MutationOptions
+): MutationResult<T> {
+  const db = useDBContext()
+  const [isPending, setIsPending] = useState(false)
+  const [error, setError] = useState<Error | undefined>(undefined)
+
+  const { collection: collectionName, operation, optimistic = false } = options
+
+  // Get collection
+  const collection = db.collections[collectionName]
+
+  // Store for rollback
+  const rollbackRef = useRef<(() => void) | null>(null)
+
+  const mutate = useCallback(
+    async (mutationData: T | UpdateMutationData<T> | DeleteMutationData<T>) => {
+      if (!collection) {
+        throw new Error(`Collection '${collectionName}' not found`)
+      }
+
+      setIsPending(true)
+      setError(undefined)
+
+      // Optimistic update storage
+      let rollbackFn: (() => void) | null = null
+
+      try {
+        if (operation === 'insert') {
+          const insertData = mutationData as T
+
+          if (optimistic) {
+            // Optimistically add to the local store immediately
+            // This triggers the subscription update
+            await collection.insert(insertData)
+
+            // If sync fails, we need to rollback
+            if (db.sync) {
+              try {
+                await db.sync.push([{ type: 'insert', collection: collectionName, data: insertData }])
+              } catch (syncError) {
+                // Rollback: delete the optimistically inserted data
+                const primaryKey = collection.primaryKey || 'id'
+                await collection.delete({ [primaryKey]: (insertData as any)[primaryKey] } as any)
+                throw syncError
+              }
+            }
+          } else {
+            await collection.insert(insertData)
+            if (db.sync) {
+              await db.sync.push([{ type: 'insert', collection: collectionName, data: insertData }])
+            }
+          }
+        } else if (operation === 'update') {
+          const updateData = mutationData as UpdateMutationData<T>
+          await collection.update(updateData.where, updateData.data)
+          if (db.sync) {
+            await db.sync.push([{ type: 'update', collection: collectionName, data: updateData }])
+          }
+        } else if (operation === 'delete') {
+          const deleteData = mutationData as DeleteMutationData<T>
+          await collection.delete({ id: deleteData.id } as any)
+          if (db.sync) {
+            await db.sync.push([{ type: 'delete', collection: collectionName, data: deleteData }])
+          }
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err))
+        setError(error)
+        throw error
+      } finally {
+        setIsPending(false)
+        rollbackRef.current = null
+      }
+    },
+    [collection, collectionName, operation, optimistic, db.sync]
+  )
+
+  const reset = useCallback(() => {
+    setIsPending(false)
+    setError(undefined)
+  }, [])
+
+  return {
+    mutate,
+    isPending,
+    error,
+    reset,
+  }
+}

package/src/data/index.ts

@@ -0,0 +1,138 @@
+/**
+ * @mdxui/terminal Data Layer
+ *
+ * TanStack DB-like integration for reactive data management.
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   createDB,
+ *   createCollection,
+ *   DBProvider,
+ *   useQuery,
+ *   useMutation,
+ * } from '@mdxui/terminal'
+ * import { z } from 'zod'
+ *
+ * // Define schema
+ * const UserSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * })
+ *
+ * // Create collection
+ * const usersCollection = createCollection({
+ *   name: 'users',
+ *   schema: UserSchema,
+ * })
+ *
+ * // Create database
+ * const db = createDB({
+ *   collections: [usersCollection],
+ * })
+ *
+ * // Use in React
+ * function App() {
+ *   return (
+ *     <DBProvider db={db}>
+ *       <UserList />
+ *     </DBProvider>
+ *   )
+ * }
+ *
+ * function UserList() {
+ *   const { data, isLoading } = useQuery({
+ *     from: 'users',
+ *     where: { role: 'admin' },
+ *   })
+ *
+ *   const { mutate } = useMutation({
+ *     collection: 'users',
+ *     operation: 'insert',
+ *   })
+ *
+ *   // ...
+ * }
+ * ```
+ */
+
+// Core functions
+export { createDB } from './db'
+export { createCollection } from './collection'
+export { createDOSync } from './sync'
+export type { DOSyncConfig, DOSyncAdapter, ReconnectOptions, ConflictResolution } from './sync'
+
+// React context
+export { DBProvider, useDBContext } from './context'
+export type { DBProviderProps } from './context'
+
+// React hooks
+export { useQuery, useMutation } from './hooks'
+
+// Reactive data hooks for data components (Table, List, Card, Metrics)
+export {
+  useReactiveData,
+  useReactiveTable,
+  useReactiveList,
+  useReactiveMetrics,
+  useReactiveCard,
+} from './reactive'
+export type {
+  SortState,
+  SelectionState,
+  PaginationState,
+  ReactiveDataOptions,
+  ReactiveDataResult,
+  ReactiveTableOptions,
+  ReactiveListOptions,
+  ReactiveMetricsOptions,
+  MetricValue,
+  ReactiveMetricsResult,
+  ReactiveCardOptions,
+  ReactiveCardResult,
+} from './reactive'
+
+// SaaS Collections
+export {
+  // Factory functions
+  UsersCollection,
+  APIKeysCollection,
+  WebhooksCollection,
+  TeamsCollection,
+  UsageCollection,
+  // Schemas
+  UserSchema,
+  UserRoleSchema,
+  APIKeySchema,
+  WebhookSchema,
+  TeamSchema,
+  UsageSchema,
+} from './saas-collections'
+export type {
+  User,
+  UserRole,
+  APIKey,
+  Webhook,
+  Team,
+  Usage,
+} from './saas-collections'
+
+// Types
+export type {
+  DB,
+  DBConfig,
+  Collection,
+  SyncAdapter,
+  FindManyOptions,
+  QueryOptions,
+  QueryResult,
+  MutationOptions,
+  MutationResult,
+  WhereClause,
+  OrderByClause,
+  ComparisonOperators,
+  FieldFilter,
+  OrderDirection,
+  MutationOperation,
+} from './types'