@outputai/core 0.8.1 → 0.8.2-next.0f9af4b.0

package/src/interface/logger.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Additional structured fields attached to a log record.
+ */
+export type LogMetadata = Record<string, unknown>;
+
+/**
+ * Log an error (level 0)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function error( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log a warn (level 1)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function warn( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log an info (level 2)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function info( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log http (level 3)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function http( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log verbose (level 4)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function verbose( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log debug (level 5)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function debug( message: string, metadata?: LogMetadata ) : void;
+
+/**
+ * Log silly (level 6)
+ * @param message Log message
+ * @param metadata Additional information to be displayed
+ */
+export declare function silly( message: string, metadata?: LogMetadata ) : void;

package/src/interface/logger.js

@@ -0,0 +1,68 @@
+import { inWorkflowContext } from '@temporalio/workflow';
+import { proxySinks } from '@temporalio/workflow';
+import { ACTIVITY_LOGGER_SYMBOL } from '#consts';
+import { isPlainObject } from '#helpers/object';
+
+const reservedMetadataFields = new Set( [
+  // Winston fields
+  'label',
+  'level',
+  'message',
+  'metadata',
+  'namespace',
+  'splat',
+  'stack',
+  'timestamp',
+  // reserved fields enriched by us
+  'workflowId',
+  'workflowType',
+  'runId',
+  'activityId',
+  'activityType',
+  'service',
+  'environment'
+] );
+
+// This is inoffensive and can be used outside workflow sandbox
+const sinks = proxySinks();
+
+// Convert npm log levels to console levels
+const levelToConsole = {
+  error: 'error',
+  warn: 'warn',
+  info: 'info',
+  http: 'log',
+  verbose: 'log',
+  debug: 'debug',
+  silly: 'log'
+};
+
+/** Drops reserved keys from object */
+const removeReservedFields = obj => Object.fromEntries( Object.entries( obj ).filter( ( [ k ] ) => !reservedMetadataFields.has( k ) ) );
+
+const log = ( level, message, metadata ) => {
+  const sanitized = {
+    message: String( message ),
+    ...( isPlainObject( metadata ) && { metadata: removeReservedFields( metadata ) } )
+  };
+
+  // When inside workflow, use sinks to send logs out
+  if ( inWorkflowContext() ) {
+    sinks.workflow.log( { level, ...sanitized } );
+  // When inside activities, use the global function to ship logs
+  } else if ( typeof globalThis[ACTIVITY_LOGGER_SYMBOL] === 'function' ) {
+    globalThis[ACTIVITY_LOGGER_SYMBOL]( { level, ...sanitized } );
+  // This fallback is used on unit tests
+  } else {
+    console[levelToConsole[level]]( sanitized.message, sanitized.metadata );
+  }
+};
+
+// Winston uses npm levels by default: https://github.com/winstonjs/winston#logging-levels
+export const error = log.bind( null, 'error' );
+export const warn = log.bind( null, 'warn' );
+export const info = log.bind( null, 'info' );
+export const http = log.bind( null, 'http' );
+export const verbose = log.bind( null, 'verbose' );
+export const debug = log.bind( null, 'debug' );
+export const silly = log.bind( null, 'silly' );

