@fsai-flow/workflow 0.0.1

package/src/lib/WorkflowHooks.ts

@@ -0,0 +1,51 @@
+// eslint-disable-next-line import/no-cycle
+import {
+	IWorkflowBase,
+	IWorkflowExecuteHooks,
+	IWorkflowHooksOptionalParameters,
+	WorkflowExecuteMode,
+} from './Interfaces';
+
+export class WorkflowHooks {
+	mode: WorkflowExecuteMode;
+
+	workflowData: IWorkflowBase;
+
+	executionId: string;
+
+	sessionId?: string;
+
+	retryOf?: string;
+
+	hookFunctions: IWorkflowExecuteHooks;
+
+	constructor(
+		hookFunctions: IWorkflowExecuteHooks,
+		mode: WorkflowExecuteMode,
+		executionId: string,
+		workflowData: IWorkflowBase,
+		optionalParameters?: IWorkflowHooksOptionalParameters,
+	) {
+		// eslint-disable-next-line no-param-reassign, @typescript-eslint/prefer-nullish-coalescing
+		optionalParameters = optionalParameters || {};
+
+		this.hookFunctions = hookFunctions;
+		this.mode = mode;
+		this.executionId = executionId;
+		this.workflowData = workflowData;
+		this.sessionId = optionalParameters.sessionId;
+		this.retryOf = optionalParameters.retryOf;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+	async executeHookFunctions(hookName: string, parameters: any[]) {
+		// tslint:disable-line:no-any
+		if (this.hookFunctions[hookName] !== undefined && Array.isArray(this.hookFunctions[hookName])) {
+			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion, no-restricted-syntax
+			for (const hookFunction of this.hookFunctions[hookName]!) {
+				// eslint-disable-next-line no-await-in-loop
+				await hookFunction.apply(this, parameters);
+			}
+		}
+	}
+}

package/src/lib/errors/base/base.error.ts

@@ -0,0 +1,68 @@
+import type { Event } from '@sentry/node';
+import callsites from 'callsites';
+
+import type { ErrorTags, ErrorLevel, ReportingOptions } from '../error.types';
+
+export type BaseErrorOptions = { description?: undefined | null } & ErrorOptions & ReportingOptions;
+
+interface ErrorOptions {
+    cause?: unknown;
+}
+
+/**
+ * Base class for all errors
+ */
+export abstract class BaseError extends Error {
+	/**
+	 * Error level. Defines which level the error should be logged/reported
+	 * @default 'error'
+	 */
+	level: ErrorLevel;
+
+	/**
+	 * Whether the error should be reported to Sentry.
+	 * @default true
+	 */
+	readonly shouldReport: boolean;
+
+	readonly description: string | null | undefined;
+
+	readonly tags: ErrorTags;
+
+	readonly extra?: Event['extra'];
+
+	readonly packageName?: string;
+
+	readonly cause?: unknown;
+
+	constructor(
+		message: string,
+		{
+			level = 'error',
+			description,
+			shouldReport,
+			tags = {},
+			extra,
+			...rest
+		}: BaseErrorOptions = {},
+	) {
+		super(message);
+		
+		if (rest.cause !== undefined) {
+			this.cause = rest.cause;
+		}
+
+		this.level = level;
+		this.shouldReport = shouldReport ?? (level === 'error' || level === 'fatal');
+		this.description = description;
+		this.tags = tags;
+		this.extra = extra;
+
+		try {
+			const filePath = callsites()[2].getFileName() ?? '';
+			const match = /packages\/([^\/]+)\//.exec(filePath)?.[1];
+
+			if (match) this.tags['packageName'] = match;
+		} catch {}
+	}
+}

package/src/lib/errors/base/operational.error.ts

@@ -0,0 +1,21 @@
+import type { BaseErrorOptions } from './base.error';
+import { BaseError } from './base.error';
+
+export type OperationalErrorOptions = Omit<BaseErrorOptions, 'level'> & {
+	level?: 'info' | 'warning' | 'error';
+};
+
+/**
+ * Error that indicates a transient issue, like a network request failing,
+ * a database query timing out, etc. These are expected to happen, are
+ * transient by nature and should be handled gracefully.
+ *
+ * Default level: warning
+ */
+export class OperationalError extends BaseError {
+	constructor(message: string, opts: OperationalErrorOptions = {}) {
+		opts.level = opts.level ?? 'warning';
+
+		super(message, opts);
+	}
+}

package/src/lib/errors/error.types.ts

@@ -0,0 +1,14 @@
+import type { Event } from '@sentry/node';
+
+export type ErrorLevel = 'fatal' | 'error' | 'warning' | 'info';
+
+export type ErrorTags = NonNullable<Event['tags']>;
+
+export type ReportingOptions = {
+	/** Whether the error should be reported to Sentry */
+	shouldReport?: boolean;
+	level?: ErrorLevel;
+	tags?: ErrorTags;
+	extra?: Event['extra'];
+	executionId?: string;
+};

package/src/lib/errors/index.ts

@@ -0,0 +1 @@
+export { OperationalError, type OperationalErrorOptions } from './base/operational.error';

package/src/lib/result.ts

@@ -0,0 +1,34 @@
+export type ResultOk<T> = { ok: true; result: T };
+export type ResultError<E> = { ok: false; error: E };
+export type Result<T, E> = ResultOk<T> | ResultError<E>;
+
+export const createResultOk = <T>(data: T): ResultOk<T> => ({
+	ok: true,
+	result: data,
+});
+
+export const createResultError = <E = unknown>(error: E): ResultError<E> => ({
+	ok: false,
+	error,
+});
+
+export function ensureError(error: unknown): Error {
+	return error instanceof Error
+		? error
+		: new Error('Error that was not an instance of Error was thrown, cause: ' + error);
+}
+
+/**
+ * Executes the given function and converts it to a Result object.
+ *
+ * @example
+ * const result = toResult(() => fs.writeFileSync('file.txt', 'Hello, World!'));
+ */
+export const toResult = <T, E extends Error = Error>(fn: () => T): Result<T, E> => {
+	try {
+		return createResultOk<T>(fn());
+	} catch (e) {
+		const error = ensureError(e);
+		return createResultError<E>(error as E);
+	}
+};

package/src/lib/utils.ts

@@ -0,0 +1,132 @@
+import {
+	parse as esprimaParse,
+	Syntax,
+	type Node as SyntaxNode,
+	type ExpressionStatement,
+} from 'esprima-next';
+import type { IDisplayOptions, INodeProperties } from './Interfaces';
+import { merge } from 'lodash';
+
+export function updateDisplayOptions(
+	displayOptions: IDisplayOptions,
+	properties: INodeProperties[],
+) {
+	return properties.map((nodeProperty) => {
+		return {
+			...nodeProperty,
+			displayOptions: merge({}, nodeProperty.displayOptions, displayOptions),
+		};
+	});
+}
+export function randomInt(max: number): number;
+export function randomInt(min: number, max: number): number;
+/**
+ * Generates a random integer within a specified range.
+ *
+ * @param {number} min - The lower bound of the range. If `max` is not provided, this value is used as the upper bound and the lower bound is set to 0.
+ * @param {number} [max] - The upper bound of the range, not inclusive.
+ * @returns {number} A random integer within the specified range.
+ */
+export function randomInt(min: number, max?: number): number {
+	if (max === undefined) {
+		max = min;
+		min = 0;
+	}
+	return min + (crypto.getRandomValues(new Uint32Array(1))[0] % (max - min));
+}
+type MutuallyExclusive<T, U> =
+	| (T & { [k in Exclude<keyof U, keyof T>]?: never })
+	| (U & { [k in Exclude<keyof T, keyof U>]?: never });
+
+type JSONParseOptions<T> = { acceptJSObject?: boolean } & MutuallyExclusive<
+	{ errorMessage?: string },
+	{ fallbackValue?: T }
+>;
+
+export const jsonParse = <T>(jsonString: string, options?: JSONParseOptions<T>): T => {
+	try {
+		return JSON.parse(jsonString) as T;
+	} catch (error) {
+		if (options?.acceptJSObject) {
+			try {
+				const jsonStringCleaned = parseJSObject(jsonString);
+				return jsonStringCleaned as T;
+			} catch (e) {
+				// Ignore this error and return the original error or the fallback value
+			}
+		}
+		if (options?.fallbackValue !== undefined) {
+			if (options.fallbackValue instanceof Function) {
+				return options.fallbackValue();
+			}
+			return options.fallbackValue;
+		} else if (options?.errorMessage) {
+			// TODO REFACTOR: Use ApplicationError from offical @fsai-flow/workflow repo
+			throw new Error(options.errorMessage);
+		}
+
+		throw error;
+	}
+};
+
+type JSONStringifyOptions = {
+	replaceCircularRefs?: boolean;
+};
+
+export const replaceCircularReferences = <T>(value: T, knownObjects = new WeakSet()): T => {
+	if (typeof value !== 'object' || value === null || value instanceof RegExp) return value;
+	if ('toJSON' in value && typeof value.toJSON === 'function') return value.toJSON() as T;
+	if (knownObjects.has(value)) return '[Circular Reference]' as T;
+	knownObjects.add(value);
+	const copy = (Array.isArray(value) ? [] : {}) as T;
+	for (const key in value) {
+		copy[key] = replaceCircularReferences(value[key], knownObjects);
+	}
+	knownObjects.delete(value);
+	return copy;
+};
+
+export const jsonStringify = (obj: unknown, options: JSONStringifyOptions = {}): string => {
+	return JSON.stringify(options?.replaceCircularRefs ? replaceCircularReferences(obj) : obj);
+};
+
+function syntaxNodeToValue(expression?: SyntaxNode | null): unknown {
+	switch (expression?.type) {
+		case Syntax.ObjectExpression:
+			return Object.fromEntries(
+				expression.properties
+					.filter((prop) => prop.type === Syntax.Property)
+					.map(({ key, value }) => [syntaxNodeToValue(key), syntaxNodeToValue(value)]),
+			);
+		case Syntax.Identifier:
+			return expression.name;
+		case Syntax.Literal:
+			return expression.value;
+		case Syntax.ArrayExpression:
+			return expression.elements.map((exp) => syntaxNodeToValue(exp));
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Parse any JavaScript ObjectExpression, including:
+ * - single quoted keys
+ * - unquoted keys
+ */
+function parseJSObject(objectAsString: string): object {
+	const jsExpression = esprimaParse(`(${objectAsString})`).body.find(
+		(node): node is ExpressionStatement =>
+			node.type === Syntax.ExpressionStatement && node.expression.type === Syntax.ObjectExpression,
+	);
+
+	return syntaxNodeToValue(jsExpression?.expression) as object;
+}
+
+/**
+ * Checks if a value is an object with a specific key and provides a type guard for the key.
+ */
+export function hasKey<T extends PropertyKey>(value: unknown, key: T): value is Record<T, unknown> {
+	return value !== null && typeof value === 'object' && value.hasOwnProperty(key);
+}
+