digital-objects 1.0.0

package/src/types.ts

@@ -0,0 +1,252 @@
+/**
+ * Core types for Digital Objects
+ *
+ * A unified nouns/verbs/things/actions model that provides:
+ * - Linguistic consistency (singular/plural, conjugations)
+ * - Entity definitions (Nouns) and instances (Things)
+ * - Action definitions (Verbs) and instances (Actions)
+ * - Graph relationships through Actions
+ * - Event sourcing and audit trails
+ */
+
+/**
+ * Query limit constants to prevent memory exhaustion
+ */
+export const DEFAULT_LIMIT = 100
+export const MAX_LIMIT = 1000
+
+/**
+ * Maximum batch size to prevent DoS attacks
+ */
+export const MAX_BATCH_SIZE = 1000
+
+/**
+ * Direction for graph traversal
+ */
+export type Direction = 'in' | 'out' | 'both'
+
+/**
+ * Validates direction parameter for graph traversal methods.
+ * @throws Error if direction is not 'in', 'out', or 'both'
+ */
+export function validateDirection(direction: string): Direction {
+  if (direction !== 'in' && direction !== 'out' && direction !== 'both') {
+    throw new Error(`Invalid direction: "${direction}". Must be "in", "out", or "both".`)
+  }
+  return direction
+}
+
+/**
+ * Noun - Entity type definition with linguistic forms
+ */
+export interface Noun {
+  name: string // 'Post', 'Author'
+  singular: string // 'post', 'author'
+  plural: string // 'posts', 'authors'
+  slug: string // URL-safe: 'post', 'author'
+  description?: string
+  schema?: Record<string, FieldDefinition>
+  createdAt: Date
+}
+
+export interface NounDefinition {
+  name: string
+  singular?: string // Auto-derived if not provided
+  plural?: string // Auto-derived if not provided
+  description?: string
+  schema?: Record<string, FieldDefinition>
+}
+
+/**
+ * Verb - Action definition with all conjugations
+ */
+export interface Verb {
+  name: string // 'create', 'publish'
+  action: string // 'create' (imperative)
+  act: string // 'creates' (3rd person)
+  activity: string // 'creating' (gerund)
+  event: string // 'created' (past participle)
+  reverseBy?: string // 'createdBy'
+  reverseAt?: string // 'createdAt'
+  reverseIn?: string // 'createdIn'
+  inverse?: string // 'delete'
+  description?: string
+  createdAt: Date
+}
+
+export interface VerbDefinition {
+  name: string
+  // All forms auto-derived if not provided
+  action?: string
+  act?: string
+  activity?: string
+  event?: string
+  reverseBy?: string
+  reverseAt?: string
+  reverseIn?: string
+  inverse?: string
+  description?: string
+}
+
+/**
+ * Thing - Entity instance
+ */
+export interface Thing<T = Record<string, unknown>> {
+  id: string
+  noun: string // References noun.name
+  data: T
+  createdAt: Date
+  updatedAt: Date
+}
+
+/**
+ * Action - Events + Relationships + Audit Trail (unified!)
+ *
+ * An action represents:
+ * - A graph edge (subject --verb--> object)
+ * - An event (something happened)
+ * - An audit record (who did what when)
+ */
+export interface Action<T = Record<string, unknown>> {
+  id: string
+  verb: string // References verb.name
+  subject?: string // Thing ID (actor/from)
+  object?: string // Thing ID (target/to)
+  data?: T // Payload/metadata
+  status: ActionStatusType
+  createdAt: Date
+  completedAt?: Date
+}
+
+/**
+ * ActionStatus constants - use these instead of string literals
+ */
+export const ActionStatus = {
+  PENDING: 'pending',
+  ACTIVE: 'active',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled',
+} as const
+
+export type ActionStatusType = (typeof ActionStatus)[keyof typeof ActionStatus]
+
+/**
+ * Field definition for schemas
+ *
+ * Can be either a simple type string or an extended definition with options
+ */
+export type FieldDefinition = SimpleFieldType | ExtendedFieldDefinition
+
+/**
+ * Simple field type - just a type string
+ */
+export type SimpleFieldType =
+  | PrimitiveType
+  | `${string}.${string}` // Relation: 'Author.posts'
+  | `[${string}.${string}]` // Array relation: '[Tag.posts]'
+  | `${PrimitiveType}?` // Optional
+
+/**
+ * Extended field definition with options like required, default, etc.
+ */
+export interface ExtendedFieldDefinition {
+  type: PrimitiveType | 'object' | 'array'
+  required?: boolean
+  default?: unknown
+}
+
+export type PrimitiveType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'datetime'
+  | 'json'
+  | 'markdown'
+  | 'url'
+
+/**
+ * Validation options for create/update operations
+ */
+export interface ValidationOptions {
+  validate?: boolean
+}
+
+/**
+ * List options for queries
+ */
+export interface ListOptions {
+  limit?: number
+  offset?: number
+  where?: Record<string, unknown>
+  orderBy?: string
+  order?: 'asc' | 'desc'
+}
+
+/**
+ * Action query options
+ */
+export interface ActionOptions extends ListOptions {
+  verb?: string
+  subject?: string
+  object?: string
+  status?: ActionStatusType | ActionStatusType[]
+}
+
+/**
+ * DigitalObjectsProvider - Core storage interface
+ *
+ * Implementations: MemoryProvider, NS (DurableObject)
+ */
+export interface DigitalObjectsProvider {
+  // Nouns
+  defineNoun(def: NounDefinition): Promise<Noun>
+  getNoun(name: string): Promise<Noun | null>
+  listNouns(): Promise<Noun[]>
+
+  // Verbs
+  defineVerb(def: VerbDefinition): Promise<Verb>
+  getVerb(name: string): Promise<Verb | null>
+  listVerbs(): Promise<Verb[]>
+
+  // Things
+  create<T>(noun: string, data: T, id?: string, options?: ValidationOptions): Promise<Thing<T>>
+  get<T>(id: string): Promise<Thing<T> | null>
+  list<T>(noun: string, options?: ListOptions): Promise<Thing<T>[]>
+  find<T>(noun: string, where: Partial<T>): Promise<Thing<T>[]>
+  update<T>(id: string, data: Partial<T>, options?: ValidationOptions): Promise<Thing<T>>
+  delete(id: string): Promise<boolean>
+  search<T>(query: string, options?: ListOptions): Promise<Thing<T>[]>
+
+  // Actions (events + edges)
+  perform<T>(verb: string, subject?: string, object?: string, data?: T): Promise<Action<T>>
+  getAction<T>(id: string): Promise<Action<T> | null>
+  listActions<T>(options?: ActionOptions): Promise<Action<T>[]>
+  deleteAction(id: string): Promise<boolean>
+
+  // Graph traversal (via actions)
+  related<T>(
+    id: string,
+    verb?: string,
+    direction?: Direction,
+    options?: ListOptions
+  ): Promise<Thing<T>[]>
+  edges<T>(
+    id: string,
+    verb?: string,
+    direction?: Direction,
+    options?: ListOptions
+  ): Promise<Action<T>[]>
+
+  // Batch operations
+  createMany<T>(noun: string, items: T[]): Promise<Thing<T>[]>
+  updateMany<T>(updates: Array<{ id: string; data: Partial<T> }>): Promise<Thing<T>[]>
+  deleteMany(ids: string[]): Promise<boolean[]>
+  performMany<T>(
+    actions: Array<{ verb: string; subject?: string; object?: string; data?: T }>
+  ): Promise<Action<T>[]>
+
+  // Lifecycle
+  close?(): Promise<void>
+}

