@outputai/core 0.7.0 → 0.7.1-next.0e958f3.0

package/src/interface/validations/index.spec.js

@@ -0,0 +1,182 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { ValidationError } from '#errors';
+import { EvaluationResult } from '../evaluation_result.js';
+import {
+  EvaluatorValidator,
+  StepValidator,
+  WorkflowValidator,
+  validateExecuteInParallel,
+  validateRequestPayload
+} from './index.js';
+
+const fn = async () => {};
+
+const workflowArgs = {
+  name: 'valid_workflow',
+  description: 'Valid workflow',
+  inputSchema: z.object( { value: z.string() } ),
+  outputSchema: z.object( { result: z.string() } ),
+  fn,
+  options: {
+    activityOptions: {
+      startToCloseTimeout: '5m',
+      retry: { maximumAttempts: 2 }
+    },
+    disableTrace: true
+  },
+  aliases: [ 'old_workflow' ]
+};
+
+const stepArgs = {
+  name: 'valid_step',
+  description: 'Valid step',
+  inputSchema: z.object( { value: z.string() } ),
+  outputSchema: z.object( { result: z.string() } ),
+  fn,
+  options: {
+    activityOptions: {
+      heartbeatTimeout: '30s'
+    }
+  }
+};
+
+const evaluatorArgs = {
+  name: 'valid_evaluator',
+  description: 'Valid evaluator',
+  inputSchema: z.object( { value: z.string() } ),
+  fn
+};
+
+describe( 'interface validators', () => {
+  describe( 'WorkflowValidator', () => {
+    it( 'validates workflow definitions, input, output, and invocation options', () => {
+      expect( () => WorkflowValidator.validateDefinition( workflowArgs ) ).not.toThrow();
+      const validator = new WorkflowValidator( workflowArgs );
+
+      expect( () => validator.validateInput( { value: 'ok' } ) ).not.toThrow();
+      expect( () => validator.validateOutput( { result: 'ok' } ) ).not.toThrow();
+      expect( () => validator.validateInvocationOptions( {
+        detached: true,
+        activityOptions: { retry: { maximumAttempts: 1 } },
+        context: { info: { workflowId: 'test-workflow' } }
+      } ) ).not.toThrow();
+    } );
+
+    it( 'throws ValidationError with useful prefixes for invalid workflow data', () => {
+      expect( () => WorkflowValidator.validateDefinition( { ...workflowArgs, name: 'bad-name' } ) ).toThrow( ValidationError );
+      expect( () => WorkflowValidator.validateDefinition( { ...workflowArgs, name: 'bad-name' } ) ).toThrow(
+        /Workflow validation failed/
+      );
+
+      const validator = new WorkflowValidator( workflowArgs );
+
+      expect( () => validator.validateInput( { value: 1 } ) ).toThrow( ValidationError );
+      expect( () => validator.validateInput( { value: 1 } ) ).toThrow( /Workflow "valid_workflow" input validation failed/ );
+      expect( () => validator.validateOutput( { result: 1 } ) ).toThrow( /Workflow "valid_workflow" output validation failed/ );
+      expect( () => validator.validateInvocationOptions( {
+        options: { activityOptions: { retry: { maximumAttempts: 1 } } }
+      } ) ).toThrow( /Workflow "valid_workflow" invocation options validation failed/ );
+    } );
+
+    it( 'skips input and output validation when schemas are omitted', () => {
+      const validator = new WorkflowValidator( {
+        name: 'schema_less_workflow',
+        fn
+      } );
+
+      expect( () => validator.validateInput( { anything: true } ) ).not.toThrow();
+      expect( () => validator.validateOutput( { anything: true } ) ).not.toThrow();
+    } );
+  } );
+
+  describe( 'StepValidator', () => {
+    it( 'validates step definitions, input, and output', () => {
+      expect( () => StepValidator.validateDefinition( stepArgs ) ).not.toThrow();
+      const validator = new StepValidator( stepArgs );
+
+      expect( () => validator.validateInput( { value: 'ok' } ) ).not.toThrow();
+      expect( () => validator.validateOutput( { result: 'ok' } ) ).not.toThrow();
+    } );
+
+    it( 'throws ValidationError with useful prefixes for invalid step data', () => {
+      expect( () => StepValidator.validateDefinition( { ...stepArgs, fn: 'not-a-function' } ) ).toThrow(
+        /Step validation failed/
+      );
+
+      const validator = new StepValidator( stepArgs );
+
+      expect( () => validator.validateInput( { value: 1 } ) ).toThrow( /Step "valid_step" input validation failed/ );
+      expect( () => validator.validateOutput( { result: 1 } ) ).toThrow( /Step "valid_step" output validation failed/ );
+    } );
+  } );
+
+  describe( 'EvaluatorValidator', () => {
+    it( 'validates evaluator definitions, input, and EvaluationResult output', () => {
+      expect( () => EvaluatorValidator.validateDefinition( evaluatorArgs ) ).not.toThrow();
+      const validator = new EvaluatorValidator( evaluatorArgs );
+
+      expect( () => validator.validateInput( { value: 'ok' } ) ).not.toThrow();
+      expect( () => validator.validateOutput( new EvaluationResult( { value: 'pass', confidence: 1 } ) ) ).not.toThrow();
+    } );
+
+    it( 'throws ValidationError for output schemas and invalid evaluator output', () => {
+      expect( () => EvaluatorValidator.validateDefinition( {
+        ...evaluatorArgs,
+        outputSchema: z.string()
+      } ) ).toThrow( /Evaluator validation failed/ );
+
+      const validator = new EvaluatorValidator( evaluatorArgs );
+
+      expect( () => validator.validateInput( { value: 1 } ) ).toThrow( /Evaluator "valid_evaluator" input validation failed/ );
+      expect( () => validator.validateOutput( { value: 'pass', confidence: 1 } ) ).toThrow(
+        /Evaluator "valid_evaluator" output validation failed/
+      );
+    } );
+  } );
+
+  describe( 'validateRequestPayload()', () => {
+    it( 'accepts valid request payloads', () => {
+      expect( () => validateRequestPayload( {
+        url: 'https://example.com',
+        method: 'POST',
+        payload: { ok: true },
+        headers: { authorization: 'Bearer token' }
+      } ) ).not.toThrow();
+    } );
+
+    it( 'throws ValidationError for invalid request payloads', () => {
+      expect( () => validateRequestPayload( {
+        url: 'ftp://example.com',
+        method: 'POST'
+      } ) ).toThrow( /Request payload validation failed/ );
+
+      expect( () => validateRequestPayload( {
+        url: 'https://example.com',
+        method: 'OPTIONS'
+      } ) ).toThrow( ValidationError );
+    } );
+  } );
+
+  describe( 'validateExecuteInParallel()', () => {
+    it( 'accepts valid parallel execution configs', () => {
+      expect( () => validateExecuteInParallel( {
+        jobs: [ () => 'ok' ],
+        concurrency: Infinity,
+        onJobCompleted: () => {}
+      } ) ).not.toThrow();
+    } );
+
+    it( 'throws ValidationError for invalid parallel execution configs', () => {
+      expect( () => validateExecuteInParallel( {
+        jobs: [ () => 'ok' ],
+        concurrency: 0
+      } ) ).toThrow( /ExecuteInParallel validation failed/ );
+
+      expect( () => validateExecuteInParallel( {
+        jobs: [ 'not-a-function' ],
+        concurrency: 1
+      } ) ).toThrow( ValidationError );
+    } );
+  } );
+} );

