feat: add @memoize decorator with expiration and handler options

Added `@memoize` decorator for caching result of calls with identical input:
- Prevents redundant calls using `executeMemoize`.
- Supports configurable expiration and memoization tracking.

The expiration is capped at 1000ms for efficiency and to avoid unnecessary memory usage.

Author: tabkram

src/common/models/executionMemoization.model.ts

@@ -0,0 +1,22 @@
+export const memoizationKey = Symbol('execution-engine/memoize');
+
+/** Default expiration that ensures multiple rapid calls can reuse the stored result */
+export const memoizationDefaultExpirationMs = 100;
+/** Maximum allowable expiration time Prevent excessive retention */
+export const memoizationMaxExpirationMs = 1000;
+
+export type MemoizationHandler<O> = (info: { isMemoized: boolean; callId: string; functionId: string; value?: Promise<O> | O; }) => void;
+
+export interface MemoizeOptions<O> {
+  /** Unique identifier for the function being memoized */
+  functionId: string;
+
+  /**
+   * Optional expiration time in milliseconds for the cached result.
+   * Default is 100ms, capped at 1000ms to prevent excessive retention.
+   */
+  expirationMs?: number;
+
+  /** Custom handler for memoization logic */
+  memoizationHandler?: MemoizationHandler<O>;
+}

src/common/utils/crypto.spec.ts

@@ -0,0 +1,29 @@
+import { generateHashId } from './crypto';
+
+describe('generateUniqueId', () => {
+  it('generates a unique hash for given inputs', () => {
+    const id1 = generateHashId('test', 123, { key: 'value' });
+    const id2 = generateHashId('test', 123, { key: 'value' });
+
+    expect(id1).toBe(id2);
+  });
+
+  it('generates different hashes for different inputs', () => {
+    const id1 = generateHashId('test1');
+    const id2 = generateHashId('test2');
+
+    expect(id1).not.toBe(id2);
+  });
+
+  it('handles empty input', () => {
+    const id1 = generateHashId();
+    const id2 = generateHashId();
+
+    expect(id1).toBe(id2);
+  });
+
+  it('creates a 64-character hash', () => {
+    const id = generateHashId('sample');
+    expect(id).toHaveLength(64);
+  });
+});

src/common/utils/crypto.ts

@@ -0,0 +1,11 @@
+import { createHash } from 'crypto';
+
+/**
+ * Generates a SHA-256 hash ID from the given inputs.
+ *
+ * @param inputs - Values to hash.
+ * @returns A 64-character hex string.
+ */
+export function generateHashId(...inputs: unknown[]): string {
+  return createHash('sha256').update(JSON.stringify(inputs)).digest('hex');
+}

src/execution/memoize.ts

