ai-workflows 1.1.0 → 2.0.0

package/src/every.ts

@@ -0,0 +1,299 @@
+/**
+ * Schedule registration using natural language
+ *
+ * Usage:
+ *   every.hour($ => { ... })
+ *   every.Thursday.at8am($ => { ... })
+ *   every.weekday.at9am($ => { ... })
+ *   every('hour during business hours', $ => { ... })
+ *   every('first Monday of the month at 9am', $ => { ... })
+ */
+
+import type { ScheduleHandler, ScheduleRegistration, ScheduleInterval } from './types.js'
+
+/**
+ * Registry of schedule handlers
+ */
+const scheduleRegistry: ScheduleRegistration[] = []
+
+/**
+ * Get all registered schedule handlers
+ */
+export function getScheduleHandlers(): ScheduleRegistration[] {
+  return [...scheduleRegistry]
+}
+
+/**
+ * Clear all registered schedule handlers
+ */
+export function clearScheduleHandlers(): void {
+  scheduleRegistry.length = 0
+}
+
+/**
+ * Register a schedule handler directly
+ */
+export function registerScheduleHandler(
+  interval: ScheduleInterval,
+  handler: ScheduleHandler
+): void {
+  scheduleRegistry.push({
+    interval,
+    handler,
+    source: handler.toString(),
+  })
+}
+
+/**
+ * Well-known cron patterns for common schedules
+ */
+const KNOWN_PATTERNS: Record<string, string> = {
+  // Time units
+  'second': '* * * * * *',
+  'minute': '* * * * *',
+  'hour': '0 * * * *',
+  'day': '0 0 * * *',
+  'week': '0 0 * * 0',
+  'month': '0 0 1 * *',
+  'year': '0 0 1 1 *',
+
+  // Days of week
+  'Monday': '0 0 * * 1',
+  'Tuesday': '0 0 * * 2',
+  'Wednesday': '0 0 * * 3',
+  'Thursday': '0 0 * * 4',
+  'Friday': '0 0 * * 5',
+  'Saturday': '0 0 * * 6',
+  'Sunday': '0 0 * * 0',
+
+  // Common patterns
+  'weekday': '0 0 * * 1-5',
+  'weekend': '0 0 * * 0,6',
+  'midnight': '0 0 * * *',
+  'noon': '0 12 * * *',
+}
+
+/**
+ * Time suffixes for day-based schedules
+ */
+const TIME_PATTERNS: Record<string, { hour: number; minute: number }> = {
+  'at6am': { hour: 6, minute: 0 },
+  'at7am': { hour: 7, minute: 0 },
+  'at8am': { hour: 8, minute: 0 },
+  'at9am': { hour: 9, minute: 0 },
+  'at10am': { hour: 10, minute: 0 },
+  'at11am': { hour: 11, minute: 0 },
+  'at12pm': { hour: 12, minute: 0 },
+  'atnoon': { hour: 12, minute: 0 },
+  'at1pm': { hour: 13, minute: 0 },
+  'at2pm': { hour: 14, minute: 0 },
+  'at3pm': { hour: 15, minute: 0 },
+  'at4pm': { hour: 16, minute: 0 },
+  'at5pm': { hour: 17, minute: 0 },
+  'at6pm': { hour: 18, minute: 0 },
+  'at7pm': { hour: 19, minute: 0 },
+  'at8pm': { hour: 20, minute: 0 },
+  'at9pm': { hour: 21, minute: 0 },
+  'atmidnight': { hour: 0, minute: 0 },
+}
+
+/**
+ * Parse a known pattern or return null
+ */
+function parseKnownPattern(pattern: string): string | null {
+  return KNOWN_PATTERNS[pattern] ?? null
+}
+
+/**
+ * Combine a day pattern with a time pattern
+ */
+function combineWithTime(baseCron: string, time: { hour: number; minute: number }): string {
+  const parts = baseCron.split(' ')
+  parts[0] = String(time.minute)
+  parts[1] = String(time.hour)
+  return parts.join(' ')
+}
+
+/**
+ * AI-powered cron conversion (placeholder - will use ai-functions)
+ */
+let cronConverter: ((description: string) => Promise<string>) | null = null
+
+/**
+ * Set the AI cron converter function
+ */
+export function setCronConverter(converter: (description: string) => Promise<string>): void {
+  cronConverter = converter
+}
+
+/**
+ * Convert natural language to cron expression
+ */
+export async function toCron(description: string): Promise<string> {
+  // First check known patterns
+  const known = parseKnownPattern(description)
+  if (known) return known
+
+  // If we have an AI converter, use it
+  if (cronConverter) {
+    return cronConverter(description)
+  }
+
+  // Otherwise, assume it's already a cron expression or throw
+  if (/^[\d\*\-\/\,\s]+$/.test(description)) {
+    return description
+  }
+
+  throw new Error(
+    `Unknown schedule pattern: "${description}". ` +
+    `Set up AI conversion with setCronConverter() for natural language schedules.`
+  )
+}
+
+/**
+ * Create the `every` proxy
+ */
+function createEveryProxy() {
+  const handler = {
+    get(_target: unknown, prop: string) {
+      // Check if it's a known pattern
+      const pattern = KNOWN_PATTERNS[prop]
+      if (pattern) {
+        // Return an object that can either be called directly or have time accessors
+        const result = (handlerFn: ScheduleHandler) => {
+          registerScheduleHandler({ type: 'cron', expression: pattern, natural: prop }, handlerFn)
+        }
+        // Add time accessors
+        return new Proxy(result, {
+          get(_t, timeKey: string) {
+            const time = TIME_PATTERNS[timeKey]
+            if (time) {
+              const cron = combineWithTime(pattern, time)
+              return (handlerFn: ScheduleHandler) => {
+                registerScheduleHandler({ type: 'cron', expression: cron, natural: `${prop}.${timeKey}` }, handlerFn)
+              }
+            }
+            return undefined
+          },
+          apply(_t, _thisArg, args) {
+            registerScheduleHandler({ type: 'cron', expression: pattern, natural: prop }, args[0])
+          }
+        })
+      }
+
+      // Check for plural time units (e.g., seconds(5), minutes(30))
+      const pluralUnits: Record<string, string> = {
+        seconds: 'second',
+        minutes: 'minute',
+        hours: 'hour',
+        days: 'day',
+        weeks: 'week',
+      }
+      if (pluralUnits[prop]) {
+        return (value: number) => (handlerFn: ScheduleHandler) => {
+          registerScheduleHandler({ type: pluralUnits[prop] as any, value, natural: `${value} ${prop}` }, handlerFn)
+        }
+      }
+
+      return undefined
+    },
+
+    apply(_target: unknown, _thisArg: unknown, args: unknown[]) {
+      // Called as every('natural language description', handler)
+      const [description, handler] = args as [string, ScheduleHandler]
+
+      if (typeof description === 'string' && typeof handler === 'function') {
+        // Register with natural language - will be converted to cron at runtime
+        registerScheduleHandler({ type: 'natural', description }, handler)
+      }
+    }
+  }
+
+  return new Proxy(function() {} as any, handler)
+}
+
+/**
+ * The `every` function/object for registering scheduled handlers
+ *
+ * @example
+ * ```ts
+ * import { every } from 'ai-workflows'
+ *
+ * // Simple intervals
+ * every.hour($ => $.log('Hourly task'))
+ * every.day($ => $.log('Daily task'))
+ *
+ * // Day + time combinations
+ * every.Monday.at9am($ => $.log('Monday morning standup'))
+ * every.weekday.at8am($ => $.log('Workday start'))
+ * every.Friday.at5pm($ => $.log('End of week report'))
+ *
+ * // Plural intervals with values
+ * every.minutes(30)($ => $.log('Every 30 minutes'))
+ * every.hours(4)($ => $.log('Every 4 hours'))
+ *
+ * // Natural language (requires AI converter)
+ * every('hour during business hours', $ => { ... })
+ * every('first Monday of the month at 9am', $ => { ... })
+ * every('every 15 minutes between 9am and 5pm on weekdays', $ => { ... })
+ * ```
+ */
+export const every = createEveryProxy()
+
+/**
+ * Convert interval to milliseconds (for simulation/testing)
+ */
+export function intervalToMs(interval: ScheduleInterval): number {
+  switch (interval.type) {
+    case 'second':
+      return (interval.value ?? 1) * 1000
+    case 'minute':
+      return (interval.value ?? 1) * 60 * 1000
+    case 'hour':
+      return (interval.value ?? 1) * 60 * 60 * 1000
+    case 'day':
+      return (interval.value ?? 1) * 24 * 60 * 60 * 1000
+    case 'week':
+      return (interval.value ?? 1) * 7 * 24 * 60 * 60 * 1000
+    case 'cron':
+    case 'natural':
+      // Cron/natural expressions need special handling
+      return 0
+  }
+}
+
+/**
+ * Format interval for display
+ */
+export function formatInterval(interval: ScheduleInterval): string {
+  if ('natural' in interval && interval.natural) {
+    return interval.natural
+  }
+
+  switch (interval.type) {
+    case 'second':
+      return interval.value && interval.value > 1
+        ? `every ${interval.value} seconds`
+        : 'every second'
+    case 'minute':
+      return interval.value && interval.value > 1
+        ? `every ${interval.value} minutes`
+        : 'every minute'
+    case 'hour':
+      return interval.value && interval.value > 1
+        ? `every ${interval.value} hours`
+        : 'every hour'
+    case 'day':
+      return interval.value && interval.value > 1
+        ? `every ${interval.value} days`
+        : 'every day'
+    case 'week':
+      return interval.value && interval.value > 1
+        ? `every ${interval.value} weeks`
+        : 'every week'
+    case 'cron':
+      return `cron: ${interval.expression}`
+    case 'natural':
+      return interval.description
+  }
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+/**
+ * ai-workflows - Event-driven workflows with $ context
+ *
+ * @example
+ * ```ts
+ * import { Workflow } from 'ai-workflows'
+ *
+ * // Create a workflow with $ context
+ * const workflow = Workflow($ => {
+ *   // Register event handlers
+ *   $.on.Customer.created(async (customer, $) => {
+ *     $.log('New customer:', customer.name)
+ *     await $.send('Email.welcome', { to: customer.email })
+ *   })
+ *
+ *   $.on.Order.completed(async (order, $) => {
+ *     $.log('Order completed:', order.id)
+ *   })
+ *
+ *   // Register scheduled tasks
+ *   $.every.hour(async ($) => {
+ *     $.log('Hourly check')
+ *   })
+ *
+ *   $.every.Monday.at9am(async ($) => {
+ *     $.log('Weekly standup reminder')
+ *   })
+ *
+ *   $.every.minutes(30)(async ($) => {
+ *     $.log('Every 30 minutes')
+ *   })
+ *
+ *   // Natural language scheduling
+ *   $.every('first Monday of the month', async ($) => {
+ *     $.log('Monthly report')
+ *   })
+ * })
+ *
+ * // Start the workflow
+ * await workflow.start()
+ *
+ * // Emit events
+ * await workflow.send('Customer.created', { name: 'John', email: 'john@example.com' })
+ * ```
+ *
+ * @example
+ * // Alternative: Use standalone on/every for global registration
+ * ```ts
+ * import { on, every, send } from 'ai-workflows'
+ *
+ * on.Customer.created(async (customer, $) => {
+ *   await $.send('Email.welcome', { to: customer.email })
+ * })
+ *
+ * every.hour(async ($) => {
+ *   $.log('Hourly task')
+ * })
+ *
+ * await send('Customer.created', { name: 'John' })
+ * ```
+ */
+
+// Main Workflow API
+export { Workflow, createTestContext, parseEvent, type WorkflowInstance } from './workflow.js'
+
+// Standalone event handling (for global registration)
+export { on, registerEventHandler, getEventHandlers, clearEventHandlers } from './on.js'
+
+// Standalone scheduling (for global registration)
+export {
+  every,
+  registerScheduleHandler,
+  getScheduleHandlers,
+  clearScheduleHandlers,
+  setCronConverter,
+  toCron,
+  intervalToMs,
+  formatInterval,
+} from './every.js'
+
+// Event emission
+export { send, getEventBus } from './send.js'
+
+// Context
+export { createWorkflowContext, createIsolatedContext } from './context.js'
+
+// Types
+export type {
+  EventHandler,
+  ScheduleHandler,
+  WorkflowContext,
+  WorkflowState,
+  WorkflowHistoryEntry,
+  EventRegistration,
+  ScheduleRegistration,
+  ScheduleInterval,
+  WorkflowDefinition,
+  WorkflowOptions,
+  ParsedEvent,
+  OnProxy,
+  EveryProxy,
+  HandlerFunction,
+  DatabaseContext,
+  ActionData,
+  ArtifactData,
+} from './types.js'

package/src/on.ts

@@ -0,0 +1,100 @@
+/**
+ * Event handler registration using on.Noun.event syntax
+ *
+ * Usage:
+ *   on.Customer.created(customer => { ... })
+ *   on.Order.completed(order => { ... })
+ *   on.Payment.failed(payment => { ... })
+ */
+
+import type { EventHandler, EventRegistration } from './types.js'
+
+/**
+ * Registry of event handlers
+ */
+const eventRegistry: EventRegistration[] = []
+
+/**
+ * Get all registered event handlers
+ */
+export function getEventHandlers(): EventRegistration[] {
+  return [...eventRegistry]
+}
+
+/**
+ * Clear all registered event handlers
+ */
+export function clearEventHandlers(): void {
+  eventRegistry.length = 0
+}
+
+/**
+ * Register an event handler directly
+ */
+export function registerEventHandler(
+  noun: string,
+  event: string,
+  handler: EventHandler
+): void {
+  eventRegistry.push({
+    noun,
+    event,
+    handler,
+    source: handler.toString(),
+  })
+}
+
+/**
+ * Event proxy type for on.Noun.event pattern
+ */
+type EventProxy = {
+  [noun: string]: {
+    [event: string]: (handler: EventHandler) => void
+  }
+}
+
+/**
+ * Create the `on` proxy
+ *
+ * This creates a proxy that allows:
+ *   on.Customer.created(handler)
+ *   on.Order.shipped(handler)
+ *
+ * The first property access captures the noun (Customer, Order)
+ * The second property access captures the event (created, shipped)
+ * The function call registers the handler
+ */
+function createOnProxy(): EventProxy {
+  return new Proxy({} as EventProxy, {
+    get(_target, noun: string) {
+      // Return a proxy for the event level
+      return new Proxy({}, {
+        get(_eventTarget, event: string) {
+          // Return a function that registers the handler
+          return (handler: EventHandler) => {
+            registerEventHandler(noun, event, handler)
+          }
+        }
+      })
+    }
+  })
+}
+
+/**
+ * The `on` object for registering event handlers
+ *
+ * @example
+ * ```ts
+ * import { on } from 'ai-workflows'
+ *
+ * on.Customer.created(async (customer, $) => {
+ *   $.log('Customer created:', customer.name)
+ *   await $.send('Email.welcome', { to: customer.email })
+ * })
+ *
+ * on.Order.completed(async (order, $) => {
+ *   $.log('Order completed:', order.id)
+ * })
+ * ```
+ */
+export const on = createOnProxy()

package/src/send.ts

@@ -0,0 +1,131 @@
+/**
+ * Event emission using send('Noun.event', data)
+ *
+ * Usage:
+ *   send('Customer.created', customer)
+ *   send('Order.completed', order)
+ */
+
+import type { ParsedEvent } from './types.js'
+import { getEventHandlers } from './on.js'
+import { createWorkflowContext } from './context.js'
+
+/**
+ * Event bus for managing event delivery
+ */
+class EventBus {
+  private pending: Array<{ event: string; data: unknown }> = []
+  private processing = false
+
+  /**
+   * Emit an event
+   */
+  async emit(event: string, data: unknown): Promise<void> {
+    this.pending.push({ event, data })
+
+    if (!this.processing) {
+      await this.process()
+    }
+  }
+
+  /**
+   * Process pending events
+   */
+  private async process(): Promise<void> {
+    this.processing = true
+
+    while (this.pending.length > 0) {
+      const item = this.pending.shift()!
+      await this.deliver(item.event, item.data)
+    }
+
+    this.processing = false
+  }
+
+  /**
+   * Deliver an event to matching handlers
+   */
+  private async deliver(event: string, data: unknown): Promise<void> {
+    const parsed = parseEvent(event)
+    if (!parsed) {
+      console.warn(`Invalid event format: ${event}. Expected Noun.event`)
+      return
+    }
+
+    const handlers = getEventHandlers()
+    const matching = handlers.filter(
+      h => h.noun === parsed.noun && h.event === parsed.event
+    )
+
+    if (matching.length === 0) {
+      // No handlers registered - that's okay, event is just not handled
+      return
+    }
+
+    // Create workflow context for handlers
+    const ctx = createWorkflowContext(this)
+
+    // Execute all matching handlers
+    await Promise.all(
+      matching.map(async ({ handler }) => {
+        try {
+          await handler(data, ctx)
+        } catch (error) {
+          console.error(`Error in handler for ${event}:`, error)
+        }
+      })
+    )
+  }
+}
+
+/**
+ * Parse event string into noun and event
+ */
+export function parseEvent(event: string): ParsedEvent | null {
+  const parts = event.split('.')
+  if (parts.length !== 2) {
+    return null
+  }
+  const [noun, eventName] = parts
+  if (!noun || !eventName) {
+    return null
+  }
+  return { noun, event: eventName }
+}
+
+/**
+ * Global event bus instance
+ */
+const globalEventBus = new EventBus()
+
+/**
+ * Send an event
+ *
+ * @example
+ * ```ts
+ * import { send } from 'ai-workflows'
+ *
+ * // Emit a customer created event
+ * await send('Customer.created', {
+ *   id: '123',
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * })
+ *
+ * // Emit an order completed event
+ * await send('Order.completed', {
+ *   id: 'order-456',
+ *   total: 99.99
+ * })
+ * ```
+ */
+export async function send<T = unknown>(event: string, data: T): Promise<void> {
+  await globalEventBus.emit(event, data)
+}
+
+/**
+ * Get the global event bus (for testing/internal use)
+ */
+export function getEventBus(): EventBus {
+  return globalEventBus
+}