digital-objects 1.0.0

package/src/ai-database-adapter.ts

@@ -0,0 +1,189 @@
+/**
+ * ai-database Adapter
+ *
+ * Wraps a DigitalObjectsProvider to provide the ai-database DBProvider interface.
+ * This enables ai-database to use digital-objects as its storage backend.
+ */
+
+import type { DigitalObjectsProvider, Thing, ListOptions as DOListOptions } from './types.js'
+
+// These types match ai-database's DBProvider interface
+export interface ListOptions {
+  limit?: number
+  offset?: number
+  where?: Record<string, unknown>
+  orderBy?: string
+  order?: 'asc' | 'desc'
+}
+
+export interface SearchOptions extends ListOptions {
+  fields?: string[]
+}
+
+export interface SemanticSearchOptions extends SearchOptions {
+  embedding?: number[]
+  minScore?: number
+}
+
+export interface HybridSearchOptions extends SearchOptions {
+  semanticWeight?: number
+  ftsWeight?: number
+  minScore?: number
+}
+
+/**
+ * ai-database DBProvider interface (simplified)
+ */
+export interface DBProvider {
+  // Entity operations
+  get(type: string, id: string): Promise<Record<string, unknown> | null>
+  list(type: string, options?: ListOptions): Promise<Record<string, unknown>[]>
+  search(type: string, query: string, options?: SearchOptions): Promise<Record<string, unknown>[]>
+  create(
+    type: string,
+    id: string | undefined,
+    data: Record<string, unknown>
+  ): Promise<Record<string, unknown>>
+  update(type: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>
+  delete(type: string, id: string): Promise<boolean>
+
+  // Relation operations
+  related(type: string, id: string, relation: string): Promise<Record<string, unknown>[]>
+  relate(
+    fromType: string,
+    fromId: string,
+    relation: string,
+    toType: string,
+    toId: string,
+    metadata?: { matchMode?: 'exact' | 'fuzzy'; similarity?: number; matchedType?: string }
+  ): Promise<void>
+  unrelate(
+    fromType: string,
+    fromId: string,
+    relation: string,
+    toType: string,
+    toId: string
+  ): Promise<void>
+}
+
+/**
+ * Convert Thing to entity format (with $id, $type)
+ */
+function thingToEntity<T>(
+  thing: Thing<T>
+): Record<string, unknown> & { $id: string; $type: string } {
+  return {
+    $id: thing.id,
+    $type: thing.noun,
+    ...thing.data,
+  } as Record<string, unknown> & { $id: string; $type: string }
+}
+
+/**
+ * Extract data from entity (remove $id, $type)
+ */
+function entityToData(entity: Record<string, unknown>): Record<string, unknown> {
+  const { $id, $type, ...data } = entity
+  return data
+}
+
+/**
+ * Create a DBProvider adapter from a DigitalObjectsProvider
+ */
+export function createDBProviderAdapter(provider: DigitalObjectsProvider): DBProvider {
+  return {
+    async get(type: string, id: string): Promise<Record<string, unknown> | null> {
+      const thing = await provider.get(id)
+      if (!thing || thing.noun !== type) return null
+      return thingToEntity(thing)
+    },
+
+    async list(type: string, options?: ListOptions): Promise<Record<string, unknown>[]> {
+      const things = await provider.list(type, options as DOListOptions)
+      return things.map(thingToEntity)
+    },
+
+    async search(
+      type: string,
+      query: string,
+      options?: SearchOptions
+    ): Promise<Record<string, unknown>[]> {
+      const things = await provider.search(query, { ...options, where: { ...options?.where } })
+      // Filter by type since search is global
+      return things.filter((t) => t.noun === type).map(thingToEntity)
+    },
+
+    async create(
+      type: string,
+      id: string | undefined,
+      data: Record<string, unknown>
+    ): Promise<Record<string, unknown>> {
+      // Ensure noun is defined
+      const existingNoun = await provider.getNoun(type)
+      if (!existingNoun) {
+        await provider.defineNoun({ name: type })
+      }
+
+      const thing = await provider.create(type, entityToData(data), id)
+      return thingToEntity(thing)
+    },
+
+    async update(
+      _type: string,
+      id: string,
+      data: Record<string, unknown>
+    ): Promise<Record<string, unknown>> {
+      const thing = await provider.update(id, entityToData(data))
+      return thingToEntity(thing)
+    },
+
+    async delete(_type: string, id: string): Promise<boolean> {
+      return provider.delete(id)
+    },
+
+    async related(type: string, id: string, relation: string): Promise<Record<string, unknown>[]> {
+      // ai-database expects related entities of a specific type via a relation
+      // digital-objects uses verb as the relation type
+      const things = await provider.related(id, relation, 'both')
+      // Filter by expected type
+      return things.filter((t) => t.noun === type).map(thingToEntity)
+    },
+
+    async relate(
+      _fromType: string,
+      fromId: string,
+      relation: string,
+      _toType: string,
+      toId: string,
+      metadata?: { matchMode?: 'exact' | 'fuzzy'; similarity?: number; matchedType?: string }
+    ): Promise<void> {
+      // Ensure verb is defined
+      const existingVerb = await provider.getVerb(relation)
+      if (!existingVerb) {
+        await provider.defineVerb({ name: relation })
+      }
+
+      await provider.perform(relation, fromId, toId, metadata)
+    },
+
+    async unrelate(
+      _fromType: string,
+      fromId: string,
+      relation: string,
+      _toType: string,
+      toId: string
+    ): Promise<void> {
+      // Find the action(s) matching this relation and delete them
+      const actions = await provider.listActions({
+        verb: relation,
+        subject: fromId,
+        object: toId,
+      })
+
+      // Delete all matching actions (for GDPR compliance)
+      for (const action of actions) {
+        await provider.deleteAction(action.id)
+      }
+    },
+  }
+}

package/src/benchmark.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createMemoryProvider } from './memory-provider.js'
+import type { DigitalObjectsProvider } from './types.js'
+
+describe('Performance Benchmarks', () => {
+  let provider: DigitalObjectsProvider
+
+  beforeEach(async () => {
+    provider = createMemoryProvider()
+    await provider.defineNoun({ name: 'Item' })
+    await provider.defineVerb({ name: 'link' })
+  })
+
+  describe('create() performance', () => {
+    it('should create 1000 things in under 100ms', async () => {
+      const start = performance.now()
+
+      for (let i = 0; i < 1000; i++) {
+        await provider.create('Item', { index: i, name: `Item ${i}` })
+      }
+
+      const elapsed = performance.now() - start
+      console.log(
+        `create() 1000 items: ${elapsed.toFixed(2)}ms (${((1000 / elapsed) * 1000).toFixed(
+          0
+        )} ops/sec)`
+      )
+      expect(elapsed).toBeLessThan(100)
+    })
+  })
+
+  describe('list() performance', () => {
+    beforeEach(async () => {
+      // Create 10k items
+      for (let i = 0; i < 10000; i++) {
+        await provider.create('Item', { index: i })
+      }
+    })
+
+    it('should list 100 items from 10k in under 10ms', async () => {
+      const start = performance.now()
+
+      const items = await provider.list('Item', { limit: 100 })
+
+      const elapsed = performance.now() - start
+      console.log(`list() 100 from 10k: ${elapsed.toFixed(2)}ms`)
+      expect(items.length).toBe(100)
+      expect(elapsed).toBeLessThan(10)
+    })
+
+    it('should list with where filter in under 50ms', async () => {
+      const start = performance.now()
+
+      const items = await provider.list('Item', { where: { index: 5000 } })
+
+      const elapsed = performance.now() - start
+      console.log(`list() with where: ${elapsed.toFixed(2)}ms`)
+      expect(elapsed).toBeLessThan(50)
+    })
+  })
+
+  describe('related() performance', () => {
+    beforeEach(async () => {
+      // Create graph: 100 items with 10 relations each
+      const items = []
+      for (let i = 0; i < 100; i++) {
+        items.push(await provider.create('Item', { index: i }))
+      }
+      for (let i = 0; i < 100; i++) {
+        for (let j = 0; j < 10; j++) {
+          const target = (i + j + 1) % 100
+          await provider.perform('link', items[i].id, items[target].id)
+        }
+      }
+    })
+
+    it('should traverse relations in under 20ms', async () => {
+      const items = await provider.list('Item', { limit: 1 })
+      const start = performance.now()
+
+      const related = await provider.related(items[0].id, 'link', 'out')
+
+      const elapsed = performance.now() - start
+      console.log(`related() traversal: ${elapsed.toFixed(2)}ms, found ${related.length} items`)
+      expect(elapsed).toBeLessThan(20)
+    })
+  })
+
+  describe('search() performance', () => {
+    beforeEach(async () => {
+      for (let i = 0; i < 1000; i++) {
+        await provider.create('Item', {
+          name: `Item ${i}`,
+          description: `This is a searchable description for item number ${i}`,
+        })
+      }
+    })
+
+    it('should search 1000 items in under 50ms', async () => {
+      const start = performance.now()
+
+      const results = await provider.search('searchable', { limit: 100 })
+
+      const elapsed = performance.now() - start
+      console.log(`search() 1000 items: ${elapsed.toFixed(2)}ms, found ${results.length} results`)
+      expect(elapsed).toBeLessThan(50)
+    })
+  })
+})

