ai-database 2.0.1 → 2.1.1

package/src/tests.ts

@@ -1,725 +0,0 @@
-/**
- * Unified Compliance Test Suite for Database Adapters
- *
- * Provides reusable test factories that any DBClient/DBClientExtended
- * implementation can use to verify compliance with the interface.
- *
- * @example
- * ```ts
- * import { createTests } from 'ai-database/tests'
- * import { createClickHouseDatabase } from '@mdxdb/clickhouse'
- *
- * createTests('ClickHouse', () => createClickHouseDatabase({ url: '...' }))
- * ```
- *
- * @packageDocumentation
- */
-
-import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest'
-import type {
-  DBClient,
-  DBClientExtended,
-  Thing,
-  Relationship,
-  QueryOptions,
-  CreateOptions,
-  Event,
-  Action,
-  Artifact,
-} from './types.js'
-
-// =============================================================================
-// Test Fixtures
-// =============================================================================
-
-export const fixtures = {
-  /** Sample namespace for tests */
-  ns: 'test.example.com',
-
-  /** Sample users */
-  users: [
-    { id: 'user-1', name: 'Alice', email: 'alice@example.com', role: 'admin' },
-    { id: 'user-2', name: 'Bob', email: 'bob@example.com', role: 'user' },
-    { id: 'user-3', name: 'Charlie', email: 'charlie@example.com', role: 'user' },
-  ],
-
-  /** Sample posts */
-  posts: [
-    { id: 'post-1', title: 'Hello World', content: 'First post', authorId: 'user-1' },
-    { id: 'post-2', title: 'Second Post', content: 'More content', authorId: 'user-1' },
-    { id: 'post-3', title: 'Bobs Post', content: 'From Bob', authorId: 'user-2' },
-  ],
-
-  /** Sample tags */
-  tags: [
-    { id: 'tag-1', name: 'typescript' },
-    { id: 'tag-2', name: 'database' },
-    { id: 'tag-3', name: 'testing' },
-  ],
-}
-
-// =============================================================================
-// Test Options
-// =============================================================================
-
-export interface CreateTestsOptions<T extends DBClient = DBClient> {
-  /** Factory function to create the client */
-  factory: () => T | Promise<T>
-  /** Optional cleanup function called after all tests */
-  cleanup?: () => void | Promise<void>
-  /** Skip certain test groups */
-  skip?: {
-    relationships?: boolean
-    search?: boolean
-    events?: boolean
-    actions?: boolean
-    artifacts?: boolean
-  }
-  /** Custom namespace (defaults to fixtures.ns) */
-  ns?: string
-}
-
-// =============================================================================
-// Main Test Factory
-// =============================================================================
-
-/**
- * Create a comprehensive test suite for a DBClient implementation
- *
- * @example Basic usage
- * ```ts
- * import { createTests } from 'ai-database/tests'
- *
- * createTests('Memory', {
- *   factory: () => new MemoryDBClient()
- * })
- * ```
- *
- * @example With cleanup
- * ```ts
- * createTests('SQLite', {
- *   factory: async () => {
- *     const db = await createSQLiteClient({ path: ':memory:' })
- *     return db
- *   },
- *   cleanup: async () => {
- *     // cleanup temp files
- *   }
- * })
- * ```
- *
- * @example Skip certain tests
- * ```ts
- * createTests('Filesystem', {
- *   factory: () => createFsClient({ root: tempDir }),
- *   skip: { events: true, actions: true, artifacts: true }
- * })
- * ```
- */
-export function createTests<T extends DBClient>(
-  name: string,
-  options: CreateTestsOptions<T>
-): void {
-  const { factory, cleanup, skip = {}, ns = fixtures.ns } = options
-
-  describe(`${name} Compliance Tests`, () => {
-    let client: T
-
-    beforeAll(async () => {
-      client = await factory()
-    })
-
-    afterAll(async () => {
-      await client.close?.()
-      await cleanup?.()
-    })
-
-    // =========================================================================
-    // Thing CRUD Operations
-    // =========================================================================
-
-    describe('Things - CRUD', () => {
-      const testThing = {
-        ns,
-        type: 'TestEntity',
-        id: 'crud-test-1',
-        data: { name: 'Test', value: 42 },
-      }
-
-      afterAll(async () => {
-        // Cleanup test data
-        try {
-          await client.delete(`https://${ns}/TestEntity/crud-test-1`)
-          await client.delete(`https://${ns}/TestEntity/crud-test-2`)
-        } catch {
-          // Ignore cleanup errors
-        }
-      })
-
-      it('creates a thing', async () => {
-        const thing = await client.create(testThing)
-
-        expect(thing).toBeDefined()
-        expect(thing.ns).toBe(ns)
-        expect(thing.type).toBe('TestEntity')
-        expect(thing.id).toBe('crud-test-1')
-        expect(thing.data.name).toBe('Test')
-        expect(thing.data.value).toBe(42)
-        expect(thing.createdAt).toBeInstanceOf(Date)
-        expect(thing.updatedAt).toBeInstanceOf(Date)
-      })
-
-      it('gets a thing by URL', async () => {
-        const thing = await client.get(`https://${ns}/TestEntity/crud-test-1`)
-
-        expect(thing).not.toBeNull()
-        expect(thing?.data.name).toBe('Test')
-      })
-
-      it('gets a thing by ID components', async () => {
-        const thing = await client.getById(ns, 'TestEntity', 'crud-test-1')
-
-        expect(thing).not.toBeNull()
-        expect(thing?.data.name).toBe('Test')
-      })
-
-      it('returns null for non-existent thing', async () => {
-        const thing = await client.get(`https://${ns}/TestEntity/does-not-exist`)
-
-        expect(thing).toBeNull()
-      })
-
-      it('updates a thing', async () => {
-        const updated = await client.update(`https://${ns}/TestEntity/crud-test-1`, {
-          data: { name: 'Updated', value: 100 },
-        })
-
-        expect(updated.data.name).toBe('Updated')
-        expect(updated.data.value).toBe(100)
-        expect(updated.updatedAt.getTime()).toBeGreaterThanOrEqual(updated.createdAt.getTime())
-      })
-
-      it('upserts a new thing', async () => {
-        const thing = await client.upsert({
-          ns,
-          type: 'TestEntity',
-          id: 'crud-test-2',
-          data: { name: 'Upserted', value: 200 },
-        })
-
-        expect(thing.id).toBe('crud-test-2')
-        expect(thing.data.name).toBe('Upserted')
-      })
-
-      it('upserts an existing thing', async () => {
-        const thing = await client.upsert({
-          ns,
-          type: 'TestEntity',
-          id: 'crud-test-2',
-          data: { name: 'Upserted Again', value: 300 },
-        })
-
-        expect(thing.data.name).toBe('Upserted Again')
-        expect(thing.data.value).toBe(300)
-      })
-
-      it('deletes a thing', async () => {
-        // Create then delete
-        await client.create({
-          ns,
-          type: 'TestEntity',
-          id: 'to-delete',
-          data: { temp: true },
-        })
-
-        const deleted = await client.delete(`https://${ns}/TestEntity/to-delete`)
-        expect(deleted).toBe(true)
-
-        const thing = await client.get(`https://${ns}/TestEntity/to-delete`)
-        expect(thing).toBeNull()
-      })
-
-      it('returns false when deleting non-existent thing', async () => {
-        const deleted = await client.delete(`https://${ns}/TestEntity/never-existed`)
-        expect(deleted).toBe(false)
-      })
-    })
-
-    // =========================================================================
-    // Query Operations
-    // =========================================================================
-
-    describe('Things - Queries', () => {
-      beforeAll(async () => {
-        // Seed test data
-        for (const user of fixtures.users) {
-          await client.upsert({
-            ns,
-            type: 'User',
-            id: user.id,
-            data: user,
-          })
-        }
-        for (const post of fixtures.posts) {
-          await client.upsert({
-            ns,
-            type: 'Post',
-            id: post.id,
-            data: post,
-          })
-        }
-      })
-
-      afterAll(async () => {
-        // Cleanup
-        for (const user of fixtures.users) {
-          try { await client.delete(`https://${ns}/User/${user.id}`) } catch { /* ignore */ }
-        }
-        for (const post of fixtures.posts) {
-          try { await client.delete(`https://${ns}/Post/${post.id}`) } catch { /* ignore */ }
-        }
-      })
-
-      it('lists all things', async () => {
-        const things = await client.list({ ns })
-
-        expect(things.length).toBeGreaterThanOrEqual(fixtures.users.length + fixtures.posts.length)
-      })
-
-      it('lists things by type', async () => {
-        const users = await client.list({ ns, type: 'User' })
-
-        expect(users.length).toBe(fixtures.users.length)
-        expect(users.every(u => u.type === 'User')).toBe(true)
-      })
-
-      it('finds things with where clause', async () => {
-        const admins = await client.find({
-          ns,
-          type: 'User',
-          where: { role: 'admin' },
-        })
-
-        expect(admins.length).toBe(1)
-        expect(admins[0]?.data.name).toBe('Alice')
-      })
-
-      it('lists with limit', async () => {
-        const things = await client.list({ ns, type: 'User', limit: 2 })
-
-        expect(things.length).toBe(2)
-      })
-
-      it('lists with offset', async () => {
-        const all = await client.list({ ns, type: 'User', orderBy: 'id' })
-        const offset = await client.list({ ns, type: 'User', orderBy: 'id', offset: 1, limit: 2 })
-
-        expect(offset.length).toBe(2)
-        expect(offset[0]?.id).toBe(all[1]?.id)
-      })
-
-      it('lists with ordering', async () => {
-        const asc = await client.list({ ns, type: 'User', orderBy: 'id', order: 'asc' })
-        const desc = await client.list({ ns, type: 'User', orderBy: 'id', order: 'desc' })
-
-        expect(asc[0]?.id).toBe('user-1')
-        expect(desc[0]?.id).toBe('user-3')
-      })
-
-      it('iterates with forEach', async () => {
-        const ids: string[] = []
-
-        await client.forEach({ ns, type: 'User' }, (thing) => {
-          ids.push(thing.id)
-        })
-
-        expect(ids.length).toBe(fixtures.users.length)
-      })
-    })
-
-    // =========================================================================
-    // Search Operations
-    // =========================================================================
-
-    if (!skip.search) {
-      describe('Things - Search', () => {
-        beforeAll(async () => {
-          // Ensure test data exists
-          for (const post of fixtures.posts) {
-            await client.upsert({
-              ns,
-              type: 'Post',
-              id: post.id,
-              data: post,
-            })
-          }
-        })
-
-        it('searches by query string', async () => {
-          const results = await client.search({
-            ns,
-            type: 'Post',
-            query: 'Hello',
-          })
-
-          expect(results.length).toBeGreaterThanOrEqual(1)
-          expect(results.some(r => r.data.title === 'Hello World')).toBe(true)
-        })
-
-        it('searches across fields', async () => {
-          const results = await client.search({
-            ns,
-            type: 'Post',
-            query: 'Bob',
-          })
-
-          expect(results.some(r => r.data.title === 'Bobs Post')).toBe(true)
-        })
-      })
-    }
-
-    // =========================================================================
-    // Relationship Operations
-    // =========================================================================
-
-    if (!skip.relationships) {
-      describe('Relationships', () => {
-        const authorUrl = `https://${ns}/User/user-1`
-        const postUrl = `https://${ns}/Post/post-1`
-
-        beforeAll(async () => {
-          // Ensure entities exist
-          await client.upsert({ ns, type: 'User', id: 'user-1', data: fixtures.users[0]! })
-          await client.upsert({ ns, type: 'Post', id: 'post-1', data: fixtures.posts[0]! })
-        })
-
-        afterAll(async () => {
-          try { await client.unrelate(postUrl, 'author', authorUrl) } catch { /* ignore */ }
-        })
-
-        it('creates a relationship', async () => {
-          const rel = await client.relate({
-            type: 'author',
-            from: postUrl,
-            to: authorUrl,
-          })
-
-          expect(rel).toBeDefined()
-          expect(rel.type).toBe('author')
-          expect(rel.from).toBe(postUrl)
-          expect(rel.to).toBe(authorUrl)
-        })
-
-        it('queries outbound related things', async () => {
-          const authors = await client.related(postUrl, 'author', 'to')
-
-          expect(authors.length).toBe(1)
-          expect(authors[0]?.id).toBe('user-1')
-        })
-
-        it('queries inbound references', async () => {
-          const posts = await client.references(authorUrl, 'author')
-
-          expect(posts.length).toBeGreaterThanOrEqual(1)
-          expect(posts.some(p => p.id === 'post-1')).toBe(true)
-        })
-
-        it('lists relationships', async () => {
-          const rels = await client.relationships(postUrl, 'author')
-
-          expect(rels.length).toBeGreaterThanOrEqual(1)
-          expect(rels[0]?.type).toBe('author')
-        })
-
-        it('removes a relationship', async () => {
-          const removed = await client.unrelate(postUrl, 'author', authorUrl)
-          expect(removed).toBe(true)
-
-          const rels = await client.relationships(postUrl, 'author')
-          expect(rels.length).toBe(0)
-        })
-      })
-    }
-  })
-}
-
-// =============================================================================
-// Extended Test Factory (Events, Actions, Artifacts)
-// =============================================================================
-
-/**
- * Create extended tests for DBClientExtended implementations
- *
- * Includes all DBClient tests plus Events, Actions, and Artifacts
- *
- * @example
- * ```ts
- * import { createExtendedTests } from 'ai-database/tests'
- *
- * createExtendedTests('ClickHouse', {
- *   factory: () => createClickHouseDatabase({ url: '...' })
- * })
- * ```
- */
-export function createExtendedTests<T extends DBClientExtended>(
-  name: string,
-  options: CreateTestsOptions<T>
-): void {
-  const { factory, cleanup, skip = {}, ns = fixtures.ns } = options
-
-  // Run base DBClient tests
-  createTests(name, options as CreateTestsOptions<DBClient>)
-
-  describe(`${name} Extended Compliance Tests`, () => {
-    let client: T
-
-    beforeAll(async () => {
-      client = await factory()
-    })
-
-    afterAll(async () => {
-      await client.close?.()
-      await cleanup?.()
-    })
-
-    // =========================================================================
-    // Event Operations
-    // =========================================================================
-
-    if (!skip.events) {
-      describe('Events', () => {
-        let eventId: string
-
-        it('tracks an event', async () => {
-          const event = await client.track({
-            type: 'User.created',
-            source: 'test-suite',
-            data: { userId: 'user-1', action: 'signup' },
-          })
-
-          eventId = event.id
-
-          expect(event).toBeDefined()
-          expect(event.id).toBeDefined()
-          expect(event.type).toBe('User.created')
-          expect(event.source).toBe('test-suite')
-          expect(event.timestamp).toBeInstanceOf(Date)
-        })
-
-        it('gets an event by ID', async () => {
-          const event = await client.getEvent(eventId)
-
-          expect(event).not.toBeNull()
-          expect(event?.type).toBe('User.created')
-        })
-
-        it('queries events by type', async () => {
-          const events = await client.queryEvents({ type: 'User.created' })
-
-          expect(events.length).toBeGreaterThanOrEqual(1)
-          expect(events.every(e => e.type === 'User.created')).toBe(true)
-        })
-
-        it('queries events by source', async () => {
-          const events = await client.queryEvents({ source: 'test-suite' })
-
-          expect(events.length).toBeGreaterThanOrEqual(1)
-        })
-
-        it('tracks event with correlation ID', async () => {
-          const event = await client.track({
-            type: 'Order.placed',
-            source: 'test-suite',
-            data: { orderId: 'order-1' },
-            correlationId: 'session-123',
-          })
-
-          expect(event.correlationId).toBe('session-123')
-
-          const related = await client.queryEvents({ correlationId: 'session-123' })
-          expect(related.some(e => e.id === event.id)).toBe(true)
-        })
-      })
-    }
-
-    // =========================================================================
-    // Action Operations
-    // =========================================================================
-
-    if (!skip.actions) {
-      describe('Actions', () => {
-        let actionId: string
-
-        it('sends an action (pending)', async () => {
-          const action = await client.send({
-            actor: 'user:test-user',
-            object: `https://${ns}/Order/order-1`,
-            action: 'approve',
-          })
-
-          actionId = action.id
-
-          expect(action).toBeDefined()
-          expect(action.status).toBe('pending')
-          expect(action.actor).toBe('user:test-user')
-          expect(action.action).toBe('approve')
-        })
-
-        it('does an action (active)', async () => {
-          const action = await client.do({
-            actor: 'user:test-user',
-            object: `https://${ns}/Order/order-2`,
-            action: 'process',
-          })
-
-          expect(action.status).toBe('active')
-          expect(action.startedAt).toBeInstanceOf(Date)
-        })
-
-        it('gets an action by ID', async () => {
-          const action = await client.getAction(actionId)
-
-          expect(action).not.toBeNull()
-          expect(action?.action).toBe('approve')
-        })
-
-        it('starts a pending action', async () => {
-          const started = await client.startAction(actionId)
-
-          expect(started.status).toBe('active')
-          expect(started.startedAt).toBeInstanceOf(Date)
-        })
-
-        it('completes an action', async () => {
-          const completed = await client.completeAction(actionId, { approved: true })
-
-          expect(completed.status).toBe('completed')
-          expect(completed.completedAt).toBeInstanceOf(Date)
-          expect(completed.result).toEqual({ approved: true })
-        })
-
-        it('fails an action', async () => {
-          const action = await client.do({
-            actor: 'system',
-            object: `https://${ns}/Task/task-1`,
-            action: 'process',
-          })
-
-          const failed = await client.failAction(action.id, 'Connection timeout')
-
-          expect(failed.status).toBe('failed')
-          expect(failed.error).toBe('Connection timeout')
-        })
-
-        it('cancels an action', async () => {
-          const action = await client.send({
-            actor: 'user:test-user',
-            object: `https://${ns}/Report/report-1`,
-            action: 'generate',
-          })
-
-          const cancelled = await client.cancelAction(action.id)
-
-          expect(cancelled.status).toBe('cancelled')
-        })
-
-        it('queries actions by status', async () => {
-          const completed = await client.queryActions({ status: 'completed' })
-
-          expect(completed.every(a => a.status === 'completed')).toBe(true)
-        })
-
-        it('queries actions by actor', async () => {
-          const actions = await client.queryActions({ actor: 'user:test-user' })
-
-          expect(actions.every(a => a.actor === 'user:test-user')).toBe(true)
-        })
-      })
-    }
-
-    // =========================================================================
-    // Artifact Operations
-    // =========================================================================
-
-    if (!skip.artifacts) {
-      describe('Artifacts', () => {
-        const artifactKey = 'test-artifact-1'
-
-        afterAll(async () => {
-          try { await client.deleteArtifact(artifactKey) } catch { /* ignore */ }
-        })
-
-        it('stores an artifact', async () => {
-          const artifact = await client.storeArtifact({
-            key: artifactKey,
-            type: 'esm',
-            source: `https://${ns}/Module/module-1`,
-            sourceHash: 'abc123',
-            content: 'export const foo = 42',
-          })
-
-          expect(artifact).toBeDefined()
-          expect(artifact.key).toBe(artifactKey)
-          expect(artifact.type).toBe('esm')
-          expect(artifact.content).toBe('export const foo = 42')
-        })
-
-        it('gets an artifact by key', async () => {
-          const artifact = await client.getArtifact(artifactKey)
-
-          expect(artifact).not.toBeNull()
-          expect(artifact?.content).toBe('export const foo = 42')
-        })
-
-        it('gets artifact by source', async () => {
-          const artifact = await client.getArtifactBySource(
-            `https://${ns}/Module/module-1`,
-            'esm'
-          )
-
-          expect(artifact).not.toBeNull()
-          expect(artifact?.key).toBe(artifactKey)
-        })
-
-        it('deletes an artifact', async () => {
-          await client.storeArtifact({
-            key: 'to-delete',
-            type: 'ast',
-            source: `https://${ns}/File/file-1`,
-            sourceHash: 'xyz789',
-            content: { type: 'Program', body: [] },
-          })
-
-          const deleted = await client.deleteArtifact('to-delete')
-          expect(deleted).toBe(true)
-
-          const artifact = await client.getArtifact('to-delete')
-          expect(artifact).toBeNull()
-        })
-
-        it('stores artifact with TTL', async () => {
-          const artifact = await client.storeArtifact({
-            key: 'ttl-artifact',
-            type: 'html',
-            source: `https://${ns}/Page/page-1`,
-            sourceHash: 'def456',
-            content: '<html></html>',
-            ttl: 60000, // 1 minute
-          })
-
-          expect(artifact.expiresAt).toBeInstanceOf(Date)
-          expect(artifact.expiresAt!.getTime()).toBeGreaterThan(Date.now())
-
-          // Cleanup
-          await client.deleteArtifact('ttl-artifact')
-        })
-      })
-    }
-  })
-}
-
-// =============================================================================
-// Re-export for convenience
-// =============================================================================
-
-export { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest'