@outputai/core 0.2.1-next.6499038.0 → 0.2.1-next.756d32d.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/core",
-  "version": "0.2.1-next.6499038.0",
+  "version": "0.2.1-next.756d32d.0",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {
@@ -37,11 +37,11 @@
     "@babel/parser": "7.29.2",
     "@babel/traverse": "7.29.0",
     "@babel/types": "7.29.0",
-    "@temporalio/activity": "1.15.0",
-    "@temporalio/client": "1.15.0",
-    "@temporalio/common": "1.15.0",
-    "@temporalio/worker": "1.15.0",
-    "@temporalio/workflow": "1.15.0",
+    "@temporalio/activity": "1.17.0",
+    "@temporalio/client": "1.17.0",
+    "@temporalio/common": "1.17.0",
+    "@temporalio/worker": "1.17.0",
+    "@temporalio/workflow": "1.17.0",
     "redis": "5.12.1",
     "stacktrace-parser": "0.1.11",
     "undici": "8.1.0",

package/src/hooks/index.d.ts

@@ -12,6 +12,42 @@ export interface ErrorHookPayload {
   error: Error;
 }
 
+/**
+ * Payload passed to the onWorkflowStart handler when a workflow run begins.
+ */
+export interface WorkflowStartHookPayload {
+  /** Identifier of the workflow run. */
+  id: string;
+  /** Name of the workflow. */
+  name: string;
+}
+
+/**
+ * Payload passed to the onWorkflowEnd handler when a workflow run completes successfully.
+ */
+export interface WorkflowEndHookPayload {
+  /** Identifier of the workflow run. */
+  id: string;
+  /** Name of the workflow. */
+  name: string;
+  /** Duration of the workflow run in milliseconds. */
+  duration: number;
+}
+
+/**
+ * Payload passed to the onWorkflowError handler when a workflow run fails.
+ */
+export interface WorkflowErrorHookPayload {
+  /** Identifier of the workflow run. */
+  id: string;
+  /** Name of the workflow. */
+  name: string;
+  /** Elapsed time before failure in milliseconds. */
+  duration: number;
+  /** The error thrown. */
+  error: Error;
+}
+
 /**
  * Register a handler to be invoked on workflow, activity or runtime errors.
  *
@@ -21,11 +57,38 @@ export declare function onError( handler: ( payload: ErrorHookPayload ) => void
 
 /**
  * Register a handler to be invoked once, before the worker starts processing tasks.
- * Runs synchronously after activities are loaded and before Worker.create().
+ * It is invoked before Worker.create().
  *
  * @param handler - Function called with no arguments.
  */
-export declare function onBeforeStart( handler: () => void ): void;
+export declare function onBeforeWorkerStart( handler: () => void ): void;
+
+/**
+ * Register a handler to be invoked when a workflow run starts.
+ *
+ * Excludes the $catalog internal workflow.
+ *
+ * @param handler - Function called with the workflow start payload.
+ */
+export declare function onWorkflowStart( handler: ( payload: WorkflowStartHookPayload ) => void ): void;
+
+/**
+ * Register a handler to be invoked when a workflow run completes successfully.
+ *
+ * Excludes the $catalog internal workflow.
+ *
+ * @param handler - Function called with the workflow end payload.
+ */
+export declare function onWorkflowEnd( handler: ( payload: WorkflowEndHookPayload ) => void ): void;
+
+/**
+ * Register a handler to be invoked when a workflow run fails.
+ *
+ * Excludes the $catalog internal workflow.
+ *
+ * @param handler - Function called with the workflow error payload.
+ */
+export declare function onWorkflowError( handler: ( payload: WorkflowErrorHookPayload ) => void ): void;
 
 /**
  * Register a handler to be invoked when a given event happens
@@ -33,4 +96,4 @@ export declare function onBeforeStart( handler: () => void ): void;
  * @param eventName - The name of the event to subscribe
  * @param handler - Function called with the event payload
  */
-export declare function on( eventName: string, handler: ( payload: object ) => void ): void;
+export declare function on( eventName: string, handler: ( payload?: object ) => void ): void;

package/src/hooks/index.js

@@ -1,34 +1,50 @@
 import { messageBus } from '#bus';
-import { BusEventType } from '#consts';
+import { BusEventType, WORKFLOW_CATALOG } from '#consts';
 import { createChildLogger } from '#logger';
 
 const log = createChildLogger( 'Hooks' );
 
+/**
+ * Invokes an external hook handler function with a try catch around it
+ *
+ * @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 ) => {
+  try {
+    await fn( args );
+  } catch ( error ) {
+    log.error( `${hookName} hook error`, { message: error.message, stack: error.stack } );
+  }
+};
+
+/** Triggers on any errors: workflow, activity and runtime */
 export const onError = handler => {
-  const invokeHandler = async args => {
-    try {
-      await handler( args );
-    } catch ( error ) {
-      log.error( 'onError hook error', { error } );
-    }
-  };
-
-  messageBus.on( BusEventType.ACTIVITY_ERROR, async ( { name, workflowName, error } ) =>
-    invokeHandler( { source: 'activity', activityName: name, workflowName, error } ) );
-  messageBus.on( BusEventType.WORKFLOW_ERROR, async ( { name, error } ) =>
-    invokeHandler( { source: 'workflow', workflowName: name, error } ) );
+  messageBus.on( BusEventType.ACTIVITY_ERROR, async ( { id, name, workflowId, workflowName, error } ) =>
+    safeInvoke( handler, { source: 'activity', activityId: id, activityName: name, workflowId, workflowName, error }, 'onError' ) );
+  messageBus.on( BusEventType.WORKFLOW_ERROR, async ( { id, name, error } ) =>
+    safeInvoke( handler, { source: 'workflow', workflowId: id, workflowName: name, error }, 'onError' ) );
   messageBus.on( BusEventType.RUNTIME_ERROR, async ( { error } ) =>
-    invokeHandler( { source: 'runtime', error } ) );
+    safeInvoke( handler, { source: 'runtime', error }, 'onError' ) );
 };
 