package/src/interface/validations/schemas.js

@@ -0,0 +1,113 @@
+import * as z from 'zod';
+import { EvaluationResult } from '../evaluation_result.js';
+
+/**
+ * Detects if a value behaves like a Zod v4 Classic/Mini schema.
+ *
+ * Zod v4 schemas from different package instances do not share the same
+ * prototype, so `instanceof z.ZodType` is too fragile here. The `_zod`
+ * property is the documented v4 runtime marker, and `safeParse` is required
+ * because the validators call it directly.
+ *
+ * @param {unknown} schema - The schema to check
+ * @returns {boolean} True if the schema is a Zod schema
+ */
+export const isZodSchema = schema =>
+  Boolean(
+    schema &&
+    typeof schema === 'object' &&
+    typeof schema._zod?.def?.type === 'string' &&
+    typeof schema.safeParse === 'function'
+  );
+
+const refineSchema = ( value, ctx ) => {
+  if ( !value || isZodSchema( value ) ) {
+    return;
+  }
+
+  ctx.addIssue( {
+    code: 'invalid_type',
+    message: 'Schema must be a Zod schema'
+  } );
+};
+
+const durationSchema = z.union( [ z.string().regex(
+  /^(\d+)(ms|s|m|h|d)$/,
+  'Expected duration like "500ms", "10s", "5m", "2h", or "1d"'
+), z.number() ] );
+
+const prioritySchema = z.object( {
+  fairnessKey: z.string().optional(),
+  fairnessWeight: z.number().min( 0.0001 ).max( 1000 ).optional(),
+  priorityKey: z.number().min( 1 ).optional()
+} );
+
+const activityOptionsSchema = z.strictObject( {
+  activityId: z.string().optional(),
+  cancellationType: z.enum( [ 'TRY_CANCEL', 'WAIT_CANCELLATION_COMPLETED', 'ABANDON' ] ).optional(),
+  heartbeatTimeout: durationSchema.optional(),
+  priority: prioritySchema.optional(),
+  retry: z.strictObject( {
+    initialInterval: durationSchema.optional(),
+    backoffCoefficient: z.number().gte( 1 ).optional(),
+    maximumInterval: durationSchema.optional(),
+    maximumAttempts: z.number().gte( 1 ).int().optional(),
+    nonRetryableErrorTypes: z.array( z.string() ).optional()
+  } ).optional(),
+  scheduleToCloseTimeout: durationSchema.optional(),
+  scheduleToStartTimeout: durationSchema.optional(),
+  startToCloseTimeout: durationSchema.optional(),
+  summary: z.string().optional()
+} );
+
+const baseSchema = z.strictObject( {
+  name: z.string().regex( /^[a-z_][a-z0-9_]*$/i ),
+  description: z.string().optional(),
+  inputSchema: z.any().optional().superRefine( refineSchema ),
+  outputSchema: z.any().optional().superRefine( refineSchema ),
+  fn: z.function(),
+  options: z.object( {
+    activityOptions: activityOptionsSchema.optional()
+  } ).optional()
+} );
+
+export const stepSchema = baseSchema;
+
+export const workflowSchema = baseSchema.extend( {
+  aliases: z.array( z.string().regex( /^[a-z_][a-z0-9_]*$/i ) ).optional().default( [] ),
+  options: baseSchema.shape.options.unwrap().extend( {
+    disableTrace: z.boolean().optional().default( false )
+  } ).optional()
+} );
+
+export const evaluatorSchema = baseSchema.omit( { outputSchema: true } );
+
+export const evaluatorOutputSchema = z.instanceof( EvaluationResult );
+
+export const httpRequestSchema = z.object( {
+  url: z.url( { protocol: /^https?$/ } ),
+  method: z.enum( [ 'GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE' ] ),
+  payload: z.any().optional(),
+  headers: z.record( z.string(), z.string() ).optional()
+} );
+
+export const workflowInvocationOptionsSchema = z.strictObject( {
+  detached: z.boolean().optional(),
+  activityOptions: activityOptionsSchema.optional(),
+  context: z.object( {
+    control: z.object( {
+      continueAsNew: z.function().optional(),
+      isContinueAsNewSuggested: z.function().optional()
+    } ).loose().optional(),
+    info: z.object( {
+      workflowId: z.string().optional(),
+      runId: z.string().optional()
+    } ).loose().optional()
+  } ).loose().optional()
+} ).optional();
+
+export const executeInParallelSchema = z.object( {
+  jobs: z.array( z.function() ),
+  concurrency: z.number().min( 1 ).or( z.literal( Infinity ) ),
+  onJobCompleted: z.function().optional()
+} );