package/test/action-status.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest'
+import { ActionStatus, MemoryProvider } from '../src/index.js'
+
+describe('ActionStatus Constants', () => {
+  describe('ActionStatus export', () => {
+    it('should export ActionStatus const object from types', () => {
+      expect(ActionStatus).toBeDefined()
+      expect(typeof ActionStatus).toBe('object')
+    })
+
+    it('should have COMPLETED equal to "completed"', () => {
+      expect(ActionStatus.COMPLETED).toBe('completed')
+    })
+
+    it('should have PENDING equal to "pending"', () => {
+      expect(ActionStatus.PENDING).toBe('pending')
+    })
+
+    it('should have ACTIVE equal to "active"', () => {
+      expect(ActionStatus.ACTIVE).toBe('active')
+    })
+
+    it('should have FAILED equal to "failed"', () => {
+      expect(ActionStatus.FAILED).toBe('failed')
+    })
+
+    it('should have CANCELLED equal to "cancelled"', () => {
+      expect(ActionStatus.CANCELLED).toBe('cancelled')
+    })
+  })
+
+  describe('ActionStatus usage in perform()', () => {
+    it('should return action with status equal to ActionStatus.COMPLETED', async () => {
+      const provider = new MemoryProvider()
+      await provider.defineVerb({ name: 'create' })
+
+      const action = await provider.perform('create')
+
+      expect(action.status).toBe(ActionStatus.COMPLETED)
+    })
+  })
+})