-export const onBeforeStart = handler => messageBus.on( BusEventType.WORKER_BEFORE_START, handler );
+/** Listen to worker before start events */
+export const onBeforeWorkerStart = handler => messageBus.on( BusEventType.WORKER_BEFORE_START, () =>
+  safeInvoke( handler, undefined, 'onBeforeWorkerStart' ) );
 
-export const on = ( eventName, handler ) => {
-  messageBus.on( `external:${eventName}`, async payload => {
-    try {
-      await handler( payload );
-    } catch ( error ) {
-      log.error( `on(${eventName}) hook error`, { error } );
-    }
-  } );
-};
+/** Listen to workflow start events, excludes catalog workflow */
+export const onWorkflowStart = handler => messageBus.on( BusEventType.WORKFLOW_START, ( { id, name } ) =>
+  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, name }, 'onWorkflowStart' ) : null );
+
+/** Listen to workflow end events, excludes catalog workflow */
+export const onWorkflowEnd = handler => messageBus.on( BusEventType.WORKFLOW_END, ( { id, name, duration } ) =>
+  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, name, duration }, 'onWorkflowEnd' ) : null );
+
+/** Listen to workflow error events, excludes catalog workflow */
+export const onWorkflowError = handler => messageBus.on( BusEventType.WORKFLOW_ERROR, ( { id, name, duration, error } ) =>
+  WORKFLOW_CATALOG !== name ? safeInvoke( handler, { id, name, duration, error }, 'onWorkflowError' ) : null );
+
+/** Generic listener for events emitted elsewhere (outside core) */
+export const on = ( eventName, handler ) => messageBus.on( `external:${eventName}`, payload =>
+  safeInvoke( handler, payload, eventName ) );

package/src/hooks/index.spec.js

