@outputai/core 0.8.1 → 0.8.2-dev.e78f6b4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.8.1",
+  "version": "0.8.2-dev.e78f6b4.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -12,13 +12,13 @@
       "types": "./src/hooks/index.d.ts",
       "import": "./src/hooks/index.js"
     },
-    "./sdk_activity_integration": {
-      "types": "./src/activity_integration/index.d.ts",
-      "import": "./src/activity_integration/index.js"
+    "./sdk/helpers": {
+      "types": "./src/sdk/helpers/index.d.ts",
+      "import": "./src/sdk/helpers/index.js"
     },
-    "./sdk_utils": {
-      "types": "./src/utils/index.d.ts",
-      "import": "./src/utils/index.js"
+    "./sdk/runtime": {
+      "types": "./src/sdk/runtime/index.d.ts",
+      "import": "./src/sdk/runtime/index.js"
     }
   },
   "files": [
@@ -48,7 +48,7 @@
     "json-stream-stringify": "3.1.6",
     "redis": "5.12.1",
     "stacktrace-parser": "0.1.11",
-    "undici": "8.1.0",
+    "undici": "8.5.0",
     "winston": "3.19.0"
   },
   "peerDependencies": {
@@ -66,8 +66,7 @@
     "#consts": "./src/consts.js",
     "#errors": "./src/errors.js",
     "#logger": "./src/logger/index.js",
-    "#utils": "./src/utils/index.js",
-    "#internal_utils/*": "./src/internal_utils/*.js",
+    "#helpers/*": "./src/helpers/*.js",
     "#tracing": "./src/tracing/internal_interface.js",
     "#trace_attribute": "./src/tracing/trace_attribute.js",
     "#async_storage": "./src/async_storage.js",

package/src/bus.js

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
-import { isPlainObject } from '#utils';
+import { isPlainObject } from '#helpers/object';
 
 const emitter = new EventEmitter();
 

package/src/consts.js

@@ -2,6 +2,7 @@ export const ACTIVITY_GET_TRACE_DESTINATIONS = '__internal#getTraceDestinations'
 export const ACTIVITY_OPTIONS_FILENAME = '__activity_options.js';
 export const ACTIVITY_SEND_HTTP_REQUEST = '__internal#sendHttpRequest';
 export const ACTIVITY_WRAPPER_VERSION_FIELD = '__output_activity_wrapper_version';
+export const ACTIVITY_LOGGER_SYMBOL = Symbol.for( '__activity_logger' );
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
 export const SHARED_STEP_PREFIX = '$shared';
 export const WORKFLOW_CATALOG = '$catalog';
@@ -24,13 +25,15 @@ export const LifecycleEvent = {
 export const BusEventType = {
   WORKER_BEFORE_START: 'worker:before_start',
 
-  WORKFLOW_START: 'workflow:start',
   WORKFLOW_END: 'workflow:end',
   WORKFLOW_ERROR: 'workflow:error',
+  WORKFLOW_LOG: 'workflow:log',
+  WORKFLOW_START: 'workflow:start',
 
-  ACTIVITY_START: 'activity:start',
   ACTIVITY_END: 'activity:end',
   ACTIVITY_ERROR: 'activity:error',
+  ACTIVITY_LOG: 'activity:log',
+  ACTIVITY_START: 'activity:start',
 
   RUNTIME_ERROR: 'runtime_error'
 };

package/src/helpers/component.js

@@ -0,0 +1,12 @@
+import { ComponentType, METADATA_ACCESS_SYMBOL } from '#consts';
+import { assignImmutableProperty } from './object.js';
+
+const createComponent = ( { handler, ...metadata } ) => {
+  assignImmutableProperty( handler, METADATA_ACCESS_SYMBOL, metadata );
+  return handler;
+};
+
+export const createStep = options => createComponent( { ...options, type: ComponentType.STEP } );
+export const createInternalStep = options => createComponent( { ...options, type: ComponentType.INTERNAL_STEP } );
+export const createEvaluator = options => createComponent( { ...options, type: ComponentType.EVALUATOR } );
+export const createWorkflow = options => createComponent( { ...options, type: ComponentType.WORKFLOW } );

package/src/helpers/component.spec.js

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { ComponentType, METADATA_ACCESS_SYMBOL } from '#consts';
+import { createEvaluator, createInternalStep, createStep, createWorkflow } from './component.js';
+
+const factories = [
+  [ 'createStep', createStep, ComponentType.STEP ],
+  [ 'createInternalStep', createInternalStep, ComponentType.INTERNAL_STEP ],
+  [ 'createEvaluator', createEvaluator, ComponentType.EVALUATOR ],
+  [ 'createWorkflow', createWorkflow, ComponentType.WORKFLOW ]
+];
+
+describe( 'component helpers', () => {
+  it.each( factories )( '%s returns the handler with typed metadata', ( _, create, type ) => {
+    const handler = () => 'ok';
+    const inputSchema = { safeParse: () => ( { success: true } ) };
+    const outputSchema = { safeParse: () => ( { success: true } ) };
+    const options = { activityOptions: { startToCloseTimeout: '1m' } };
+
+    const component = create( {
+      name: 'test_component',
+      description: 'Test component',
+      inputSchema,
+      outputSchema,
+      handler,
+      options
+    } );
+
+    expect( component ).toBe( handler );
+    expect( component[METADATA_ACCESS_SYMBOL] ).toEqual( {
+      name: 'test_component',
+      description: 'Test component',
+      inputSchema,
+      outputSchema,
+      options,
+      type
+    } );
+  } );
+
+  it( 'defines metadata as a hidden immutable property', () => {
+    const handler = () => {};
+    const component = createStep( { name: 'hidden_step', handler } );
+
+    expect( Object.getOwnPropertyDescriptor( component, METADATA_ACCESS_SYMBOL ) ).toEqual( {
+      value: { name: 'hidden_step', type: ComponentType.STEP },
+      writable: false,
+      configurable: false,
+      enumerable: false
+    } );
+    expect( Object.keys( component ) ).toEqual( [] );
+    expect( () => {
+      component[METADATA_ACCESS_SYMBOL] = { name: 'updated' };
+    } ).toThrow( TypeError );
+  } );
+} );

package/src/helpers/fetch.js

@@ -0,0 +1,105 @@
+/**
+ * Consume Fetch's HTTP Response and return a serialized version of it;
+ *
+ * @param {Response} response
+ * @returns {object} Serialized response
+ */
+export const serializeFetchResponse = async response => {
+  const headers = Object.fromEntries( response.headers );
+  const contentType = headers['content-type'] || '';
+
+  const body = await ( async () => {
+    if ( contentType.includes( 'application/json' ) ) {
+      return response.json();
+    }
+    if ( contentType.startsWith( 'text/' ) ) {
+      return response.text();
+    }
+    return response.arrayBuffer().then( buf => Buffer.from( buf ).toString( 'base64' ) );
+  } )();
+
+  return {
+    url: response.url,
+    status: response.status,
+    statusText: response.statusText,
+    ok: response.ok,
+    headers,
+    body
+  };
+};
+/**
+ * Duck-typing to detect a Node Readable (Stream) without importing anything
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+const isReadable = v =>
+  typeof v === 'object' &&
+  typeof v?.read === 'function' &&
+  typeof v?.on === 'function' &&
+  typeof v?.pipe === 'function' &&
+  v?.readable !== false;
+
+/**
+ * Based on the type of a payload, serialized it to be send as the body of a fetch POST request and also infer its Content Type.
+ *
+ * Non serializable types versus Content-Type reference (for Node)
+ *
+ * |Type|Is self-describing)|Inferred type by fetch|Defined mime type|
+ * |-|-|-|-}
+ * |Blob|yes|`blob.type`||
+ * |File|yes|`file.type`||
+ * |FormData|yes|"multipart/form-data; boundary=..."||
+ * |URLSearchParams|yes|"application/x-www-form-urlencoded;charset=UTF-8"||
+ * |ArrayBuffer|no||"application/octet-stream"|
+ * |TypedArray (Uint8Array,Uint16Array)||"application/octet-stream"||
+ * |DataView|no||"application/octet-stream"|
+ * |ReadableStream, Readable, AsyncIterator|no||Can't, because stream must be read|
+ *
+ * If payload is none of the above types, test it:
+ * If the it is an object, serialize using JSON.stringify and set content-type to `application/json`;
+ * Else, it is a JS primitive, serialize using JSON.stringify and set content-type to `text/plain`;
+ *
+ * This implementation is overkill for temporal workflows since the only types available there will be:
+ * - URLSearchParams
+ * - ArrayBuffer
+ * - TypedArrays
+ * - DataView
+ * - asyncGenerator
+ * The others are non deterministic and are not available at runtime, but this function was build to be flexible
+ *
+ * @see {@link https://fetch.spec.whatwg.org/#bodyinit}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch}
+ *
+ * @param {unknown} payload
+ * @returns {object} An object with the serialized body and inferred content-type
+ */
+export const serializeBodyAndInferContentType = payload => {
+  const dataTypes = [ Blob, File, URLSearchParams, FormData ];
+
+  // empty body
+  if ( [ null, undefined ].includes( payload ) ) {
+    return { body: undefined, contentType: undefined };
+  }
+
+  // Buffer types, covers ArrayBuffer, TypedArrays and DataView
+  if ( payload instanceof ArrayBuffer || ArrayBuffer.isView( payload ) ) {
+    return { body: payload, contentType: 'application/octet-stream' };
+  }
+
+  // These data types auto assigned mime types
+  if ( dataTypes.some( t => payload instanceof t ) ) {
+    return { body: payload, contentType: undefined };
+  }
+
+  // ReadableStream, Readable and Async Iterator mimes cant be determined without reading it
+  if ( payload instanceof ReadableStream || typeof payload[Symbol.asyncIterator] === 'function' || isReadable( payload ) ) {
+    return { body: payload, contentType: undefined };
+  }
+
+  if ( typeof payload === 'object' ) {
+    return { body: JSON.stringify( payload ), contentType: 'application/json; charset=UTF-8' };
+  }
+
+  return { body: String( payload ), contentType: 'text/plain; charset=UTF-8' };
+};

package/src/helpers/fetch.spec.js

@@ -0,0 +1,203 @@
+import { describe, it, expect } from 'vitest';
+import { Readable } from 'node:stream';
+import { serializeBodyAndInferContentType, serializeFetchResponse } from './fetch.js';
+
+describe( 'serializeFetchResponse', () => {
+  it( 'serializes JSON response body and flattens headers', async () => {
+    const payload = { a: 1, b: 'two' };
+    const response = new Response( JSON.stringify( payload ), {
+      status: 200,
+      statusText: 'OK',
+      headers: { 'content-type': 'application/json' }
+    } );
+
+    const result = await serializeFetchResponse( response );
+    expect( result.status ).toBe( 200 );
+    expect( result.ok ).toBe( true );
+    expect( result.statusText ).toBe( 'OK' );
+    expect( result.headers['content-type'] ).toContain( 'application/json' );
+    expect( result.body ).toEqual( payload );
+  } );
+
+  it( 'serializes text/* response via text()', async () => {
+    const bodyText = 'hello world';
+    const response = new Response( bodyText, {
+      status: 201,
+      statusText: 'Created',
+      headers: { 'content-type': 'text/plain; charset=utf-8' }
+    } );
+
+    const result = await serializeFetchResponse( response );
+    expect( result.status ).toBe( 201 );
+    expect( result.ok ).toBe( true );
+    expect( result.statusText ).toBe( 'Created' );
+    expect( result.headers['content-type'] ).toContain( 'text/plain' );
+    expect( result.body ).toBe( bodyText );
+  } );
+
+  if ( typeof ReadableStream !== 'undefined' ) {
+    it( 'serializes ReadableStream body for text/* via text()', async () => {
+      const encoder = new TextEncoder();
+      const chunk = encoder.encode( 'streamed text' );
+      const stream = new ReadableStream( {
+        start( controller ) {
+          controller.enqueue( chunk );
+          controller.close();
+        }
+      } );
+      const response = new Response( stream, {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'content-type': 'text/plain; charset=utf-8' }
+      } );
+
+      const result = await serializeFetchResponse( response );
+      expect( result.status ).toBe( 200 );
+      expect( result.ok ).toBe( true );
+      expect( result.statusText ).toBe( 'OK' );
+      expect( result.headers['content-type'] ).toContain( 'text/plain' );
+      expect( result.body ).toBe( 'streamed text' );
+    } );
+  }
+
+  it( 'serializes non-text/non-json response as base64 from arrayBuffer()', async () => {
+    const bytes = Uint8Array.from( [ 0, 1, 2, 3 ] );
+    const response = new Response( bytes, {
+      status: 200,
+      statusText: 'OK',
+      headers: { 'content-type': 'application/octet-stream' }
+    } );
+
+    const result = await serializeFetchResponse( response );
+    expect( result.status ).toBe( 200 );
+    expect( result.ok ).toBe( true );
+    expect( result.statusText ).toBe( 'OK' );
+    expect( result.headers['content-type'] ).toBe( 'application/octet-stream' );
+    expect( result.body ).toBe( Buffer.from( bytes ).toString( 'base64' ) );
+  } );
+
+  it( 'defaults to base64 when content-type header is missing', async () => {
+    const bytes = Uint8Array.from( [ 0, 1, 2, 3 ] );
+    const response = new Response( bytes, { status: 200 } );
+    // No headers set; content-type resolves to ''
+
+    const result = await serializeFetchResponse( response );
+    expect( result.headers['content-type'] ?? '' ).toBe( '' );
+    expect( result.body ).toBe( Buffer.from( bytes ).toString( 'base64' ) );
+  } );
+} );
+
+describe( 'serializeBodyAndInferContentType', () => {
+  it( 'returns undefineds for null payload', () => {
+    const { body, contentType } = serializeBodyAndInferContentType( null );
+    expect( body ).toBeUndefined();
+    expect( contentType ).toBeUndefined();
+  } );
+
+  it( 'returns undefineds for undefined payload', () => {
+    const { body, contentType } = serializeBodyAndInferContentType( undefined );
+    expect( body ).toBeUndefined();
+    expect( contentType ).toBeUndefined();
+  } );
+
+  it( 'handles ArrayBuffer with octet-stream', () => {
+    const buf = new ArrayBuffer( 4 );
+    const { body, contentType } = serializeBodyAndInferContentType( buf );
+    expect( body ).toBe( buf );
+    expect( contentType ).toBe( 'application/octet-stream' );
+  } );
+
+  it( 'handles TypedArray with octet-stream', () => {
+    const view = new Uint8Array( [ 1, 2, 3 ] );
+    const { body, contentType } = serializeBodyAndInferContentType( view );
+    expect( body ).toBe( view );
+    expect( contentType ).toBe( 'application/octet-stream' );
+  } );
+
+  it( 'handles DataView with octet-stream', () => {
+    const ab = new ArrayBuffer( 2 );
+    const dv = new DataView( ab );
+    const { body, contentType } = serializeBodyAndInferContentType( dv );
+    expect( body ).toBe( dv );
+    expect( contentType ).toBe( 'application/octet-stream' );
+  } );
+
+  // Environment-provided web types
+  if ( typeof URLSearchParams !== 'undefined' ) {
+    it( 'passes through URLSearchParams without content type', () => {
+      const usp = new URLSearchParams( { a: '1', b: 'two' } );
+      const { body, contentType } = serializeBodyAndInferContentType( usp );
+      expect( body ).toBe( usp );
+      expect( contentType ).toBeUndefined();
+    } );
+  }
+
+  if ( typeof FormData !== 'undefined' ) {
+    it( 'passes through FormData without content type', () => {
+      const fd = new FormData();
+      fd.append( 'a', '1' );
+      const { body, contentType } = serializeBodyAndInferContentType( fd );
+      expect( body ).toBe( fd );
+      expect( contentType ).toBeUndefined();
+    } );
+  }
+
+  if ( typeof Blob !== 'undefined' ) {
+    it( 'passes through Blob without content type', () => {
+      const blob = new Blob( [ 'abc' ], { type: 'text/plain' } );
+      const { body, contentType } = serializeBodyAndInferContentType( blob );
+      expect( body ).toBe( blob );
+      expect( contentType ).toBeUndefined();
+    } );
+  }
+
+  if ( typeof File !== 'undefined' ) {
+    it( 'passes through File without content type', () => {
+      const file = new File( [ 'abc' ], 'a.txt', { type: 'text/plain' } );
+      const { body, contentType } = serializeBodyAndInferContentType( file );
+      expect( body ).toBe( file );
+      expect( contentType ).toBeUndefined();
+    } );
+  }
+
+  it( 'passes through async iterator without content type', () => {
+    const asyncIter = ( async function *() {
+      yield 'chunk';
+    } )();
+    const { body, contentType } = serializeBodyAndInferContentType( asyncIter );
+    expect( typeof body[Symbol.asyncIterator] ).toBe( 'function' );
+    expect( contentType ).toBeUndefined();
+  } );
+
+  it( 'passes through Node Readable without content type', () => {
+    const readable = Readable.from( [ 'a', 'b' ] );
+    const { body, contentType } = serializeBodyAndInferContentType( readable );
+    expect( body ).toBe( readable );
+    expect( contentType ).toBeUndefined();
+  } );
+
+  it( 'serializes plain object as JSON with JSON content type', () => {
+    const input = { a: 1, b: 'two' };
+    const { body, contentType } = serializeBodyAndInferContentType( input );
+    expect( body ).toBe( JSON.stringify( input ) );
+    expect( contentType ).toBe( 'application/json; charset=UTF-8' );
+  } );
+
+  it( 'serializes string primitive with text/plain content type', () => {
+    const { body, contentType } = serializeBodyAndInferContentType( 'hello' );
+    expect( body ).toBe( 'hello' );
+    expect( contentType ).toBe( 'text/plain; charset=UTF-8' );
+  } );
+
+  it( 'serializes number primitive with text/plain content type', () => {
+    const { body, contentType } = serializeBodyAndInferContentType( 42 );
+    expect( body ).toBe( '42' );
+    expect( contentType ).toBe( 'text/plain; charset=UTF-8' );
+  } );
+
+  it( 'serializes boolean primitive with text/plain content type', () => {
+    const { body, contentType } = serializeBodyAndInferContentType( true );
+    expect( body ).toBe( 'true' );
+    expect( contentType ).toBe( 'text/plain; charset=UTF-8' );
+  } );
+} );

package/src/helpers/function.js

@@ -0,0 +1,15 @@
+/**
+ * Returns a function that invokes the fn argument only once when called, further calls do nothing.
+ * @param {Function} fn
+ * @returns {Function}
+ */
+export const runOnce = fn => {
+  const state = { executed: false, result: undefined };
+  return ( ...args ) => {
+    if ( !state.executed ) {
+      state.executed = true;
+      return state.result = fn( ...args );
+    }
+    return state.result;
+  };
+};

package/src/helpers/function.spec.js

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi } from 'vitest';
+import { runOnce } from './function.js';
+
+describe( 'runOnce', () => {
+  it( 'calls the wrapped function only once', () => {
+    const fn = vi.fn();
+    const once = runOnce( fn );
+
+    once();
+    once();
+    once();
+
+    expect( fn ).toHaveBeenCalledOnce();
+  } );
+
+  it( 'passes arguments and replays the first call result', () => {
+    const fn = vi.fn( ( a, b ) => a + b );
+    const once = runOnce( fn );
+
+    expect( once( 2, 3 ) ).toBe( 5 );
+    expect( once( 4, 5 ) ).toBe( 5 );
+    expect( once( 6, 7 ) ).toBe( 5 );
+    expect( fn ).toHaveBeenCalledWith( 2, 3 );
+    expect( fn ).toHaveBeenCalledOnce();
+  } );
+
+  it( 'replays the first returned promise', () => {
+    const result = Promise.resolve( 'done' );
+    const fn = vi.fn( () => result );
+    const once = runOnce( fn );
+
+    expect( once() ).toBe( result );
+    expect( once() ).toBe( result );
+    expect( fn ).toHaveBeenCalledOnce();
+  } );
+
+  it( 'does not retry when the first call throws', () => {
+    const error = new Error( 'boom' );
+    const fn = vi.fn( () => {
+      throw error;
+    } );
+    const once = runOnce( fn );
+
+    expect( () => once() ).toThrow( error );
+    expect( once() ).toBeUndefined();
+    expect( fn ).toHaveBeenCalledOnce();
+  } );
+} );

package/src/helpers/object.js

@@ -0,0 +1,98 @@
+/**
+ * Detect a JS plain object.
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+export const isPlainObject = v =>
+  typeof v === 'object' &&
+    !Array.isArray( v ) &&
+    v !== null &&
+    [ Object.prototype, null ].includes( Object.getPrototypeOf( v ) );
+
+/**
+ * Node safe clone implementation that doesn't use global structuredClone()
+ * @param {object} v
+ * @returns {object}
+ */
+export const clone = v => {
+  try {
+    return JSON.parse( JSON.stringify( v ) );
+  } catch {
+    return v;
+  }
+};
+
+/**
+ * Creates a new object merging object "b" onto object "a", using a resolver function to define the value to keep.
+ * - Object "b" fields that also exists on "a" will have their value defined by the "resolver" function
+ * - Object "b" fields that don't exist on object "a" will be added;
+ * - Object "a" fields that don't exist on object "b" will be preserved;
+ *
+ * If "b" isn't an object, a new object equal to "a" is returned
+ *
+ * @param {object} a - The base object
+ * @param {object} b - The target object
+ * @param {function} resolver - A function that return the value to be kept. First argument is value a, second is value b
+ * @returns {object} A new object
+ */
+export const deepMergeWithResolver = ( a, b, resolver ) => {
+  if ( !isPlainObject( a ) ) {
+    throw new Error( 'Parameter "a" is not an object.' );
+  }
+  if ( !isPlainObject( b ) ) {
+    return clone( a );
+  }
+  return Object.entries( b ).reduce( ( obj, [ k, v ] ) =>
+    Object.assign( obj, {
+      [k]: ( () => {
+        if ( isPlainObject( v ) && isPlainObject( a[k] ) ) {
+          return deepMergeWithResolver( a[k], v, resolver );
+        }
+        if ( Object.hasOwn( a, k ) ) {
+          return resolver( a[k], v );
+        }
+        return v;
+      } )()
+    } )
+  , clone( a ) );
+};
+
+/**
+ * Creates a new object merging object "b" onto object "a" biased to "b":
+ * - Object "b" will overwrite fields on object "a";
+ * - Object "b" fields that don't exist on object "a" will be added;
+ * - Object "a" fields that don't exist on object "b" will be preserved;
+ *
+ * If "b" isn't an object, a new object equal to "a" is returned
+ *
+ * @param {object} a - The base object
+ * @param {object} b - The target object
+ * @returns {object} A new object
+ */
+export const deepMerge = ( a, b ) => deepMergeWithResolver( a, b, ( _, b ) => b );
+
+/**
+ * Adds an non-writable, non-configurable and non-enumerable property to an object
+ * @param {object} obj
+ * @param {string} key
+ * @param {any} value
+ * @returns
+ */
+export const assignImmutableProperty = ( obj, key, value ) => Object.defineProperty( obj, key, {
+  value,
+  writable: false,
+  configurable: false,
+  enumerable: false
+} );
+
+/**
+ * Receives an array and returns a copy of it with the elements shuffled
+ *
+ * @param {array} arr
+ * @returns {array}
+ */
+export const shuffleArray = arr => arr
+  .map( v => ( { v, sort: Math.random() } ) )
+  .sort( ( a, b ) => a.sort - b.sort )
+  .map( ( { v } ) => v );