ai-workflows 2.0.2 → 2.1.1

package/test/types-event-handler.test.ts

@@ -0,0 +1,225 @@
+/**
+ * TDD RED Phase Tests: EventHandler generic order
+ * Issue: primitives.org.ai-01s
+ *
+ * These tests verify that EventHandler uses <TOutput, TInput> order
+ * (output first, then input), consistent with Promise<T> patterns.
+ *
+ * Current implementation uses <T, R> where T is input, R is output.
+ * These tests should FAIL until the type order is fixed.
+ *
+ * The current signature is:
+ *   EventHandler<T = unknown, R = unknown> = (data: T, $) => R | void | Promise<R | void>
+ *
+ * The desired signature is:
+ *   EventHandler<TOutput = unknown, TInput = unknown> = (data: TInput, $) => TOutput | void | Promise<TOutput | void>
+ *
+ * TEST STRATEGY:
+ * - Tests use @ts-expect-error to mark lines that SHOULD error with CURRENT types
+ * - When types are FIXED, these @ts-expect-error comments will become errors
+ *   (because the expected error won't occur)
+ * - This makes the test file fail to compile when types are correct = TDD RED
+ */
+import { describe, it, expect, expectTypeOf, assertType } from 'vitest'
+import type { EventHandler, WorkflowContext } from '../src/types.js'
+import { Workflow } from '../src/workflow.js'
+
+describe('EventHandler generic order - TDD RED', () => {
+  // Test data types
+  interface CustomerData {
+    id: string
+    name: string
+    email: string
+  }
+
+  interface ProcessResult {
+    success: boolean
+    processedAt: number
+  }
+
+  interface OrderInput {
+    orderId: string
+    items: string[]
+  }
+
+  describe('EventHandler<TOutput, TInput> order - documents current behavior', () => {
+    /**
+     * This test documents the CURRENT behavior:
+     * - EventHandler<T, R> where T is INPUT (first), R is OUTPUT (second)
+     *
+     * When we CHANGE to <TOutput, TInput>:
+     * - The @ts-expect-error comments below will fail (no error to expect)
+     * - The test file won't compile until @ts-expect-error is removed
+     */
+
+    it('documents: FIXED types have output first, input second', () => {
+      // FIXED: EventHandler<Output, Input>
+      // - First generic (TOutput) is the return type
+      // - Second generic (TInput) is the data parameter type
+      //
+      // EventHandler<ProcessResult, OrderInput> means:
+      // - data: OrderInput (second generic)
+      // - returns: ProcessResult (first generic)
+      const handler: EventHandler<ProcessResult, OrderInput> = (data, $) => {
+        // With FIXED types, data is OrderInput (second generic)
+        const _orderId: string = data.orderId
+        const _items: string[] = data.items
+
+        // Return type is ProcessResult (first generic)
+        return { success: true, processedAt: Date.now() }
+      }
+
+      expect(handler).toBeDefined()
+    })
+
+    it('documents: calling handler with correct args works with fixed types', () => {
+      const handler: EventHandler<ProcessResult, OrderInput> = (data, $) => {
+        // Fixed: data is OrderInput, returns ProcessResult
+        return { success: true, processedAt: Date.now() }
+      }
+
+      // With FIXED types, first arg should be OrderInput
+      handler({ orderId: '1', items: [] }, {} as WorkflowContext)
+    })
+
+    it('PASSES: data is second generic with fixed types', () => {
+      // With FIXED types <TOutput, TInput>:
+      // EventHandler<ProcessResult, OrderInput> means:
+      // - data: OrderInput (second generic)
+      // - return: ProcessResult (first generic)
+
+      const handler: EventHandler<ProcessResult, OrderInput> = (data, $) => {
+        // Data is correctly typed as OrderInput (second generic)
+        const orderId: string = data.orderId
+        const items: string[] = data.items
+
+        return { success: true, processedAt: Date.now() }
+      }
+
+      // Calling with OrderInput as data - now works correctly
+      handler({ orderId: '123', items: ['a'] }, {} as WorkflowContext)
+    })
+  })
+
+  describe('WorkflowContext.do<TResult, TInput> order - FIXED types', () => {
+    /**
+     * FIXED $.do signature: <TResult, TInput>(event, data: TInput) => Promise<TResult>
+     *
+     * The order puts Result first (like Promise<T>)
+     */
+    it('documents: FIXED $.do has result first, input second', () => {
+      const workflow = Workflow($ => {
+        $.on.Order.process(() => ({ success: true, processedAt: Date.now() }))
+      })
+
+      // With FIXED types: $.do<TResult, TInput>
+      // - First generic (TResult) is the result/output type
+      // - Second generic (TInput) is the data/input type
+
+      // $.do<ProcessResult, OrderInput> means data: OrderInput, returns Promise<ProcessResult>
+      workflow.$.do<ProcessResult, OrderInput>('Order.process', { orderId: '123', items: [] })
+    })
+
+    it('PASSES: $.do accepts data as second generic type', async () => {
+      const workflow = Workflow($ => {
+        $.on.Order.process((order: OrderInput) => ({
+          success: true,
+          processedAt: Date.now()
+        }))
+      })
+
+      try {
+        // With FIXED types, data is OrderInput (second generic), result is ProcessResult (first generic)
+        const result: ProcessResult = await workflow.$.do<ProcessResult, OrderInput>(
+          'Order.process',
+          { orderId: '123', items: ['item1'] }  // OrderInput - accepted with fixed types
+        )
+      } catch {
+        // Expected to throw - we're testing types, not runtime
+      }
+    })
+  })
+
+  describe('WorkflowContext.try<TResult, TInput> order - FIXED types', () => {
+    it('documents: FIXED $.try has result first, input second', () => {
+      const workflow = Workflow($ => {
+        $.on.Test.action(() => ({ orderId: 'x', items: [] }))
+      })
+
+      // Same pattern as $.do - don't await to avoid runtime error
+      // $.try<ProcessResult, OrderInput> means data: OrderInput, returns Promise<ProcessResult>
+      const _promise = workflow.$.try<ProcessResult, OrderInput>('Test.action', { orderId: 'x', items: [] })
+    })
+
+    it('PASSES: $.try accepts data as second generic type', async () => {
+      const workflow = Workflow($ => {
+        $.on.Payment.validate((input: { amount: number }) => ({ valid: input.amount > 0 }))
+      })
+
+      try {
+        // With FIXED types, data is { amount: number }, result is { valid: boolean }
+        const result: { valid: boolean } = await workflow.$.try<{ valid: boolean }, { amount: number }>(
+          'Payment.validate',
+          { amount: 100 }  // Accepted with fixed types
+        )
+      } catch {
+        // Expected
+      }
+    })
+  })
+
+  describe('Type inference consistency', () => {
+    /**
+     * When the generic order is fixed, these patterns should all work:
+     *
+     * EventHandler<void, CustomerData>     - fire and forget with CustomerData input
+     * EventHandler<ProcessResult, void>    - returns ProcessResult, no input needed
+     * EventHandler<string, number>         - takes number, returns string
+     *
+     * Like Promise<T> where T is what you get, not what you put in
+     */
+
+    it('should support EventHandler<void, InputType> for fire-and-forget handlers', () => {
+      // A handler that receives data but returns nothing
+      type FireForgetHandler = EventHandler<void, CustomerData>
+
+      const handler: FireForgetHandler = (customer, $) => {
+        // customer should be CustomerData (second generic = input)
+        // Note: we don't call $.log here to avoid runtime issues with mock context
+        console.log(`Processing ${customer.name} (${customer.email})`)
+        // Returns void (first generic = output)
+      }
+
+      // Should be callable with CustomerData - using real workflow context
+      const workflow = Workflow(_ => {})
+      handler({ id: '1', name: 'John', email: 'john@example.com' }, workflow.$)
+    })
+
+    it('should support EventHandler<OutputType, void> for parameterless handlers', () => {
+      // A handler that takes no data but returns a result
+      // This is less common but should be expressible
+      type NoInputHandler = EventHandler<ProcessResult, void>
+
+      // Note: This is a stretch case - handlers always receive data param
+      // but we should be able to type it as void/undefined
+    })
+
+    it('should mirror Promise<T> convention where T is the resolved value', () => {
+      // Just as Promise<string> means "will resolve to string"
+      // EventHandler<string, number> should mean "will return string (given number input)"
+
+      // Test that first generic controls return type
+      type StringReturningHandler = EventHandler<string, number>
+
+      const handler: StringReturningHandler = (num, $) => {
+        return `The number is ${num}`
+      }
+
+      const result = handler(42, {} as WorkflowContext)
+      // With correct types, result should be string | void | Promise<...>
+      if (typeof result === 'string') {
+        expect(result).toBe('The number is 42')
+      }
+    })
+  })
+})