package/test/batch-limits.test.ts

@@ -0,0 +1,165 @@
+/**
+ * TDD RED Phase Tests: Batch Operation Size Limits
+ *
+ * Issue: aip-kl39
+ * Security: Prevent DoS attacks via unlimited batch operations
+ *
+ * These tests should FAIL initially, proving no limits exist.
+ * The GREEN phase (aip-eihe) will add the implementation.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { MemoryProvider } from '../src/memory-provider.js'
+import { ValidationError } from '../src/errors.js'
+import type { DigitalObjectsProvider } from '../src/types.js'
+
+// This constant should be exported from types.ts in GREEN phase
+const EXPECTED_MAX_BATCH_SIZE = 1000
+
+describe('Batch Operation Size Limits', () => {
+  let provider: DigitalObjectsProvider
+
+  beforeEach(() => {
+    provider = new MemoryProvider()
+  })
+
+  describe('MAX_BATCH_SIZE constant', () => {
+    it('should export MAX_BATCH_SIZE constant from types.ts', async () => {
+      // This test verifies that MAX_BATCH_SIZE is exported from types.ts
+      // In RED phase, this will fail because the constant doesn't exist
+      const types = await import('../src/types.js')
+
+      expect(types).toHaveProperty('MAX_BATCH_SIZE')
+      expect((types as { MAX_BATCH_SIZE?: number }).MAX_BATCH_SIZE).toBe(EXPECTED_MAX_BATCH_SIZE)
+    })
+  })
+
+  describe('createMany', () => {
+    it('should reject batch with more than 1000 items', async () => {
+      const items = Array.from({ length: 1001 }, (_, i) => ({ name: `Item ${i}` }))
+
+      await expect(provider.createMany('thing', items)).rejects.toThrow(ValidationError)
+    })
+
+    it('should include batch size in error message', async () => {
+      const items = Array.from({ length: 1001 }, (_, i) => ({ name: `Item ${i}` }))
+
+      try {
+        await provider.createMany('thing', items)
+        expect.fail('Expected ValidationError to be thrown')
+      } catch (error) {
+        expect(error).toBeInstanceOf(ValidationError)
+        expect((error as ValidationError).message).toContain('1000')
+        expect((error as ValidationError).message).toContain('1001')
+      }
+    })
+
+    it('should allow exactly 1000 items', async () => {
+      const items = Array.from({ length: 1000 }, (_, i) => ({ name: `Item ${i}` }))
+
+      // This should not throw - 1000 is the limit, not over it
+      const results = await provider.createMany('thing', items)
+      expect(results).toHaveLength(1000)
+    })
+  })
+
+  describe('updateMany', () => {
+    it('should reject batch with more than 1000 items', async () => {
+      // Create items first
+      const items = Array.from({ length: 10 }, (_, i) => ({ name: `Item ${i}` }))
+      const created = await provider.createMany('thing', items)
+
+      // Try to update more than 1000 (even if they don't exist)
+      const updates = Array.from({ length: 1001 }, (_, i) => ({
+        id: created[i % created.length].id,
+        data: { name: `Updated ${i}` },
+      }))
+
+      await expect(provider.updateMany(updates)).rejects.toThrow(ValidationError)
+    })
+
+    it('should include batch size in error message', async () => {
+      const updates = Array.from({ length: 1001 }, (_, i) => ({
+        id: `fake-id-${i}`,
+        data: { name: `Updated ${i}` },
+      }))
+
+      try {
+        await provider.updateMany(updates)
+        expect.fail('Expected ValidationError to be thrown')
+      } catch (error) {
+        expect(error).toBeInstanceOf(ValidationError)
+        expect((error as ValidationError).message).toContain('1000')
+        expect((error as ValidationError).message).toContain('1001')
+      }
+    })
+  })
+
+  describe('deleteMany', () => {
+    it('should reject batch with more than 1000 items', async () => {
+      const ids = Array.from({ length: 1001 }, (_, i) => `fake-id-${i}`)
+
+      await expect(provider.deleteMany(ids)).rejects.toThrow(ValidationError)
+    })
+
+    it('should include batch size in error message', async () => {
+      const ids = Array.from({ length: 1001 }, (_, i) => `fake-id-${i}`)
+
+      try {
+        await provider.deleteMany(ids)
+        expect.fail('Expected ValidationError to be thrown')
+      } catch (error) {
+        expect(error).toBeInstanceOf(ValidationError)
+        expect((error as ValidationError).message).toContain('1000')
+        expect((error as ValidationError).message).toContain('1001')
+      }
+    })
+  })
+
+  describe('performMany', () => {
+    it('should reject batch with more than 1000 items', async () => {
+      const actions = Array.from({ length: 1001 }, (_, i) => ({
+        verb: 'test',
+        data: { index: i },
+      }))
+
+      await expect(provider.performMany(actions)).rejects.toThrow(ValidationError)
+    })
+
+    it('should include batch size in error message', async () => {
+      const actions = Array.from({ length: 1001 }, (_, i) => ({
+        verb: 'test',
+        data: { index: i },
+      }))
+
+      try {
+        await provider.performMany(actions)
+        expect.fail('Expected ValidationError to be thrown')
+      } catch (error) {
+        expect(error).toBeInstanceOf(ValidationError)
+        expect((error as ValidationError).message).toContain('1000')
+        expect((error as ValidationError).message).toContain('1001')
+      }
+    })
+  })
+
+  describe('Security validation', () => {
+    it('should validate batch size before processing any items', async () => {
+      // This ensures the validation happens BEFORE any expensive operations
+      // Not after processing some items
+      const items = Array.from({ length: 1001 }, (_, i) => ({ name: `Item ${i}` }))
+
+      const startTime = Date.now()
+      try {
+        await provider.createMany('thing', items)
+        expect.fail('Expected ValidationError to be thrown')
+      } catch (error) {
+        const elapsed = Date.now() - startTime
+        // Should fail fast - well under 100ms for just validation
+        // If it takes longer, items are being processed before validation
+        expect(elapsed).toBeLessThan(100)
+        expect(error).toBeInstanceOf(ValidationError)
+      }
+    })
+  })
+})

package/test/docs.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+const CONTENT_DIR = join(__dirname, '../../../content/digital-objects')
+
+describe('Documentation Structure', () => {
+  describe('content/digital-objects/ folder', () => {
+    it('should exist', () => {
+      expect(existsSync(CONTENT_DIR)).toBe(true)
+    })
+
+    it('should have meta.json with proper structure', () => {
+      const metaPath = join(CONTENT_DIR, 'meta.json')
+      expect(existsSync(metaPath)).toBe(true)
+      const meta = JSON.parse(readFileSync(metaPath, 'utf-8'))
+      expect(meta.title).toBe('Digital Objects')
+      expect(meta.root).toBe(true)
+      expect(Array.isArray(meta.pages)).toBe(true)
+    })
+  })
+
+  describe('Required MDX files', () => {
+    const requiredFiles = [
+      'index.mdx',
+      'nouns.mdx',
+      'verbs.mdx',
+      'things.mdx',
+      'actions.mdx',
+      'graph.mdx',
+      'providers.mdx',
+      'r2-persistence.mdx',
+    ]
+
+    for (const file of requiredFiles) {
+      it(`should have ${file}`, () => {
+        expect(existsSync(join(CONTENT_DIR, file))).toBe(true)
+      })
+
+      it(`${file} should have proper frontmatter`, () => {
+        const content = readFileSync(join(CONTENT_DIR, file), 'utf-8')
+        expect(content.startsWith('---')).toBe(true)
+        expect(content).toMatch(/title:\s*.+/)
+        expect(content).toMatch(/description:\s*.+/)
+      })
+    }
+  })
+})

package/test/errors.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest'
+import {
+  DigitalObjectsError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  errorToResponse,
+} from '../src/errors.js'
+import { MemoryProvider } from '../src/memory-provider.js'
+
+describe('Error Classes', () => {
+  describe('DigitalObjectsError', () => {
+    it('should create error with message, code, and statusCode', () => {
+      const error = new DigitalObjectsError('Something went wrong', 'CUSTOM_ERROR', 503)
+
+      expect(error.message).toBe('Something went wrong')
+      expect(error.code).toBe('CUSTOM_ERROR')
+      expect(error.statusCode).toBe(503)
+      expect(error.name).toBe('DigitalObjectsError')
+      expect(error instanceof Error).toBe(true)
+    })
+
+    it('should default statusCode to 500', () => {
+      const error = new DigitalObjectsError('Server error', 'SERVER_ERROR')
+
+      expect(error.statusCode).toBe(500)
+    })
+  })
+
+  describe('NotFoundError', () => {
+    it('should create error with type and id', () => {
+      const error = new NotFoundError('Thing', 'abc-123')
+
+      expect(error.message).toBe('Thing not found: abc-123')
+      expect(error.code).toBe('NOT_FOUND')
+      expect(error.statusCode).toBe(404)
+      expect(error.name).toBe('NotFoundError')
+      expect(error instanceof DigitalObjectsError).toBe(true)
+    })
+  })
+
+  describe('ValidationError', () => {
+    it('should create error with message and field errors', () => {
+      const fieldErrors = [
+        { field: 'email', message: 'Invalid email format' },
+        { field: 'age', message: 'Must be a positive number' },
+      ]
+      const error = new ValidationError('Validation failed', fieldErrors)
+
+      expect(error.message).toBe('Validation failed')
+      expect(error.code).toBe('VALIDATION_ERROR')
+      expect(error.statusCode).toBe(400)
+      expect(error.name).toBe('ValidationError')
+      expect(error.errors).toEqual(fieldErrors)
+      expect(error instanceof DigitalObjectsError).toBe(true)
+    })
+  })
+
+  describe('ConflictError', () => {
+    it('should create error with message', () => {
+      const error = new ConflictError('Resource already exists')
+
+      expect(error.message).toBe('Resource already exists')
+      expect(error.code).toBe('CONFLICT')
+      expect(error.statusCode).toBe(409)
+      expect(error.name).toBe('ConflictError')
+      expect(error instanceof DigitalObjectsError).toBe(true)
+    })
+  })
+})
+
+describe('errorToResponse', () => {
+  it('should convert DigitalObjectsError to HTTP response', () => {
+    const error = new DigitalObjectsError('Custom error', 'CUSTOM', 422)
+    const { body, status } = errorToResponse(error)
+
+    expect(status).toBe(422)
+    expect(body).toEqual({
+      error: 'CUSTOM',
+      message: 'Custom error',
+    })
+  })
+
+  it('should convert NotFoundError to HTTP response', () => {
+    const error = new NotFoundError('User', 'user-123')
+    const { body, status } = errorToResponse(error)
+
+    expect(status).toBe(404)
+    expect(body).toEqual({
+      error: 'NOT_FOUND',
+      message: 'User not found: user-123',
+    })
+  })
+
+  it('should convert ValidationError to HTTP response with field errors', () => {
+    const fieldErrors = [{ field: 'name', message: 'Required' }]
+    const error = new ValidationError('Invalid input', fieldErrors)
+    const { body, status } = errorToResponse(error)
+
+    expect(status).toBe(400)
+    expect(body).toEqual({
+      error: 'VALIDATION_ERROR',
+      message: 'Invalid input',
+      errors: fieldErrors,
+    })
+  })
+
+  it('should convert unknown errors to generic 500 response', () => {
+    const error = new Error('Internal failure')
+    const { body, status } = errorToResponse(error)
+
+    expect(status).toBe(500)
+    expect(body).toEqual({
+      error: 'INTERNAL_ERROR',
+      message: 'An internal error occurred',
+    })
+  })
+
+  it('should convert non-Error values to generic 500 response', () => {
+    const { body, status } = errorToResponse('string error')
+
+    expect(status).toBe(500)
+    expect(body).toEqual({
+      error: 'INTERNAL_ERROR',
+      message: 'An internal error occurred',
+    })
+  })
+})
+
+describe('Provider Error Integration', () => {
+  describe('MemoryProvider', () => {
+    it('should throw NotFoundError when updating non-existent thing', async () => {
+      const provider = new MemoryProvider()
+
+      await expect(provider.update('non-existent-id', { name: 'test' })).rejects.toThrow(
+        NotFoundError
+      )
+
+      try {
+        await provider.update('non-existent-id', { name: 'test' })
+      } catch (error) {
+        expect(error).toBeInstanceOf(NotFoundError)
+        expect((error as NotFoundError).message).toBe('Thing not found: non-existent-id')
+        expect((error as NotFoundError).statusCode).toBe(404)
+      }
+    })
+  })
+})