package/src/interface/validations/schemas.spec.js

@@ -0,0 +1,209 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { EvaluationResult } from '../evaluation_result.js';
+import {
+  evaluatorOutputSchema,
+  evaluatorSchema,
+  executeInParallelSchema,
+  httpRequestSchema,
+  isZodSchema,
+  stepSchema,
+  workflowInvocationOptionsSchema,
+  workflowSchema
+} from './schemas.js';
+
+const fn = () => {};
+const validBase = {
+  name: 'valid_name',
+  description: 'Valid description',
+  inputSchema: z.object( { value: z.string() } ),
+  outputSchema: z.object( { result: z.string() } ),
+  fn,
+  options: {
+    activityOptions: {
+      startToCloseTimeout: '5m',
+      heartbeatTimeout: 1000,
+      retry: {
+        initialInterval: '10s',
+        backoffCoefficient: 2,
+        maximumInterval: '1m',
+        maximumAttempts: 3,
+        nonRetryableErrorTypes: [ 'FatalError' ]
+      },
+      priority: {
+        fairnessKey: 'tenant',
+        fairnessWeight: 1,
+        priorityKey: 2
+      },
+      summary: 'Short summary'
+    }
+  }
+};
+
+describe( 'validation schemas', () => {
+  describe( 'isZodSchema()', () => {
+    it( 'identifies Zod schemas', () => {
+      expect( isZodSchema( z.object( { name: z.string() } ) ) ).toBe( true );
+      expect( isZodSchema( z.string() ) ).toBe( true );
+      expect( isZodSchema( z.array( z.number() ) ) ).toBe( true );
+      expect( isZodSchema( z.union( [ z.string(), z.number() ] ) ) ).toBe( true );
+    } );
+
+    it( 'uses the Zod v4 runtime shape instead of instanceof', () => {
+      const schemaLikeFromAnotherPackageInstance = {
+        _zod: {
+          def: {
+            type: 'object'
+          }
+        },
+        safeParse: () => ( { success: true, data: {} } )
+      };
+
+      expect( isZodSchema( schemaLikeFromAnotherPackageInstance ) ).toBe( true );
+    } );
+
+    it( 'rejects non-Zod values', () => {
+      expect( isZodSchema( { type: 'object' } ) ).toBe( false );
+      expect( isZodSchema( {} ) ).toBe( false );
+      expect( isZodSchema( [] ) ).toBe( false );
+      expect( isZodSchema( null ) ).toBe( false );
+      expect( isZodSchema( undefined ) ).toBe( false );
+      expect( isZodSchema( 'string' ) ).toBe( false );
+    } );
+
+    it( 'rejects objects that only partially match the Zod shape', () => {
+      expect( isZodSchema( { safeParse: () => ( { success: true } ) } ) ).toBe( false );
+      expect( isZodSchema( { _zod: { def: { type: 'string' } } } ) ).toBe( false );
+      expect( isZodSchema( { _zod: { def: {} }, safeParse: () => ( { success: true } ) } ) ).toBe( false );
+      expect( isZodSchema( { _zod: null, safeParse: () => ( { success: true } ) } ) ).toBe( false );
+    } );
+  } );
+
+  describe( 'stepSchema', () => {
+    it( 'accepts a valid step definition', () => {
+      expect( stepSchema.safeParse( validBase ).success ).toBe( true );
+    } );
+
+    it( 'rejects invalid names, non-Zod schemas, invalid activity options, and unknown top-level keys', () => {
+      expect( stepSchema.safeParse( { ...validBase, name: 'invalid-name' } ).success ).toBe( false );
+      expect( stepSchema.safeParse( { ...validBase, inputSchema: { type: 'object' } } ).success ).toBe( false );
+      expect( stepSchema.safeParse( {
+        ...validBase,
+        options: { activityOptions: { retry: { maximumAttempts: 0 } } }
+      } ).success ).toBe( false );
+      expect( stepSchema.safeParse( { ...validBase, unexpected: true } ).success ).toBe( false );
+    } );
+  } );
+
+  describe( 'workflowSchema', () => {
+    it( 'accepts workflow-specific options and aliases', () => {
+      const result = workflowSchema.safeParse( {
+        ...validBase,
+        aliases: [ 'old_name' ],
+        options: {
+          ...validBase.options,
+          disableTrace: true
+        }
+      } );
+
+      expect( result.success ).toBe( true );
+    } );
+
+    it( 'defaults aliases and rejects invalid workflow fields', () => {
+      const result = workflowSchema.safeParse( validBase );
+      expect( result.success && result.data.aliases ).toEqual( [] );
+
+      expect( workflowSchema.safeParse( { ...validBase, aliases: [ 'bad-alias' ] } ).success ).toBe( false );
+      expect( workflowSchema.safeParse( {
+        ...validBase,
+        options: { ...validBase.options, disableTrace: 'yes' }
+      } ).success ).toBe( false );
+    } );
+  } );
+
+  describe( 'evaluatorSchema and evaluatorOutputSchema', () => {
+    it( 'accepts evaluator definitions without outputSchema', () => {
+      const { outputSchema: _outputSchema, ...validEvaluator } = validBase;
+      expect( evaluatorSchema.safeParse( validEvaluator ).success ).toBe( true );
+    } );
+
+    it( 'rejects evaluator definitions with outputSchema', () => {
+      expect( evaluatorSchema.safeParse( validBase ).success ).toBe( false );
+    } );
+
+    it( 'accepts only EvaluationResult instances as evaluator output', () => {
+      expect( evaluatorOutputSchema.safeParse( new EvaluationResult( { value: 'ok', confidence: 1 } ) ).success ).toBe( true );
+      expect( evaluatorOutputSchema.safeParse( { value: 'ok', confidence: 1 } ).success ).toBe( false );
+    } );
+  } );
+
+  describe( 'httpRequestSchema', () => {
+    it( 'accepts valid HTTP request payloads', () => {
+      expect( httpRequestSchema.safeParse( {
+        url: 'https://example.com',
+        method: 'POST',
+        payload: { ok: true },
+        headers: { authorization: 'Bearer token' }
+      } ).success ).toBe( true );
+    } );
+
+    it( 'rejects invalid URL protocols, methods, and header values', () => {
+      expect( httpRequestSchema.safeParse( { url: 'ftp://example.com', method: 'GET' } ).success ).toBe( false );
+      expect( httpRequestSchema.safeParse( { url: 'https://example.com', method: 'OPTIONS' } ).success ).toBe( false );
+      expect( httpRequestSchema.safeParse( {
+        url: 'https://example.com',
+        method: 'GET',
+        headers: { count: 1 }
+      } ).success ).toBe( false );
+    } );
+  } );
+
+  describe( 'workflowInvocationOptionsSchema', () => {
+    it( 'accepts omitted options and valid invocation configuration', () => {
+      expect( workflowInvocationOptionsSchema.safeParse( undefined ).success ).toBe( true );
+      expect( workflowInvocationOptionsSchema.safeParse( {
+        detached: true,
+        activityOptions: { retry: { maximumAttempts: 1 } },
+        context: {
+          control: {
+            continueAsNew: fn,
+            isContinueAsNewSuggested: fn,
+            extraControl: true
+          },
+          info: {
+            workflowId: 'wf',
+            runId: 'run',
+            extraInfo: true
+          },
+          extraContext: true
+        }
+      } ).success ).toBe( true );
+    } );
+
+    it( 'rejects stale option shapes and invalid invocation values', () => {
+      expect( workflowInvocationOptionsSchema.safeParse( {
+        options: { activityOptions: { retry: { maximumAttempts: 1 } } }
+      } ).success ).toBe( false );
+      expect( workflowInvocationOptionsSchema.safeParse( { detached: 'true' } ).success ).toBe( false );
+      expect( workflowInvocationOptionsSchema.safeParse( {
+        activityOptions: { retry: { maximumAttempts: 0 } }
+      } ).success ).toBe( false );
+      expect( workflowInvocationOptionsSchema.safeParse( {
+        context: { control: { continueAsNew: 'nope' } }
+      } ).success ).toBe( false );
+    } );
+  } );
+
+  describe( 'executeInParallelSchema', () => {
+    it( 'accepts valid execution configs', () => {
+      expect( executeInParallelSchema.safeParse( { jobs: [ fn ], concurrency: 1 } ).success ).toBe( true );
+      expect( executeInParallelSchema.safeParse( { jobs: [ fn ], concurrency: Infinity, onJobCompleted: fn } ).success ).toBe( true );
+    } );
+
+    it( 'rejects invalid execution configs', () => {
+      expect( executeInParallelSchema.safeParse( { jobs: [], concurrency: 0 } ).success ).toBe( false );
+      expect( executeInParallelSchema.safeParse( { jobs: [ 'not-a-function' ], concurrency: 1 } ).success ).toBe( false );
+      expect( executeInParallelSchema.safeParse( { jobs: [ fn ], concurrency: 1, onJobCompleted: 'nope' } ).success ).toBe( false );
+    } );
+  } );
+} );

