@output.ai/core 0.5.1 → 0.5.2

package/src/interface/workflow.spec.js

@@ -1,79 +1,495 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { z } from 'zod';
 
+const inWorkflowContextMock = vi.hoisted( () => vi.fn( () => true ) );
 const traceDestinationsStepMock = vi.fn().mockResolvedValue( { local: '/tmp/trace' } );
-const proxyActivitiesMock = vi.fn( () => new Proxy( {}, {
-  get: ( _, prop ) => {
-    if ( prop === '__internal#getTraceDestinations' ) {
-      return traceDestinationsStepMock;
+const executeChildMock = vi.fn().mockResolvedValue( undefined );
+const continueAsNewMock = vi.fn().mockResolvedValue( undefined );
+
+const createStepsProxy = ( stepSpy = vi.fn() ) =>
+  new Proxy( {}, {
+    get: ( _, prop ) => {
+      if ( prop === '__internal#getTraceDestinations' ) {
+        return traceDestinationsStepMock;
+      }
+      if ( typeof prop === 'string' && ( prop.includes( '#' ) ) ) {
+        return stepSpy;
+      }
+      return vi.fn();
     }
-    return vi.fn();
-  }
-} ) );
-const workflowInfoMock = vi.fn( () => ( {
+  } );
+
+const stepSpyRef = { current: vi.fn().mockResolvedValue( {} ) };
+const proxyActivitiesMock = vi.fn( () => {
+  stepSpyRef.current = vi.fn().mockResolvedValue( {} );
+  return createStepsProxy( stepSpyRef.current );
+} );
+
+const workflowInfoReturn = {
   workflowId: 'wf-test-123',
   workflowType: 'test_wf',
   memo: {},
   startTime: new Date( '2025-01-01T00:00:00Z' ),
   continueAsNewSuggested: false
-} ) );
+};
+const workflowInfoMock = vi.fn( () => ( { ...workflowInfoReturn } ) );
 
 vi.mock( '@temporalio/workflow', () => ( {
-  proxyActivities: proxyActivitiesMock,
-  inWorkflowContext: () => true,
-  executeChild: vi.fn(),
+  proxyActivities: ( ...args ) => proxyActivitiesMock( ...args ),
+  inWorkflowContext: inWorkflowContextMock,
+  executeChild: ( ...args ) => executeChildMock( ...args ),
   workflowInfo: workflowInfoMock,
-  uuid4: () => 'uuid-mock',
+  uuid4: () => '550e8400e29b41d4a716446655440000',
   ParentClosePolicy: { TERMINATE: 'TERMINATE', ABANDON: 'ABANDON' },
-  continueAsNew: vi.fn()
+  continueAsNew: continueAsNewMock
 } ) );
 
-vi.mock( '#consts', () => ( {
-  SHARED_STEP_PREFIX: '__shared',
-  ACTIVITY_GET_TRACE_DESTINATIONS: '__internal#getTraceDestinations',
-  METADATA_ACCESS_SYMBOL: Symbol( 'metadata' )
-} ) );
+vi.mock( '#consts', async importOriginal => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    SHARED_STEP_PREFIX: '__shared',
+    ACTIVITY_GET_TRACE_DESTINATIONS: '__internal#getTraceDestinations'
+  };
+} );
 
 describe( 'workflow()', () => {
   beforeEach( () => {
     vi.clearAllMocks();
-    workflowInfoMock.mockReturnValue( {
-      workflowId: 'wf-test-123',
-      workflowType: 'test_wf',
-      memo: {},
-      startTime: new Date( '2025-01-01T00:00:00Z' ),
-      continueAsNewSuggested: false
+    inWorkflowContextMock.mockReturnValue( true );
+    workflowInfoMock.mockReturnValue( { ...workflowInfoReturn } );
+    workflowInfoReturn.memo = {};
+    proxyActivitiesMock.mockImplementation( () => {
+      stepSpyRef.current = vi.fn().mockResolvedValue( {} );
+      return createStepsProxy( stepSpyRef.current );
+    } );
+  } );
+
+  describe( 'options and defaults', () => {
+    it( 'does not throw when options is omitted (disableTrace defaults to false)', async () => {
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'no_options_wf',
+        description: 'Workflow without options',
+        inputSchema: z.object( { value: z.string() } ),
+        outputSchema: z.object( { value: z.string() } ),
+        fn: async ( { value } ) => ( { value } )
+      } );
+
+      const result = await wf( { value: 'hello' } );
+      expect( result.output ).toEqual( { value: 'hello' } );
+    } );
+
+    it( 'respects disableTrace: true when options is provided', async () => {
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'trace_disabled_wf',
+        description: 'Workflow with tracing disabled',
+        inputSchema: z.object( { value: z.string() } ),
+        outputSchema: z.object( { value: z.string() } ),
+        options: { disableTrace: true },
+        fn: async ( { value } ) => ( { value } )
+      } );
+
+      const result = await wf( { value: 'hello' } );
+      expect( result.output ).toEqual( { value: 'hello' } );
+    } );
+
+    it( 'merges custom activityOptions with defaults via deepMerge', async () => {
+      const { workflow } = await import( './workflow.js' );
+
+      workflow( {
+        name: 'custom_activity_wf',
+        description: 'Workflow with custom activity options',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {} ),
+        options: {
+          activityOptions: {
+            startToCloseTimeout: '5m',
+            retry: { maximumAttempts: 5 }
+          }
+        },
+        fn: async () => ( {} )
+      } );
+
+      expect( proxyActivitiesMock ).toHaveBeenCalledWith(
+        expect.objectContaining( {
+          startToCloseTimeout: '5m',
+          retry: expect.objectContaining( { maximumAttempts: 5 } )
+        } )
+      );
     } );
   } );
 