package/src/interface/logger.spec.js

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ACTIVITY_LOGGER_SYMBOL } from '#consts';
+
+const workflowLogMock = vi.fn();
+const proxySinksMock = vi.fn( () => ( {
+  workflow: {
+    log: workflowLogMock
+  }
+} ) );
+const inWorkflowContextMock = vi.fn( () => false );
+
+vi.mock( '@temporalio/workflow', () => ( {
+  inWorkflowContext: inWorkflowContextMock,
+  proxySinks: proxySinksMock
+} ) );
+
+const logLevels = [
+  'error',
+  'warn',
+  'info',
+  'http',
+  'verbose',
+  'debug',
+  'silly'
+];
+
+const consoleMethodsByLevel = {
+  error: 'error',
+  warn: 'warn',
+  info: 'info',
+  http: 'log',
+  verbose: 'log',
+  debug: 'debug',
+  silly: 'log'
+};
+
+const loadLogger = async () => import( './logger.js' );
+
+describe( 'interface/logger', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    inWorkflowContextMock.mockReturnValue( false );
+    delete globalThis[ACTIVITY_LOGGER_SYMBOL];
+  } );
+
+  afterEach( () => {
+    delete globalThis[ACTIVITY_LOGGER_SYMBOL];
+    vi.restoreAllMocks();
+  } );
+
+  it( 'proxies sinks once when the module is loaded', async () => {
+    await loadLogger();
+
+    expect( proxySinksMock ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'logs every level through workflow sinks inside workflow context', async () => {
+    const logger = await loadLogger();
+    inWorkflowContextMock.mockReturnValue( true );
+
+    logLevels.forEach( level => {
+      logger[level]( `${level} message`, { requestId: level } );
+    } );
+
+    logLevels.forEach( ( level, index ) => {
+      const payload = {
+        level,
+        message: `${level} message`,
+        metadata: { requestId: level }
+      };
+
+      expect( workflowLogMock ).toHaveBeenNthCalledWith( index + 1, payload );
+    } );
+  } );
+
+  it( 'sanitizes messages and metadata before logging', async () => {
+    const logger = await loadLogger();
+    inWorkflowContextMock.mockReturnValue( true );
+
+    logger.info( 123, {
+      requestId: 'req-1',
+      level: 'error',
+      message: 'metadata message'
+    } );
+
+    expect( workflowLogMock ).toHaveBeenCalledWith( {
+      level: 'info',
+      message: '123',
+      metadata: { requestId: 'req-1' }
+    } );
+  } );
+
+  it( 'logs every level through the activity global logger when it is set outside workflow context', async () => {
+    const logger = await loadLogger();
+    const activityLoggerMock = vi.fn();
+    globalThis[ACTIVITY_LOGGER_SYMBOL] = activityLoggerMock;
+
+    logLevels.forEach( level => {
+      logger[level]( `${level} message`, { requestId: level } );
+    } );
+
+    logLevels.forEach( ( level, index ) => {
+      expect( activityLoggerMock ).toHaveBeenNthCalledWith( index + 1, {
+        level,
+        message: `${level} message`,
+        metadata: { requestId: level }
+      } );
+    } );
+    expect( workflowLogMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'logs every level to its native console method when no workflow or activity logger is available', async () => {
+    const logger = await loadLogger();
+    const consoleMocks = Object.fromEntries(
+      [ 'debug', 'error', 'info', 'log', 'warn' ].map( method => [
+        method,
+        vi.spyOn( console, method ).mockImplementation( () => {} )
+      ] )
+    );
+
+    logLevels.forEach( level => {
+      logger[level]( `${level} message`, { requestId: level } );
+    } );
+
+    logLevels.forEach( level => {
+      expect( consoleMocks[consoleMethodsByLevel[level]] ).toHaveBeenCalledWith(
+        `${level} message`,
+        { requestId: level }
+      );
+    } );
+    expect( consoleMocks.error ).toHaveBeenCalledTimes( 1 );
+    expect( consoleMocks.warn ).toHaveBeenCalledTimes( 1 );
+    expect( consoleMocks.info ).toHaveBeenCalledTimes( 1 );
+    expect( consoleMocks.debug ).toHaveBeenCalledTimes( 1 );
+    expect( consoleMocks.log ).toHaveBeenCalledTimes( 3 );
+    expect( workflowLogMock ).not.toHaveBeenCalled();
+  } );
+} );

package/src/interface/step.js

@@ -1,6 +1,5 @@
 import { StepValidator } from './validations/index.js';
-import { setMetadata } from '#utils';
-import { ComponentType } from '#consts';
+import { createStep } from '#helpers/component';
 
 /**
  * Create a new step (activity flavor) and return a wrapper function around its fn handler
@@ -9,13 +8,17 @@ export function step( { name, description, inputSchema, outputSchema, fn, option
   StepValidator.validateDefinition( { name, description, inputSchema, outputSchema, fn, options } );
   const validator = new StepValidator( { name, inputSchema, outputSchema } );
 
-  const wrapper = async input => {
-    validator.validateInput( input );
-    const output = await fn( input );
-    validator.validateOutput( output );
-    return output;
-  };
-
-  setMetadata( wrapper, { name, description, inputSchema, outputSchema, type: ComponentType.STEP, options } );
-  return wrapper;
-};
+  return createStep( {
+    name,
+    description,
+    inputSchema,
+    outputSchema,
+    options,
+    handler: async input => {
+      validator.validateInput( input );
+      const output = await fn( input );
+      validator.validateOutput( output );
+      return output;
+    }
+  } );
+}

package/src/interface/step.spec.js

@@ -1,11 +1,11 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ValidationError } from '#errors';
-import { ComponentType } from '#consts';
 
 const validateDefinitionMock = vi.hoisted( () => vi.fn() );
 const validateInputMock = vi.hoisted( () => vi.fn() );
 const validateOutputMock = vi.hoisted( () => vi.fn() );
 const validatorConstructorMock = vi.hoisted( () => vi.fn() );
+const createStepMock = vi.hoisted( () => vi.fn( ( { handler } ) => handler ) );
 
 vi.mock( './validations/index.js', () => {
   class StepValidator {
@@ -23,12 +23,16 @@ vi.mock( './validations/index.js', () => {
   return { StepValidator };
 } );
 
+vi.mock( '#helpers/component', () => ( {
+  createStep: createStepMock
+} ) );
+
 describe( 'step()', () => {
   beforeEach( () => {
     vi.clearAllMocks();
   } );
 
-  it( 'validates the definition, creates a runtime validator, and attaches metadata', async () => {
+  it( 'validates the definition, creates a runtime validator, and creates a step component', async () => {
     const { step } = await import( './step.js' );
     const inputSchema = { safeParse: vi.fn() };
     const outputSchema = { safeParse: vi.fn() };
@@ -58,15 +62,15 @@ describe( 'step()', () => {
       outputSchema
     } );
 
-    const [ metadataSymbol ] = Object.getOwnPropertySymbols( wrapper );
-    expect( wrapper[metadataSymbol] ).toEqual( {
+    expect( createStepMock ).toHaveBeenCalledWith( {
       name: 'test_step',
       description: 'Test step',
       inputSchema,
       outputSchema,
-      type: ComponentType.STEP,
-      options
+      options,
+      handler: expect.any( Function )
     } );
+    expect( wrapper ).toBe( createStepMock.mock.calls[0][0].handler );
   } );
 
   it( 'validates input and output around the step function', async () => {

package/src/interface/webhook.d.ts

@@ -1,10 +1,29 @@
-import type { SerializedFetchResponse } from '../utils/index.d.ts';
-
 /**
  * Allowed HTTP methods for request helpers.
  */
 export type HttpMethod = 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 
+/** Represents a {Response} serialized to plain object */
+export type SerializedFetchResponse = {
+  /** The response url */
+  url: string,
+
+  /** The response status code */
+  status: number,
+
+  /** The response status text */
+  statusText: string,
+
+  /** Flag indicating if the request succeeded */
+  ok: boolean,
+
+  /** Object with response headers */
+  headers: Record<string, string>,
+
+  /** Response body, either JSON, text, or an arrayBuffer converted to base64 */
+  body: object | string
+};
+
 /**
  * Send an POST HTTP request to a URL, optionally with a payload, then wait for a webhook response.
  *

package/src/interface/workflow.js

@@ -1,10 +1,12 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
 import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4, ParentClosePolicy } from '@temporalio/workflow';
 import { WorkflowValidator } from './validations/index.js';
-import { deepMerge, setMetadata, toUrlSafeBase64 } from '#utils';
-import { WorkflowContext } from '#internal_utils/workflow_context';
-import { TraceInfo } from '#internal_utils/trace_info';
+import { toUrlSafeBase64 } from '#helpers/string';
+import { WorkflowContext } from '#helpers/workflow_context';
+import { TraceInfo } from '#helpers/trace_info';
+import { deepMerge } from '#helpers/object';
 import { defaultOptions } from './workflow_activity_options.js';
+import { createWorkflow } from '#helpers/component';
 import {
   ACTIVITY_WRAPPER_VERSION_FIELD,
   ACTIVITY_GET_TRACE_DESTINATIONS,
@@ -34,84 +36,89 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
   const { disableTrace, activityOptions } = deepMerge( defaultOptions, options );
   const validator = new WorkflowValidator( { name, inputSchema, outputSchema } );
 
-  const wrapper = async ( input, extra = {} ) => {
-    validator.validateInvocationOptions( extra );
-
-    // this returns a plain function, for example, in unit tests
-    if ( !inWorkflowContext() ) {
-      validator.validateInput( input );
-      const output = await fn( input, deepMerge( WorkflowContext.build(), extra?.context ) );
-      validator.validateOutput( output );
-      return output;
-    }
+  return createWorkflow( {
+    name,
+    description,
+    inputSchema,
+    outputSchema,
+    options,
+    aliases,
+    handler: async ( input, extra = {} ) => {
+      validator.validateInvocationOptions( extra );
+
+      // this returns a plain function, for example, in unit tests
+      if ( !inWorkflowContext() ) {
+        validator.validateInput( input );
+        const output = await fn( input, deepMerge( WorkflowContext.build(), extra?.context ) );
+        validator.validateOutput( output );
+        return output;
+      }
 
-    const { workflowId, workflowType, memo, root } = workflowInfo();
-
-    // if the stack already includes this workflowId, means the workflow() function was called
-    // from within a running workflow, meaning it is suppose to start a child workflow
-    const isChild = Array.isArray( memo.stack ) ? memo.stack.includes( workflowId ) :
-      checkChildFallback( { workflowType, aliases, name } );
-
-    if ( isChild ) {
-      const result = await executeChild( name, {
-        args: undefined === input ? [] : [ input ],
-        workflowId: `${workflowId}-${toUrlSafeBase64( uuid4() )}`,
-        parentClosePolicy: ParentClosePolicy[extra?.detached ? 'ABANDON' : 'TERMINATE'],
-        memo: {
-          ...memo, // Preserve memo and mix activityOptions, if provided
-          ...( extra?.activityOptions && {
-            activityOptions: deepMerge( memo?.activityOptions ?? {}, extra?.activityOptions )
-          } )
-        }
-      } );
-      return result.output;
-    }
+      const { workflowId, workflowType, memo, root } = workflowInfo();
+
+      // if the stack already includes this workflowId, means the workflow() function was called
+      // from within a running workflow, meaning it is suppose to start a child workflow
+      const isChild = Array.isArray( memo.stack ) ? memo.stack.includes( workflowId ) :
+        checkChildFallback( { workflowType, aliases, name } );
+
+      if ( isChild ) {
+        const result = await executeChild( name, {
+          args: undefined === input ? [] : [ input ],
+          workflowId: `${workflowId}-${toUrlSafeBase64( uuid4() )}`,
+          parentClosePolicy: ParentClosePolicy[extra?.detached ? 'ABANDON' : 'TERMINATE'],
+          memo: {
+            ...memo, // Preserve memo and mix activityOptions, if provided
+            ...( extra?.activityOptions && {
+              activityOptions: deepMerge( memo?.activityOptions ?? {}, extra?.activityOptions )
+            } )
+          }
+        } );
+        return result.output;
+      }
 
-    const isRoot = !root;
+      const isRoot = !root;
 
-    memo.stack = [ ...memo.stack ?? [], workflowId ];
-    // Parent options have prevalence on nested calls, child will be overwritten
-    memo.activityOptions = deepMerge( activityOptions, memo.activityOptions );
-    // Trace info is only added in the root workflow
-    if ( isRoot ) {
-      memo.traceInfo = TraceInfo.build( { disableTrace } );
-    }
+      memo.stack = [ ...memo.stack ?? [], workflowId ];
+      // Parent options have prevalence on nested calls, child will be overwritten
+      memo.activityOptions = deepMerge( activityOptions, memo.activityOptions );
+      // Trace info is only added in the root workflow
+      if ( isRoot ) {
+        memo.traceInfo = TraceInfo.build( { disableTrace } );
+      }
 
-    const steps = proxyActivities( memo.activityOptions );
-    const traceDest = isRoot && parseActivityOutput( await steps[ACTIVITY_GET_TRACE_DESTINATIONS]( memo.traceInfo ) );
-
-    try {
-      validator.validateInput( input );
-
-      // Creates an activity caller based on a prefix
-      const createCaller = prefix => async ( t, ...args ) => parseActivityOutput( await steps[`${prefix}#${t}`]( ...args ) );
-
-      // This are functions used by the AST to replace direct activity (step/evaluator) calls
-      const dispatchers = {
-        invokeStep: createCaller( name ),
-        invokeSharedStep: createCaller( SHARED_STEP_PREFIX ),
-        invokeEvaluator: createCaller( name ),
-        invokeSharedEvaluator: createCaller( SHARED_STEP_PREFIX )
-      };
-
-      // The workflow function execution with "this" set with the dispatchers
-      const output = await fn.call( dispatchers, input, WorkflowContext.build() );
-      validator.validateOutput( output );
-
-      return {
-        [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
-        output,
-        ...( traceDest && { trace: { destinations: traceDest } } )
-      };
-    } catch ( error ) {
-      if ( isRoot && traceDest ) {
-        // Append the trace destinations so it is carried to interceptor
-        error[METADATA_ACCESS_SYMBOL] = { trace: { destinations: traceDest } };
+      const steps = proxyActivities( memo.activityOptions );
+      const traceDest = isRoot && parseActivityOutput( await steps[ACTIVITY_GET_TRACE_DESTINATIONS]( memo.traceInfo ) );
+
+      try {
+        validator.validateInput( input );
+
+        // Creates an activity caller based on a prefix
+        const createCaller = prefix => async ( t, ...args ) => parseActivityOutput( await steps[`${prefix}#${t}`]( ...args ) );
+
+        // This are functions used by the AST to replace direct activity (step/evaluator) calls
+        const dispatchers = {
+          invokeStep: createCaller( name ),
+          invokeSharedStep: createCaller( SHARED_STEP_PREFIX ),
+          invokeEvaluator: createCaller( name ),
+          invokeSharedEvaluator: createCaller( SHARED_STEP_PREFIX )
+        };
+
+        // The workflow function execution with "this" set with the dispatchers
+        const output = await fn.call( dispatchers, input, WorkflowContext.build() );
+        validator.validateOutput( output );
+
+        return {
+          [WORKFLOW_WRAPPER_VERSION_FIELD]: 1,
+          output,
+          ...( traceDest && { trace: { destinations: traceDest } } )
+        };
+      } catch ( error ) {
+        if ( isRoot && traceDest ) {
+          // Append the trace destinations so it is carried to interceptor
+          error[METADATA_ACCESS_SYMBOL] = { trace: { destinations: traceDest } };
+        }
+        throw error;
       }
-      throw error;
     }
-  };
-
-  setMetadata( wrapper, { name, description, inputSchema, outputSchema, aliases } );
-  return wrapper;
-};
+  } );
+}

package/src/interface/workflow.spec.js

@@ -19,6 +19,7 @@ const validateInputMock = vi.hoisted( () => vi.fn() );
 const validateOutputMock = vi.hoisted( () => vi.fn() );
 const validateInvocationOptionsMock = vi.hoisted( () => vi.fn() );
 const validatorConstructorMock = vi.hoisted( () => vi.fn() );
+const createWorkflowMock = vi.hoisted( () => vi.fn( ( { handler } ) => handler ) );
 
 vi.mock( './validations/index.js', () => {
   class WorkflowValidator {
@@ -37,6 +38,10 @@ vi.mock( './validations/index.js', () => {
   return { WorkflowValidator };
 } );
 
+vi.mock( '#helpers/component', () => ( {
+  createWorkflow: createWorkflowMock
+} ) );
+
 vi.mock( '@temporalio/workflow', async importOriginal => {
   const actual = await importOriginal();
   return {
@@ -151,7 +156,7 @@ describe( 'workflow()', () => {
     expect( () => workflow( workflowDefinition( { name: 'invalid_name' } ) ) ).toThrow( error );
   } );
 
-  it( 'attaches workflow metadata to the wrapper', async () => {
+  it( 'creates a workflow component with definition metadata', async () => {
     const { workflow } = await import( './workflow.js' );
     const inputSchema = z.object( { value: z.string() } );
     const outputSchema = z.object( { ok: z.boolean() } );
@@ -165,14 +170,16 @@ describe( 'workflow()', () => {
       fn: async () => ( { ok: true } )
     } ) );
 
-    const [ metadataSymbol ] = Object.getOwnPropertySymbols( wf );
-    expect( wf[metadataSymbol] ).toEqual( {
+    expect( createWorkflowMock ).toHaveBeenCalledWith( {
       name: 'metadata_wf',
       description: 'Metadata workflow',
       inputSchema,
       outputSchema,
-      aliases: [ 'metadata_alias' ]
+      options: {},
+      aliases: [ 'metadata_alias' ],
+      handler: expect.any( Function )
     } );
+    expect( wf ).toBe( createWorkflowMock.mock.calls[0][0].handler );
   } );
 
   describe( 'outside Temporal workflow context', () => {