@output.ai/core 0.1.14 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/index.d.ts

@@ -45,6 +45,55 @@ export type WorkflowCallConfig = {
   detached?: boolean
 };
 
+/**
+ * The second argument for the workflow's fn function
+ */
+export type WorkflowContext<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+> = {
+
+  /**
+   * Functions that allow fine control over the underlying Temporal workflows
+   */
+  control: {
+    /**
+     * Lets Workflow Execution close successfully and creates a new Workflow Execution.
+     *
+     * The new Workflow Execution is in the same chain as previous workflow but it will generate another trace file.
+     *
+     * It is akin to a checkpoint for when the Workflow gets too long or approaches certain scaling limits.
+     *
+     * It accepts input with the same schema as the parent workflow function (`inputSchema`).
+     *
+     * Calling the function needs to be the last statement for the workflow, accompanied by a `return`:
+     * ```js
+     *   return control.continueAsNew();
+     * ```
+     * Upon returning it, the parent workflow execution is closed without any output and the new execution takes its place.
+     *
+     * The function return type respects the `outputSchema` although no values are ever returned, the execution is just replaced.
+     *
+     * @see {@link https://docs.temporal.io/develop/typescript/continue-as-new}
+     * @param {z.infer<InputSchema>|undefined} input - The input for the new run. Omit when the workflow has no input schema.
+     * @returns {z.infer<OutputSchema>|void} The workflow output type for type-checking; never returns at runtime.
+     */
+    continueAsNew: InputSchema extends AnyZodSchema ?
+      ( input: z.infer<InputSchema> ) => ( OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void ) :
+      () => ( OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void ),
+
+    /** Indicates whether the Temporal runtime suggests continuing this workflow as new.
+     *
+     * Use this to decide whether to `continueAsNew` before long waits or at loop boundaries.
+     * Prefer returning the `continueAsNew(...)` call immediately when this becomes `true`.
+     *
+     * @see {@link https://docs.temporal.io/develop/typescript/continue-as-new#how-to-test}
+     * @returns {boolean} True if a continue-as-new is suggested for the current run; otherwise false.
+     */
+    isContinueAsNewSuggested: () => boolean
+  }
+};
+
 /*
 ╭─────────╮
 │ S T E P │╮
@@ -165,9 +214,9 @@ export async function step( options: {
  * @param {string} [options.description] - Description of the workflow
  * @param {z.ZodType} options.inputSchema - Zod schema for workflow input
  * @param {z.ZodType} options.outputSchema - Zod schema for workflow output
- * @param {function} options.fn - Workflow logic: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ * @param {function} options.fn - Workflow logic
  * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ * @returns {function} Callable workflow function
  */
 export function workflow<
   InputSchema extends AnyZodSchema,
@@ -177,7 +226,7 @@ export function workflow<
   description?: string,
   inputSchema: InputSchema,
   outputSchema: OutputSchema,
-  fn: ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>,
+  fn: ( input: z.infer<InputSchema>, context: WorkflowContext<InputSchema, OutputSchema> ) => Promise<z.infer<OutputSchema>>,
   options?: Options
 } ): ( input: z.infer<InputSchema>, extra?: WorkflowCallConfig ) => Promise<z.infer<OutputSchema>>;
 
@@ -188,9 +237,9 @@ export function workflow<
  * @param {string} options.name - Unique workflow name
  * @param {string} [options.description] - Description of the workflow
  * @param {z.ZodType} options.inputSchema - Zod schema for workflow input
- * @param {function} options.fn - Workflow logic: `(input: z.infer<InputSchema>) => Promise<void>`
+ * @param {function} options.fn - Workflow logic
  * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function: `(input: z.infer<InputSchema>) => Promise<void>`
+ * @returns {function} Callable workflow function
  */
 export function workflow<
   InputSchema extends AnyZodSchema