-  it( 'does not throw when options is omitted (disableTrace defaults to false)', async () => {
-    const { workflow } = await import( './workflow.js' );
+  describe( 'wrapper metadata', () => {
+    it( 'attaches name, description, inputSchema, outputSchema to wrapper via setMetadata', async () => {
+      const { workflow } = await import( './workflow.js' );
+      const inputSchema = z.object( { x: z.number() } );
+      const outputSchema = z.object( { y: z.number() } );
 
-    const wf = workflow( {
-      name: 'no_options_wf',
-      description: 'Workflow without options',
-      inputSchema: z.object( { value: z.string() } ),
-      outputSchema: z.object( { value: z.string() } ),
-      fn: async ( { value } ) => ( { value } )
+      const wf = workflow( {
+        name: 'meta_wf',
+        description: 'Meta workflow',
+        inputSchema,
+        outputSchema,
+        fn: async input => ( { y: input.x } )
+      } );
+
+      const symbols = Object.getOwnPropertySymbols( wf );
+      expect( symbols ).toHaveLength( 1 );
+      const meta = wf[symbols[0]];
+      expect( meta ).toEqual( { name: 'meta_wf', description: 'Meta workflow', inputSchema, outputSchema } );
+    } );
+  } );
+
+  describe( 'when not in workflow context (unit-test path)', () => {
+    it( 'validates input, runs fn with test context, validates output, returns plain output', async () => {
+      inWorkflowContextMock.mockReturnValue( false );
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'unit_path_wf',
+        description: 'Unit path',
+        inputSchema: z.object( { a: z.string() } ),
+        outputSchema: z.object( { b: z.string() } ),
+        fn: async ( input, context ) => ( {
+          b: String( context.info.workflowId ) + input.a
+        } )
+      } );
+
+      const result = await wf( { a: '-ok' } );
+      expect( result ).toEqual( { b: 'test-workflow-ok' } );
+      expect( workflowInfoMock ).not.toHaveBeenCalled();
+      expect( traceDestinationsStepMock ).not.toHaveBeenCalled();
+    } );
+
+    it( 'merges extra.context into context when provided', async () => {
+      inWorkflowContextMock.mockReturnValue( false );
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'extra_ctx_wf',
+        description: 'Extra context',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( { id: z.string() } ),
+        fn: async ( _, context ) => ( { id: context.extraId ?? 'default' } )
+      } );
+
+      const result = await wf( {}, { context: { extraId: 'injected' } } );
+      expect( result ).toEqual( { id: 'injected' } );
+    } );
+  } );
+
+  describe( 'input and output validation', () => {
+    it( 'throws ValidationError when input does not match inputSchema', async () => {
+      const { workflow } = await import( './workflow.js' );
+      const { ValidationError } = await import( '#errors' );
+
+      const wf = workflow( {
+        name: 'validate_in_wf',
+        description: 'Input validation',
+        inputSchema: z.object( { required: z.string() } ),
+        outputSchema: z.object( {} ),
+        fn: async () => ( {} )
+      } );
+
+      await expect( wf( { wrong: 1 } ) ).rejects.toThrow( ValidationError );
+      await expect( wf( { wrong: 1 } ) ).rejects.toThrow( /Workflow validate_in_wf input/ );
     } );
 
-    const result = await wf( { value: 'hello' } );
-    expect( result.output ).toEqual( { value: 'hello' } );
+    it( 'throws ValidationError when output does not match outputSchema', async () => {
+      const { workflow } = await import( './workflow.js' );
+      const { ValidationError } = await import( '#errors' );
+
+      const wf = workflow( {
+        name: 'validate_out_wf',
+        description: 'Output validation',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( { required: z.string() } ),
+        fn: async () => ( { other: 1 } )
+      } );
+
+      await expect( wf( {} ) ).rejects.toThrow( ValidationError );
+      await expect( wf( {} ) ).rejects.toThrow( /Workflow validate_out_wf output/ );
+    } );
   } );
 
