digital-objects 1.0.0

package/test/ns-namespace.test.ts

@@ -0,0 +1,307 @@
+/**
+ * Namespace ID Validation Tests
+ *
+ * Tests for validateNamespaceId() function and worker fetch handler integration.
+ *
+ * Issue: aip-b5g0
+ *
+ * The namespace ID is extracted from the 'ns' query parameter and used to
+ * identify a Durable Object instance. Invalid namespace IDs should be rejected
+ * with a 400 Bad Request response.
+ *
+ * Valid namespace IDs:
+ * - Alphanumeric characters (a-z, A-Z, 0-9)
+ * - Hyphens (-)
+ * - Underscores (_)
+ * - Length: 1-64 characters
+ *
+ * Invalid namespace IDs:
+ * - Empty string
+ * - Dots, slashes, special characters
+ * - Length > 64 characters
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { validateNamespaceId } from '../src/ns.js'
+import worker from '../src/ns.js'
+import type { Env } from '../src/ns.js'
+
+describe('Namespace ID Validation', () => {
+  describe('validateNamespaceId()', () => {
+    describe('valid namespace patterns', () => {
+      it('should accept simple alphanumeric namespaces', () => {
+        expect(validateNamespaceId('default')).toBe(true)
+        expect(validateNamespaceId('tenant1')).toBe(true)
+        expect(validateNamespaceId('MyNamespace')).toBe(true)
+        expect(validateNamespaceId('UPPERCASE')).toBe(true)
+        expect(validateNamespaceId('lowercase')).toBe(true)
+        expect(validateNamespaceId('MixedCase123')).toBe(true)
+      })
+
+      it('should accept namespaces with hyphens', () => {
+        expect(validateNamespaceId('my-namespace')).toBe(true)
+        expect(validateNamespaceId('tenant-1')).toBe(true)
+        expect(validateNamespaceId('a-b-c-d')).toBe(true)
+        expect(validateNamespaceId('My-Mixed-Case')).toBe(true)
+      })
+
+      it('should accept namespaces with underscores', () => {
+        expect(validateNamespaceId('my_namespace')).toBe(true)
+        expect(validateNamespaceId('tenant_1')).toBe(true)
+        expect(validateNamespaceId('a_b_c_d')).toBe(true)
+        expect(validateNamespaceId('My_Mixed_Case')).toBe(true)
+      })
+
+      it('should accept namespaces with mixed hyphens and underscores', () => {
+        expect(validateNamespaceId('my-namespace_v1')).toBe(true)
+        expect(validateNamespaceId('tenant_1-prod')).toBe(true)
+        expect(validateNamespaceId('a_b-c_d')).toBe(true)
+      })
+
+      it('should accept single character namespaces', () => {
+        expect(validateNamespaceId('a')).toBe(true)
+        expect(validateNamespaceId('Z')).toBe(true)
+        expect(validateNamespaceId('1')).toBe(true)
+        expect(validateNamespaceId('_')).toBe(true)
+        expect(validateNamespaceId('-')).toBe(true)
+      })
+
+      it('should accept namespaces starting with numbers', () => {
+        expect(validateNamespaceId('123')).toBe(true)
+        expect(validateNamespaceId('1st-tenant')).toBe(true)
+        expect(validateNamespaceId('2_namespace')).toBe(true)
+      })
+
+      it('should accept maximum length namespace (64 chars)', () => {
+        const maxLengthNs = 'a'.repeat(64)
+        expect(validateNamespaceId(maxLengthNs)).toBe(true)
+      })
+    })
+
+    describe('invalid namespace patterns', () => {
+      it('should reject empty string', () => {
+        expect(validateNamespaceId('')).toBe(false)
+      })
+
+      it('should reject namespaces with dots', () => {
+        expect(validateNamespaceId('namespace.v1')).toBe(false)
+        expect(validateNamespaceId('a.b.c')).toBe(false)
+        expect(validateNamespaceId('.hidden')).toBe(false)
+        expect(validateNamespaceId('trailing.')).toBe(false)
+      })
+
+      it('should reject namespaces with slashes', () => {
+        expect(validateNamespaceId('namespace/v1')).toBe(false)
+        expect(validateNamespaceId('a/b/c')).toBe(false)
+        expect(validateNamespaceId('/leading')).toBe(false)
+        expect(validateNamespaceId('trailing/')).toBe(false)
+        expect(validateNamespaceId('back\\slash')).toBe(false)
+      })
+
+      it('should reject namespaces with special characters', () => {
+        expect(validateNamespaceId('namespace!')).toBe(false)
+        expect(validateNamespaceId('namespace@')).toBe(false)
+        expect(validateNamespaceId('namespace#')).toBe(false)
+        expect(validateNamespaceId('namespace$')).toBe(false)
+        expect(validateNamespaceId('namespace%')).toBe(false)
+        expect(validateNamespaceId('namespace^')).toBe(false)
+        expect(validateNamespaceId('namespace&')).toBe(false)
+        expect(validateNamespaceId('namespace*')).toBe(false)
+        expect(validateNamespaceId('namespace(')).toBe(false)
+        expect(validateNamespaceId('namespace)')).toBe(false)
+        expect(validateNamespaceId('namespace=')).toBe(false)
+        expect(validateNamespaceId('namespace+')).toBe(false)
+        expect(validateNamespaceId('namespace[')).toBe(false)
+        expect(validateNamespaceId('namespace]')).toBe(false)
+        expect(validateNamespaceId('namespace{')).toBe(false)
+        expect(validateNamespaceId('namespace}')).toBe(false)
+        expect(validateNamespaceId('namespace|')).toBe(false)
+        expect(validateNamespaceId('namespace;')).toBe(false)
+        expect(validateNamespaceId('namespace:')).toBe(false)
+        expect(validateNamespaceId("namespace'")).toBe(false)
+        expect(validateNamespaceId('namespace"')).toBe(false)
+        expect(validateNamespaceId('namespace<')).toBe(false)
+        expect(validateNamespaceId('namespace>')).toBe(false)
+        expect(validateNamespaceId('namespace,')).toBe(false)
+        expect(validateNamespaceId('namespace?')).toBe(false)
+        expect(validateNamespaceId('namespace`')).toBe(false)
+        expect(validateNamespaceId('namespace~')).toBe(false)
+      })
+
+      it('should reject namespaces with spaces', () => {
+        expect(validateNamespaceId('my namespace')).toBe(false)
+        expect(validateNamespaceId(' leading')).toBe(false)
+        expect(validateNamespaceId('trailing ')).toBe(false)
+        expect(validateNamespaceId('  ')).toBe(false)
+      })
+
+      it('should reject namespaces exceeding 64 characters', () => {
+        const tooLongNs = 'a'.repeat(65)
+        expect(validateNamespaceId(tooLongNs)).toBe(false)
+      })
+
+      it('should reject very long namespaces', () => {
+        const veryLongNs = 'a'.repeat(100)
+        expect(validateNamespaceId(veryLongNs)).toBe(false)
+
+        const extremelyLongNs = 'a'.repeat(1000)
+        expect(validateNamespaceId(extremelyLongNs)).toBe(false)
+      })
+
+      it('should reject namespaces with unicode characters', () => {
+        expect(validateNamespaceId('namespace\u0000')).toBe(false) // null byte
+        expect(validateNamespaceId('namespace\u00e9')).toBe(false) // é
+        expect(validateNamespaceId('namespace\u4e2d')).toBe(false) // 中
+        expect(validateNamespaceId('\u2603')).toBe(false) // snowman emoji
+      })
+
+      it('should reject namespaces with newlines or tabs', () => {
+        expect(validateNamespaceId('namespace\n')).toBe(false)
+        expect(validateNamespaceId('namespace\r')).toBe(false)
+        expect(validateNamespaceId('namespace\t')).toBe(false)
+        expect(validateNamespaceId('\nleading')).toBe(false)
+      })
+    })
+
+    describe('edge cases', () => {
+      it('should handle boundary length (63, 64, 65 characters)', () => {
+        expect(validateNamespaceId('a'.repeat(63))).toBe(true) // just under
+        expect(validateNamespaceId('a'.repeat(64))).toBe(true) // exactly at limit
+        expect(validateNamespaceId('a'.repeat(65))).toBe(false) // just over
+      })
+    })
+  })
+
+  describe('Worker fetch handler integration', () => {
+    const createMockEnv = (): Env => {
+      const mockStub = {
+        fetch: vi.fn().mockResolvedValue(new Response('OK')),
+      }
+
+      return {
+        NS: {
+          idFromName: vi.fn().mockReturnValue('mock-id'),
+          get: vi.fn().mockReturnValue(mockStub),
+        } as unknown as DurableObjectNamespace,
+      }
+    }
+
+    it('should allow valid namespace and forward to Durable Object', async () => {
+      const env = createMockEnv()
+      const request = new Request('https://example.com/nouns?ns=my-tenant-1')
+
+      const response = await worker.fetch(request, env)
+
+      expect(response.status).toBe(200)
+      expect(env.NS.idFromName).toHaveBeenCalledWith('my-tenant-1')
+    })
+
+    it('should use default namespace when ns parameter is omitted', async () => {
+      const env = createMockEnv()
+      const request = new Request('https://example.com/nouns')
+
+      const response = await worker.fetch(request, env)
+
+      expect(response.status).toBe(200)
+      expect(env.NS.idFromName).toHaveBeenCalledWith('default')
+    })
+
+    it('should return 400 for invalid namespace with dots', async () => {
+      const env = createMockEnv()
+      const request = new Request('https://example.com/nouns?ns=my.namespace')
+
+      const response = await worker.fetch(request, env)
+
+      expect(response.status).toBe(400)
+      const body = await response.json()
+      expect(body.error).toBe('INVALID_NAMESPACE')
+      expect(body.message).toContain('Invalid namespace ID')
+      // Should NOT have called idFromName
+      expect(env.NS.idFromName).not.toHaveBeenCalled()
+    })
+
+    it('should return 400 for invalid namespace with slashes', async () => {
+      const env = createMockEnv()
+      const request = new Request('https://example.com/nouns?ns=namespace/v1')
+
+      const response = await worker.fetch(request, env)
+
+      expect(response.status).toBe(400)
+      const body = await response.json()
+      expect(body.error).toBe('INVALID_NAMESPACE')
+      expect(env.NS.idFromName).not.toHaveBeenCalled()
+    })
+
+    it('should return 400 for invalid namespace with special characters', async () => {
+      const env = createMockEnv()
+      const request = new Request('https://example.com/nouns?ns=' + encodeURIComponent('ns@#$%'))
+
+      const response = await worker.fetch(request, env)
+
+      expect(response.status).toBe(400)
+      const body = await response.json()
+      expect(body.error).toBe('INVALID_NAMESPACE')
+      expect(env.NS.idFromName).not.toHaveBeenCalled()
+    })
+
+    it('should return 400 for namespace exceeding 64 characters', async () => {
+      const env = createMockEnv()
+      const longNs = 'a'.repeat(65)
+      const request = new Request(`https://example.com/nouns?ns=${longNs}`)
+
+      const response = await worker.fetch(request, env)
+
+      expect(response.status).toBe(400)
+      const body = await response.json()
+      expect(body.error).toBe('INVALID_NAMESPACE')
+      expect(env.NS.idFromName).not.toHaveBeenCalled()
+    })
+
+    it('should return 400 for empty namespace string', async () => {
+      const env = createMockEnv()
+      const request = new Request('https://example.com/nouns?ns=')
+
+      const response = await worker.fetch(request, env)
+
+      expect(response.status).toBe(400)
+      const body = await response.json()
+      expect(body.error).toBe('INVALID_NAMESPACE')
+      expect(env.NS.idFromName).not.toHaveBeenCalled()
+    })
+
+    it('should return 400 for namespace with spaces', async () => {
+      const env = createMockEnv()
+      const request = new Request(
+        'https://example.com/nouns?ns=' + encodeURIComponent('my namespace')
+      )
+
+      const response = await worker.fetch(request, env)
+
+      expect(response.status).toBe(400)
+      const body = await response.json()
+      expect(body.error).toBe('INVALID_NAMESPACE')
+      expect(env.NS.idFromName).not.toHaveBeenCalled()
+    })
+
+    it('should allow valid namespaces with hyphens and underscores', async () => {
+      const env = createMockEnv()
+      const request = new Request('https://example.com/nouns?ns=my-tenant_v1')
+
+      const response = await worker.fetch(request, env)
+
+      expect(response.status).toBe(200)
+      expect(env.NS.idFromName).toHaveBeenCalledWith('my-tenant_v1')
+    })
+
+    it('should allow 64-character namespace (boundary test)', async () => {
+      const env = createMockEnv()
+      const maxNs = 'a'.repeat(64)
+      const request = new Request(`https://example.com/nouns?ns=${maxNs}`)
+
+      const response = await worker.fetch(request, env)
+
+      expect(response.status).toBe(200)
+      expect(env.NS.idFromName).toHaveBeenCalledWith(maxNs)
+    })
+  })
+})

package/test/performance.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Performance tests for N+1 query patterns
+ *
+ * These tests verify that related() uses batch queries instead of N+1 patterns.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { createMemoryProvider, MemoryProvider } from '../src/memory-provider.js'
+import type { DigitalObjectsProvider, Thing } from '../src/types.js'
+
+describe('N+1 Query Pattern Prevention', () => {
+  let provider: MemoryProvider
+
+  beforeEach(async () => {
+    provider = createMemoryProvider() as MemoryProvider
+    await provider.defineNoun({ name: 'Item' })
+    await provider.defineVerb({ name: 'link' })
+  })
+
+  describe('related() should use batch query', () => {
+    it('should fetch 100 related items with batch query, not 100 individual queries', async () => {
+      // Create source item
+      const source = await provider.create('Item', { name: 'source' })
+
+      // Create 100 target items and link them
+      const targets: Thing<{ name: string }>[] = []
+      for (let i = 0; i < 100; i++) {
+        const target = await provider.create('Item', { name: `target-${i}` })
+        targets.push(target)
+        await provider.perform('link', source.id, target.id)
+      }
+
+      // Spy on get() to count individual queries
+      const getSpy = vi.spyOn(provider, 'get')
+
+      // Fetch related items
+      const related = await provider.related(source.id, 'link', 'out')
+
+      // Verify we got all related items
+      expect(related).toHaveLength(100)
+
+      // KEY TEST: Should NOT call get() 100 times (N+1 pattern)
+      // With batch query, get() should be called 0 times (uses getMany internally)
+      expect(getSpy).toHaveBeenCalledTimes(0)
+    })
+
+    it('should have getMany() method for batch fetching', async () => {
+      // Test that getMany method exists
+      expect(typeof (provider as any).getMany).toBe('function')
+    })
+
+    it('getMany() should fetch multiple items in single operation', async () => {
+      // Create multiple items
+      const item1 = await provider.create('Item', { name: 'item-1' })
+      const item2 = await provider.create('Item', { name: 'item-2' })
+      const item3 = await provider.create('Item', { name: 'item-3' })
+
+      // Fetch all at once
+      const items = await (provider as any).getMany([item1.id, item2.id, item3.id])
+
+      expect(items).toHaveLength(3)
+      expect(items.map((i: Thing<{ name: string }>) => i.data.name).sort()).toEqual([
+        'item-1',
+        'item-2',
+        'item-3',
+      ])
+    })
+
+    it('getMany() should return empty array for empty input', async () => {
+      const items = await (provider as any).getMany([])
+      expect(items).toEqual([])
+    })
+
+    it('getMany() should skip non-existent IDs', async () => {
+      const item1 = await provider.create('Item', { name: 'item-1' })
+
+      const items = await (provider as any).getMany([
+        item1.id,
+        'non-existent-id-1',
+        'non-existent-id-2',
+      ])
+
+      expect(items).toHaveLength(1)
+      expect(items[0].id).toBe(item1.id)
+    })
+  })
+
+  describe('related() performance benchmark', () => {
+    it('should be faster with batch query than N+1', async () => {
+      // Create source and many targets
+      const source = await provider.create('Item', { name: 'source' })
+      for (let i = 0; i < 100; i++) {
+        const target = await provider.create('Item', { name: `target-${i}` })
+        await provider.perform('link', source.id, target.id)
+      }
+
+      // Benchmark batch query approach
+      const start = performance.now()
+      const related = await provider.related(source.id, 'link', 'out')
+      const batchTime = performance.now() - start
+
+      expect(related).toHaveLength(100)
+
+      // Log performance for visibility
+      console.log(`related() with 100 items: ${batchTime.toFixed(2)}ms`)
+
+      // Should be fast - batch query should complete well under 50ms
+      expect(batchTime).toBeLessThan(50)
+    })
+
+    it('should handle large edge sets efficiently (500 edges)', async () => {
+      const source = await provider.create('Item', { name: 'source' })
+      for (let i = 0; i < 500; i++) {
+        const target = await provider.create('Item', { name: `target-${i}` })
+        await provider.perform('link', source.id, target.id)
+      }
+
+      const start = performance.now()
+      const related = await provider.related(source.id, 'link', 'out')
+      const elapsed = performance.now() - start
+
+      console.log(`related() with 500 items: ${elapsed.toFixed(2)}ms`)
+
+      // With batch query, should still be reasonably fast
+      expect(elapsed).toBeLessThan(200)
+    })
+  })
+
+  describe('related() with direction variations', () => {
+    it('should use batch query for inbound relations', async () => {
+      const target = await provider.create('Item', { name: 'target' })
+
+      // Create 50 sources pointing to this target
+      for (let i = 0; i < 50; i++) {
+        const source = await provider.create('Item', { name: `source-${i}` })
+        await provider.perform('link', source.id, target.id)
+      }
+
+      const getSpy = vi.spyOn(provider, 'get')
+      const inbound = await provider.related(target.id, 'link', 'in')
+
+      expect(inbound).toHaveLength(50)
+      // Should NOT call get() 50 times
+      expect(getSpy).toHaveBeenCalledTimes(0)
+    })
+
+    it('should use batch query for bidirectional relations', async () => {
+      const node = await provider.create('Item', { name: 'node' })
+
+      // Create edges in both directions
+      for (let i = 0; i < 25; i++) {
+        const other = await provider.create('Item', { name: `outbound-${i}` })
+        await provider.perform('link', node.id, other.id)
+      }
+      for (let i = 0; i < 25; i++) {
+        const other = await provider.create('Item', { name: `inbound-${i}` })
+        await provider.perform('link', other.id, node.id)
+      }
+
+      const getSpy = vi.spyOn(provider, 'get')
+      const both = await provider.related(node.id, 'link', 'both')
+
+      expect(both).toHaveLength(50)
+      // Should NOT call get() 50 times
+      expect(getSpy).toHaveBeenCalledTimes(0)
+    })
+  })
+})

package/test/schema-validation-error.test.ts

@@ -0,0 +1,213 @@
+/**
+ * Tests for ValidationError consistency in schema-validation.ts
+ *
+ * These tests verify that validateData() throws ValidationError (not generic Error)
+ * for consistency with the error handling patterns in digital-objects.
+ */
+import { describe, it, expect } from 'vitest'
+import { validateData } from '../src/schema-validation.js'
+import { ValidationError, DigitalObjectsError } from '../src/errors.js'
+import type { FieldDefinition } from '../src/types.js'
+
+describe('ValidationError Consistency', () => {
+  describe('validateData() error type', () => {
+    it('should throw ValidationError, not generic Error', () => {
+      const schema: Record<string, FieldDefinition> = {
+        email: { type: 'string', required: true },
+      }
+
+      let thrownError: unknown
+
+      try {
+        validateData({}, schema, { validate: true })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        thrownError = error
+      }
+
+      // This should be ValidationError, not generic Error
+      expect(thrownError).toBeInstanceOf(ValidationError)
+    })
+
+    it('should NOT throw just a generic Error', () => {
+      const schema: Record<string, FieldDefinition> = {
+        email: { type: 'string', required: true },
+      }
+
+      let thrownError: unknown
+
+      try {
+        validateData({}, schema, { validate: true })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        thrownError = error
+      }
+
+      // Verify constructor name is ValidationError, not just Error
+      expect((thrownError as Error).constructor.name).toBe('ValidationError')
+    })
+  })
+
+  describe('ValidationError inheritance chain', () => {
+    it('should inherit from DigitalObjectsError', () => {
+      const schema: Record<string, FieldDefinition> = {
+        name: { type: 'string', required: true },
+      }
+
+      let thrownError: unknown
+
+      try {
+        validateData({}, schema, { validate: true })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        thrownError = error
+      }
+
+      expect(thrownError).toBeInstanceOf(DigitalObjectsError)
+    })
+
+    it('should also be an instance of Error', () => {
+      const schema: Record<string, FieldDefinition> = {
+        name: { type: 'string', required: true },
+      }
+
+      let thrownError: unknown
+
+      try {
+        validateData({}, schema, { validate: true })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        thrownError = error
+      }
+
+      expect(thrownError).toBeInstanceOf(Error)
+    })
+  })
+
+  describe('ValidationError properties', () => {
+    it('should have proper fieldErrors array', () => {
+      const schema: Record<string, FieldDefinition> = {
+        email: { type: 'string', required: true },
+        age: 'number',
+      }
+
+      let thrownError: unknown
+
+      try {
+        validateData({ age: 'not-a-number' }, schema, { validate: true })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        thrownError = error
+      }
+
+      expect(thrownError).toBeInstanceOf(ValidationError)
+
+      const validationError = thrownError as ValidationError
+      expect(validationError.errors).toBeDefined()
+      expect(Array.isArray(validationError.errors)).toBe(true)
+      expect(validationError.errors.length).toBeGreaterThan(0)
+    })
+
+    it('should have field and message in each error', () => {
+      const schema: Record<string, FieldDefinition> = {
+        email: { type: 'string', required: true },
+      }
+
+      let thrownError: unknown
+
+      try {
+        validateData({}, schema, { validate: true })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        thrownError = error
+      }
+
+      const validationError = thrownError as ValidationError
+
+      for (const fieldError of validationError.errors) {
+        expect(fieldError).toHaveProperty('field')
+        expect(fieldError).toHaveProperty('message')
+        expect(typeof fieldError.field).toBe('string')
+        expect(typeof fieldError.message).toBe('string')
+      }
+    })
+
+    it('should have correct field names in errors', () => {
+      const schema: Record<string, FieldDefinition> = {
+        email: { type: 'string', required: true },
+        name: { type: 'string', required: true },
+      }
+
+      let thrownError: unknown
+
+      try {
+        validateData({}, schema, { validate: true })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        thrownError = error
+      }
+
+      const validationError = thrownError as ValidationError
+      const fieldNames = validationError.errors.map((e) => e.field)
+
+      expect(fieldNames).toContain('email')
+      expect(fieldNames).toContain('name')
+    })
+
+    it('should have VALIDATION_ERROR code', () => {
+      const schema: Record<string, FieldDefinition> = {
+        email: { type: 'string', required: true },
+      }
+
+      let thrownError: unknown
+
+      try {
+        validateData({}, schema, { validate: true })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        thrownError = error
+      }
+
+      const validationError = thrownError as ValidationError
+      expect(validationError.code).toBe('VALIDATION_ERROR')
+    })
+
+    it('should have 400 status code', () => {
+      const schema: Record<string, FieldDefinition> = {
+        email: { type: 'string', required: true },
+      }
+
+      let thrownError: unknown
+
+      try {
+        validateData({}, schema, { validate: true })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        thrownError = error
+      }
+
+      const validationError = thrownError as ValidationError
+      expect(validationError.statusCode).toBe(400)
+    })
+  })
+
+  describe('ValidationError message', () => {
+    it('should contain error count in message', () => {
+      const schema: Record<string, FieldDefinition> = {
+        email: { type: 'string', required: true },
+      }
+
+      let thrownError: unknown
+
+      try {
+        validateData({}, schema, { validate: true })
+        expect.fail('Should have thrown')
+      } catch (error) {
+        thrownError = error
+      }
+
+      const validationError = thrownError as ValidationError
+      expect(validationError.message).toMatch(/Validation failed/)
+    })
+  })
+})