@mdxui/terminal 2.0.0

package/src/data/collection.ts

@@ -0,0 +1,316 @@
+/**
+ * @mdxui/terminal Collection Implementation
+ *
+ * In-memory collection with Zod validation, reactive subscriptions, filtering,
+ * sorting, and pagination support. Provides full CRUD operations with type safety.
+ */
+
+import type { ZodSchema } from 'zod'
+import type { Collection, FindManyOptions, WhereClause, OrderByClause, FieldFilter } from './types'
+
+/**
+ * Configuration for creating a collection
+ *
+ * @template T - The document type stored in this collection
+ *
+ * @example
+ * ```typescript
+ * const config: CreateCollectionConfig<User> = {
+ *   name: 'users',
+ *   schema: UserSchema,
+ *   primaryKey: 'id',
+ *   indexes: ['email', 'role']
+ * }
+ * ```
+ */
+export interface CreateCollectionConfig<T> {
+  /** Collection name - used to reference in queries and mutations */
+  name: string
+  /** Zod schema for automatic validation on all insert/update operations */
+  schema: ZodSchema<T>
+  /** Primary key field (defaults to 'id'). Used for duplicate detection */
+  primaryKey?: string
+  /** Fields to index for faster queries (metadata only for future optimization) */
+  indexes?: string[]
+}
+
+/**
+ * Check if a value matches a field filter
+ */
+function matchesFilter<T>(value: T, filter: FieldFilter<T>): boolean {
+  // Direct equality
+  if (filter === null || filter === undefined || typeof filter !== 'object') {
+    return value === filter
+  }
+
+  // Comparison operators
+  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 {
+  // Handle $or operator
+  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
+
+    // Check remaining fields (AND with the $or result)
+    const { $or, ...rest } = where
+    if (Object.keys(rest).length === 0) return true
+    return matchesWhere(doc, rest as WhereClause<T>)
+  }
+
+  // Check all field conditions (AND)
+  for (const [key, filter] of Object.entries(where)) {
+    if (key === '$or') continue
+    const value = doc[key]
+    if (!matchesFilter(value, filter as FieldFilter<any>)) {
+      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]
+
+      // Handle null/undefined - put them last
+      if (aVal === null || aVal === undefined) {
+        if (bVal !== null && bVal !== undefined) return 1
+        continue
+      }
+      if (bVal === null || bVal === undefined) return -1
+
+      // Compare values
+      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
+  })
+}
+
+/**
+ * Create a typed in-memory collection with Zod validation
+ *
+ * @template T - The document type (must be a Record for proper typing)
+ *
+ * @param config - Collection configuration (name, schema, primaryKey, indexes)
+ * @returns A fully typed collection instance with CRUD operations and subscriptions
+ *
+ * @remarks
+ * - All documents are validated against the provided Zod schema on insert/update
+ * - Primary key defaults to 'id' if not specified
+ * - 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
+ * - Thread-safe for concurrent operations (in-memory only)
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod'
+ * import { createCollection } from '@mdxui/terminal'
+ *
+ * // Define schema
+ * const UserSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ *   age: z.number().optional(),
+ *   role: z.enum(['admin', 'user', 'guest'])
+ * })
+ *
+ * type User = z.infer<typeof UserSchema>
+ *
+ * // Create collection
+ * const users = createCollection<User>({
+ *   name: 'users',
+ *   schema: UserSchema,
+ *   primaryKey: 'id',
+ *   indexes: ['email', 'role']
+ * })
+ *
+ * // CRUD Operations
+ * const user = await users.insert({
+ *   id: '1',
+ *   name: 'Alice',
+ *   email: 'alice@example.com',
+ *   role: 'admin'
+ * })
+ *
+ * const updated = await users.update(
+ *   { id: '1' },
+ *   { name: 'Alicia' }
+ * )
+ *
+ * const found = await users.findOne({ id: '1' })
+ *
+ * const admins = await users.findMany({
+ *   where: { role: 'admin' },
+ *   orderBy: { name: 'asc' }
+ * })
+ *
+ * await users.delete({ id: '1' })
+ *
+ * // Subscribe to changes
+ * const unsubscribe = users.subscribe((allUsers) => {
+ *   console.log('Users updated:', allUsers)
+ * })
+ * ```
+ */
+export function createCollection<T extends Record<string, any>>(
+  config: CreateCollectionConfig<T>
+): Collection<T> {
+  const { name, schema, primaryKey = 'id', indexes = [] } = config
+
+  // In-memory storage
+  const data = new Map<string, T>()
+  const subscribers = new Set<(data: T[]) => void>()
+
+  const collection: Collection<T> = {
+    name,
+    schema,
+    primaryKey: primaryKey as string,
+    indexes: indexes as string[],
+
+    async insert(doc: T): Promise<T> {
+      // Validate against schema
+      const validated = schema.parse(doc)
+      const id = validated[primaryKey as keyof T]
+
+      // Check for duplicates
+      if (data.has(String(id))) {
+        throw new Error(`Duplicate ${primaryKey}: ${id}`)
+      }
+
+      data.set(String(id), validated)
+      collection._notify()
+      return validated
+    },
+
+    async update(filter: Partial<T>, updates: Partial<T>): Promise<T[]> {
+      const updated: T[] = []
+
+      for (const [key, doc] of data.entries()) {
+        if (matchesWhere(doc, filter as WhereClause<T>)) {
+          const newDoc = { ...doc, ...updates }
+          // Validate updated document
+          const validated = schema.parse(newDoc)
+          data.set(key, validated)
+          updated.push(validated)
+        }
+      }
+
+      if (updated.length > 0) {
+        collection._notify()
+      }
+
+      return updated
+    },
+
+    async delete(filter: Partial<T>): Promise<void> {
+      let deleted = false
+
+      for (const [key, doc] of data.entries()) {
+        if (matchesWhere(doc, filter as WhereClause<T>)) {
+          data.delete(key)
+          deleted = true
+        }
+      }
+
+      if (deleted) {
+        collection._notify()
+      }
+    },
+
+    async findOne(filter: Partial<T>): Promise<T | null> {
+      for (const doc of data.values()) {
+        if (matchesWhere(doc, filter as WhereClause<T>)) {
+          return doc
+        }
+      }
+      return null
+    },
+
+    async findMany(options?: FindManyOptions<T>): Promise<T[]> {
+      let results = Array.from(data.values())
+
+      // Apply where filter
+      if (options?.where) {
+        results = results.filter(doc => matchesWhere(doc, options.where!))
+      }
+
+      // Apply ordering
+      if (options?.orderBy) {
+        results = sortDocuments(results, options.orderBy)
+      }
+
+      // Apply offset
+      if (options?.offset !== undefined) {
+        results = results.slice(options.offset)
+      }
+
+      // Apply limit
+      if (options?.limit !== undefined) {
+        results = results.slice(0, options.limit)
+      }
+
+      return results
+    },
+
+    subscribe(callback: (data: T[]) => void): () => void {
+      subscribers.add(callback)
+      return () => {
+        subscribers.delete(callback)
+      }
+    },
+
+    _notify(): void {
+      const allData = Array.from(data.values())
+      for (const callback of subscribers) {
+        callback(allData)
+      }
+    },
+  }
+
+  return collection
+}