-  it( 'respects disableTrace: true when options is provided', async () => {
-    const { workflow } = await import( './workflow.js' );
+  describe( 'root workflow (in workflow context)', () => {
+    it( 'calls getTraceDestinations, returns { output, trace } and assigns executionContext to memo', async () => {
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'root_wf',
+        description: 'Root',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( { v: z.number() } ),
+        fn: async () => ( { v: 42 } )
+      } );
 
-    const wf = workflow( {
-      name: 'trace_disabled_wf',
-      description: 'Workflow with tracing disabled',
-      inputSchema: z.object( { value: z.string() } ),
-      outputSchema: z.object( { value: z.string() } ),
-      options: { disableTrace: true },
-      fn: async ( { value } ) => ( { value } )
+      const result = await wf( {} );
+      expect( traceDestinationsStepMock ).toHaveBeenCalledTimes( 1 );
+      expect( result ).toEqual( {
+        output: { v: 42 },
+        trace: { destinations: { local: '/tmp/trace' } }
+      } );
+      const memo = workflowInfoMock().memo;
+      expect( memo.executionContext ).toEqual( {
+        workflowId: 'wf-test-123',
+        workflowName: 'root_wf',
+        disableTrace: false,
+        startTime: new Date( '2025-01-01T00:00:00Z' ).getTime()
+      } );
     } );
 
-    const result = await wf( { value: 'hello' } );
-    expect( result.output ).toEqual( { value: 'hello' } );
+    it( 'sets executionContext.disableTrace when options.disableTrace is true', async () => {
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'root_no_trace_wf',
+        description: 'Root no trace',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {} ),
+        options: { disableTrace: true },
+        fn: async () => ( {} )
+      } );
+
+      await wf( {} );
+      expect( workflowInfoMock().memo.executionContext.disableTrace ).toBe( true );
+    } );
+  } );
+
+  describe( 'child workflow (memo.executionContext already set)', () => {
+    it( 'does not call getTraceDestinations and returns plain output', async () => {
+      workflowInfoMock.mockReturnValue( {
+        ...workflowInfoReturn,
+        memo: { executionContext: { workflowId: 'parent-1', workflowName: 'parent_wf' } }
+      } );
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'child_wf',
+        description: 'Child',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( { x: z.string() } ),
+        fn: async () => ( { x: 'child' } )
+      } );
+
+      const result = await wf( {} );
+      expect( traceDestinationsStepMock ).not.toHaveBeenCalled();
+      expect( result ).toEqual( { x: 'child' } );
+    } );
+  } );
+
+  describe( 'bound this: invokeStep, invokeSharedStep, invokeEvaluator', () => {
+    it( 'invokeStep calls steps with workflowName#stepName', async () => {
+      const getCalls = [];
+      proxyActivitiesMock.mockImplementation( () => new Proxy( {}, {
+        get: ( _, prop ) => {
+          if ( prop === '__internal#getTraceDestinations' ) {
+            return traceDestinationsStepMock;
+          }
+          if ( typeof prop === 'string' && prop.includes( '#' ) ) {
+            getCalls.push( prop );
+            return vi.fn().mockResolvedValue( {} );
+          }
+          return vi.fn();
+        }
+      } ) );
+
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'invoke_wf',
+        description: 'Invoke',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {} ),
+        async fn() {
+          await this.invokeStep( 'myStep', { foo: 1 } );
+          return {};
+        }
+      } );
+
+      await wf( {} );
+      expect( getCalls ).toContain( 'invoke_wf#myStep' );
+    } );
+
+    it( 'invokeSharedStep calls steps with SHARED_STEP_PREFIX#stepName', async () => {
+      const { workflow } = await import( './workflow.js' );
+      const sharedSpy = vi.fn().mockResolvedValue( {} );
+      proxyActivitiesMock.mockImplementation( () => new Proxy( {}, {
+        get: ( _, prop ) => {
+          if ( prop === '__internal#getTraceDestinations' ) {
+            return traceDestinationsStepMock;
+          }
+          if ( prop === '__shared#sharedStep' ) {
+            return sharedSpy;
+          }
+          return vi.fn();
+        }
+      } ) );
+
+      const wf = workflow( {
+        name: 'shared_wf',
+        description: 'Shared',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {} ),
+        async fn() {
+          await this.invokeSharedStep( 'sharedStep', { data: 2 } );
+          return {};
+        }
+      } );
+
+      await wf( {} );
+      expect( sharedSpy ).toHaveBeenCalledWith( { data: 2 }, undefined );
+    } );
+
+    it( 'invokeEvaluator calls steps with workflowName#evaluatorName', async () => {
+      const evalSpy = vi.fn().mockResolvedValue( true );
+      proxyActivitiesMock.mockImplementation( () => new Proxy( {}, {
+        get: ( _, prop ) => {
+          if ( prop === '__internal#getTraceDestinations' ) {
+            return traceDestinationsStepMock;
+          }
+          if ( prop === 'eval_wf#myEvaluator' ) {
+            return evalSpy;
+          }
+          return vi.fn();
+        }
+      } ) );
+
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'eval_wf',
+        description: 'Eval',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {} ),
+        async fn() {
+          await this.invokeEvaluator( 'myEvaluator', { x: 3 } );
+          return {};
+        }
+      } );
+
+      await wf( {} );
+      expect( evalSpy ).toHaveBeenCalledWith( { x: 3 }, undefined );
+    } );
+  } );
+
+  describe( 'startWorkflow', () => {
+    it( 'calls executeChild with correct args and TERMINATE when not detached', async () => {
+      const { workflow } = await import( './workflow.js' );
+      const { ParentClosePolicy } = await import( '@temporalio/workflow' );
+
+      const wf = workflow( {
+        name: 'parent_wf',
+        description: 'Parent',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {} ),
+        async fn() {
+          await this.startWorkflow( 'child_wf', { id: 1 } );
+          return {};
+        }
+      } );
+
+      await wf( {} );
+      expect( executeChildMock ).toHaveBeenCalledWith( 'child_wf', {
+        args: [ { id: 1 } ],
+        workflowId: expect.stringMatching( /^wf-test-123-/ ),
+        parentClosePolicy: ParentClosePolicy.TERMINATE,
+        memo: expect.objectContaining( {
+          executionContext: expect.any( Object ),
+          parentId: 'wf-test-123'
+        } )
+      } );
+    } );
+
+    it( 'uses ABANDON when extra.detached is true', async () => {
+      const { workflow } = await import( './workflow.js' );
+      const { ParentClosePolicy } = await import( '@temporalio/workflow' );
+
+      const wf = workflow( {
+        name: 'detach_wf',
+        description: 'Detach',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {} ),
+        async fn() {
+          await this.startWorkflow( 'child_wf', null, { detached: true } );
+          return {};
+        }
+      } );
+
+      await wf( {} );
+      expect( executeChildMock ).toHaveBeenCalledWith( 'child_wf', expect.objectContaining( {
+        parentClosePolicy: ParentClosePolicy.ABANDON
+      } ) );
+    } );
+
+    it( 'passes empty args when input is null/omitted', async () => {
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'no_input_wf',
+        description: 'No input',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {} ),
+        async fn() {
+          await this.startWorkflow( 'child_wf' );
+          return {};
+        }
+      } );
+
+      await wf( {} );
+      expect( executeChildMock ).toHaveBeenCalledWith( 'child_wf', expect.objectContaining( {
+        args: []
+      } ) );
+    } );
+  } );
+
+  describe( 'context.control', () => {
+    it( 'exposes info.workflowId and control/info namespaces when not in workflow context', async () => {
+      inWorkflowContextMock.mockReturnValue( false );
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'control_wf',
+        description: 'Control',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {
+          workflowId: z.string(),
+          hasControl: z.boolean(),
+          hasInfo: z.boolean()
+        } ),
+        fn: async ( _, context ) => ( {
+          workflowId: context.info?.workflowId,
+          hasControl: 'control' in context,
+          hasInfo: 'info' in context
+        } )
+      } );
+
+      const result = await wf( {} );
+      expect( result.workflowId ).toBe( 'test-workflow' );
+      expect( result.hasControl ).toBe( true );
+      expect( result.hasInfo ).toBe( true );
+    } );
+  } );
+
+  describe( 'error handling (root workflow)', () => {
+    it( 'rethrows error from fn and rejects with same message', async () => {
+      const { workflow } = await import( './workflow.js' );
+
+      const wf = workflow( {
+        name: 'err_wf',
+        description: 'Error',
+        inputSchema: z.object( {} ),
+        outputSchema: z.object( {} ),
+        fn: async () => {
+          throw new Error( 'workflow failed' );
+        }
+      } );
+
+      await expect( wf( {} ) ).rejects.toThrow( 'workflow failed' );
+    } );
   } );
 } );

