ai-workflows 2.0.2 → 2.1.3

package/src/types.ts

@@ -17,11 +17,15 @@ export interface HandlerFunction<T = unknown> {
 /**
  * Event handler function type
  * Can return void (for send) or a result (for do/try)
+ *
+ * Generic order follows Promise<T> convention:
+ * - TOutput (first) is what the handler returns
+ * - TInput (second) is what the handler receives
  */
-export type EventHandler<T = unknown, R = unknown> = (
-  data: T,
+export type EventHandler<TOutput = unknown, TInput = unknown> = (
+  data: TInput,
   $: WorkflowContext
-) => R | void | Promise<R | void>
+) => TOutput | void | Promise<TOutput | void>
 
 /**
  * Schedule handler function type
@@ -43,14 +47,22 @@ export interface WorkflowContext {
   /**
    * Do an action (durable, waits for result)
    * Retries on failure, stores result durably
+   *
+   * Generic order follows Promise<T> convention:
+   * - TResult (first) is what the action returns
+   * - TInput (second) is what data is passed to the action
    */
-  do: <TData = unknown, TResult = unknown>(event: string, data: TData) => Promise<TResult>
+  do: <TResult = unknown, TInput = unknown>(event: string, data: TInput) => Promise<TResult>
 
   /**
    * Try an action (non-durable, waits for result)
    * Simple execution without durability guarantees
+   *
+   * Generic order follows Promise<T> convention:
+   * - TResult (first) is what the action returns
+   * - TInput (second) is what data is passed to the action
    */
-  try: <TData = unknown, TResult = unknown>(event: string, data: TData) => Promise<TResult>
+  try: <TResult = unknown, TInput = unknown>(event: string, data: TInput) => Promise<TResult>
 
   /** Register event handler ($.on.Noun.event) */
   on: OnProxy
@@ -142,24 +154,151 @@ export interface ArtifactData {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * Event handler proxy for a specific noun
+ * Allows $.on.Noun.event(handler) pattern
+ */
+export type NounEventProxy = {
+  [event: string]: (handler: EventHandler) => void
+}
+
 /**
  * Event proxy type for $.on.Noun.event pattern
+ *
+ * Includes explicit known nouns for IDE autocomplete while
+ * preserving index signature for dynamic noun access.
  */
 export type OnProxy = {
-  [noun: string]: {
-    [event: string]: (handler: EventHandler) => void
-  }
+  // Known nouns (for autocomplete)
+  Customer: NounEventProxy
+  Order: NounEventProxy
+  Payment: NounEventProxy
+  User: NounEventProxy
+  Email: NounEventProxy
+  Invoice: NounEventProxy
+  Product: NounEventProxy
+  Subscription: NounEventProxy
+  // Index signature for dynamic nouns
+  [noun: string]: NounEventProxy
+}
+
+/**
+ * Schedule handler with optional time modifiers
+ * Allows $.every.Monday.at9am(handler) pattern
+ */
+export type DayScheduleProxy = ((handler: ScheduleHandler) => void) & {
+  at6am: (handler: ScheduleHandler) => void
+  at7am: (handler: ScheduleHandler) => void
+  at8am: (handler: ScheduleHandler) => void
+  at9am: (handler: ScheduleHandler) => void
+  at10am: (handler: ScheduleHandler) => void
+  at11am: (handler: ScheduleHandler) => void
+  at12pm: (handler: ScheduleHandler) => void
+  atnoon: (handler: ScheduleHandler) => void
+  at1pm: (handler: ScheduleHandler) => void
+  at2pm: (handler: ScheduleHandler) => void
+  at3pm: (handler: ScheduleHandler) => void
+  at4pm: (handler: ScheduleHandler) => void
+  at5pm: (handler: ScheduleHandler) => void
+  at6pm: (handler: ScheduleHandler) => void
+  atmidnight: (handler: ScheduleHandler) => void
+  [timeKey: string]: (handler: ScheduleHandler) => void
 }
 
 /**
  * Every proxy type for $.every patterns
+ *
+ * Includes explicit known schedule patterns for IDE autocomplete while
+ * preserving index signature for dynamic patterns.
  */
 export type EveryProxy = {
+  // Callable for natural language schedules
   (description: string, handler: ScheduleHandler): void
 } & {
-  [key: string]: ((handler: ScheduleHandler) => void) | ((value: number) => (handler: ScheduleHandler) => void) | {
-    [timeKey: 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
+  month: (handler: ScheduleHandler) => void
+  year: (handler: ScheduleHandler) => void
+
+  // Known days of week with time modifiers
+  Monday: DayScheduleProxy
+  Tuesday: DayScheduleProxy
+  Wednesday: DayScheduleProxy
+  Thursday: DayScheduleProxy
+  Friday: DayScheduleProxy
+  Saturday: DayScheduleProxy
+  Sunday: DayScheduleProxy
+  weekday: DayScheduleProxy
+  weekend: DayScheduleProxy
+  midnight: (handler: ScheduleHandler) => void
+  noon: (handler: ScheduleHandler) => void
+
+  // Plural forms for specifying intervals
+  seconds: (value: number) => (handler: ScheduleHandler) => void
+  minutes: (value: number) => (handler: ScheduleHandler) => void
+  hours: (value: number) => (handler: ScheduleHandler) => void
+  days: (value: number) => (handler: ScheduleHandler) => void
+  weeks: (value: number) => (handler: ScheduleHandler) => void
+
+  // Index signature for dynamic patterns
+  [key: string]: ((handler: ScheduleHandler) => void) | ((value: number) => (handler: ScheduleHandler) => void) | DayScheduleProxy
+}
+
+/**
+ * Callable target type for EveryProxy
+ * Used as a properly-typed Proxy target that supports both call and property access
+ */
+export type EveryProxyTarget = {
+  (description: string, handler: ScheduleHandler): void
+}
+
+/**
+ * ProxyHandler type for OnProxy
+ * Provides proper typing for the two-level noun.event proxy pattern
+ */
+export interface OnProxyHandler extends ProxyHandler<Record<string, NounEventProxy>> {
+  get(target: Record<string, NounEventProxy>, noun: string, receiver: unknown): NounEventProxy
+}
+
+/**
+ * ProxyHandler type for the inner noun level (event accessors)
+ */
+export interface NounEventProxyHandler extends ProxyHandler<Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void>> {
+  get(
+    target: Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void>,
+    event: string,
+    receiver: unknown
+  ): (handler: EventHandler, dependencies?: DependencyConfig) => void
+}
+
+/**
+ * ProxyHandler type for EveryProxy
+ * Handles both function calls and property access for schedule patterns
+ */
+export interface EveryProxyHandler extends ProxyHandler<EveryProxyTarget> {
+  get(target: EveryProxyTarget, prop: string, receiver: unknown): unknown
+  apply(target: EveryProxyTarget, thisArg: unknown, args: [string, ScheduleHandler]): void
+}
+
+/**
+ * ProxyHandler type for day schedule patterns with time modifiers
+ * Handles $.every.Monday.at9am pattern
+ */
+export interface DayScheduleProxyHandler extends ProxyHandler<(handler: ScheduleHandler) => void> {
+  get(
+    target: (handler: ScheduleHandler) => void,
+    timeKey: string,
+    receiver: unknown
+  ): ((handler: ScheduleHandler) => void) | undefined
+  apply(
+    target: (handler: ScheduleHandler) => void,
+    thisArg: unknown,
+    args: [ScheduleHandler]
+  ): void
 }
 
 /**
@@ -184,6 +323,30 @@ export interface WorkflowHistoryEntry {
   data?: unknown
 }
 
+/**
+ * Dependency type: hard (must succeed) or soft (can proceed on failure)
+ */
+export type DependencyType = 'hard' | 'soft'
+
+/**
+ * Configuration for step dependencies
+ */
+export interface DependencyConfig {
+  /**
+   * Step(s) that must complete before this step runs
+   * Can be a single step ID or array of step IDs
+   * Format: 'Noun.event' (e.g., 'Step1.complete')
+   */
+  dependsOn: string | string[]
+
+  /**
+   * Type of dependency (default: 'hard')
+   * - 'hard': Dependency must complete successfully
+   * - 'soft': Step can proceed even if dependency fails
+   */
+  type?: DependencyType
+}
+
 /**
  * Event registration with source
  */
@@ -192,6 +355,8 @@ export interface EventRegistration {
   event: string
   handler: EventHandler
   source: string
+  /** Optional dependency configuration for workflow step ordering */
+  dependencies?: DependencyConfig
 }
 
 /**
@@ -203,6 +368,48 @@ export interface ScheduleRegistration {
   source: string
 }
 
+/**
+ * Time-based interval types (singular form)
+ * Used as discriminant values in ScheduleInterval
+ */
+export type TimeIntervalType = 'second' | 'minute' | 'hour' | 'day' | 'week'
+
+/**
+ * Mapping from plural unit names to their singular interval types
+ * Used for type-safe conversion in every.units(value) patterns
+ */
+export type PluralUnitMapping = {
+  seconds: 'second'
+  minutes: 'minute'
+  hours: 'hour'
+  days: 'day'
+  weeks: 'week'
+}
+
+/**
+ * Plural unit keys
+ */
+export type PluralUnitKey = keyof PluralUnitMapping
+
+/**
+ * Type guard to check if a string is a valid plural unit key
+ */
+export function isPluralUnitKey(key: string): key is PluralUnitKey {
+  return key === 'seconds' || key === 'minutes' || key === 'hours' || key === 'days' || key === 'weeks'
+}
+
+/**
+ * Constant mapping object with strict typing
+ * Maps plural forms to their singular interval type values
+ */
+export const PLURAL_UNITS: Readonly<PluralUnitMapping> = {
+  seconds: 'second',
+  minutes: 'minute',
+  hours: 'hour',
+  days: 'day',
+  weeks: 'week',
+} as const
+
 /**
  * Schedule intervals
  */