@outputai/core 0.1.0

package/src/interface/step.d.ts

@@ -0,0 +1,138 @@
+import type { z } from 'zod';
+import type { AnyZodSchema, TemporalActivityOptions } from './types.d.ts';
+
+/**
+ * Options for a step.
+ */
+export type StepOptions = {
+
+  /**
+   * Temporal activity options for this step.
+   */
+  activityOptions?: TemporalActivityOptions
+};
+
+/**
+ * The handler function of a step.
+ *
+ * @param input - The step input; it matches the schema defined by `inputSchema`.
+ *
+ * @returns A value matching the schema defined by `outputSchema`.
+ */
+export type StepFunction<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+> = InputSchema extends AnyZodSchema ?
+  ( input: z.infer<InputSchema> ) => Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void> :
+  () => Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void>;
+
+/**
+ * A wrapper around the user defined `fn` handler function.
+ *
+ * It accepts the same input and returns the same value, calling the user function inside.
+ *
+ * It adds input and output validation based on the `inputSchema`, `outputSchema`.
+ *
+ * @param input - The Step input; it matches the schema defined by `inputSchema`.
+ * @returns A value matching the schema defined by `outputSchema`.
+ */
+export type StepFunctionWrapper<StepFunction> =
+  Parameters<StepFunction> extends [infer Input] ?
+    ( input: Input ) => ReturnType<StepFunction> :
+    () => ReturnType<StepFunction>;
+
+/**
+ * Creates a step.
+ *
+ * A step is a logical unit of work that can perform I/O. It is translated to a Temporal Activity.
+ *
+ * The step logic is defined in the `fn` handler function.
+ *
+ * The schema of the input that the function receives as the first argument is defined by the `inputSchema` option.
+ *
+ * The output of the `fn` handler must match the schema defined by `outputSchema`; otherwise, a validation error is raised.
+ *
+ * @example
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   outputSchema: z.string(),
+ *   fn: async input => {
+ *     const result = await ai.call( input.value );
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without outputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   fn: async input => {
+ *     await ai.call( input.value );
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without inputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   outputSchema: z.string(),
+ *   fn: async () => {
+ *     const result = await ai.call();
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without inputSchema and outputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   fn: async () => {
+ *     await ai.call();
+ *   }
+ * } )
+ * ```
+ *
+ * @remarks
+ * - Never call another step from within a step.
+ * - Never call a workflow from within a step.
+ *
+ * @typeParam InputSchema - Zod schema of the fn's input.
+ * @typeParam OutputSchema - Zod schema of the fn's return.
+ *
+ * @throws {@link ValidationError}
+ * @throws {@link FatalError}
+ *
+ * @param params - Step parameters
+ * @param params.name - Human-readable step name (must start with a letter or underscore, followed by letters, numbers, or underscores)
+ * @param params.description - Description of the step
+ * @param params.inputSchema - Zod schema for the `fn` input
+ * @param params.outputSchema - Zod schema for the `fn` output
+ * @param params.fn - A handler function containing the step code
+ * @param params.options - Optional step options.
+ * @returns The same handler function set at `fn`
+ */
+export declare function step<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+>( params: {
+  name: string;
+  description?: string;
+  inputSchema?: InputSchema;
+  outputSchema?: OutputSchema;
+  fn: StepFunction<InputSchema, OutputSchema>;
+  options?: StepOptions;
+} ): StepFunctionWrapper<StepFunction<InputSchema, OutputSchema>>;

package/src/interface/step.js

@@ -0,0 +1,22 @@
+// THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
+import { setMetadata } from '#utils';
+import { validateStep } from './validations/static.js';
+import { validateWithSchema } from './validations/runtime.js';
+import { ComponentType } from '#consts';
+
+export function step( { name, description, inputSchema, outputSchema, fn, options } ) {
+  validateStep( { name, description, inputSchema, outputSchema, fn, options } );
+
+  const wrapper = async input => {
+    validateWithSchema( inputSchema, input, `Step ${name} input` );
+
+    const output = await fn( input );
+
+    validateWithSchema( outputSchema, output, `Step ${name} output` );
+
+    return output;
+  };
+
+  setMetadata( wrapper, { name, description, inputSchema, outputSchema, type: ComponentType.STEP, options } );
+  return wrapper;
+};

