@outputai/core 0.10.0 → 0.10.1-next.09ed166.0

package/src/helpers/object.spec.js

@@ -95,98 +95,86 @@ describe( 'clone', () => {
 } );
 
 describe( 'deepMerge', () => {
-  it( 'Overwrites properties in object "a"', () => {
+  it( 'returns a clone when only the base object is provided', () => {
     const a = {
-      a: 1,
-      b: {
-        c: 2
-      }
+      nested: { value: 1 }
     };
-    const b = {
-      a: false,
-      b: {
-        c: true
-      }
-    };
-    expect( deepMerge( a, b ) ).toEqual( {
-      a: false,
-      b: {
-        c: true
-      }
-    } );
-  } );
+    const result = deepMerge( a );
 
-  it( 'Adds properties existing in "b" but absent in "a"', () => {
-    const a = {
-      a: 1
-    };
-    const b = {
-      a: false,
-      b: true
-    };
-    expect( deepMerge( a, b ) ).toEqual( {
-      a: false,
-      b: true
+    a.nested.value = 2;
+
+    expect( result ).toEqual( {
+      nested: { value: 1 }
     } );
   } );
 
-  it( 'Keep extra properties in "a"', () => {
-    const a = {
-      a: 1
-    };
-    const b = {
-      b: true
-    };
-    expect( deepMerge( a, b ) ).toEqual( {
-      a: 1,
-      b: true
+  it( 'Throws when first argument is not a plain object', () => {
+    expect( () => deepMerge( null ) ).toThrow( Error );
+  } );
+
+  it( 'merges multiple objects from left to right using rightmost values', () => {
+    expect( deepMerge(
+      {
+        a: 1,
+        nested: {
+          a: 'base',
+          kept: true
+        }
+      },
+      {
+        b: 2,
+        nested: {
+          a: 'first',
+          b: 'first'
+        }
+      },
+      {
+        a: 3,
+        nested: {
+          b: 'second',
+          c: 'second'
+        }
+      }
+    ) ).toEqual( {
+      a: 3,
+      b: 2,
+      nested: {
+        a: 'first',
+        b: 'second',
+        c: 'second',
+        kept: true
+      }
     } );
   } );
 
-  it( 'Merge object is a clone', () => {
-    const a = {
-      a: 1
-    };
-    const b = {
-      b: 1
-    };
-    const result = deepMerge( a, b );
-    a.a = 2;
-    b.b = 2;
-    expect( result.a ).toEqual( 1 );
+  it( 'ignores non-object values among multiple overlays', () => {
+    expect( deepMerge(
+      { a: 1 },
+      null,
+      { b: 2 },
+      undefined,
+      { a: 3 }
+    ) ).toEqual( {
+      a: 3,
+      b: 2
+    } );
   } );
+} );
 
-  it( 'Returns copy of "a" if "b" is not an object', () => {
+describe( 'deepMergeWithResolver', () => {
+  it( 'returns a clone when only the base object and resolver are provided', () => {
     const a = {
-      a: 1
+      nested: { value: 1 }
     };
-    expect( deepMerge( a, null ) ).toEqual( { a: 1 } );
-    expect( deepMerge( a, undefined ) ).toEqual( { a: 1 } );
-  } );
+    const result = deepMergeWithResolver( a, ( x, y ) => x + y );
 
-  it( 'Copy of object "a" is a clone', () => {
-    const a = {
-      a: 1
-    };
-    const result = deepMerge( a, null );
-    a.a = 2;
-    expect( result.a ).toEqual( 1 );
-  } );
+    a.nested.value = 2;
 
-  it( 'Throws when first argument is not a plain object', () => {
-    expect( () => deepMerge( Function ) ).toThrow( Error );
-    expect( () => deepMerge( () => {} ) ).toThrow( Error );
-    expect( () => deepMerge( 'a' ) ).toThrow( Error );
-    expect( () => deepMerge( true ) ).toThrow( Error );
-    expect( () => deepMerge( /a/ ) ).toThrow( Error );
-    expect( () => deepMerge( [] ) ).toThrow( Error );
-    expect( () => deepMerge( class Foo {}, class Foo {} ) ).toThrow( Error );
-    expect( () => deepMerge( Number.constructor, Number.constructor ) ).toThrow( Error );
-    expect( () => deepMerge( Number.constructor.prototype, Number.constructor.prototype ) ).toThrow( Error );
+    expect( result ).toEqual( {
+      nested: { value: 1 }
+    } );
   } );
-} );
 
-describe( 'deepMergeWithResolver', () => {
   it( 'uses resolver for existing leaf values, including nested leaves', () => {
     const a = {
       cost: { total: 1 },
@@ -235,6 +223,66 @@ describe( 'deepMergeWithResolver', () => {
     expect( () => deepMergeWithResolver( [], {}, ( x, y ) => x + y ) ).toThrow( Error );
     expect( () => deepMergeWithResolver( 'a', {}, ( x, y ) => x + y ) ).toThrow( Error );
   } );
+
+  it( 'throws when last argument is not a resolver function', () => {
+    expect( () => deepMergeWithResolver( { a: 1 }, { a: 2 } ) )
+      .toThrow( 'Last argument (resolver) is not a function.' );
+  } );
+
+  it( 'merges multiple objects using the resolver from left to right', () => {
+    const resolver = vi.fn( ( x, y ) => `${ x }:${ y }` );
+
+    expect( deepMergeWithResolver(
+      {
+        a: 'base',
+        nested: {
+          count: 1,
+          kept: 'yes'
+        }
+      },
+      {
+        a: 'first',
+        nested: {
+          count: 2,
+          firstOnly: true
+        }
+      },
+      {
+        a: 'second',
+        nested: {
+          count: 3,
+          secondOnly: true
+        }
+      },
+      resolver
+    ) ).toEqual( {
+      a: 'base:first:second',
+      nested: {
+        count: '1:2:3',
+        firstOnly: true,
+        kept: 'yes',
+        secondOnly: true
+      }
+    } );
+    expect( resolver ).toHaveBeenCalledTimes( 4 );
+  } );
+
+  it( 'ignores non-object values among multiple resolver overlays', () => {
+    const resolver = vi.fn( ( x, y ) => x + y );
+
+    expect( deepMergeWithResolver(
+      { a: 1 },
+      null,
+      { a: 2 },
+      undefined,
+      { b: 3 },
+      resolver
+    ) ).toEqual( {
+      a: 3,
+      b: 3
+    } );
+    expect( resolver ).toHaveBeenCalledOnce();
+  } );
 } );
 
 describe( 'isPlainObject', () => {

package/src/hooks/index.d.ts

@@ -99,35 +99,19 @@ export interface Aggregations {
 }
 
 /**
- * Common lifecycle hook payload fields for events associated with a workflow.
+ * Common hook payload fields
  */
 export interface HookPayloadBase {
   /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
   eventId: string;
   /** Timestamp of the event */
   eventDate: number;
-  /** Information about the current workflow execution */
-  workflowDetails: WorkflowDetails;
-}
-
-/**
- * Common hook payload fields for events associated with an activity.
- */
-export interface ActivityPayloadBase extends HookPayloadBase {
-  /** Temporal's activityInfo(). */
-  activityInfo: Info;
-  /** Output component kind for the activity, e.g. step or evaluator. */
-  outputActivityKind: string;
 }
 
 /**
  * Payload passed to the onError() handler when a workflow, activity or runtime error occurs.
  */
-export interface ErrorHookPayload {
-  /** UUID v4 stamped per emit. Stable per-emit idempotency key. */
-  eventId: string;
-  /** Timestamp of the event */
-  eventDate: number;
+export interface ErrorHookPayload extends HookPayloadBase {
   /** Origin of the error: workflow execution, activity execution, or runtime. */
   source: 'workflow' | 'activity' | 'runtime';
   /** Information about the current workflow execution */
@@ -135,45 +119,60 @@ export interface ErrorHookPayload {
   /** Temporal's activityInfo(). If source is activity */
   activityInfo?: Info;
   /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */
-  outputActivityKind?: string;
+  outputActivityKind: string;
   /** Attribute totals collected during the activity execution. */
   aggregations?: Aggregations | null;
   /** The error thrown. */
   error: Error;
 }
 
+/**
+ * Common hook payload fields for events associated with an workflow.
+ */
+export interface WorkflowPayloadBase extends HookPayloadBase {
+  /** Information about the current workflow execution */
+  workflowDetails: WorkflowDetails;
+}
+
 /**
  * Payload passed to the onWorkflowStart() handler when a workflow run begins.
  */
-export type WorkflowStartHookPayload = HookPayloadBase;
+export type WorkflowStartHookPayload = WorkflowPayloadBase;
 
 /**
  * Payload passed to the onWorkflowEnd() handler when a workflow run completes successfully.
  */
-export type WorkflowEndHookPayload = HookPayloadBase;
+export type WorkflowEndHookPayload = WorkflowPayloadBase;
 
 /**
  * Payload passed to the onWorkflowError() handler when a workflow run fails.
  */
-export interface WorkflowErrorHookPayload extends HookPayloadBase {
+export interface WorkflowErrorHookPayload extends WorkflowPayloadBase {
   /** The error thrown. */
   error: Error;
 }
 
 /**
- * Common activity lifecycle hook payload fields.
+ * Common hook payload fields for events associated with an activity.
  */
-export type ActivityHookPayload = ActivityPayloadBase;
+export interface ActivityPayloadBase extends HookPayloadBase {
+  /** Information about the current workflow execution */
+  workflowDetails: WorkflowDetails;
+  /** Temporal's activityInfo(). */
+  activityInfo: Info;
+  /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */
+  outputActivityKind: string;
+}
 
 /**
  * Payload passed to the onActivityStart() handler when an activity starts.
  */
-export type ActivityStartHookPayload = ActivityHookPayload;
+export type ActivityStartHookPayload = ActivityPayloadBase;
 
 /**
  * Payload passed to the onActivityEnd() handler when an activity completes successfully.
  */
-export interface ActivityEndHookPayload extends ActivityHookPayload {
+export interface ActivityEndHookPayload extends ActivityPayloadBase {
   /** Attribute totals collected during the activity execution. */
   aggregations: Aggregations | null;
 }
@@ -181,7 +180,7 @@ export interface ActivityEndHookPayload extends ActivityHookPayload {
 /**
  * Payload passed to the onActivityError() handler when an activity fails.
  */
-export interface ActivityErrorHookPayload extends ActivityHookPayload {
+export interface ActivityErrorHookPayload extends ActivityPayloadBase {
   /** Attribute totals collected during the activity execution. */
   aggregations: Aggregations | null;
   /** The error thrown. */
@@ -233,8 +232,6 @@ export declare function onWorkflowError( handler: ( payload: WorkflowErrorHookPa
 /**
  * Register a handler to be invoked when an activity starts.
  *
- * Excludes internal activities.
- *
  * @param handler - Function called with the activity start payload.
  */
 export declare function onActivityStart( handler: ( payload: ActivityStartHookPayload ) => void ): void;
@@ -242,8 +239,6 @@ export declare function onActivityStart( handler: ( payload: ActivityStartHookPa
 /**
  * Register a handler to be invoked when an activity completes successfully.
  *
- * Excludes internal activities.
- *
  * @param handler - Function called with the activity end payload.
  */
 export declare function onActivityEnd( handler: ( payload: ActivityEndHookPayload ) => void ): void;
@@ -251,24 +246,32 @@ export declare function onActivityEnd( handler: ( payload: ActivityEndHookPayloa
 /**
  * Register a handler to be invoked when an activity fails.
  *
- * Excludes internal activities.
- *
  * @param handler - Function called with the activity error payload.
  */
 export declare function onActivityError( handler: ( payload: ActivityErrorHookPayload ) => void ): void;
 
-/**
- * Framework-managed envelope added to payloads passed to on() handlers.
- */
-export interface OnHookEnvelope extends HookPayloadBase {
-  /** Temporal's activityInfo(). */
-  activityInfo: Info;
-  /** Output component kind for the activity, e.g. step, evaluator, or internal_step. */
+/** Framework metadata, optional activity context, and the emitted payload. */
+export type ExternalHookPayload<TPayload = unknown> = HookPayloadBase & {
+  /** Information about the current workflow execution, when emitted from an activity. */
+  workflowDetails?: WorkflowDetails;
+  /** Temporal's activityInfo(), when emitted from an activity. */
+  activityInfo?: Info;
+  /** Output component kind, when emitted from an activity. */
   outputActivityKind?: string;
-}
+  /** The emitted payload */
+  payload: TPayload | undefined;
+};
 
-export type OnHookPayload<TAttributes extends Record<string, unknown> = Record<string, unknown>> =
-  OnHookEnvelope & TAttributes;
+/**
+ * Emit a custom event from the current activity.
+ *
+ * @param eventName - The name of the event to emit.
+ * @param payload - Optional value forwarded to on() handlers.
+ */
+export declare function emit(
+  eventName: string,
+  payload?: unknown
+): boolean;
 
 /**
  * Register a handler to be invoked when a given event happens
@@ -276,7 +279,7 @@ export type OnHookPayload<TAttributes extends Record<string, unknown> = Record<s
  * @param eventName - The name of the event to subscribe
  * @param handler - Function called with the event payload
  */
-export declare function on<TAttributes extends Record<string, unknown> = Record<string, unknown>>(
+export declare function on<TPayload = unknown>(
   eventName: string,
-  handler: ( payload: OnHookPayload<TAttributes> ) => void
+  handler: ( event: ExternalHookPayload<TPayload> ) => void
 ): void;

package/src/hooks/index.js

@@ -1,17 +1,17 @@
-import { messageBus } from '#bus';
-import { BusEventType, ComponentType, WORKFLOW_CATALOG } from '#consts';
+import { mainEventBus, stepEventBus } from '#bus';
+import { BusEventType } from '#consts';
 import { createChildLogger } from '#logger';
 
 const log = createChildLogger( 'Hooks' );
 
 /**
- * Invokes an external hook handler function with a try catch around it
+ * Invokes a function within a try catch and log the error
  *
  * @param {Function} fn
  * @param {any} args - Args to invoke the function with
  * @param {string} hookName - hookName to identify this hook function in the logs
  */
-const safeInvoke = async ( fn, args, hookName ) => {
+const callHookCb = async ( fn, args, hookName ) => {
   try {
     await fn( args );
   } catch ( error ) {
@@ -19,50 +19,55 @@ const safeInvoke = async ( fn, args, hookName ) => {
   }
 };
 
-/** Triggers on any errors: workflow, activity and runtime */
-export const onError = handler => {
-  messageBus.on( BusEventType.ACTIVITY_ERROR, async payload =>
-    safeInvoke( handler, { source: 'activity', ...payload }, 'onError' ) );
-  messageBus.on( BusEventType.WORKFLOW_ERROR, async payload =>
-    safeInvoke( handler, { source: 'workflow', ...payload }, 'onError' ) );
-  messageBus.on( BusEventType.RUNTIME_ERROR, async payload =>
-    safeInvoke( handler, { source: 'runtime', ...payload }, 'onError' ) );
+// General Life-cycle
+// --------------------------------------
+const onError = cb => {
+  mainEventBus.on( BusEventType.ACTIVITY_ERROR, async payload =>
+    callHookCb( cb, { source: 'activity', ...payload }, 'onError' ) );
+  mainEventBus.on( BusEventType.WORKFLOW_ERROR, async payload =>
+    callHookCb( cb, { source: 'workflow', ...payload }, 'onError' ) );
+  mainEventBus.on( BusEventType.RUNTIME_ERROR, async payload =>
+    callHookCb( cb, { source: 'runtime', ...payload }, 'onError' ) );
 };
 
-/** Listen to worker before start events */
-export const onBeforeWorkerStart = handler => messageBus.on( BusEventType.WORKER_BEFORE_START, () =>
-  safeInvoke( handler, undefined, 'onBeforeWorkerStart' ) );
+const onBeforeWorkerStart = cb => mainEventBus.on( BusEventType.WORKER_BEFORE_START, () => callHookCb( cb, undefined, 'onBeforeWorkerStart' ) );
 
-/** Catalog workflow events should not be emitted */
-const shouldEmitWorkflowEvent = workflowDetails => WORKFLOW_CATALOG !== workflowDetails.workflowType;
+// Workflow Life-cycle
+// --------------------------------------
+const onWorkflowStart = cb => mainEventBus.on( BusEventType.WORKFLOW_START, payload => callHookCb( cb, payload, 'onWorkflowStart' ) );
+const onWorkflowEnd = cb => mainEventBus.on( BusEventType.WORKFLOW_END, payload => callHookCb( cb, payload, 'onWorkflowEnd' ) );
+const onWorkflowError = cb => mainEventBus.on( BusEventType.WORKFLOW_ERROR, payload => callHookCb( cb, payload, 'onWorkflowError' ) );
 
-/** Listen to workflow start events, excludes catalog workflow */
-export const onWorkflowStart = handler => messageBus.on( BusEventType.WORKFLOW_START, ( { workflowDetails, ...eventFields } ) =>
-  shouldEmitWorkflowEvent( workflowDetails ) ? safeInvoke( handler, { workflowDetails, ...eventFields }, 'onWorkflowStart' ) : null );
+// Activity Life-cycle
+// --------------------------------------
+const onActivityStart = cb => mainEventBus.on( BusEventType.ACTIVITY_START, fields => callHookCb( cb, fields, 'onActivityStart' ) );
+const onActivityEnd = cb => mainEventBus.on( BusEventType.ACTIVITY_END, fields => callHookCb( cb, fields, 'onActivityEnd' ) );
+const onActivityError = cb => mainEventBus.on( BusEventType.ACTIVITY_ERROR, fields => callHookCb( cb, fields, 'onActivityError' ) );
 
-/** Listen to workflow end events, excludes catalog workflow */
-export const onWorkflowEnd = handler => messageBus.on( BusEventType.WORKFLOW_END, ( { workflowDetails, ...eventFields } ) =>
-  shouldEmitWorkflowEvent( workflowDetails ) ? safeInvoke( handler, { workflowDetails, ...eventFields }, 'onWorkflowEnd' ) : null );
-
-/** Listen to workflow error events, excludes catalog workflow */
-export const onWorkflowError = handler => messageBus.on( BusEventType.WORKFLOW_ERROR, ( { workflowDetails, ...eventFields } ) =>
-  shouldEmitWorkflowEvent( workflowDetails ) ? safeInvoke( handler, { workflowDetails, ...eventFields }, 'onWorkflowError' ) : null );
-
-/** Internal activities do not trigger hooks */
-const shouldEmitActivityEvent = outputActivityKind => outputActivityKind !== ComponentType.INTERNAL_STEP;
-
-/** Listen to workflow start events, excludes catalog workflow */
-export const onActivityStart = handler => messageBus.on( BusEventType.ACTIVITY_START, ( { outputActivityKind, ...eventFields } ) =>
-  shouldEmitActivityEvent( outputActivityKind ) ? safeInvoke( handler, { outputActivityKind, ...eventFields }, 'onActivityStart' ) : null );
-
-/** Listen to workflow end events, excludes catalog workflow */
-export const onActivityEnd = handler => messageBus.on( BusEventType.ACTIVITY_END, ( { outputActivityKind, ...eventFields } ) =>
-  shouldEmitActivityEvent( outputActivityKind ) ? safeInvoke( handler, { outputActivityKind, ...eventFields }, 'onActivityEnd' ) : null );
+// Generic Events
+// --------------------------------------
+/** Listen to both sdk and custom events */
+const on = ( eventName, cb ) => {
+  stepEventBus.on( `sdk:${eventName}`, payload => callHookCb( cb, payload, eventName ) );
+  stepEventBus.on( `usr:${eventName}`, payload => callHookCb( cb, payload, eventName ) );
+};
 
-/** Listen to workflow error events, excludes catalog workflow */
-export const onActivityError = handler => messageBus.on( BusEventType.ACTIVITY_ERROR, ( { outputActivityKind, ...eventFields } ) =>
-  shouldEmitActivityEvent( outputActivityKind ) ? safeInvoke( handler, { outputActivityKind, ...eventFields }, 'onActivityError' ) : null );
+/**
+ * Emits a custom event
+ * @param {string} eventName
+ * @param {any} payload
+ */
+const emit = ( eventName, payload ) => stepEventBus.emit( `usr:${eventName}`, payload );
 
-/** Generic listener for events emitted elsewhere (outside core) */
-export const on = ( eventName, handler ) => messageBus.on( `external:${eventName}`, payload =>
-  safeInvoke( handler, payload, eventName ) );
+export {
+  emit,
+  on,
+  onActivityEnd,
+  onActivityError,
+  onActivityStart,
+  onBeforeWorkerStart,
+  onError,
+  onWorkflowEnd,
+  onWorkflowError,
+  onWorkflowStart
+};