@@ -0,0 +1,74 @@
+import { execute } from './execute';
+import {
+  memoizationDefaultExpirationMs,
+  memoizationKey,
+  memoizationMaxExpirationMs,
+  MemoizeOptions
+} from '../common/models/executionMemoization.model';
+import { generateHashId } from '../common/utils/crypto';
+
+export function executeMemoize<O>(
+  blockFunction: (...params: unknown[]) => Promise<O>,
+  inputs?: Array<unknown>,
+  options?: MemoizeOptions<O>
+): Promise<Awaited<O>>;
+
+export function executeMemoize<O>(
+  blockFunction: (...params: unknown[]) => O,
+  inputs?: Array<unknown>,
+  options?: MemoizeOptions<O>
+): O;
+
+
+/**
+ * Executes a function with memoization to prevent redundant executions.
+ * The result is stored temporarily and cleared after a short delay.
+ *
+ * @param blockFunction - The function to execute and memoize.
+ * @param inputs - Arguments used to generate a unique memoization key.
+ * @param options - Additional options including a unique function identifier.
+ * @param options.expirationMs - Duration (in milliseconds) before clearing the stored result,
+ *                                capped at 1000ms to prevent excessive retention.
+ * @param options.memoizationHandler - Optional callback triggered after checking memoization memory.
+ * @returns The memoized result or a newly computed value.
+ *
+ * @remarks
+ * The JavaScript engine may clear the memoized value before another call retrieves it.
+ * A short delay (e.g., 100ms) ensures that multiple rapid calls can reuse the stored result.
+ * The expiration is capped at 1000ms for efficiency and to avoid unnecessary memory usage.
+ */
+export function executeMemoize<O>(
+  blockFunction: (...params: unknown[]) => O | Promise<O>,
+  inputs: Array<unknown> = [],
+  options: MemoizeOptions<O>
+): Promise<O> | O {
+  const expirationMs = Math.min(options.expirationMs ?? memoizationDefaultExpirationMs, memoizationMaxExpirationMs); // Default short delay and Prevent excessive retention
+  const memoizationFullStore: Map<string, Map<string, Promise<O> | O>> = this[memoizationKey] ??= new Map<string, Map<string, Promise<O> | O>>();
+  const memoizationStore = memoizationFullStore.get(options.functionId) ?? new Map<string, Promise<O> | O>();
+  const callId = generateHashId(...inputs);
+  const memoizedValue = memoizationStore.get(callId);
+
+  if (typeof options.memoizationHandler === 'function') {
+    options.memoizationHandler({ functionId: options.functionId, callId, isMemoized: !!memoizedValue, value: memoizedValue });
+  }
+
+  if (memoizedValue) {
+    return memoizedValue;
+  } else {
+    const callResponseOrPromise = (execute.bind(this) as typeof execute)(
+      blockFunction.bind(this) as typeof blockFunction,
+      inputs
+    );
+    memoizationStore.set(callId, callResponseOrPromise);
+    this[memoizationKey].set(options.functionId, memoizationStore);
+
+    if (callResponseOrPromise instanceof Promise) {
+      callResponseOrPromise.finally(() =>
+        setTimeout(() => memoizationStore.delete(callId), expirationMs)
+      );
+    } else {
+      setTimeout(() => memoizationStore.delete(callId), expirationMs);
+    }
+    return callResponseOrPromise;
+  }
+}

src/execution/memoizeDecorator.spec.ts

@@ -0,0 +1,74 @@
+import { memoize } from './memoizeDecorator';
+
+describe('memoize decorator', () => {
+  it('should memoize Fibonacci results and prevent redundant function calls', async () => {
+    let memoizationCheckCount = 0;
+    let memoizedCalls = 0;
+    let totalFunctionCalls = 0;
+
+    class Calculator {
+      @memoize(({ isMemoized }) => {
+        memoizationCheckCount++;
+        if (isMemoized) {
+          memoizedCalls++;
+        }
+      })
+      fibonacci(n: number): number {
+        totalFunctionCalls++;
+        if (n <= 1) {
+          return n;
+        }
+        return this.fibonacci(n - 1) + this.fibonacci(n - 2);
+      }
+    }
+
+
+    const calculator = new Calculator();
+    memoizationCheckCount = 0;
+    memoizedCalls = 0;
+    totalFunctionCalls = 0;
+    const fib3 = calculator.fibonacci(3);
+    expect(memoizedCalls).toBe(0);
+    expect(totalFunctionCalls).toBe(5); // fib(3) = (fib(2) = fib(1) + fib(0)) + fib(1)
+    expect(memoizationCheckCount).toEqual(totalFunctionCalls + memoizedCalls);
+    expect(fib3).toBe(2);
+
+    memoizationCheckCount = 0;
+    memoizedCalls = 0;
+    totalFunctionCalls = 0;
+    // first call:
+    const fib50_1 = calculator.fibonacci(50);
+    expect(memoizedCalls).toBeGreaterThan(0);
+    expect(totalFunctionCalls).toBeLessThan(1274); // 1274 calls for fibonacci(50) if all exist
+    expect(memoizationCheckCount).toEqual(totalFunctionCalls + memoizedCalls);
+    expect(fib50_1).toBe(12586269025);
+    const memoizedCallsAfterFirstCall = memoizedCalls;
+    const totalFunctionCallsAfterFirstCall = totalFunctionCalls;
+
+    // second call:
+    const fib50_2 = calculator.fibonacci(50);
+    expect(memoizedCalls).toBe(memoizedCallsAfterFirstCall + 1); // a new get of memoized fib50
+    expect(totalFunctionCalls).toBe(totalFunctionCallsAfterFirstCall); // no new call, fib50 is memoized
+    expect(memoizationCheckCount).toEqual(totalFunctionCalls + memoizedCalls);
+    expect(fib50_2).toBe(12586269025);
+
+
+    memoizationCheckCount = 0;
+    memoizedCalls = 0;
+    totalFunctionCalls = 0;
+    const fib51 = calculator.fibonacci(51);
+    expect(totalFunctionCalls).toBe(1); // we need 1 extra call to get fibonacci of 51 as we did fibonacci(50)
+    expect(memoizedCalls).toBe(2); // yes fib(51-1) and fib(51-2) are memoized
+    expect(memoizationCheckCount).toBe(3); // 2memoized and 1 call
+    expect(fib51).toBe(20365011074);
+
+    memoizationCheckCount = 0;
+    memoizedCalls = 0;
+    totalFunctionCalls = 0;
+    const fib5 = calculator.fibonacci(6);
+    expect(totalFunctionCalls).toBe(0); // no need for extra call to get fibonacci of 5 as we did fibonacci(50)
+    expect(memoizedCalls).toBe(1); // yes fib(5) is memoized implicitly
+    expect(memoizationCheckCount).toBe(1); // 1memoized
+    expect(fib5).toBe(8);
+  });
+});