package/src/data/collections.ts

@@ -0,0 +1,50 @@
+/**
+ * @mdxui/terminal SaaS Collections
+ *
+ * TDD RED Phase: This is a stub file that will cause tests to fail with meaningful errors.
+ * The GREEN phase implementation will replace this with actual schemas and collections.
+ *
+ * Pre-built Zod schemas and collections for common SaaS primitives:
+ * - Users: Authentication and user management
+ * - APIKeys: API key management with permissions
+ * - Webhooks: Webhook configuration and event subscriptions
+ * - Teams: Team/organization management with members and plans
+ */
+
+import { z } from 'zod'
+import { createCollection } from './collection'
+import type { Collection } from './types'
+
+// ============================================================================
+// RED PHASE STUBS - These will fail validation tests
+// ============================================================================
+
+// Placeholder schemas that will fail the tests
+// GREEN phase will implement proper schemas
+
+export const UserSchema = z.object({})
+export const APIKeySchema = z.object({})
+export const WebhookSchema = z.object({})
+export const TeamSchema = z.object({})
+
+// Type exports
+export type User = z.infer<typeof UserSchema>
+export type APIKey = z.infer<typeof APIKeySchema>
+export type Webhook = z.infer<typeof WebhookSchema>
+export type Team = z.infer<typeof TeamSchema>
+
+// Placeholder collections that will fail
+export const usersCollection = undefined as unknown as Collection<User>
+export const apiKeysCollection = undefined as unknown as Collection<APIKey>
+export const webhooksCollection = undefined as unknown as Collection<Webhook>
+export const teamsCollection = undefined as unknown as Collection<Team>
+
+// Factory function placeholder
+export function createSaaSCollections() {
+  return {
+    users: undefined as unknown as Collection<User>,
+    apiKeys: undefined as unknown as Collection<APIKey>,
+    webhooks: undefined as unknown as Collection<Webhook>,
+    teams: undefined as unknown as Collection<Team>,
+  }
+}

