@output.ai/core 0.3.0 → 0.3.2

package/src/interface/evaluator.spec.js

@@ -3,7 +3,8 @@ import {
   EvaluationResult,
   EvaluationStringResult,
   EvaluationNumberResult,
-  EvaluationBooleanResult
+  EvaluationBooleanResult,
+  EvaluationFeedback
 } from './evaluator.js';
 import { ValidationError } from '#errors';
 
@@ -98,6 +99,467 @@ describe( 'interface/evaluator - EvaluationResult classes', () => {
       const bad = EvaluationBooleanResult.schema.safeParse( { value: 'false', confidence: 1 } );
       expect( bad.success ).toBe( false );
     } );
+
+    it( 'schema getter does not cause infinite recursion', () => {
+      // Access schema multiple times to ensure no stack overflow
+      const schema1 = EvaluationResult.schema;
+      const schema2 = EvaluationResult.schema;
+      const schema3 = EvaluationStringResult.schema;
+      const schema4 = EvaluationNumberResult.schema;
+      const schema5 = EvaluationBooleanResult.schema;
+
+      expect( schema1 ).toBeDefined();
+      expect( schema2 ).toBeDefined();
+      expect( schema3 ).toBeDefined();
+      expect( schema4 ).toBeDefined();
+      expect( schema5 ).toBeDefined();
+
+      // Verify schemas can be used for validation
+      const result = schema1.safeParse( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 'dim1', confidence: 0.9 },
+          { value: 42, confidence: 0.8 }
+        ]
+      } );
+      expect( result.success ).toBe( true );
+    } );
+
+    it( 'schema includes dimensions field', () => {
+      const schema = EvaluationResult.schema;
+      const result = schema.safeParse( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 'string-dim', confidence: 0.9 },
+          { value: 42, confidence: 0.8 },
+          { value: true, confidence: 0.7 }
+        ]
+      } );
+      expect( result.success ).toBe( true );
+      if ( result.success ) {
+        expect( result.data.dimensions ).toHaveLength( 3 );
+      }
+    } );
+
+    it( 'schema validates dimensions value types', () => {
+      const schema = EvaluationResult.schema;
+
+      // Valid: primitive value types
+      const valid = schema.safeParse( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 'string', confidence: 0.9 },
+          { value: 42, confidence: 0.8 },
+          { value: true, confidence: 0.7 }
+        ]
+      } );
+      expect( valid.success ).toBe( true );
+
+      // Invalid: non-primitive value type in dimensions
+      const invalid = schema.safeParse( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: { object: 'not allowed' }, confidence: 0.9 }
+        ]
+      } );
+      expect( invalid.success ).toBe( false );
+    } );
+  } );
+
+  describe( 'new fields: name, dimensions, feedback', () => {
+    it( 'accepts optional name field', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        name: 'test-evaluation'
+      } );
+      expect( result.name ).toBe( 'test-evaluation' );
+    } );
+
+    it( 'name defaults to undefined when not provided', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8
+      } );
+      expect( result.name ).toBeUndefined();
+    } );
+
+    it( 'validates name must be string if provided', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        name: 123
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'accepts dimensions array with EvaluationResult instances', () => {
+      const dim1 = new EvaluationStringResult( { value: 'dim1', confidence: 0.9 } );
+      const dim2 = new EvaluationNumberResult( { value: 42, confidence: 0.8 } );
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.7,
+        dimensions: [ dim1, dim2 ]
+      } );
+      expect( result.dimensions ).toHaveLength( 2 );
+      expect( result.dimensions[0] ).toBe( dim1 );
+      expect( result.dimensions[1] ).toBe( dim2 );
+    } );
+
+    it( 'dimensions defaults to empty array when not provided', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8
+      } );
+      expect( result.dimensions ).toEqual( [] );
+    } );
+
+    it( 'validates dimensions must match subclass schema', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [ { invalid: 'object' } ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'validates dimensions array structure', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 'valid', confidence: 0.9 },
+          { invalid: 'missing confidence' }
+        ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'accepts dimensions with all three subclass types', () => {
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.7,
+        dimensions: [
+          new EvaluationStringResult( { value: 'string-dim', confidence: 0.9 } ),
+          new EvaluationNumberResult( { value: 42, confidence: 0.8 } ),
+          new EvaluationBooleanResult( { value: true, confidence: 0.7 } )
+        ]
+      } );
+      expect( result.dimensions ).toHaveLength( 3 );
+      expect( result.dimensions[0] ).toBeInstanceOf( EvaluationStringResult );
+      expect( result.dimensions[1] ).toBeInstanceOf( EvaluationNumberResult );
+      expect( result.dimensions[2] ).toBeInstanceOf( EvaluationBooleanResult );
+    } );
+
+    it( 'accepts plain objects matching subclass schemas in dimensions', () => {
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.7,
+        dimensions: [
+          { value: 'string-dim', confidence: 0.9 },
+          { value: 42, confidence: 0.8 },
+          { value: true, confidence: 0.7 }
+        ]
+      } );
+      expect( result.dimensions ).toHaveLength( 3 );
+      expect( result.dimensions[0].value ).toBe( 'string-dim' );
+      expect( result.dimensions[1].value ).toBe( 42 );
+      expect( result.dimensions[2].value ).toBe( true );
+    } );
+
+    it( 'accepts string dimension value type', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 'string-value', confidence: 0.9 }
+        ]
+      } );
+      expect( result.dimensions[0].value ).toBe( 'string-value' );
+    } );
+
+    it( 'accepts number dimension value type', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 123, confidence: 0.9 }
+        ]
+      } );
+      expect( result.dimensions[0].value ).toBe( 123 );
+    } );
+
+    it( 'accepts boolean dimension value type', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: true, confidence: 0.9 }
+        ]
+      } );
+      expect( result.dimensions[0].value ).toBe( true );
+    } );
+
+    it( 'rejects dimensions with non-primitive value types', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: { object: 'not allowed' }, confidence: 0.9 }
+        ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'rejects dimensions with array value types', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: [ 1, 2, 3 ], confidence: 0.9 }
+        ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'accepts nested dimensions (recursive)', () => {
+      const nestedDim = new EvaluationStringResult( {
+        value: 'nested',
+        confidence: 0.9,
+        dimensions: [
+          new EvaluationNumberResult( { value: 10, confidence: 0.8 } )
+        ]
+      } );
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.7,
+        dimensions: [ nestedDim ]
+      } );
+      expect( result.dimensions ).toHaveLength( 1 );
+      expect( result.dimensions[0].dimensions ).toHaveLength( 1 );
+      expect( result.dimensions[0].dimensions[0].value ).toBe( 10 );
+    } );
+
+    it( 'accepts nested dimensions with plain objects', () => {
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.7,
+        dimensions: [
+          {
+            value: 'nested',
+            confidence: 0.9,
+            dimensions: [
+              { value: 10, confidence: 0.8 }
+            ]
+          }
+        ]
+      } );
+      expect( result.dimensions ).toHaveLength( 1 );
+      expect( result.dimensions[0].dimensions ).toHaveLength( 1 );
+      expect( result.dimensions[0].dimensions[0].value ).toBe( 10 );
+    } );
+
+    it( 'accepts feedback array with EvaluationFeedback instances', () => {
+      const feedback1 = new EvaluationFeedback( {
+        issue: 'Issue 1',
+        suggestion: 'Fix this',
+        priority: 'high'
+      } );
+      const feedback2 = new EvaluationFeedback( {
+        issue: 'Issue 2',
+        reference: 'ref-123'
+      } );
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        feedback: [ feedback1, feedback2 ]
+      } );
+      expect( result.feedback ).toHaveLength( 2 );
+      expect( result.feedback[0] ).toBe( feedback1 );
+      expect( result.feedback[1] ).toBe( feedback2 );
+    } );
+
+    it( 'accepts feedback array with plain objects matching schema', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        feedback: [
+          { issue: 'Issue 1', suggestion: 'Fix', priority: 'high' },
+          { issue: 'Issue 2', reference: 'ref-123' }
+        ]
+      } );
+      expect( result.feedback ).toHaveLength( 2 );
+      expect( result.feedback[0].issue ).toBe( 'Issue 1' );
+      expect( result.feedback[1].issue ).toBe( 'Issue 2' );
+    } );
+
+    it( 'feedback defaults to empty array when not provided', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8
+      } );
+      expect( result.feedback ).toEqual( [] );
+    } );
+
+    it( 'validates feedback must match EvaluationFeedback schema', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        feedback: [ { invalid: 'object' } ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'validates feedback issue is required', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        feedback: [ { suggestion: 'missing issue' } ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'validates feedback priority enum values', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        feedback: [ { issue: 'test', priority: 'invalid' } ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'accepts all new fields together', () => {
+      const dim = new EvaluationStringResult( { value: 'dim', confidence: 0.9 } );
+      const feedback = new EvaluationFeedback( { issue: 'test issue', priority: 'medium' } );
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.8,
+        name: 'comprehensive-test',
+        dimensions: [ dim ],
+        feedback: [ feedback ],
+        reasoning: 'test reasoning'
+      } );
+      expect( result.name ).toBe( 'comprehensive-test' );
+      expect( result.dimensions ).toHaveLength( 1 );
+      expect( result.feedback ).toHaveLength( 1 );
+      expect( result.reasoning ).toBe( 'test reasoning' );
+    } );
+  } );
+} );
+
+describe( 'interface/evaluator - EvaluationFeedback class', () => {
+  describe( 'constructor', () => {
+    it( 'creates feedback with required issue', () => {
+      const feedback = new EvaluationFeedback( { issue: 'Test issue' } );
+      expect( feedback.issue ).toBe( 'Test issue' );
+      expect( feedback.suggestion ).toBeUndefined();
+      expect( feedback.reference ).toBeUndefined();
+      expect( feedback.priority ).toBeUndefined();
+    } );
+
+    it( 'creates feedback with all fields', () => {
+      const feedback = new EvaluationFeedback( {
+        issue: 'Critical bug',
+        suggestion: 'Fix immediately',
+        reference: 'BUG-123',
+        priority: 'critical'
+      } );
+      expect( feedback.issue ).toBe( 'Critical bug' );
+      expect( feedback.suggestion ).toBe( 'Fix immediately' );
+      expect( feedback.reference ).toBe( 'BUG-123' );
+      expect( feedback.priority ).toBe( 'critical' );
+    } );
+
+    it( 'accepts optional fields', () => {
+      const feedback = new EvaluationFeedback( {
+        issue: 'Minor issue',
+        suggestion: 'Consider fixing'
+      } );
+      expect( feedback.issue ).toBe( 'Minor issue' );
+      expect( feedback.suggestion ).toBe( 'Consider fixing' );
+      expect( feedback.reference ).toBeUndefined();
+      expect( feedback.priority ).toBeUndefined();
+    } );
+  } );
+
+  describe( 'static schema getter', () => {
+    it( 'validates required issue field', () => {
+      const ok = EvaluationFeedback.schema.safeParse( { issue: 'Test issue' } );
+      expect( ok.success ).toBe( true );
+
+      const bad = EvaluationFeedback.schema.safeParse( {} );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'validates issue must be string', () => {
+      const bad = EvaluationFeedback.schema.safeParse( { issue: 123 } );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'accepts optional suggestion field', () => {
+      const ok = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        suggestion: 'Fix it'
+      } );
+      expect( ok.success ).toBe( true );
+    } );
+
+    it( 'validates suggestion must be string if provided', () => {
+      const bad = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        suggestion: 123
+      } );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'accepts optional reference field', () => {
+      const ok = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        reference: 'REF-123'
+      } );
+      expect( ok.success ).toBe( true );
+    } );
+
+    it( 'validates reference must be string if provided', () => {
+      const bad = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        reference: 123
+      } );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'accepts valid priority enum values', () => {
+      const priorities = [ 'low', 'medium', 'high', 'critical' ];
+      for ( const priority of priorities ) {
+        const ok = EvaluationFeedback.schema.safeParse( {
+          issue: 'Test',
+          priority
+        } );
+        expect( ok.success ).toBe( true );
+      }
+    } );
+
+    it( 'rejects invalid priority values', () => {
+      const bad = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        priority: 'invalid'
+      } );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'validates priority must be string if provided', () => {
+      const bad = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        priority: 123
+      } );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'accepts all fields together', () => {
+      const ok = EvaluationFeedback.schema.safeParse( {
+        issue: 'Critical bug',
+        suggestion: 'Fix immediately',
+        reference: 'BUG-123',
+        priority: 'critical'
+      } );
+      expect( ok.success ).toBe( true );
+    } );
   } );
 } );
 