src/execution/memoizeDecorator.ts

@@ -0,0 +1,28 @@
+import { executeMemoize } from './memoize';
+import { MemoizationHandler } from '../common/models/executionMemoization.model';
+
+/**
+ * Decorator to memoize method executions and prevent redundant calls.
+ *
+ * @param memoizationHandler - Optional callback triggered after checking memory
+ * @param expirationMs  - Duration (in milliseconds) before clearing the stored result,
+ *                                capped at 1000ms to prevent excessive retention.
+ * @returns A method decorator for applying memoization.
+ *
+ * @remarks
+ * Uses `executeMemoize` internally to store and reuse results.
+ * A short delay (e.g., 100ms) ensures that multiple rapid calls can reuse the stored result.
+ */
+export function memoize<O>(memoizationHandler?: MemoizationHandler<O>, expirationMs?: number): MethodDecorator {
+  return function <T extends Record<string, unknown>>(target: T, propertyKey: string, descriptor: PropertyDescriptor) {
+    const originalMethod = descriptor.value;
+    descriptor.value = function(...args: unknown[]): ReturnType<typeof originalMethod> {
+      const functionSignature = `${target.constructor.name}.${propertyKey}(${descriptor.value.length})`;
+      return (executeMemoize.bind(this) as typeof executeMemoize<Promise<Awaited<O>> | O>)(
+        originalMethod.bind(this),
+        args,
+        { functionId: functionSignature, memoizationHandler, expirationMs }
+      );
+    };
+  };
+}

src/index.ts

@@ -7,12 +7,15 @@ export * from './common/models/engineNodeData.model';
 export * from './common/models/engineTrace.model';
 export * from './common/models/engineTraceOptions.model';
 export * from './common/models/executionFunction.model';
+export * from './common/models/executionMemoization.model';
 export * from './common/models/executionTrace.model';
 export * from './common/models/timer.model';
 export * from './engine/executionEngine';
 export * from './engine/executionEngineDecorators';
 export * from './engine/traceableEngine';
 export * from './execution/execute';
+export * from './execution/memoize';
+export * from './execution/memoizeDecorator';
 export * from './timer/executionTimer';
 export * from './trace/trace';
 export * from './trace/traceDecorator';