package/src/interface/types.d.ts

@@ -0,0 +1,27 @@
+import type { z } from 'zod';
+import type { ActivityOptions } from '@temporalio/workflow';
+/**
+ * Similar to `Partial<T>` but applies to nested properties recursively, creating a deep optional variant of `T`:
+ * - Objects: All properties become optional, recursively.
+ * - Functions: Preserved as‑is (only the property itself becomes optional).
+ * - Primitives: Returned unchanged.
+ * Useful for config overrides with strong IntelliSense on nested fields and methods.
+ */
+export type DeepPartial<T> =
+  T extends ( ...args: any[] ) => unknown ? T : // eslint-disable-line @typescript-eslint/no-explicit-any
+    T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } :
+      T;
+
+/**
+ * Type alias for any Zod schema type.
+ */
+export type AnyZodSchema = z.ZodType<any, any, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+/**
+ * Native Temporal configurations for activities.
+ *
+ * All native options are accepted except 'versioningIntent', 'taskQueue', 'allowEagerDispatch'.
+ *
+ * @see {@link https://typescript.temporal.io/api/interfaces/common.ActivityOptions}
+ */
+export type TemporalActivityOptions = Omit<ActivityOptions, 'versioningIntent' | 'taskQueue' | 'allowEagerDispatch'>;

package/src/interface/validations/runtime.js

@@ -0,0 +1,20 @@
+import { ValidationError } from '#errors';
+
+/**
+ * Validates data against a Zod schema using safeParse
+ * @param {unknown} schema - The Zod schema to validate against
+ * @param {unknown} data - The data to validate
+ * @param {string} context - Description of what's being validated (for error messages)
+ * @throws {ValidationError} If validation fails
+ * @returns {void}
+ */
+export function validateWithSchema( schema, data, context ) {
+  if ( !schema ) {
+    return;
+  }
+
+  const result = schema.safeParse( data );
+  if ( !result.success ) {
+    throw new ValidationError( `${context} validation failed: ${result.error.message}` );
+  }
+}

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

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { validateWithSchema } from './runtime.js';
+import { ValidationError } from '#errors';
+
+describe( 'runtime validations', () => {
+  describe( 'validateWithSchema', () => {
+    it( 'no-ops when schema is falsy', () => {
+      expect( () => validateWithSchema( undefined, { a: 1 }, 'X' ) ).not.toThrow();
+      expect( () => validateWithSchema( null, { a: 1 }, 'X' ) ).not.toThrow();
+    } );
+
+    it( 'passes on valid data', () => {
+      const schema = z.object( { a: z.string(), b: z.number().optional() } );
+      expect( () => validateWithSchema( schema, { a: 'ok' }, 'Test' ) ).not.toThrow();
+    } );
+
+    it( 'throws ValidationError on invalid data and prefixes context', () => {
+      const schema = z.object( { a: z.string() } );
+      const call = () => validateWithSchema( schema, { a: 1 }, 'MyCtx' );
+      expect( call ).toThrow( ValidationError );
+      try {
+        call();
+      } catch ( e ) {
+        expect( String( e.message ) ).toContain( 'MyCtx validation failed:' );
+      }
+    } );
+  } );
+} );

package/src/interface/validations/schema_utils.js