@@ -198,7 +247,7 @@ export function workflow<
   name: string,
   description?: string,
   inputSchema: InputSchema,
-  fn: ( input: z.infer<InputSchema> ) => Promise<void>,
+  fn: ( input: z.infer<InputSchema>, context: WorkflowContext<InputSchema, undefined> ) => Promise<void>,
   options?: Options
 } ): ( input: z.infer<InputSchema>, extra?: WorkflowCallConfig ) => Promise<void>;
 
@@ -209,9 +258,9 @@ export function workflow<
  * @param {string} options.name - Unique workflow name
  * @param {string} [options.description] - Description of the workflow
  * @param {z.ZodType} options.outputSchema - Zod schema for workflow output
- * @param {function} options.fn - Workflow logic: `() => Promise<z.infer<OutputSchema>>`
+ * @param {function} options.fn - Workflow logic
  * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function: `() => Promise<z.infer<OutputSchema>>`
+ * @returns {function} Callable workflow function
  */
 export function workflow<
   OutputSchema extends AnyZodSchema
@@ -219,7 +268,7 @@ export function workflow<
   name: string,
   description?: string,
   outputSchema: OutputSchema,
-  fn: () => Promise<z.infer<OutputSchema>>,
+  fn: ( input?: undefined | null, context: WorkflowContext<undefined, OutputSchema> ) => Promise<z.infer<OutputSchema>>,
   options?: Options
 } ): ( input?: undefined | null, extra?: WorkflowCallConfig ) => Promise<z.infer<OutputSchema>>;
 
@@ -229,14 +278,14 @@ export function workflow<
  * @param {object} options - Workflow options
  * @param {string} options.name - Unique workflow name
  * @param {string} [options.description] - Description of the workflow
- * @param {function} options.fn - Workflow logic: `() => Promise<void>`
+ * @param {function} options.fn - Workflow logic
  * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function: `() => Promise<void>`
+ * @returns {function} Callable workflow function
  */
 export function workflow( options : {
   name: string,
   description?: string,
-  fn: () => Promise<void>,
+  fn: ( input?: undefined | null, context: WorkflowContext<undefined, undefined> ) => Promise<void>,
   options?: Options
 } ): ( input?: undefined | null, extra?: WorkflowCallConfig ) => Promise<void>;
 

package/src/index.js

@@ -3,6 +3,7 @@ import { step } from './interface/step.js';
 import { workflow } from './interface/workflow.js';
 import { createWebhook } from './interface/webhook.js';
 import { FatalError, ValidationError } from './errors.js';
+export { continueAsNew } from '@temporalio/workflow';
 import { z } from 'zod';
 
 export {

package/src/interface/workflow.js

@@ -1,5 +1,5 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4, ParentClosePolicy } from '@temporalio/workflow';
+import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4, ParentClosePolicy, continueAsNew } from '@temporalio/workflow';
 import { validateWorkflow } from './validations/static.js';
 import { validateWithSchema } from './validations/runtime.js';
 import { SHARED_STEP_PREFIX, ACTIVITY_GET_TRACE_DESTINATIONS } from '#consts';