package/src/data/context.tsx

@@ -0,0 +1,174 @@
+/**
+ * @mdxui/terminal Database Context
+ *
+ * React Context API provider for database access throughout component tree.
+ * Enables hooks like `useQuery` and `useMutation` to access the database
+ * without prop drilling.
+ */
+
+import * as React from 'react'
+import { createContext, useContext, type ReactNode } from 'react'
+import type { DB } from './types'
+
+/**
+ * React Context for database instance
+ *
+ * @remarks
+ * Created as undefined by default - must be provided by DBProvider wrapper.
+ * Used internally by useQuery and useMutation hooks.
+ *
+ * @internal
+ */
+const DBContext = createContext<DB | undefined>(undefined)
+
+/**
+ * Props for DBProvider component
+ *
+ * @example
+ * ```typescript
+ * const props: DBProviderProps = {
+ *   db: myDatabase,
+ *   children: <App />
+ * }
+ * ```
+ */
+export interface DBProviderProps {
+  /** Database instance to provide to all children */
+  db: DB
+  /** React components that will have access to the database */
+  children: ReactNode
+}
+
+/**
+ * Database provider component - wraps your app to provide database context
+ *
+ * Provides database access to all child components via React Context.
+ * Must wrap any component using `useQuery` or `useMutation` hooks.
+ *
+ * @remarks
+ * - Use at the top level of your app (e.g., around `<App />`)
+ * - Can have multiple DBProviders with different database instances
+ * - All useQuery and useMutation hooks must be within a DBProvider
+ * - Throws error if hooks are used outside DBProvider
+ *
+ * @example
+ * ```tsx
+ * import { z } from 'zod'
+ * import { createDB, createCollection, DBProvider } from '@mdxui/terminal'
+ *
+ * // Create database
+ * const db = createDB({
+ *   collections: [usersCollection, todosCollection]
+ * })
+ *
+ * // Wrap app with provider
+ * export function App() {
+ *   return (
+ *     <DBProvider db={db}>
+ *       <UserList />
+ *       <TodoForm />
+ *     </DBProvider>
+ *   )
+ * }
+ *
+ * // Now these hooks work:
+ * function UserList() {
+ *   const { data, isLoading } = useQuery({
+ *     from: 'users',
+ *     where: { role: 'admin' }
+ *   })
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *   return (
+ *     <ul>
+ *       {data?.map(user => (
+ *         <li key={user.id}>{user.name}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function TodoForm() {
+ *   const { mutate, isPending } = useMutation({
+ *     collection: 'todos',
+ *     operation: 'insert'
+ *   })
+ *
+ *   return (
+ *     <form onSubmit={(e) => {
+ *       e.preventDefault()
+ *       mutate({ id: '1', title: 'New', completed: false })
+ *     }}>
+ *       <button disabled={isPending}>Add Todo</button>
+ *     </form>
+ *   )
+ * }
+ * ```
+ */
+export function DBProvider({ db, children }: DBProviderProps): React.ReactElement {
+  return React.createElement(DBContext.Provider, { value: db }, children)
+}
+
+/**
+ * Hook to access the database instance from context
+ *
+ * @returns The database instance from the nearest DBProvider
+ * @throws Error if used outside a DBProvider component
+ *
+ * @remarks
+ * - Must be called within a component tree wrapped by DBProvider
+ * - Allows direct access to collections (advanced use case)
+ * - Most apps use useQuery/useMutation instead
+ * - Useful for manual collection operations outside hooks
+ *
+ * @example
+ * ```tsx
+ * // Direct database access (advanced)
+ * function MyComponent() {
+ *   const db = useDBContext()
+ *
+ *   // Manually query
+ *   const handleClick = async () => {
+ *     const admins = await db.collections.users.findMany({
+ *       where: { role: 'admin' }
+ *     })
+ *     console.log('Admins:', admins)
+ *   }
+ *
+ *   return <button onClick={handleClick}>Get Admins</button>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Subscribe to collection changes (advanced)
+ * function CollectionMonitor() {
+ *   const db = useDBContext()
+ *
+ *   React.useEffect(() => {
+ *     const unsubscribe = db.collections.users.subscribe((users) => {
+ *       console.log('Users changed:', users)
+ *     })
+ *     return unsubscribe
+ *   }, [db])
+ *
+ *   return <div>Monitoring changes...</div>
+ * }
+ * ```
+ */
+export function useDBContext(): DB {
+  const db = useContext(DBContext)
+  if (!db) {
+    throw new Error(
+      'useDBContext must be used within a DBProvider. ' +
+      'Wrap your component with <DBProvider db={...}> at a higher level in the component tree.'
+    )
+  }
+  return db
+}
+
+/**
+ * Internal: Export context for use by other hooks
+ * @internal
+ */
+export { DBContext }