@@ -0,0 +1,8 @@
+import { ZodType } from 'zod';
+
+/**
+ * Detects if a schema is a ZodType instance
+ * @param {unknown} schema - The schema to check
+ * @returns {boolean} True if the schema is a Zod schema
+ */
+export const isZodSchema = schema => schema instanceof ZodType;

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

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+
+// Import the actual implementations
+import { isZodSchema } from './schema_utils.js';
+
+describe( 'Schema Detection', () => {
+  describe( 'isZodSchema', () => {
+    it( 'should correctly identify Zod schemas', () => {
+      const zodSchema = z.object( {
+        name: z.string(),
+        age: z.number()
+      } );
+
+      expect( isZodSchema( zodSchema ) ).toBe( true );
+    } );
+
+    it( 'should correctly identify Zod string schema', () => {
+      const zodString = z.string();
+      expect( isZodSchema( zodString ) ).toBe( true );
+    } );
+
+    it( 'should correctly identify Zod array schema', () => {
+      const zodArray = z.array( z.number() );
+      expect( isZodSchema( zodArray ) ).toBe( true );
+    } );
+
+    it( 'should correctly identify Zod union schema', () => {
+      const zodUnion = z.union( [ z.string(), z.number() ] );
+      expect( isZodSchema( zodUnion ) ).toBe( true );
+    } );
+
+    it( 'should return false for JSON Schema objects', () => {
+      const jsonSchema = {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          age: { type: 'number' }
+        },
+        required: [ 'name' ]
+      };
+
+      expect( isZodSchema( jsonSchema ) ).toBe( false );
+    } );
+
+    it( 'should return false for plain objects', () => {
+      expect( isZodSchema( {} ) ).toBe( false );
+      expect( isZodSchema( { type: 'string' } ) ).toBe( false );
+    } );
+
+    it( 'should return false for null and undefined', () => {
+      expect( isZodSchema( null ) ).toBeFalsy();
+      expect( isZodSchema( undefined ) ).toBeFalsy();
+    } );
+
+    it( 'should return false for primitive values', () => {
+      expect( isZodSchema( 'string' ) ).toBe( false );
+      expect( isZodSchema( 123 ) ).toBe( false );
+      expect( isZodSchema( true ) ).toBe( false );
+    } );
+
+    it( 'should return false for arrays', () => {
+      expect( isZodSchema( [] ) ).toBe( false );
+      expect( isZodSchema( [ 1, 2, 3 ] ) ).toBe( false );
+    } );
+  } );
+} );

package/src/interface/validations/static.js

@@ -0,0 +1,136 @@
+import * as z from 'zod';
+import { isZodSchema } from './schema_utils.js';
+
+/**
+ * Error is thrown when the definition of a step/workflow has problems
+ */
+export class StaticValidationError extends Error {};
+
+const refineSchema = ( value, ctx ) => {
+  if ( !value || isZodSchema( value ) ) {
+    return;
+  }
+
+  ctx.addIssue( {
+    code: 'invalid_type',
+    message: 'Schema must be a Zod schema'
+  } );
+};
+
+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"'
+), z.number() ] );
+
+export const prioritySchema = z.object( {
+  fairnessKey: z.string().optional(),
+  fairnessWeight: z.number().min( 0.0001 ).max( 1000 ).optional(),
+  priorityKey: z.number().min( 1 ).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: 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()
+    } ).optional()
+  } ).optional()
+} );
+
+const stepSchema = baseSchema;
+
+const workflowSchema = baseSchema.extend( {
+  options: baseSchema.shape.options.unwrap().extend( {
+    disableTrace: z.boolean().optional().default( false )
+  } ).optional()
+} );
+
+const evaluatorSchema = baseSchema.omit( { outputSchema: true } );
+
+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()
+} );
+
+const validateAgainstSchema = ( schema, args ) => {
+  const result = schema.safeParse( args );
+  if ( !result.success ) {
+    throw new StaticValidationError( z.prettifyError( result.error ) );
+  }
+};
+
+/**
+ * Validate step payload
+ *
+ * @param {object} args - The step arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateStep( args ) {
+  validateAgainstSchema( stepSchema, args );
+};
+
+/**
+ * Validate evaluator payload
+ *
+ * @param {object} args - The evaluator arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateEvaluator( args ) {
+  validateAgainstSchema( evaluatorSchema, args );
+};
+
+/**
+ * Validate workflow payload
+ *
+ * @param {object} args - The workflow arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateWorkflow( args ) {
+  validateAgainstSchema( workflowSchema, args );
+};
+
+/**
+ * Validate request payload
+ *
+ * @param {object} args - The request arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+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 );
+};