@@ -25,10 +25,9 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
   const steps = proxyActivities( activityOptions );
 
   const wrapper = async input => {
-    validateWithSchema( inputSchema, input, `Workflow ${name} input` );
-
     // this returns a plain function, for example, in unit tests
     if ( !inWorkflowContext() ) {
+      validateWithSchema( inputSchema, input, `Workflow ${name} input` );
       const output = await fn( input );
       validateWithSchema( outputSchema, output, `Workflow ${name} output` );
       return output;
@@ -36,12 +35,22 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
 
     const { workflowId, memo, startTime } = workflowInfo();
 
+    /* Context Object definition
+       - Control namespace: This object adds functions to interact with Temporal flow mechanisms
+    */
+    const context = {
+      control: {
+        isContinueAsNewSuggested: () => workflowInfo().continueAsNewSuggested,
+        continueAsNew
+      }
+    };
+
     // Root workflows will not have the execution context yet, since it is set here.
     const isRoot = !memo.executionContext;
 
-    // Create the execution context object or preserve if it already exists:
-    // It will always contains the information about the root workflow
-    // It will be used to as context for tracing (connecting events)
+    /* Creates the execution context object or preserve if it already exists:
+       It will always contain the information about the root workflow
+       It will be used to as context for tracing (connecting events) */
     const executionContext = memo.executionContext ?? {
       workflowId,
       workflowName: name,
@@ -53,6 +62,9 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
       activityOptions: memo.activityOptions ?? activityOptions // Also preserve the original activity options
     } );
 
+    // validation comes after setting memo to have that info already set for interceptor even if validations fail
+    validateWithSchema( inputSchema, input, `Workflow ${name} input` );
+
     // binds the methods called in the code that Webpack loader will add, they will exposed via "this"
     const output = await fn.call( {
       invokeStep: async ( stepName, input, options ) => steps[`${workflowPath}#${stepName}`]( input, options ),
@@ -81,7 +93,7 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
             ...( extra?.options && { activityOptions: mergeActivityOptions( activityOptions, extra.options ) } )
           }
         } )
-    }, input );
+    }, input, context );
 
     validateWithSchema( outputSchema, output, `Workflow ${name} output` );
 

package/src/tracing/trace_engine.js

@@ -4,6 +4,7 @@ import { serializeError } from './tools/utils.js';
 import { isStringboolTrue } from '#utils';
 import * as localProcessor from './processors/local/index.js';
 import * as s3Processor from './processors/s3/index.js';
+import { ComponentType } from '#consts';
 
 const traceBus = new EventEmitter();
 const processors = [
@@ -49,11 +50,15 @@ const serializeDetails = details => details instanceof Error ? serializeError( d
  * @param {object} fields - All the trace fields
  * @returns {void}
  */
-export const addEventPhase = ( phase, { kind, name, id, parentId, details, executionContext } ) =>
-  traceBus.emit( 'entry', {
-    executionContext,
-    entry: { kind, phase, name, id, parentId, phase, timestamp: Date.now(), details: serializeDetails( details ) }
-  } );
+export const addEventPhase = ( phase, { kind, name, id, parentId, details, executionContext } ) => {
+  // Ignores internal steps in the actual trace files
+  if ( kind !== ComponentType.INTERNAL_STEP ) {
+    traceBus.emit( 'entry', {
+      executionContext,
+      entry: { kind, phase, name, id, parentId, phase, timestamp: Date.now(), details: serializeDetails( details ) }
+    } );
+  }
+};
 
 /**
  * Adds an Event Phase, complementing the options with parentId and executionContext from the async storage.

package/src/worker/interceptors/workflow.js

@@ -1,5 +1,5 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { workflowInfo, proxySinks, ApplicationFailure } from '@temporalio/workflow';
+import { workflowInfo, proxySinks, ApplicationFailure, ContinueAsNew } from '@temporalio/workflow';
 import { memoToHeaders } from '../sandboxed_utils.js';
 import { mergeActivityOptions } from '#utils';
 // this is a dynamic generated file with activity configs overwrites
@@ -37,6 +37,13 @@ class WorkflowExecutionInterceptor {
       sinks.trace.addWorkflowEventEnd( output );
       return output;
     } catch ( error ) {
+      /* When the error is ContinueAsNew it represents the point where the actual workflow code was
+      delegated to another run. In this case the result in the traces will be the string below and
+      a new trace file will be generated */
+      if ( error instanceof ContinueAsNew ) {
+        sinks.trace.addWorkflowEventEnd( '<continued_as_new>' );
+        throw error;
+      }
       sinks.trace.addWorkflowEventError( error );
       throw new ApplicationFailure( error.message, error.constructor.name );
     }