package/test/types-proxy-autocomplete.test.ts

@@ -0,0 +1,345 @@
+/**
+ * TDD RED Phase Tests: OnProxy/EveryProxy autocomplete
+ * Issue: primitives.org.ai-5qe
+ *
+ * These tests verify that TypeScript sees known properties on $.on and $.every
+ * instead of treating everything as unknown from index signatures.
+ *
+ * Current implementation uses pure index signatures which causes:
+ * - $.on to be typed as { [noun: string]: { [event: string]: ... } }
+ * - $.every has union type with index signature
+ * - IDE autocomplete doesn't show known patterns (hour, day, Monday, etc.)
+ *
+ * The issue is that index signatures make TypeScript treat all properties
+ * as having the same type, which hides known properties from autocomplete.
+ *
+ * These tests should FAIL until proper typing with explicit known properties is implemented.
+ */
+import { describe, it, expect, expectTypeOf } from 'vitest'
+import type { WorkflowContext, OnProxy, EveryProxy, ScheduleHandler, EventHandler } from '../src/types.js'
+import { Workflow, createTestContext } from '../src/workflow.js'
+
+/**
+ * Helper type to check if a type has specific known keys
+ * This fails if the type only has an index signature
+ */
+type HasKnownKey<T, K extends string> = K extends keyof T ? true : false
+
+/**
+ * Expected OnProxy type with explicit known nouns
+ * This is what we WANT the type to look like
+ */
+type ExpectedOnProxy = {
+  // Known nouns (for autocomplete)
+  Customer: { [event: string]: (handler: EventHandler) => void }
+  Order: { [event: string]: (handler: EventHandler) => void }
+  Payment: { [event: string]: (handler: EventHandler) => void }
+  User: { [event: string]: (handler: EventHandler) => void }
+  // Index signature for dynamic nouns
+  [noun: string]: { [event: string]: (handler: EventHandler) => void }
+}
+
+/**
+ * Expected EveryProxy type with explicit known patterns
+ */
+type ExpectedEveryProxy = {
+  // Callable
+  (description: string, handler: ScheduleHandler): void
+  // Known time units (for autocomplete)
+  second: (handler: ScheduleHandler) => void
+  minute: (handler: ScheduleHandler) => void
+  hour: (handler: ScheduleHandler) => void
+  day: (handler: ScheduleHandler) => void
+  week: (handler: ScheduleHandler) => void
+  // Known days
+  Monday: ((handler: ScheduleHandler) => void) & { at9am: (handler: ScheduleHandler) => void }
+  Tuesday: ((handler: ScheduleHandler) => void) & { at9am: (handler: ScheduleHandler) => void }
+  // etc...
+  // Plural forms
+  seconds: (value: number) => (handler: ScheduleHandler) => void
+  minutes: (value: number) => (handler: ScheduleHandler) => void
+  hours: (value: number) => (handler: ScheduleHandler) => void
+  // Index signature for unknown patterns
+  [key: string]: unknown
+}
+
+describe('OnProxy/EveryProxy autocomplete - TDD RED', () => {
+  describe('OnProxy known property types - documents current limitations', () => {
+    /**
+     * Current OnProxy type:
+     *   { [noun: string]: { [event: string]: (handler: EventHandler) => void } }
+     *
+     * This makes TypeScript unable to distinguish known nouns from unknown ones.
+     * IDE autocomplete will not suggest "Customer", "Order", etc.
+     *
+     * Desired OnProxy type should have explicit known properties for autocomplete.
+     *
+     * TEST STRATEGY:
+     * - Document that current types use pure index signatures
+     * - When types are fixed to have explicit properties, @ts-expect-error will fail
+     */
+
+    it('documents: CURRENT OnProxy uses pure index signature (no explicit keys)', () => {
+      // With current types, OnProxy is { [noun: string]: ... }
+      // This means 'Customer' is NOT an explicit key, just matches index signature
+      //
+      // HasKnownKey returns true for index signatures because any string is valid
+      // So we can't easily test this at compile time
+
+      // Instead, document that accessing onProxy.Customer gives same type as any other key
+      const onProxy: OnProxy = {} as OnProxy
+
+      // These are all the same type because of index signature
+      type CustomerType = typeof onProxy.Customer
+      type RandomType = typeof onProxy.RandomNoun
+
+      // Both should be the same - this is CURRENT behavior we want to change
+      expectTypeOf<CustomerType>().toEqualTypeOf<RandomType>()
+    })
+
+    it('documents: IDE autocomplete shows nothing for $.on. with current types', () => {
+      // This is a documentation test - can't test autocomplete at runtime
+      // But we document that pure index signatures don't provide suggestions
+
+      const workflow = Workflow($ => {})
+
+      // When typing "workflow.$.on." the IDE shows NO suggestions
+      // because OnProxy is { [noun: string]: ... } with no explicit keys
+
+      // With FIXED types, IDE would suggest: Customer, Order, Payment, User, etc.
+
+      // Current behavior: any string access works but no autocomplete
+      const _customer = workflow.$.on.Customer  // Works but no suggestion
+      const _random = workflow.$.on.AnyRandomString  // Also works, same type
+    })
+
+    it('PASSES: OnProxy has explicit known nouns', () => {
+      // With FIXED types: OnProxy has explicit Customer, Order, etc. keys
+
+      type OnProxyKeys = keyof OnProxy
+      // With explicit keys: keyof includes 'Customer' | 'Order' | string
+
+      // This now works - Customer is a valid OnProxyKeys value
+      const _customerKey: OnProxyKeys = 'Customer'
+      const _orderKey: OnProxyKeys = 'Order'
+      const _paymentKey: OnProxyKeys = 'Payment'
+    })
+  })
+
+  describe('EveryProxy known property types - documents current limitations', () => {
+    /**
+     * Current EveryProxy type has a complex union with index signature:
+     *   { (description, handler): void } & { [key: string]: ... }
+     *
+     * This makes it hard for TypeScript to determine specific property types.
+     * Known patterns like .hour, .Monday should be explicitly typed
+     * for better IDE autocomplete.
+     *
+     * TEST STRATEGY:
+     * - Document current union type behavior
+     * - Use @ts-expect-error for things that will work when fixed
+     */
+
+    it('documents: CURRENT EveryProxy uses union type with index signature', () => {
+      // Current EveryProxy type makes property access return a union type
+      // not a specific type like (handler: ScheduleHandler) => void
+
+      const workflow = Workflow($ => {})
+      const every = workflow.$.every
+
+      // With current types, $.every.hour is a union type, not specifically typed
+      type HourType = typeof every.hour
+
+      // Document that hour is a complex union, not just a function
+      // (This is the limitation we want to fix)
+    })
+
+    it('documents: $.every.hour works but has union type', () => {
+      const workflow = Workflow($ => {})
+
+      // $.every.hour IS callable in practice (runtime works)
+      // But TypeScript types it as a union which is confusing
+      const hour = workflow.$.every.hour
+
+      // This passes because union includes function type
+      expectTypeOf(hour).toBeFunction()
+
+      // Runtime: hour(() => {}) works
+      // Type: hour is union type, not specifically (handler) => void
+    })
+
+    it('PASSES: $.every.Monday.at9am is directly typed', () => {
+      const workflow = Workflow($ => {})
+
+      const monday = workflow.$.every.Monday
+
+      // With FIXED types: monday.at9am is (handler: ScheduleHandler) => void
+      const at9am: (handler: ScheduleHandler) => void = monday.at9am
+
+      // Can call it directly
+      at9am(() => {})
+    })
+
+    it('documents: $.every.minutes curried call works at runtime', () => {
+      const workflow = Workflow($ => {})
+
+      // $.every.minutes(30) works at runtime
+      // Types may be confusing due to union
+      const minutes = workflow.$.every.minutes
+
+      // First call with number
+      expectTypeOf(minutes).toBeFunction()
+
+      // Runtime works, types are union
+      const every30 = workflow.$.every.minutes(30)
+      expectTypeOf(every30).toBeFunction()
+    })
+
+    it('PASSES: keyof EveryProxy includes known patterns', () => {
+      // With FIXED types: keyof EveryProxy includes 'hour' | 'Monday' | 'minutes' | string
+
+      type EveryProxyKeys = keyof EveryProxy
+
+      // These are all valid EveryProxy keys
+      const _hourKey: EveryProxyKeys = 'hour'
+      const _mondayKey: EveryProxyKeys = 'Monday'
+      const _minutesKey: EveryProxyKeys = 'minutes'
+    })
+
+    it('documents: IDE autocomplete limited with current union types', () => {
+      // When typing "workflow.$.every." the IDE may show:
+      // - Some suggestions from union type
+      // - But not clear, specific suggestions for known patterns
+
+      const workflow = Workflow($ => {})
+
+      // With FIXED types, IDE would clearly suggest:
+      // - hour, minute, second, day, week
+      // - Monday, Tuesday, Wednesday, etc.
+      // - minutes, hours, seconds, etc.
+
+      // Current behavior: union type makes suggestions confusing
+      type HourType = typeof workflow.$.every.hour
+      type MinutesType = typeof workflow.$.every.minutes
+    })
+  })
+
+  describe('$.send type safety', () => {
+    it('should have $.send callable and typed', () => {
+      const workflow = Workflow($ => {})
+
+      // $.send should be a function
+      expectTypeOf(workflow.$.send).toBeFunction()
+
+      // Should not be unknown
+      expectTypeOf(workflow.$.send).not.toBeUnknown()
+
+      // Should return Promise<void>
+      expectTypeOf(workflow.$.send<{ id: string }>).returns.toEqualTypeOf<Promise<void>>()
+    })
+
+    it('should type-check send call with data', async () => {
+      const workflow = Workflow($ => {
+        $.on.Email.welcome((data, ctx) => {
+          ctx.log('Welcome email sent')
+        })
+      })
+
+      // $.send should accept event name and typed data
+      await workflow.$.send('Email.welcome', { to: 'test@example.com' })
+
+      // The data parameter type should be inferred or explicitly typed
+      await workflow.$.send<{ to: string }>('Email.welcome', { to: 'test@example.com' })
+    })
+  })
+
+  describe('$.state accessibility', () => {
+    it('should have $.state accessible and typed', () => {
+      const workflow = Workflow($ => {})
+
+      // $.state should be accessible
+      expectTypeOf(workflow.$.state).not.toBeUnknown()
+
+      // Should be a record type
+      expectTypeOf(workflow.$.state).toMatchTypeOf<Record<string, unknown>>()
+    })
+
+    it('should allow reading and writing state', () => {
+      const workflow = Workflow($ => {
+        // Writing to state
+        $.state.userId = '123'
+        $.state.counter = 0
+
+        // Reading from state
+        const userId = $.state.userId
+        const counter = $.state.counter
+
+        expect(userId).toBe('123')
+        expect(counter).toBe(0)
+      })
+    })
+
+    it('should have $.set and $.get methods typed', () => {
+      const workflow = Workflow($ => {})
+
+      // $.set should be callable
+      expectTypeOf(workflow.$.set).toBeFunction()
+      expectTypeOf(workflow.$.set<string>).toBeCallableWith('key', 'value')
+
+      // $.get should be callable and return typed value
+      expectTypeOf(workflow.$.get).toBeFunction()
+      expectTypeOf(workflow.$.get<string>).returns.toEqualTypeOf<string | undefined>()
+    })
+  })
+
+  describe('Dynamic noun/event access still works', () => {
+    /**
+     * Even with explicit known properties, dynamic access should still work
+     * through the index signature fallback.
+     */
+
+    it('should allow $.on.DynamicNoun.dynamicEvent access', () => {
+      const workflow = Workflow($ => {
+        // Dynamic access should still work
+        $.on.SomeNewNoun.someEvent(() => {})
+      })
+
+      expect(workflow.definition.events).toHaveLength(1)
+      expect(workflow.definition.events[0]?.noun).toBe('SomeNewNoun')
+      expect(workflow.definition.events[0]?.event).toBe('someEvent')
+    })
+
+    it('should allow $.on[variable] access pattern', () => {
+      const workflow = Workflow($ => {})
+
+      const nounName = 'DynamicEntity' as string
+      const events = workflow.$.on[nounName]
+
+      // Should still be accessible and usable
+      expectTypeOf(events).not.toBeUnknown()
+    })
+  })
+
+  describe('createTestContext type safety', () => {
+    it('should return properly typed context', () => {
+      const ctx = createTestContext()
+
+      // Should have all WorkflowContext properties
+      expectTypeOf(ctx.send).toBeFunction()
+      expectTypeOf(ctx.on).toEqualTypeOf<OnProxy>()
+      expectTypeOf(ctx.every).toEqualTypeOf<EveryProxy>()
+      expectTypeOf(ctx.state).toMatchTypeOf<Record<string, unknown>>()
+      expectTypeOf(ctx.getState).toBeFunction()
+      expectTypeOf(ctx.set).toBeFunction()
+      expectTypeOf(ctx.get).toBeFunction()
+      expectTypeOf(ctx.log).toBeFunction()
+    })
+
+    it('should have emittedEvents property typed', () => {
+      const ctx = createTestContext()
+
+      // Should have emittedEvents array
+      expectTypeOf(ctx.emittedEvents).toEqualTypeOf<Array<{ event: string; data: unknown }>>()
+    })
+  })
+})