@mdxui/terminal 2.0.0

package/src/__tests__/data/db.test.ts

@@ -0,0 +1,1265 @@
+/**
+ * @mdxui/terminal TanStack DB Integration Tests
+ *
+ * TDD RED Phase: These tests define the contract for TanStack DB integration.
+ * All tests should FAIL initially because the implementation doesn't exist yet.
+ *
+ * The data layer provides:
+ * - createDB() - Database instance creation
+ * - createCollection() - Typed collection with Zod schema validation
+ * - useQuery() - Reactive data queries with filtering and sorting
+ * - useMutation() - Mutations with optimistic updates
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { z } from 'zod'
+import { renderHook, act, waitFor } from '@testing-library/react'
+import * as React from 'react'
+
+// ============================================================================
+// Test Schemas
+// ============================================================================
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  age: z.number().optional(),
+  role: z.enum(['admin', 'user', 'guest']),
+  createdAt: z.date(),
+})
+
+const TodoSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  completed: z.boolean(),
+  priority: z.number().min(1).max(5),
+  userId: z.string(),
+})
+
+type User = z.infer<typeof UserSchema>
+type Todo = z.infer<typeof TodoSchema>
+
+// ============================================================================
+// createDB() Tests
+// ============================================================================
+
+describe('@mdxui/terminal data layer - createDB', () => {
+  it('creates a database instance', async () => {
+    const { createDB } = await import('@mdxui/terminal')
+
+    const db = createDB()
+
+    expect(db).toBeDefined()
+    expect(typeof db).toBe('object')
+  })
+
+  it('accepts collections array configuration', async () => {
+    const { createDB, createCollection } = await import('@mdxui/terminal')
+
+    const usersCollection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    const todosCollection = createCollection({
+      name: 'todos',
+      schema: TodoSchema,
+    })
+
+    const db = createDB({
+      collections: [usersCollection, todosCollection],
+    })
+
+    expect(db).toBeDefined()
+    expect(db.collections).toBeDefined()
+    expect(db.collections.users).toBeDefined()
+    expect(db.collections.todos).toBeDefined()
+  })
+
+  it('accepts sync adapter configuration', async () => {
+    const { createDB } = await import('@mdxui/terminal')
+
+    const mockSyncAdapter = {
+      push: vi.fn(),
+      pull: vi.fn(),
+      subscribe: vi.fn(),
+    }
+
+    const db = createDB({
+      sync: mockSyncAdapter,
+    })
+
+    expect(db).toBeDefined()
+    expect(db.sync).toBe(mockSyncAdapter)
+  })
+
+  it('returns database with standard methods', async () => {
+    const { createDB } = await import('@mdxui/terminal')
+
+    const db = createDB()
+
+    expect(typeof db.close).toBe('function')
+    expect(typeof db.clear).toBe('function')
+  })
+})
+
+// ============================================================================
+// createCollection() Tests
+// ============================================================================
+
+describe('@mdxui/terminal data layer - createCollection', () => {
+  it('creates a typed collection with name and schema', async () => {
+    const { createCollection } = await import('@mdxui/terminal')
+
+    const collection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    expect(collection).toBeDefined()
+    expect(collection.name).toBe('users')
+    expect(collection.schema).toBe(UserSchema)
+  })
+
+  it('validates data against Zod schema on insert', async () => {
+    const { createDB, createCollection } = await import('@mdxui/terminal')
+
+    const usersCollection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    const db = createDB({
+      collections: [usersCollection],
+    })
+
+    const validUser: User = {
+      id: '1',
+      name: 'John Doe',
+      email: 'john@example.com',
+      role: 'user',
+      createdAt: new Date(),
+    }
+
+    // Valid data should not throw
+    await expect(db.collections.users.insert(validUser)).resolves.not.toThrow()
+  })
+
+  it('rejects invalid data on insert', async () => {
+    const { createDB, createCollection } = await import('@mdxui/terminal')
+
+    const usersCollection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    const db = createDB({
+      collections: [usersCollection],
+    })
+
+    const invalidUser = {
+      id: '1',
+      name: 'John Doe',
+      email: 'not-an-email', // Invalid email
+      role: 'user',
+      createdAt: new Date(),
+    }
+
+    await expect(db.collections.users.insert(invalidUser)).rejects.toThrow()
+  })
+
+  it('returns collection with CRUD methods', async () => {
+    const { createCollection } = await import('@mdxui/terminal')
+
+    const collection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    expect(typeof collection.insert).toBe('function')
+    expect(typeof collection.update).toBe('function')
+    expect(typeof collection.delete).toBe('function')
+    expect(typeof collection.findOne).toBe('function')
+    expect(typeof collection.findMany).toBe('function')
+  })
+
+  it('supports primary key configuration', async () => {
+    const { createCollection } = await import('@mdxui/terminal')
+
+    const collection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+      primaryKey: 'id',
+    })
+
+    expect(collection.primaryKey).toBe('id')
+  })
+
+  it('supports optional indexes configuration', async () => {
+    const { createCollection } = await import('@mdxui/terminal')
+
+    const collection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+      indexes: ['email', 'role'],
+    })
+
+    expect(collection.indexes).toContain('email')
+    expect(collection.indexes).toContain('role')
+  })
+})
+
+// ============================================================================
+// useQuery() Hook Tests
+// ============================================================================
+
+describe('@mdxui/terminal data layer - useQuery', () => {
+  // Provider wrapper for hooks
+  let wrapper: React.FC<{ children: React.ReactNode }>
+
+  beforeEach(async () => {
+    const { createDB, createCollection, DBProvider } = await import('@mdxui/terminal')
+
+    const usersCollection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    const db = createDB({
+      collections: [usersCollection],
+    })
+
+    // Seed test data
+    await db.collections.users.insert({
+      id: '1',
+      name: 'Alice',
+      email: 'alice@example.com',
+      age: 30,
+      role: 'admin',
+      createdAt: new Date('2024-01-01'),
+    })
+    await db.collections.users.insert({
+      id: '2',
+      name: 'Bob',
+      email: 'bob@example.com',
+      age: 25,
+      role: 'user',
+      createdAt: new Date('2024-02-01'),
+    })
+    await db.collections.users.insert({
+      id: '3',
+      name: 'Charlie',
+      email: 'charlie@example.com',
+      age: 35,
+      role: 'user',
+      createdAt: new Date('2024-03-01'),
+    })
+
+    wrapper = ({ children }) =>
+      React.createElement(DBProvider, { db }, children)
+  })
+
+  it('returns reactive data from collection', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined()
+      expect(result.current.data).toHaveLength(3)
+    })
+  })
+
+  it('supports from collection parameter', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined()
+    })
+
+    expect(result.current.data?.[0]).toHaveProperty('name')
+    expect(result.current.data?.[0]).toHaveProperty('email')
+  })
+
+  it('supports where filtering with equality', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+          where: { role: 'admin' },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(1)
+      expect(result.current.data?.[0].name).toBe('Alice')
+    })
+  })
+
+  it('supports where filtering with comparison operators', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+          where: { age: { $gt: 28 } },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(2)
+      expect(result.current.data?.every((u) => (u.age ?? 0) > 28)).toBe(true)
+    })
+  })
+
+  it('supports orderBy sorting ascending', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+          orderBy: { age: 'asc' },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(3)
+      expect(result.current.data?.[0].name).toBe('Bob') // age 25
+      expect(result.current.data?.[1].name).toBe('Alice') // age 30
+      expect(result.current.data?.[2].name).toBe('Charlie') // age 35
+    })
+  })
+
+  it('supports orderBy sorting descending', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+          orderBy: { age: 'desc' },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(3)
+      expect(result.current.data?.[0].name).toBe('Charlie') // age 35
+      expect(result.current.data?.[2].name).toBe('Bob') // age 25
+    })
+  })
+
+  it('supports multiple orderBy fields', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+          orderBy: [
+            { role: 'asc' },
+            { age: 'desc' },
+          ],
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(3)
+      // admin first, then users sorted by age desc
+      expect(result.current.data?.[0].role).toBe('admin')
+    })
+  })
+
+  it('updates when data changes', async () => {
+    const { useQuery, createDB, createCollection, DBProvider } = await import('@mdxui/terminal')
+
+    const usersCollection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    const db = createDB({
+      collections: [usersCollection],
+    })
+
+    await db.collections.users.insert({
+      id: '1',
+      name: 'Initial User',
+      email: 'initial@example.com',
+      role: 'user',
+      createdAt: new Date(),
+    })
+
+    const testWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) =>
+      React.createElement(DBProvider, { db }, children)
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+        }),
+      { wrapper: testWrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(1)
+    })
+
+    // Add new user
+    await act(async () => {
+      await db.collections.users.insert({
+        id: '2',
+        name: 'New User',
+        email: 'new@example.com',
+        role: 'admin',
+        createdAt: new Date(),
+      })
+    })
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(2)
+    })
+  })
+
+  it('returns loading state', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+        }),
+      { wrapper }
+    )
+
+    // Initially loading
+    expect(result.current.isLoading).toBe(true)
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false)
+    })
+  })
+
+  it('returns error state on query failure', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'nonexistent_collection' as any,
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.error).toBeDefined()
+    })
+  })
+
+  it('supports limit parameter', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+          limit: 2,
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(2)
+    })
+  })
+
+  it('supports offset parameter', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+          orderBy: { age: 'asc' },
+          offset: 1,
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data?.[0].name).toBe('Alice') // skipped Bob
+    })
+  })
+})
+
+// ============================================================================
+// useMutation() Hook Tests
+// ============================================================================
+
+describe('@mdxui/terminal data layer - useMutation', () => {
+  let wrapper: React.FC<{ children: React.ReactNode }>
+  let db: any
+
+  beforeEach(async () => {
+    const { createDB, createCollection, DBProvider } = await import('@mdxui/terminal')
+
+    const usersCollection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    db = createDB({
+      collections: [usersCollection],
+    })
+
+    await db.collections.users.insert({
+      id: '1',
+      name: 'Alice',
+      email: 'alice@example.com',
+      role: 'admin',
+      createdAt: new Date(),
+    })
+
+    wrapper = ({ children }) =>
+      React.createElement(DBProvider, { db }, children)
+  })
+
+  it('returns mutation function', async () => {
+    const { useMutation } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useMutation({
+          collection: 'users',
+          operation: 'insert',
+        }),
+      { wrapper }
+    )
+
+    expect(result.current.mutate).toBeDefined()
+    expect(typeof result.current.mutate).toBe('function')
+  })
+
+  it('executes insert mutation', async () => {
+    const { useMutation, useQuery } = await import('@mdxui/terminal')
+
+    const { result: mutationResult } = renderHook(
+      () =>
+        useMutation({
+          collection: 'users',
+          operation: 'insert',
+        }),
+      { wrapper }
+    )
+
+    const { result: queryResult } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(queryResult.current.data).toHaveLength(1)
+    })
+
+    await act(async () => {
+      await mutationResult.current.mutate({
+        id: '2',
+        name: 'Bob',
+        email: 'bob@example.com',
+        role: 'user',
+        createdAt: new Date(),
+      })
+    })
+
+    await waitFor(() => {
+      expect(queryResult.current.data).toHaveLength(2)
+    })
+  })
+
+  it('executes update mutation', async () => {
+    const { useMutation, useQuery } = await import('@mdxui/terminal')
+
+    const { result: mutationResult } = renderHook(
+      () =>
+        useMutation({
+          collection: 'users',
+          operation: 'update',
+        }),
+      { wrapper }
+    )
+
+    await act(async () => {
+      await mutationResult.current.mutate({
+        where: { id: '1' },
+        data: { name: 'Alice Updated' },
+      })
+    })
+
+    const { result: queryResult } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+          where: { id: '1' },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(queryResult.current.data?.[0].name).toBe('Alice Updated')
+    })
+  })
+
+  it('executes delete mutation', async () => {
+    const { useMutation, useQuery } = await import('@mdxui/terminal')
+
+    const { result: mutationResult } = renderHook(
+      () =>
+        useMutation({
+          collection: 'users',
+          operation: 'delete',
+        }),
+      { wrapper }
+    )
+
+    await act(async () => {
+      await mutationResult.current.mutate({ id: '1' })
+    })
+
+    const { result: queryResult } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(queryResult.current.data).toHaveLength(0)
+    })
+  })
+
+  it('supports optimistic updates', async () => {
+    const { useMutation, useQuery } = await import('@mdxui/terminal')
+
+    const { result: queryResult } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(queryResult.current.data).toHaveLength(1)
+    })
+
+    const { result: mutationResult } = renderHook(
+      () =>
+        useMutation({
+          collection: 'users',
+          operation: 'insert',
+          optimistic: true,
+        }),
+      { wrapper }
+    )
+
+    // With optimistic update, data should update immediately
+    act(() => {
+      mutationResult.current.mutate({
+        id: '2',
+        name: 'Bob',
+        email: 'bob@example.com',
+        role: 'user',
+        createdAt: new Date(),
+      })
+    })
+
+    // Should immediately reflect the optimistic update
+    expect(queryResult.current.data).toHaveLength(2)
+  })
+
+  it('rolls back optimistic update on error', async () => {
+    const { useMutation, useQuery, createDB, createCollection, DBProvider } =
+      await import('@mdxui/terminal')
+
+    const usersCollection = createCollection({
+      name: 'users',
+      schema: UserSchema,
+    })
+
+    // Create DB with a sync adapter that fails
+    const failingSyncAdapter = {
+      push: vi.fn().mockRejectedValue(new Error('Sync failed')),
+      pull: vi.fn(),
+      subscribe: vi.fn(),
+    }
+
+    const failingDb = createDB({
+      collections: [usersCollection],
+      sync: failingSyncAdapter,
+    })
+
+    await failingDb.collections.users.insert({
+      id: '1',
+      name: 'Alice',
+      email: 'alice@example.com',
+      role: 'admin',
+      createdAt: new Date(),
+    })
+
+    const failingWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) =>
+      React.createElement(DBProvider, { db: failingDb }, children)
+
+    const { result: queryResult } = renderHook(
+      () =>
+        useQuery({
+          from: 'users',
+        }),
+      { wrapper: failingWrapper }
+    )
+
+    await waitFor(() => {
+      expect(queryResult.current.data).toHaveLength(1)
+    })
+
+    const { result: mutationResult } = renderHook(
+      () =>
+        useMutation({
+          collection: 'users',
+          operation: 'insert',
+          optimistic: true,
+        }),
+      { wrapper: failingWrapper }
+    )
+
+    await act(async () => {
+      try {
+        await mutationResult.current.mutate({
+          id: '2',
+          name: 'Bob',
+          email: 'bob@example.com',
+          role: 'user',
+          createdAt: new Date(),
+        })
+      } catch {
+        // Expected to fail
+      }
+    })
+
+    // Should roll back to original state
+    await waitFor(() => {
+      expect(queryResult.current.data).toHaveLength(1)
+    })
+  })
+
+  it('returns isPending state during mutation', async () => {
+    const { useMutation } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useMutation({
+          collection: 'users',
+          operation: 'insert',
+        }),
+      { wrapper }
+    )
+
+    expect(result.current.isPending).toBe(false)
+
+    act(() => {
+      result.current.mutate({
+        id: '2',
+        name: 'Bob',
+        email: 'bob@example.com',
+        role: 'user',
+        createdAt: new Date(),
+      })
+    })
+
+    expect(result.current.isPending).toBe(true)
+
+    await waitFor(() => {
+      expect(result.current.isPending).toBe(false)
+    })
+  })
+
+  it('returns error state on mutation failure', async () => {
+    const { useMutation } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useMutation({
+          collection: 'users',
+          operation: 'insert',
+        }),
+      { wrapper }
+    )
+
+    await act(async () => {
+      try {
+        await result.current.mutate({
+          id: '1', // Duplicate ID should fail
+          name: 'Duplicate',
+          email: 'dup@example.com',
+          role: 'user',
+          createdAt: new Date(),
+        })
+      } catch {
+        // Expected
+      }
+    })
+
+    expect(result.current.error).toBeDefined()
+  })
+})
+
+// ============================================================================
+// Query Filtering Tests
+// ============================================================================
+
+describe('@mdxui/terminal data layer - query filtering', () => {
+  let wrapper: React.FC<{ children: React.ReactNode }>
+
+  beforeEach(async () => {
+    const { createDB, createCollection, DBProvider } = await import('@mdxui/terminal')
+
+    const todosCollection = createCollection({
+      name: 'todos',
+      schema: TodoSchema,
+    })
+
+    const db = createDB({
+      collections: [todosCollection],
+    })
+
+    // Seed test data
+    await db.collections.todos.insert({
+      id: '1',
+      title: 'Buy groceries',
+      completed: false,
+      priority: 3,
+      userId: 'user1',
+    })
+    await db.collections.todos.insert({
+      id: '2',
+      title: 'Write tests',
+      completed: true,
+      priority: 5,
+      userId: 'user1',
+    })
+    await db.collections.todos.insert({
+      id: '3',
+      title: 'Review PR',
+      completed: false,
+      priority: 4,
+      userId: 'user2',
+    })
+    await db.collections.todos.insert({
+      id: '4',
+      title: 'Deploy app',
+      completed: true,
+      priority: 5,
+      userId: 'user2',
+    })
+
+    wrapper = ({ children }) =>
+      React.createElement(DBProvider, { db }, children)
+  })
+
+  it('filters with $eq (equality)', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          where: { completed: { $eq: true } },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(2)
+      expect(result.current.data?.every((t) => t.completed)).toBe(true)
+    })
+  })
+
+  it('filters with $ne (not equal)', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          where: { userId: { $ne: 'user1' } },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(2)
+      expect(result.current.data?.every((t) => t.userId !== 'user1')).toBe(true)
+    })
+  })
+
+  it('filters with $gt (greater than)', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          where: { priority: { $gt: 3 } },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(3)
+      expect(result.current.data?.every((t) => t.priority > 3)).toBe(true)
+    })
+  })
+
+  it('filters with $gte (greater than or equal)', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          where: { priority: { $gte: 4 } },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(3)
+      expect(result.current.data?.every((t) => t.priority >= 4)).toBe(true)
+    })
+  })
+
+  it('filters with $lt (less than)', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          where: { priority: { $lt: 5 } },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(2)
+      expect(result.current.data?.every((t) => t.priority < 5)).toBe(true)
+    })
+  })
+
+  it('filters with $lte (less than or equal)', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          where: { priority: { $lte: 4 } },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(2)
+      expect(result.current.data?.every((t) => t.priority <= 4)).toBe(true)
+    })
+  })
+
+  it('filters with $in (in array)', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          where: { priority: { $in: [3, 5] } },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(3)
+      expect(result.current.data?.every((t) => [3, 5].includes(t.priority))).toBe(
+        true
+      )
+    })
+  })
+
+  it('filters with $nin (not in array)', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          where: { priority: { $nin: [3, 5] } },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(1)
+      expect(result.current.data?.[0].priority).toBe(4)
+    })
+  })
+
+  it('combines multiple where conditions (AND)', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          where: {
+            completed: false,
+            priority: { $gte: 3 },
+          },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(2)
+      expect(result.current.data?.every((t) => !t.completed && t.priority >= 3)).toBe(
+        true
+      )
+    })
+  })
+
+  it('filters with $or operator', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          where: {
+            $or: [{ priority: 5 }, { userId: 'user1' }],
+          },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data).toHaveLength(3)
+    })
+  })
+})
+
+// ============================================================================
+// Query Sorting Tests
+// ============================================================================
+
+describe('@mdxui/terminal data layer - query sorting', () => {
+  let wrapper: React.FC<{ children: React.ReactNode }>
+
+  beforeEach(async () => {
+    const { createDB, createCollection, DBProvider } = await import('@mdxui/terminal')
+
+    const todosCollection = createCollection({
+      name: 'todos',
+      schema: TodoSchema,
+    })
+
+    const db = createDB({
+      collections: [todosCollection],
+    })
+
+    await db.collections.todos.insert({
+      id: '1',
+      title: 'A task',
+      completed: false,
+      priority: 3,
+      userId: 'user1',
+    })
+    await db.collections.todos.insert({
+      id: '2',
+      title: 'B task',
+      completed: true,
+      priority: 3,
+      userId: 'user2',
+    })
+    await db.collections.todos.insert({
+      id: '3',
+      title: 'C task',
+      completed: false,
+      priority: 1,
+      userId: 'user1',
+    })
+
+    wrapper = ({ children }) =>
+      React.createElement(DBProvider, { db }, children)
+  })
+
+  it('sorts by single field ascending', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          orderBy: { title: 'asc' },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data?.[0].title).toBe('A task')
+      expect(result.current.data?.[1].title).toBe('B task')
+      expect(result.current.data?.[2].title).toBe('C task')
+    })
+  })
+
+  it('sorts by single field descending', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          orderBy: { title: 'desc' },
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      expect(result.current.data?.[0].title).toBe('C task')
+      expect(result.current.data?.[2].title).toBe('A task')
+    })
+  })
+
+  it('sorts by multiple fields', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'todos',
+          orderBy: [
+            { priority: 'asc' },
+            { title: 'desc' },
+          ],
+        }),
+      { wrapper }
+    )
+
+    await waitFor(() => {
+      // Priority 1 first
+      expect(result.current.data?.[0].priority).toBe(1)
+      // Then priority 3, sorted by title desc (B before A)
+      expect(result.current.data?.[1].title).toBe('B task')
+      expect(result.current.data?.[2].title).toBe('A task')
+    })
+  })
+
+  it('handles null/undefined values in sort', async () => {
+    const { createDB, createCollection, DBProvider, useQuery } = await import('@mdxui/terminal')
+
+    const SchemaWithOptional = z.object({
+      id: z.string(),
+      name: z.string(),
+      score: z.number().optional(),
+    })
+
+    const collection = createCollection({
+      name: 'items',
+      schema: SchemaWithOptional,
+    })
+
+    const db = createDB({
+      collections: [collection],
+    })
+
+    await db.collections.items.insert({ id: '1', name: 'A', score: 10 })
+    await db.collections.items.insert({ id: '2', name: 'B' }) // no score
+    await db.collections.items.insert({ id: '3', name: 'C', score: 5 })
+
+    const testWrapper: React.FC<{ children: React.ReactNode }> = ({ children }) =>
+      React.createElement(DBProvider, { db }, children)
+
+    const { result } = renderHook(
+      () =>
+        useQuery({
+          from: 'items',
+          orderBy: { score: 'asc' },
+        }),
+      { wrapper: testWrapper }
+    )
+
+    await waitFor(() => {
+      // Nulls should be last or first consistently
+      expect(result.current.data).toHaveLength(3)
+    })
+  })
+})
+
+// ============================================================================
+// DBProvider Tests
+// ============================================================================
+
+describe('@mdxui/terminal data layer - DBProvider', () => {
+  it('exports DBProvider component', async () => {
+    const { DBProvider } = await import('@mdxui/terminal')
+
+    expect(DBProvider).toBeDefined()
+  })
+
+  it('provides database context to children', async () => {
+    const { createDB, DBProvider, useDBContext } = await import('@mdxui/terminal')
+
+    const db = createDB()
+
+    const wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) =>
+      React.createElement(DBProvider, { db }, children)
+
+    const { result } = renderHook(() => useDBContext(), { wrapper })
+
+    expect(result.current).toBe(db)
+  })
+
+  it('throws error when useQuery used outside DBProvider', async () => {
+    const { useQuery } = await import('@mdxui/terminal')
+
+    expect(() =>
+      renderHook(() =>
+        useQuery({
+          from: 'users',
+        })
+      )
+    ).toThrow()
+  })
+})