package/src/interface/validations/static.js

@@ -17,6 +17,12 @@ const refineSchema = ( value, ctx ) => {
   } );
 };
 
+export const executeInParallelSchema = z.object( {
+  jobs: z.array( z.function() ),
+  concurrency: z.number().min( 1 ).or( z.literal( Infinity ) ),
+  onJobCompleted: z.function().optional()
+} );
+
 export const durationSchema = z.union( [ z.string().regex(
   /^(\d+)(ms|s|m|h|d)$/,
   'Expected duration like "500ms", "10s", "5m", "2h", or "1d"'
@@ -108,3 +114,13 @@ export function validateWorkflow( args ) {
 export function validateRequestPayload( args ) {
   validateAgainstSchema( httpRequestSchema, args );
 };
+
+/**
+ * Validate executeInParallel
+ *
+ * @param {object} args - The request arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateExecuteInParallel( args ) {
+  validateAgainstSchema( executeInParallelSchema, args );
+};

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

@@ -1,6 +1,13 @@
 import { describe, it, expect } from 'vitest';
 import { z } from 'zod';
-import { validateStep, validateWorkflow, validateRequestPayload, validateEvaluator, StaticValidationError } from './static.js';
+import {
+  validateStep,
+  validateWorkflow,
+  validateRequestPayload,
+  validateEvaluator,
+  validateExecuteInParallel,
+  StaticValidationError
+} from './static.js';
 
 const validArgs = Object.freeze( {
   name: 'valid_name',
@@ -259,4 +266,75 @@ describe( 'interface/validator', () => {
       expect( () => validateRequestPayload( request ) ).not.toThrow();
     } );
   } );
+
+  describe( 'validateExecuteInParallel', () => {
+    const validArgs = Object.freeze( {
+      jobs: [ () => {}, () => {} ],
+      concurrency: 5
+    } );
+
+    it( 'passes for valid args', () => {
+      expect( () => validateExecuteInParallel( { ...validArgs } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing concurrency', () => {
+      const error = new StaticValidationError( '✖ Invalid input\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { jobs: validArgs.jobs } ) ).toThrow( error );
+    } );
+
+    it( 'passes with onJobCompleted callback', () => {
+      const args = {
+        ...validArgs,
+        onJobCompleted: () => {}
+      };
+      expect( () => validateExecuteInParallel( args ) ).not.toThrow();
+    } );
+
+    it( 'passes with concurrency 1', () => {
+      expect( () => validateExecuteInParallel( { ...validArgs, concurrency: 1 } ) ).not.toThrow();
+    } );
+
+    it( 'passes with concurrency Infinity', () => {
+      expect( () => validateExecuteInParallel( { ...validArgs, concurrency: Infinity } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing jobs', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected array, received undefined\n  → at jobs' );
+      expect( () => validateExecuteInParallel( { concurrency: 5 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-array jobs', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected array, received string\n  → at jobs' );
+      expect( () => validateExecuteInParallel( { jobs: 'not-array', concurrency: 5 } ) ).toThrow( error );
+    } );
+
+    it( 'passes with empty jobs array', () => {
+      expect( () => validateExecuteInParallel( { jobs: [], concurrency: 5 } ) ).not.toThrow();
+    } );
+
+    it( 'rejects jobs array with non-function', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received string\n  → at jobs[1]' );
+      expect( () => validateExecuteInParallel( { jobs: [ () => {}, 'not-function' ], concurrency: 5 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-number concurrency', () => {
+      const error = new StaticValidationError( '✖ Invalid input\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { jobs: validArgs.jobs, concurrency: '5' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects zero concurrency', () => {
+      const error = new StaticValidationError( '✖ Too small: expected number to be >=1\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { jobs: validArgs.jobs, concurrency: 0 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects negative concurrency', () => {
+      const error = new StaticValidationError( '✖ Too small: expected number to be >=1\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { ...validArgs, concurrency: -1 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-function onJobCompleted', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received string\n  → at onJobCompleted' );
+      expect( () => validateExecuteInParallel( { ...validArgs, onJobCompleted: 'not-function' } ) ).toThrow( error );
+    } );
+  } );
 } );

package/src/interface/workflow_utils.js

@@ -0,0 +1,49 @@
+import { validateExecuteInParallel } from './validations/static.js';
+
+/**
+ * Execute jobs in parallel with optional concurrency limit.
+ *
+ * Returns all job results (successes and failures) sorted by original job index.
+ *
+ * @param {Array<Function>} jobs Array of functions to execute
+ * @param {Number} [concurrency] Max concurrent jobs, default is Infinity (no concurrency limit)
+ * @param {Function} [onJobCompleted] Optional callback invoked as each job completes
+ */
+export const executeInParallel = async ( { jobs, concurrency = Infinity, onJobCompleted } ) => {
+  validateExecuteInParallel( { jobs, concurrency, onJobCompleted } );
+  // allows this function to be called without testing over and over to check if it is not null;
+  const onJobCompletedSafeCb = onJobCompleted ?? ( _ => 0 );
+  const results = [];
+  const jobsCount = jobs.length;
+  const jobsPool = jobs.slice().map( ( job, index ) => ( {
+    index,
+    fn: async () => {
+      try {
+        const result = await job();
+        return { ok: true, result, index };
+      } catch ( error ) {
+        return { ok: false, error, index };
+      }
+    },
+    promise: null
+  } ) );
+
+  const activeJobs = jobsPool.splice( 0, concurrency );
+  activeJobs.forEach( job => job.promise = job.fn() ); // start jobs
+
+  while ( results.length < jobsCount ) {
+    const result = await Promise.race( activeJobs.map( job => job.promise ) );
+    results.push( result );
+    onJobCompletedSafeCb( result );
+
+    activeJobs.splice( activeJobs.findIndex( job => job.index === result.index ), 1 ); // remove completed job
+
+    if ( jobsPool.length > 0 ) {
+      const nextJob = jobsPool.shift();
+      nextJob.promise = nextJob.fn();
+      activeJobs.push( nextJob );
+    }
+  }
+
+  return results.sort( ( a, b ) => a.index - b.index );
+};