package/src/interface/workflow_context.js

@@ -0,0 +1,31 @@
+/**
+ * Context instance builder
+ */
+export class Context {
+
+  /**
+   * Builds a new context instance
+   * @param {object} options - Arguments to build a new context instance
+   * @param {string} workflowId
+   * @param {function} continueAsNew
+   * @param {function} isContinueAsNewSuggested
+   * @returns {object} context
+   */
+  static build( { workflowId, continueAsNew, isContinueAsNewSuggested } ) {
+    return {
+      /**
+       * Control namespace: This object adds functions to interact with Temporal flow mechanisms
+       */
+      control: {
+        continueAsNew,
+        isContinueAsNewSuggested
+      },
+      /**
+       * Info namespace: abstracts workflowInfo()
+       */
+      info: {
+        workflowId
+      }
+    };
+  }
+};

package/src/interface/workflow_utils.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Result of a single job executed by `executeInParallel`.
+ *
+ * @typeParam T - The return type of the job function
+ */
+export type ParallelJobResult<T> =
+  | { ok: true; result: T; index: number } |
+  { ok: false; error: unknown; index: number };
+
+/**
+ * Execute jobs in parallel with optional concurrency limit.
+ *
+ * Returns all job results (successes and failures) sorted by original job index.
+ * Each result contains `ok` (boolean), `index` (original position), and either
+ * `result` (on success) or `error` (on failure).
+ *
+ * Jobs must be wrapped in arrow functions—do not pass promises directly.
+ *
+ * @example
+ * ```ts
+ * const results = await executeInParallel( {
+ *   jobs: [
+ *     () => myStep( data1 ),
+ *     () => myStep( data2 ),
+ *     () => myStep( data3 )
+ *   ],
+ *   concurrency: 2
+ * } );
+ *
+ * // Handle the discriminated union (result only exists when ok is true)
+ * const successfulResults = results.filter( r => r.ok ).map( r => r.result );
+ *
+ * // Or handle each result individually
+ * for ( const r of results ) {
+ *   if ( r.ok ) {
+ *     console.log( `Job ${r.index} succeeded:`, r.result );
+ *   } else {
+ *     console.log( `Job ${r.index} failed:`, r.error );
+ *   }
+ * }
+ * ```
+ *
+ * @param params - Parameters object
+ * @param params.jobs - Array of arrow functions returning step/activity calls (not promises directly)
+ * @param params.concurrency - Max concurrent jobs (default: Infinity)
+ * @param params.onJobCompleted - Optional callback invoked as each job completes (in completion order)
+ * @returns Array of results sorted by original job index
+ */
+export declare function executeInParallel<T>( params: {
+  jobs: Array<() => Promise<T> | T>;
+  concurrency?: number;
+  onJobCompleted?: ( result: ParallelJobResult<T> ) => void;
+} ): Promise<Array<ParallelJobResult<T>>>;

package/src/interface/workflow_utils.js

@@ -1,3 +1,4 @@
+// THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
 import { validateExecuteInParallel } from './validations/static.js';
 
 /**

package/src/utils/index.d.ts

@@ -94,7 +94,7 @@ export function isPlainObject( object: unknown ): boolean;
  * @param arr - The array to shuffle
  * @returns A shuffled array copy
  */
-export function shuffleArray( arr: array ): array;
+export function shuffleArray( arr: unknown[] ): unknown[];
 
 /**
  * Creates a new object by merging object `b` onto object `a`, biased toward `b`: