ai-workflows 2.1.3 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflows",
-  "version": "2.1.3",
+  "version": "2.3.0",
   "description": "Event-driven workflows with state machine support",
   "type": "module",
   "main": "dist/index.js",
@@ -9,11 +9,36 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./worker": {
+      "import": "./dist/worker/index.js",
+      "types": "./dist/worker/index.d.ts"
+    },
+    "./durable-execution": {
+      "import": "./dist/durable-execution.js",
+      "types": "./dist/durable-execution.d.ts"
     }
   },
-  "dependencies": {},
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:workers": "vitest --config vitest.workers.config.ts",
+    "test:workers:coverage": "vitest run --config vitest.workers.config.ts --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@org.ai/types": "2.3.0",
+    "digital-objects": "1.1.0"
+  },
   "devDependencies": {
-    "vitest": "^2.1.0"
+    "@cloudflare/vitest-pool-workers": "^0.8.0",
+    "@cloudflare/workers-types": "^4.20250109.0",
+    "vitest": "^2.1.0",
+    "wrangler": "^4.0.0"
   },
   "keywords": [
     "ai",
@@ -22,13 +47,5 @@
     "state-machine",
     "primitives"
   ],
-  "license": "MIT",
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "vitest",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "clean": "rm -rf dist"
-  }
-}
+  "license": "MIT"
+}

package/src/__tests__/digital-objects-adapter.test.ts

@@ -0,0 +1,274 @@
+/**
+ * Tests for digital-objects adapter
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createMemoryProvider, type DigitalObjectsProvider } from 'digital-objects'
+import {
+  createDigitalObjectsAdapter,
+  createSimpleAdapter,
+  type DigitalObjectsDatabaseContext,
+} from '../digital-objects-adapter.js'
+import type { DatabaseContext } from '../types.js'
+
+describe('createDigitalObjectsAdapter', () => {
+  let provider: DigitalObjectsProvider
+  let adapter: DigitalObjectsDatabaseContext
+
+  beforeEach(async () => {
+    provider = createMemoryProvider()
+    adapter = await createDigitalObjectsAdapter(provider)
+  })
+
+  describe('auto-definition', () => {
+    it('should define workflow nouns', async () => {
+      const workflowNoun = await provider.getNoun('Workflow')
+      expect(workflowNoun).not.toBeNull()
+      expect(workflowNoun?.name).toBe('Workflow')
+
+      const artifactNoun = await provider.getNoun('Artifact')
+      expect(artifactNoun).not.toBeNull()
+
+      const scheduleNoun = await provider.getNoun('Schedule')
+      expect(scheduleNoun).not.toBeNull()
+
+      const cascadeNoun = await provider.getNoun('Cascade')
+      expect(cascadeNoun).not.toBeNull()
+    })
+
+    it('should define workflow verbs', async () => {
+      const emitVerb = await provider.getVerb('emit')
+      expect(emitVerb).not.toBeNull()
+      expect(emitVerb?.name).toBe('emit')
+
+      const executeVerb = await provider.getVerb('execute')
+      expect(executeVerb).not.toBeNull()
+
+      const completeVerb = await provider.getVerb('complete')
+      expect(completeVerb).not.toBeNull()
+
+      const stepVerb = await provider.getVerb('step')
+      expect(stepVerb).not.toBeNull()
+    })
+
+    it('should skip definition if already defined', async () => {
+      // Create another adapter - should not throw
+      const adapter2 = await createDigitalObjectsAdapter(provider)
+      expect(adapter2).toBeDefined()
+    })
+
+    it('should skip auto-definition when disabled', async () => {
+      const freshProvider = createMemoryProvider()
+      await createDigitalObjectsAdapter(freshProvider, { autoDefine: true })
+
+      // Nouns should be defined
+      const workflowNoun = await freshProvider.getNoun('Workflow')
+      expect(workflowNoun).not.toBeNull()
+    })
+  })
+
+  describe('recordEvent', () => {
+    it('should record events as Actions', async () => {
+      await adapter.recordEvent('Customer.created', { name: 'John', email: 'john@example.com' })
+
+      const actions = await provider.listActions({ verb: 'emit' })
+      expect(actions.length).toBe(1)
+      expect(actions[0]?.data).toMatchObject({
+        event: 'Customer.created',
+        data: { name: 'John', email: 'john@example.com' },
+      })
+    })
+
+    it('should associate events with workflow when workflowId is set', async () => {
+      const adapterWithWorkflow = await createDigitalObjectsAdapter(provider, {
+        workflowId: 'wf-123',
+      })
+
+      await adapterWithWorkflow.recordEvent('Order.completed', { orderId: 'order-1' })
+
+      const actions = await provider.listActions({ verb: 'emit', subject: 'wf-123' })
+      expect(actions.length).toBe(1)
+    })
+  })
+
+  describe('createAction', () => {
+    it('should create actions with proper verb', async () => {
+      await adapter.createAction({
+        actor: 'user-1',
+        object: 'document-1',
+        action: 'edit',
+        status: 'pending',
+        metadata: { changes: ['title'] },
+      })
+
+      const actions = await provider.listActions({ verb: 'edit' })
+      expect(actions.length).toBe(1)
+      expect(actions[0]?.subject).toBe('user-1')
+      expect(actions[0]?.object).toBe('document-1')
+    })
+  })
+
+  describe('completeAction', () => {
+    it('should record completion as an action', async () => {
+      // First create an action
+      const action = await provider.perform('process', 'worker', 'task-1', {})
+
+      // Complete it
+      await adapter.completeAction(action.id, { success: true, output: 'done' })
+
+      // Verify completion action was recorded
+      const completions = await provider.listActions({ verb: 'complete' })
+      expect(completions.length).toBe(1)
+      expect(completions[0]?.object).toBe(action.id)
+      expect(completions[0]?.data).toMatchObject({
+        result: { success: true, output: 'done' },
+      })
+    })
+  })
+
+  describe('artifacts', () => {
+    it('should store artifacts as Things', async () => {
+      await adapter.storeArtifact({
+        key: 'ast-hash-123',
+        type: 'ast',
+        sourceHash: 'abc123',
+        content: { type: 'Program', body: [] },
+        metadata: { language: 'javascript' },
+      })
+
+      const thing = await provider.get('ast-hash-123')
+      expect(thing).not.toBeNull()
+      expect(thing?.noun).toBe('Artifact')
+      expect(thing?.data).toMatchObject({
+        key: 'ast-hash-123',
+        type: 'ast',
+        sourceHash: 'abc123',
+      })
+    })
+
+    it('should retrieve artifact content', async () => {
+      await adapter.storeArtifact({
+        key: 'compiled-module',
+        type: 'esm',
+        sourceHash: 'def456',
+        content: 'export default function() {}',
+      })
+
+      const content = await adapter.getArtifact('compiled-module')
+      expect(content).toBe('export default function() {}')
+    })
+
+    it('should return null for non-existent artifact', async () => {
+      const content = await adapter.getArtifact('does-not-exist')
+      expect(content).toBeNull()
+    })
+
+    it('should include workflowId when set', async () => {
+      const adapterWithWorkflow = await createDigitalObjectsAdapter(provider, {
+        workflowId: 'wf-456',
+      })
+
+      await adapterWithWorkflow.storeArtifact({
+        key: 'workflow-artifact',
+        type: 'bundle',
+        sourceHash: 'ghi789',
+        content: { bundled: true },
+      })
+
+      const thing = await provider.get('workflow-artifact')
+      expect(thing?.data).toHaveProperty('workflowId', 'wf-456')
+    })
+  })
+
+  describe('extended methods', () => {
+    it('should provide access to provider', () => {
+      expect(adapter.provider).toBe(provider)
+    })
+
+    it('should get workflow by id', async () => {
+      await provider.create(
+        'Workflow',
+        {
+          name: 'test-workflow',
+          status: 'running',
+          context: { userId: '123' },
+        },
+        'wf-test'
+      )
+
+      const workflow = await adapter.getWorkflow('wf-test')
+      expect(workflow).not.toBeNull()
+      expect(workflow?.data).toMatchObject({ name: 'test-workflow' })
+    })
+
+    it('should update workflow', async () => {
+      await provider.create(
+        'Workflow',
+        {
+          name: 'test-workflow',
+          status: 'running',
+          context: {},
+        },
+        'wf-update'
+      )
+
+      const updated = await adapter.updateWorkflow('wf-update', {
+        status: 'completed',
+        context: { result: 'done' },
+      })
+
+      expect(updated.data).toMatchObject({
+        status: 'completed',
+        context: { result: 'done' },
+      })
+    })
+
+    it('should list workflow actions', async () => {
+      const adapterWithWorkflow = await createDigitalObjectsAdapter(provider, {
+        workflowId: 'wf-actions',
+      })
+
+      await adapterWithWorkflow.recordEvent('Event1', {})
+      await adapterWithWorkflow.recordEvent('Event2', {})
+
+      const actions = await adapterWithWorkflow.listWorkflowActions('wf-actions')
+      expect(actions.length).toBe(2)
+    })
+
+    it('should list actions by verb', async () => {
+      await adapter.recordEvent('Event1', {})
+      await adapter.recordEvent('Event2', {})
+
+      const actions = await adapter.listActionsByVerb('emit')
+      expect(actions.length).toBe(2)
+    })
+  })
+})
+
+describe('createSimpleAdapter', () => {
+  it('should return only DatabaseContext interface', async () => {
+    const provider = createMemoryProvider()
+    const simple = await createSimpleAdapter(provider)
+
+    // Should have all DatabaseContext methods
+    expect(typeof simple.recordEvent).toBe('function')
+    expect(typeof simple.createAction).toBe('function')
+    expect(typeof simple.completeAction).toBe('function')
+    expect(typeof simple.storeArtifact).toBe('function')
+    expect(typeof simple.getArtifact).toBe('function')
+
+    // Should NOT have extended methods
+    expect((simple as DigitalObjectsDatabaseContext).provider).toBeUndefined()
+    expect((simple as DigitalObjectsDatabaseContext).getWorkflow).toBeUndefined()
+  })
+
+  it('should work with workflow options', async () => {
+    const provider = createMemoryProvider()
+    const simple = await createSimpleAdapter(provider, { workflowId: 'wf-simple' })
+
+    await simple.recordEvent('Test.event', { data: 'test' })
+
+    const actions = await provider.listActions({ subject: 'wf-simple' })
+    expect(actions.length).toBe(1)
+  })
+})

package/src/__tests__/durable-workflow.test.ts

@@ -0,0 +1,297 @@
+/**
+ * Tests for DurableWorkflow
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { createMemoryProvider, type DigitalObjectsProvider } from 'digital-objects'
+import {
+  DurableWorkflow,
+  createDurableWorkflow,
+  type DurableWorkflowState,
+} from '../durable-workflow.js'
+
+describe('DurableWorkflow', () => {
+  let provider: DigitalObjectsProvider
+
+  beforeEach(() => {
+    provider = createMemoryProvider()
+  })
+
+  afterEach(async () => {
+    // Clean up any workflows
+    await provider.close?.()
+  })
+
+  describe('initialization', () => {
+    it('should create a new workflow instance', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await workflow.initialize('test-workflow', ($) => {
+        $.on.Test.event(async () => {})
+      })
+
+      // Verify workflow was created in digital-objects
+      const thing = await provider.get<DurableWorkflowState>(workflow.id)
+      expect(thing).not.toBeNull()
+      expect(thing?.noun).toBe('Workflow')
+      expect(thing?.data.name).toBe('test-workflow')
+      expect(thing?.data.status).toBe('running')
+    })
+
+    it('should use provided instance ID', async () => {
+      const workflow = new DurableWorkflow(provider, { instanceId: 'my-workflow-id' })
+
+      await workflow.initialize('named-workflow', ($) => {})
+
+      expect(workflow.id).toBe('my-workflow-id')
+
+      const thing = await provider.get('my-workflow-id')
+      expect(thing).not.toBeNull()
+    })
+
+    it('should register event handlers', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await workflow.initialize('event-workflow', ($) => {
+        $.on.Customer.created(async () => {})
+        $.on.Order.completed(async () => {})
+      })
+
+      const thing = await provider.get<DurableWorkflowState>(workflow.id)
+      expect(thing?.data.registeredEvents).toContain('Customer.created')
+      expect(thing?.data.registeredEvents).toContain('Order.completed')
+    })
+
+    it('should register schedule handlers', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await workflow.initialize('schedule-workflow', ($) => {
+        $.every.minutes(30)(async () => {})
+      })
+
+      const thing = await provider.get<DurableWorkflowState>(workflow.id)
+      expect(thing?.data.registeredSchedules).toContain('minute:30')
+    })
+
+    it('should reject double initialization', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await workflow.initialize('test', ($) => {})
+
+      await expect(workflow.initialize('test2', ($) => {})).rejects.toThrow(
+        'Workflow already initialized'
+      )
+    })
+
+    it('should initialize with context', async () => {
+      const workflow = new DurableWorkflow(provider, {
+        context: { userId: 'user-123', tenant: 'acme' },
+      })
+
+      await workflow.initialize('context-workflow', ($) => {})
+
+      const thing = await provider.get<DurableWorkflowState>(workflow.id)
+      expect(thing?.data.context).toMatchObject({
+        userId: 'user-123',
+        tenant: 'acme',
+      })
+    })
+  })
+
+  describe('state management', () => {
+    it('should get current state', async () => {
+      const workflow = new DurableWorkflow(provider, {
+        context: { counter: 0 },
+      })
+
+      await workflow.initialize('state-workflow', ($) => {
+        $.state.counter = 1
+      })
+
+      const state = workflow.getState()
+      expect(state.context.counter).toBe(1)
+    })
+
+    it('should persist state changes', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await workflow.initialize('persist-workflow', ($) => {
+        $.set('key1', 'value1')
+        $.set('key2', { nested: true })
+      })
+
+      // Wait for async persist
+      await new Promise((r) => setTimeout(r, 10))
+
+      const thing = await provider.get<DurableWorkflowState>(workflow.id)
+      expect(thing?.data.context.key1).toBe('value1')
+      expect(thing?.data.context.key2).toMatchObject({ nested: true })
+    })
+
+    it('should support $.get and $.set', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      let capturedValue: unknown
+
+      await workflow.initialize('getset-workflow', ($) => {
+        $.set('myKey', 'myValue')
+        capturedValue = $.get('myKey')
+      })
+
+      expect(capturedValue).toBe('myValue')
+    })
+  })
+
+  describe('event handling', () => {
+    it('should send events and trigger handlers', async () => {
+      const workflow = new DurableWorkflow(provider)
+      const handler = vi.fn()
+
+      await workflow.initialize('event-workflow', ($) => {
+        $.on.Test.triggered(handler)
+      })
+
+      await workflow.start()
+      await workflow.send('Test.triggered', { value: 42 })
+
+      expect(handler).toHaveBeenCalledTimes(1)
+      expect(handler).toHaveBeenCalledWith(
+        expect.objectContaining({ value: 42 }),
+        expect.anything()
+      )
+
+      await workflow.destroy()
+    })
+
+    it('should record events as Actions', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await workflow.initialize('action-workflow', ($) => {
+        $.on.Event.happened(async () => {})
+      })
+
+      await workflow.start()
+      await workflow.send('Event.happened', { data: 'test' })
+
+      // Wait for async persistence
+      await new Promise((r) => setTimeout(r, 10))
+
+      const actions = await provider.listActions({ verb: 'emit' })
+      expect(actions.length).toBeGreaterThan(0)
+
+      await workflow.destroy()
+    })
+
+    it('should throw for uninitialized workflow', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await expect(workflow.send('Test.event', {})).rejects.toThrow('Workflow not initialized')
+    })
+  })
+
+  describe('history', () => {
+    it('should track history entries', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await workflow.initialize('history-workflow', ($) => {
+        $.on.Step.one(async () => {})
+      })
+
+      await workflow.start()
+      await workflow.send('Step.one', {})
+
+      const state = workflow.getState()
+      expect(state.history.length).toBeGreaterThan(0)
+      expect(state.history.some((h) => h.name === 'workflow.started')).toBe(true)
+
+      await workflow.destroy()
+    })
+
+    it('should persist history as Actions', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await workflow.initialize('persist-history', ($) => {
+        $.log('Test log message')
+      })
+
+      // Wait for async persistence
+      await new Promise((r) => setTimeout(r, 10))
+
+      const actions = await provider.listActions({ verb: 'action', subject: workflow.id })
+      expect(actions.some((a) => a.data?.name === 'log')).toBe(true)
+
+      await workflow.destroy()
+    })
+  })
+
+  describe('lifecycle', () => {
+    it('should start and stop workflow', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await workflow.initialize('lifecycle-workflow', ($) => {})
+
+      await workflow.start()
+
+      let thing = await provider.get<DurableWorkflowState>(workflow.id)
+      expect(thing?.data.status).toBe('running')
+
+      await workflow.stop()
+
+      thing = await provider.get<DurableWorkflowState>(workflow.id)
+      expect(thing?.data.status).toBe('paused')
+    })
+
+    it('should destroy workflow', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await workflow.initialize('destroy-workflow', ($) => {})
+      await workflow.start()
+      await workflow.destroy()
+
+      const thing = await provider.get<DurableWorkflowState>(workflow.id)
+      expect(thing?.data.status).toBe('completed')
+    })
+
+    it('should reject start before initialization', async () => {
+      const workflow = new DurableWorkflow(provider)
+
+      await expect(workflow.start()).rejects.toThrow('Workflow not initialized')
+    })
+  })
+
+  describe('recovery', () => {
+    it('should restore workflow from existing state', async () => {
+      // Create initial workflow
+      const workflow1 = new DurableWorkflow(provider, { instanceId: 'recovery-test' })
+
+      await workflow1.initialize('recoverable', ($) => {
+        $.set('data', 'original')
+      })
+
+      await workflow1.start()
+      await workflow1.stop()
+
+      // Create new workflow with same ID - should restore
+      const workflow2 = new DurableWorkflow(provider, { instanceId: 'recovery-test' })
+
+      await workflow2.initialize('recoverable', ($) => {})
+
+      const state = workflow2.getState()
+      expect(state.context.data).toBe('original')
+
+      await workflow2.destroy()
+    })
+  })
+
+  describe('createDurableWorkflow factory', () => {
+    it('should create workflow instance', () => {
+      const workflow = createDurableWorkflow(provider)
+      expect(workflow).toBeInstanceOf(DurableWorkflow)
+    })
+
+    it('should pass options', () => {
+      const workflow = createDurableWorkflow(provider, { instanceId: 'factory-test' })
+      expect(workflow.id).toBe('factory-test')
+    })
+  })
+})