package/src/errors.ts

@@ -0,0 +1,91 @@
+/**
+ * Standardized error classes for digital-objects
+ *
+ * These errors provide consistent error handling across all providers
+ * (MemoryProvider, NS Durable Object) with proper HTTP status codes.
+ */
+
+/**
+ * Base error class for all digital-objects errors
+ */
+export class DigitalObjectsError extends Error {
+  constructor(message: string, public code: string, public statusCode: number = 500) {
+    super(message)
+    this.name = 'DigitalObjectsError'
+  }
+}
+
+/**
+ * Thrown when a resource is not found
+ */
+export class NotFoundError extends DigitalObjectsError {
+  constructor(type: string, id: string) {
+    super(`${type} not found: ${id}`, 'NOT_FOUND', 404)
+    this.name = 'NotFoundError'
+  }
+}
+
+/**
+ * Thrown when validation fails
+ */
+export class ValidationError extends DigitalObjectsError {
+  constructor(message: string, public errors: Array<{ field: string; message: string }>) {
+    super(message, 'VALIDATION_ERROR', 400)
+    this.name = 'ValidationError'
+  }
+}
+
+/**
+ * Thrown when there's a conflict (e.g., duplicate ID)
+ */
+export class ConflictError extends DigitalObjectsError {
+  constructor(message: string) {
+    super(message, 'CONFLICT', 409)
+    this.name = 'ConflictError'
+  }
+}
+
+/**
+ * Thrown when a server error occurs (5xx status codes)
+ */
+export class ServerError extends DigitalObjectsError {
+  constructor(message: string, statusCode: number = 500) {
+    super(message, 'SERVER_ERROR', statusCode)
+    this.name = 'ServerError'
+  }
+}
+
+/**
+ * Thrown when a network error occurs (connection refused, timeout, etc.)
+ */
+export class NetworkError extends DigitalObjectsError {
+  constructor(message: string, public cause?: Error) {
+    super(message, 'NETWORK_ERROR', 503)
+    this.name = 'NetworkError'
+  }
+}
+
+/**
+ * Convert an error to an HTTP-safe JSON response body
+ */
+export function errorToResponse(error: unknown): { body: object; status: number } {
+  if (error instanceof DigitalObjectsError) {
+    return {
+      body: {
+        error: error.code,
+        message: error.message,
+        ...(error instanceof ValidationError ? { errors: error.errors } : {}),
+      },
+      status: error.statusCode,
+    }
+  }
+
+  // Don't expose internal error details to clients
+  return {
+    body: {
+      error: 'INTERNAL_ERROR',
+      message: 'An internal error occurred',
+    },
+    status: 500,
+  }
+}

package/src/http-schemas.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod'
+
+export const NounDefinitionSchema = z.object({
+  name: z.string().min(1),
+  singular: z.string().optional(),
+  plural: z.string().optional(),
+  description: z.string().optional(),
+  schema: z.record(z.any()).optional(),
+})
+
+export const VerbDefinitionSchema = z.object({
+  name: z.string().min(1),
+  action: z.string().optional(),
+  act: z.string().optional(),
+  activity: z.string().optional(),
+  event: z.string().optional(),
+  reverseBy: z.string().optional(),
+  inverse: z.string().optional(),
+  description: z.string().optional(),
+})
+
+export const CreateThingSchema = z.object({
+  noun: z.string().min(1),
+  data: z.record(z.any()),
+  id: z.string().optional(),
+})
+
+export const UpdateThingSchema = z.object({
+  data: z.record(z.any()),
+})
+
+export const PerformActionSchema = z.object({
+  verb: z.string().min(1),
+  subject: z.string().optional(),
+  object: z.string().optional(),
+  data: z.any().optional(),
+})
+
+// Batch operation schemas
+export const BatchCreateThingsSchema = z.object({
+  noun: z.string().min(1),
+  items: z.array(z.record(z.any())),
+})
+
+export const BatchUpdateThingsSchema = z.object({
+  updates: z.array(
+    z.object({
+      id: z.string().min(1),
+      data: z.record(z.any()),
+    })
+  ),
+})
+
+export const BatchDeleteThingsSchema = z.object({
+  ids: z.array(z.string().min(1)),
+})
+
+export const BatchPerformActionsSchema = z.object({
+  actions: z.array(
+    z.object({
+      verb: z.string().min(1),
+      subject: z.string().optional(),
+      object: z.string().optional(),
+      data: z.any().optional(),
+    })
+  ),
+})

package/src/index.ts

@@ -0,0 +1,87 @@
+/**
+ * digital-objects - Unified storage primitive for AI primitives
+ *
+ * Core concepts:
+ * - **Nouns**: Entity type definitions (singular/plural/schema)
+ * - **Verbs**: Action definitions (conjugations, reverse forms)
+ * - **Things**: Entity instances (the actual data)
+ * - **Actions**: Events + Relationships + Audit Trail (unified graph edges)
+ *
+ * Providers:
+ * - `MemoryProvider`: In-memory for tests
+ * - `NS`: SQLite in Cloudflare Durable Objects (import from 'digital-objects/ns')
+ *
+ * @packageDocumentation
+ */
+
+// Types
+export type {
+  Noun,
+  NounDefinition,
+  Verb,
+  VerbDefinition,
+  Thing,
+  Action,
+  ActionStatusType,
+  FieldDefinition,
+  PrimitiveType,
+  ListOptions,
+  ActionOptions,
+  DigitalObjectsProvider,
+  Direction,
+} from './types.js'
+
+// Validation utilities and constants
+export { validateDirection, MAX_BATCH_SIZE, ActionStatus } from './types.js'
+
+// Memory Provider
+export { MemoryProvider, createMemoryProvider } from './memory-provider.js'
+
+// Linguistic utilities
+export { deriveNoun, deriveVerb, pluralize, singularize } from './linguistic.js'
+
+// NS Client (for HTTP access to NS Durable Object)
+export { NSClient, createNSClient } from './ns-client.js'
+export type { NSClientOptions } from './ns-client.js'
+
+// R2 Persistence (backup/restore to Cloudflare R2)
+export {
+  createSnapshot,
+  restoreSnapshot,
+  appendWAL,
+  replayWAL,
+  compactWAL,
+  exportJSONL,
+  importJSONL,
+  exportToR2,
+  importFromR2,
+} from './r2-persistence.js'
+export type { Snapshot, WALEntry, SnapshotOptions, SnapshotResult } from './r2-persistence.js'
+
+// ai-database Adapter
+export { createDBProviderAdapter } from './ai-database-adapter.js'
+export type {
+  DBProvider,
+  ListOptions as DBListOptions,
+  SearchOptions,
+  SemanticSearchOptions,
+  HybridSearchOptions,
+} from './ai-database-adapter.js'
+
+// Errors
+export {
+  DigitalObjectsError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  errorToResponse,
+} from './errors.js'
+
+// Schema Validation
+export { validateOnly, validateData } from './schema-validation.js'
+export type {
+  SchemaValidationError,
+  ValidationErrorCode,
+  ValidationResult,
+  ValidationOptions,
+} from './schema-validation.js'