package/src/interface/webhook.js

@@ -2,7 +2,7 @@
 import { defineSignal, setHandler, proxyActivities, workflowInfo, proxySinks, uuid4, Trigger } from '@temporalio/workflow';
 import { ACTIVITY_SEND_HTTP_REQUEST } from '#consts';
 import { FatalError } from '#errors';
-import { validateRequestPayload } from './validations/static.js';
+import { validateRequestPayload } from './validations/index.js';
 
 /**
  * Call the internal activity to make a HTTP request and returns its response.

package/src/interface/webhook.spec.js

@@ -6,7 +6,7 @@ vi.mock( '#consts', () => ( {
 } ) );
 
 const validateRequestPayloadMock = vi.fn();
-vi.mock( './validations/static.js', () => ( {
+vi.mock( './validations/index.js', () => ( {
   validateRequestPayload: validateRequestPayloadMock
 } ) );
 

package/src/interface/workflow.d.ts

@@ -79,20 +79,21 @@ export type WorkflowContext<
 };
 
 /**
- * Configuration for workflow invocations.
+ * Options for workflow invocations.
  *
  * Allows overriding Temporal Activity options for this workflow.
  */
-export type WorkflowInvocationConfiguration<Context extends WorkflowContext = WorkflowContext> = {
+export type WorkflowInvocationOptions<Context extends WorkflowContext = WorkflowContext> = {
 
   /**
    * Temporal activity options for this invocation (overrides the workflow's default activity options).
    */
-  options?: TemporalActivityOptions,
+  activityOptions?: TemporalActivityOptions,
 
   /**
-   * Configures whether this workflow runs detached.
-   * Detached workflows called without explicitly awaiting the result are "fire-and-forget" and may outlive the parent.
+   * Configures whether this workflow runs detached:
+   * - `detached=true` maps to `ParentClosePolicy.ABANDON`: if parent closes before child, the child keeps executing.
+   * - `detached=false` maps to `ParentClosePolicy.TERMINATE`: if parent closes before child, the child is terminated.
    */
   detached?: boolean,
 
@@ -140,19 +141,19 @@ export type WorkflowFunction<
  *
  * It accepts the same input and returns the same value, calling the user function inside.
  *
- * The second argument is a WorkflowInvocationConfiguration object, allowing workflows configuration overwrite.
+ * The second argument is a WorkflowInvocationOptions object, allowing workflows configuration overwrite.
  *
  * It adds input and output validation based on the `inputSchema`, `outputSchema`.
  *
  * @param input - The workflow input; it matches the schema defined by `inputSchema`.
- * @param config - Additional configuration for the invocation.
+ * @param options - Additional options for the invocation.
  * @returns A value matching the schema defined by `outputSchema`.
  */
 export type WorkflowFunctionWrapper<WorkflowFunction> =
   [Parameters<WorkflowFunction>[0]] extends [undefined | null] ?
-    ( input?: undefined | null, config?: WorkflowInvocationConfiguration ) =>
+    ( input?: undefined | null, options?: WorkflowInvocationOptions ) =>
     ReturnType<WorkflowFunction> :
-    ( input: Parameters<WorkflowFunction>[0], config?: WorkflowInvocationConfiguration ) =>
+    ( input: Parameters<WorkflowFunction>[0], options?: WorkflowInvocationOptions ) =>
     ReturnType<WorkflowFunction>;
 
 /**