@@ -0,0 +1,176 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BusEventType, WORKFLOW_CATALOG } from '#consts';
+
+const logErrorMock = vi.hoisted( () => vi.fn() );
+const createChildLoggerMock = vi.hoisted( () =>
+  vi.fn( () => ( { error: logErrorMock } ) )
+);
+
+const onHandlers = vi.hoisted( () => ( {} ) );
+const messageBusMock = vi.hoisted( () => ( {
+  on: vi.fn( ( eventType, handler ) => {
+    onHandlers[eventType] = handler;
+  } )
+} ) );
+
+vi.mock( '#logger', () => ( { createChildLogger: createChildLoggerMock } ) );
+vi.mock( '#bus', () => ( { messageBus: messageBusMock } ) );
+
+import {
+  on,
+  onBeforeWorkerStart,
+  onError,
+  onWorkflowEnd,
+  onWorkflowError,
+  onWorkflowStart
+} from './index.js';
+
+describe( 'hooks/index', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    Object.keys( onHandlers ).forEach( k => {
+      delete onHandlers[k];
+    } );
+  } );
+
+  describe( 'onError', () => {
+    it( 'registers activity, workflow, and runtime error listeners', () => {
+      const handler = vi.fn().mockResolvedValue( undefined );
+      onError( handler );
+
+      expect( messageBusMock.on ).toHaveBeenCalledWith( BusEventType.ACTIVITY_ERROR, expect.any( Function ) );
+      expect( messageBusMock.on ).toHaveBeenCalledWith( BusEventType.WORKFLOW_ERROR, expect.any( Function ) );
+      expect( messageBusMock.on ).toHaveBeenCalledWith( BusEventType.RUNTIME_ERROR, expect.any( Function ) );
+    } );
+
+    it( 'invokes handler with activity-shaped payload', async () => {
+      const handler = vi.fn().mockResolvedValue( undefined );
+      onError( handler );
+
+      const err = new Error( 'act-fail' );
+      await onHandlers[BusEventType.ACTIVITY_ERROR]( {
+        id: 'act-1',
+        name: 'wf#step',
+        workflowId: 'wf-run-1',
+        workflowName: 'wf',
+        error: err
+      } );
+
+      expect( handler ).toHaveBeenCalledWith( {
+        source: 'activity',
+        activityId: 'act-1',
+        activityName: 'wf#step',
+        workflowId: 'wf-run-1',
+        workflowName: 'wf',
+        error: err
+      } );
+    } );
+
+    it( 'invokes handler with workflow-shaped payload', async () => {
+      const handler = vi.fn().mockResolvedValue( undefined );
+      onError( handler );
+
+      const err = new Error( 'wf-fail' );
+      await onHandlers[BusEventType.WORKFLOW_ERROR]( {
+        id: 'wf-run-2',
+        name: 'myWorkflow',
+        error: err
+      } );
+
+      expect( handler ).toHaveBeenCalledWith( {
+        source: 'workflow',
+        workflowId: 'wf-run-2',
+        workflowName: 'myWorkflow',
+        error: err
+      } );
+    } );
+
+    it( 'logs and does not rethrow when handler rejects', async () => {
+      const handler = vi.fn().mockRejectedValue( new Error( 'boom' ) );
+      onError( handler );
+
+      const error = new Error( 'rt' );
+      await onHandlers[BusEventType.RUNTIME_ERROR]( { error } );
+
+      expect( handler ).toHaveBeenCalledWith( { source: 'runtime', error } );
+    } );
+  } );
+
+  describe( 'onBeforeWorkerStart', () => {
+    it( 'registers and invokes handler with undefined payload', async () => {
+      const handler = vi.fn().mockResolvedValue( undefined );
+      onBeforeWorkerStart( handler );
+
+      expect( messageBusMock.on ).toHaveBeenCalledWith( BusEventType.WORKER_BEFORE_START, expect.any( Function ) );
+      await onHandlers[BusEventType.WORKER_BEFORE_START]();
+
+      expect( handler ).toHaveBeenCalledWith( undefined );
+    } );
+  } );
+
+  describe( 'onWorkflowStart', () => {
+    it( 'skips catalog workflow name', async () => {
+      const handler = vi.fn().mockResolvedValue( undefined );
+      onWorkflowStart( handler );
+
+      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_START]( { id: '1', name: WORKFLOW_CATALOG } ) );
+      expect( handler ).not.toHaveBeenCalled();
+
+      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_START]( { id: '2', name: 'myWorkflow' } ) );
+      expect( handler ).toHaveBeenCalledWith( { id: '2', name: 'myWorkflow' } );
+    } );
+  } );
+
+  describe( 'onWorkflowEnd', () => {
+    it( 'skips catalog workflow name', async () => {
+      const handler = vi.fn().mockResolvedValue( undefined );
+      onWorkflowEnd( handler );
+
+      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_END]( {
+        id: '1',
+        name: WORKFLOW_CATALOG,
+        duration: 10
+      } ) );
+      expect( handler ).not.toHaveBeenCalled();
+
+      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_END]( { id: '2', name: 'myWorkflow', duration: 5 } ) );
+      expect( handler ).toHaveBeenCalledWith( { id: '2', name: 'myWorkflow', duration: 5 } );
+    } );
+  } );
+
+  describe( 'onWorkflowError', () => {
+    it( 'skips catalog workflow name', async () => {
+      const handler = vi.fn().mockResolvedValue( undefined );
+      const err = new Error( 'wf' );
+      onWorkflowError( handler );
+
+      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_ERROR]( {
+        id: '1',
+        name: WORKFLOW_CATALOG,
+        duration: 1,
+        error: err
+      } ) );
+      expect( handler ).not.toHaveBeenCalled();
+
+      await Promise.resolve( onHandlers[BusEventType.WORKFLOW_ERROR]( {
+        id: '2',
+        name: 'myWorkflow',
+        duration: 2,
+        error: err
+      } ) );
+      expect( handler ).toHaveBeenCalledWith( { id: '2', name: 'myWorkflow', duration: 2, error: err } );
+    } );
+  } );
+
+  describe( 'on', () => {
+    it( 'subscribes to external event channel and forwards payload', async () => {
+      const handler = vi.fn().mockResolvedValue( undefined );
+      on( 'myEvent', handler );
+
+      expect( messageBusMock.on ).toHaveBeenCalledWith( 'external:myEvent', expect.any( Function ) );
+      await onHandlers['external:myEvent']( { foo: 1 } );
+
+      expect( handler ).toHaveBeenCalledWith( { foo: 1 } );
+    } );
+  } );
+} );