package/src/data/db.ts

@@ -0,0 +1,127 @@
+/**
+ * @mdxui/terminal Database Implementation
+ *
+ * In-memory database with collection management, sync adapter support,
+ * and centralized data access for React applications.
+ */
+
+import type { DB, DBConfig, SyncAdapter, Collection } from './types'
+
+/**
+ * Create a database instance with collections and optional sync adapter
+ *
+ * @param config - Database configuration with collections and sync adapter
+ * @returns A fully typed database instance for accessing collections
+ *
+ * @remarks
+ * - Collections are accessed via `db.collections[name]`
+ * - All data is stored in-memory (cleared on process exit)
+ * - Optional sync adapter can push/pull changes to a remote backend
+ * - Use within `DBProvider` for React applications
+ * - Thread-safe for concurrent operations
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod'
+ * import { createDB, createCollection } from '@mdxui/terminal'
+ *
+ * // Define schemas
+ * const UserSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ *   role: z.enum(['admin', 'user', 'guest'])
+ * })
+ *
+ * // Create collections
+ * const usersCollection = createCollection({
+ *   name: 'users',
+ *   schema: UserSchema,
+ *   primaryKey: 'id'
+ * })
+ *
+ * // Create database with collections
+ * const db = createDB({
+ *   collections: [usersCollection],
+ *   sync: customSyncAdapter // optional
+ * })
+ *
+ * // Access collections
+ * const user = await db.collections.users.insert({
+ *   id: '1',
+ *   name: 'Alice',
+ *   email: 'alice@example.com',
+ *   role: 'admin'
+ * })
+ *
+ * const all = await db.collections.users.findMany()
+ * const admins = await db.collections.users.findMany({
+ *   where: { role: 'admin' }
+ * })
+ *
+ * // Clean up
+ * await db.clear()
+ * db.close()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With sync adapter for remote sync
+ * const syncAdapter = {
+ *   async push(changes) {
+ *     await fetch('/api/sync', {
+ *       method: 'POST',
+ *       body: JSON.stringify(changes)
+ *     })
+ *   },
+ *   async pull() {
+ *     const res = await fetch('/api/sync')
+ *     return res.json()
+ *   },
+ *   subscribe(callback) {
+ *     const ws = new WebSocket('wss://...')
+ *     ws.onmessage = (e) => callback(e.data)
+ *     return () => ws.close()
+ *   }
+ * }
+ *
+ * const db = createDB({
+ *   collections: [usersCollection],
+ *   sync: syncAdapter
+ * })
+ * ```
+ */
+export function createDB(config?: DBConfig): DB {
+  const collections: Record<string, Collection<any>> = {}
+
+  // Register collections
+  if (config?.collections) {
+    for (const collection of config.collections) {
+      collections[collection.name] = collection
+    }
+  }
+
+  const db: DB = {
+    collections,
+    sync: config?.sync,
+
+    close(): void {
+      // Clean up resources
+      // In a real implementation, this would close connections
+    },
+
+    async clear(): Promise<void> {
+      // Clear all data in all collections
+      for (const collection of Object.values(collections)) {
+        // Get all documents and delete them
+        const docs = await collection.findMany()
+        for (const doc of docs) {
+          const primaryKey = collection.primaryKey || 'id'
+          await collection.delete({ [primaryKey]: doc[primaryKey] } as any)
+        }
+      }
+    },
+  }
+
+  return db
+}