@hotmeshio/hotmesh 0.4.0 → 0.4.2

package/build/services/memflow/context.d.ts

@@ -0,0 +1,143 @@
+import { HotMesh } from '../hotmesh';
+import { SearchService } from '../search';
+/**
+ * The Context module provides methods for reading and writing
+ * JSONB data to a workflow's context. The instance methods
+ * exposed by this class are available for use from within
+ * a running workflow.
+ *
+ * @example
+ * ```typescript
+ * //contextWorkflow.ts
+ * import { workflow } from '@hotmeshio/hotmesh';
+ *
+ * export async function contextExample(): Promise<void> {
+ *   const context = await workflow.context();
+ *   await context.set({ user: { id: 123 } });
+ *   await context.merge({ user: { name: "John" } });
+ *   const user = await context.get("user");
+ *   // user = { id: 123, name: "John" }
+ * }
+ * ```
+ */
+export declare class Context {
+    /**
+     * @private
+     */
+    jobId: string;
+    /**
+     * @private
+     */
+    searchSessionId: string;
+    /**
+     * @private
+     */
+    searchSessionIndex: number;
+    /**
+     * @private
+     */
+    hotMeshClient: HotMesh;
+    /**
+     * @private
+     */
+    search: SearchService<any> | null;
+    /**
+     * @private
+     */
+    workflowDimension: string;
+    /**
+     * @private
+     */
+    constructor(workflowId: string, hotMeshClient: HotMesh, searchSessionId: string);
+    /**
+     * increments the index to return a unique search session guid when
+     * calling any method that produces side effects (changes the value)
+     * @private
+     */
+    getSearchSessionGuid(): string;
+    /**
+     * Sets the entire context object. This replaces any existing context.
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.set({ user: { id: 123, name: "John" } });
+     */
+    set(value: any): Promise<any>;
+    /**
+     * Deep merges the provided object with the existing context
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.merge({ user: { email: "john@example.com" } });
+     */
+    merge<T>(value: T): Promise<T>;
+    /**
+     * Gets a value from the context by path
+     *
+     * @example
+     * const context = await workflow.context();
+     * const user = await context.get("user");
+     * const email = await context.get("user.email");
+     */
+    get(path?: string): Promise<any>;
+    /**
+     * Deletes a value from the context by path
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.delete("user.email");
+     */
+    delete(path: string): Promise<any>;
+    /**
+     * Appends a value to an array at the specified path
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.append("items", { id: 1, name: "New Item" });
+     */
+    append(path: string, value: any): Promise<any[]>;
+    /**
+     * Prepends a value to an array at the specified path
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.prepend("items", { id: 0, name: "First Item" });
+     */
+    prepend(path: string, value: any): Promise<any[]>;
+    /**
+     * Removes an item from an array at the specified path and index
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.remove("items", 0); // Remove first item
+     */
+    remove(path: string, index: number): Promise<any[]>;
+    /**
+     * Increments a numeric value at the specified path
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.increment("counter", 5);
+     */
+    increment(path: string, value?: number): Promise<number>;
+    /**
+     * Toggles a boolean value at the specified path
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.toggle("settings.enabled");
+     */
+    toggle(path: string): Promise<boolean>;
+    /**
+     * Sets a value at the specified path only if it doesn't already exist
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.setIfNotExists("user.id", 123);
+     */
+    setIfNotExists(path: string, value: any): Promise<any>;
+    /**
+     * @private
+     */
+    private deepMerge;
+}

package/build/services/memflow/context.js

@@ -0,0 +1,299 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Context = void 0;
+const key_1 = require("../../modules/key");
+const storage_1 = require("../../modules/storage");
+/**
+ * The Context module provides methods for reading and writing
+ * JSONB data to a workflow's context. The instance methods
+ * exposed by this class are available for use from within
+ * a running workflow.
+ *
+ * @example
+ * ```typescript
+ * //contextWorkflow.ts
+ * import { workflow } from '@hotmeshio/hotmesh';
+ *
+ * export async function contextExample(): Promise<void> {
+ *   const context = await workflow.context();
+ *   await context.set({ user: { id: 123 } });
+ *   await context.merge({ user: { name: "John" } });
+ *   const user = await context.get("user");
+ *   // user = { id: 123, name: "John" }
+ * }
+ * ```
+ */
+class Context {
+    /**
+     * @private
+     */
+    constructor(workflowId, hotMeshClient, searchSessionId) {
+        /**
+         * @private
+         */
+        this.searchSessionIndex = 0;
+        const keyParams = {
+            appId: hotMeshClient.appId,
+            jobId: workflowId,
+        };
+        this.jobId = key_1.KeyService.mintKey(hotMeshClient.namespace, key_1.KeyType.JOB_STATE, keyParams);
+        this.searchSessionId = searchSessionId;
+        this.hotMeshClient = hotMeshClient;
+        this.search = hotMeshClient.engine.search;
+        // Get workflow dimension from async local storage
+        const store = storage_1.asyncLocalStorage.getStore();
+        this.workflowDimension = store?.get('workflowDimension') ?? '';
+    }
+    /**
+     * increments the index to return a unique search session guid when
+     * calling any method that produces side effects (changes the value)
+     * @private
+     */
+    getSearchSessionGuid() {
+        return `${this.searchSessionId}-${this.searchSessionIndex++}-`;
+    }
+    /**
+     * Sets the entire context object. This replaces any existing context.
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.set({ user: { id: 123, name: "John" } });
+     */
+    async set(value) {
+        const ssGuid = this.getSearchSessionGuid();
+        const store = storage_1.asyncLocalStorage.getStore();
+        const replay = store?.get('replay') ?? {};
+        if (ssGuid in replay) {
+            return JSON.parse(replay[ssGuid]);
+        }
+        // Use single transactional call to update context and store replay value
+        const result = await this.search.updateContext(this.jobId, {
+            '@context': JSON.stringify(value),
+            [ssGuid]: '', // Pass replay ID to hash module for transactional replay storage
+        });
+        return result || value;
+    }
+    /**
+     * Deep merges the provided object with the existing context
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.merge({ user: { email: "john@example.com" } });
+     */
+    async merge(value) {
+        const ssGuid = this.getSearchSessionGuid();
+        const store = storage_1.asyncLocalStorage.getStore();
+        const replay = store?.get('replay') ?? {};
+        if (ssGuid in replay) {
+            return JSON.parse(replay[ssGuid]);
+        }
+        // Use server-side JSONB merge operation with replay storage
+        const newContext = await this.search.updateContext(this.jobId, {
+            '@context:merge': JSON.stringify(value),
+            [ssGuid]: '', // Pass replay ID to hash module
+        });
+        return newContext;
+    }
+    /**
+     * Gets a value from the context by path
+     *
+     * @example
+     * const context = await workflow.context();
+     * const user = await context.get("user");
+     * const email = await context.get("user.email");
+     */
+    async get(path) {
+        const ssGuid = this.getSearchSessionGuid();
+        const store = storage_1.asyncLocalStorage.getStore();
+        const replay = store?.get('replay') ?? {};
+        if (ssGuid in replay) {
+            // Replay cache stores the already-extracted value, not full context
+            return JSON.parse(replay[ssGuid]);
+        }
+        let value;
+        if (!path) {
+            // No path - fetch entire context with replay storage
+            const result = await this.search.updateContext(this.jobId, {
+                '@context:get': '',
+                [ssGuid]: '', // Pass replay ID to hash module
+            });
+            // setFields returns the actual context value for @context:get operations
+            value = result || {};
+        }
+        else {
+            // Use PostgreSQL JSONB path extraction for specific paths with replay storage
+            const result = await this.search.updateContext(this.jobId, {
+                '@context:get': path,
+                [ssGuid]: '', // Pass replay ID to hash module
+            });
+            // setFields returns the actual path value for @context:get operations
+            value = result;
+        }
+        return value;
+    }
+    /**
+     * Deletes a value from the context by path
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.delete("user.email");
+     */
+    async delete(path) {
+        const ssGuid = this.getSearchSessionGuid();
+        const store = storage_1.asyncLocalStorage.getStore();
+        const replay = store?.get('replay') ?? {};
+        if (ssGuid in replay) {
+            return JSON.parse(replay[ssGuid]);
+        }
+        // Use server-side JSONB delete operation with replay storage
+        const newContext = await this.search.updateContext(this.jobId, {
+            '@context:delete': path,
+            [ssGuid]: '', // Pass replay ID to hash module
+        });
+        return newContext;
+    }
+    /**
+     * Appends a value to an array at the specified path
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.append("items", { id: 1, name: "New Item" });
+     */
+    async append(path, value) {
+        const ssGuid = this.getSearchSessionGuid();
+        const store = storage_1.asyncLocalStorage.getStore();
+        const replay = store?.get('replay') ?? {};
+        if (ssGuid in replay) {
+            return JSON.parse(replay[ssGuid]);
+        }
+        // Use server-side JSONB array append operation with replay storage
+        const newArray = await this.search.updateContext(this.jobId, {
+            '@context:append': JSON.stringify({ path, value }),
+            [ssGuid]: '', // Pass replay ID to hash module
+        });
+        return newArray;
+    }
+    /**
+     * Prepends a value to an array at the specified path
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.prepend("items", { id: 0, name: "First Item" });
+     */
+    async prepend(path, value) {
+        const ssGuid = this.getSearchSessionGuid();
+        const store = storage_1.asyncLocalStorage.getStore();
+        const replay = store?.get('replay') ?? {};
+        if (ssGuid in replay) {
+            return JSON.parse(replay[ssGuid]);
+        }
+        // Use server-side JSONB array prepend operation with replay storage
+        const newArray = await this.search.updateContext(this.jobId, {
+            '@context:prepend': JSON.stringify({ path, value }),
+            [ssGuid]: '', // Pass replay ID to hash module
+        });
+        return newArray;
+    }
+    /**
+     * Removes an item from an array at the specified path and index
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.remove("items", 0); // Remove first item
+     */
+    async remove(path, index) {
+        const ssGuid = this.getSearchSessionGuid();
+        const store = storage_1.asyncLocalStorage.getStore();
+        const replay = store?.get('replay') ?? {};
+        if (ssGuid in replay) {
+            return JSON.parse(replay[ssGuid]);
+        }
+        // Use server-side JSONB array remove operation with replay storage
+        const newArray = await this.search.updateContext(this.jobId, {
+            '@context:remove': JSON.stringify({ path, index }),
+            [ssGuid]: '', // Pass replay ID to hash module
+        });
+        return newArray;
+    }
+    /**
+     * Increments a numeric value at the specified path
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.increment("counter", 5);
+     */
+    async increment(path, value = 1) {
+        const ssGuid = this.getSearchSessionGuid();
+        const store = storage_1.asyncLocalStorage.getStore();
+        const replay = store?.get('replay') ?? {};
+        if (ssGuid in replay) {
+            return JSON.parse(replay[ssGuid]);
+        }
+        // Use server-side JSONB increment operation with replay storage
+        const newValue = await this.search.updateContext(this.jobId, {
+            '@context:increment': JSON.stringify({ path, value }),
+            [ssGuid]: '', // Pass replay ID to hash module
+        });
+        return Number(newValue);
+    }
+    /**
+     * Toggles a boolean value at the specified path
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.toggle("settings.enabled");
+     */
+    async toggle(path) {
+        const ssGuid = this.getSearchSessionGuid();
+        const store = storage_1.asyncLocalStorage.getStore();
+        const replay = store?.get('replay') ?? {};
+        if (ssGuid in replay) {
+            return JSON.parse(replay[ssGuid]);
+        }
+        // Use server-side JSONB toggle operation with replay storage
+        const newValue = await this.search.updateContext(this.jobId, {
+            '@context:toggle': path,
+            [ssGuid]: '', // Pass replay ID to hash module
+        });
+        return Boolean(newValue);
+    }
+    /**
+     * Sets a value at the specified path only if it doesn't already exist
+     *
+     * @example
+     * const context = await workflow.context();
+     * await context.setIfNotExists("user.id", 123);
+     */
+    async setIfNotExists(path, value) {
+        const ssGuid = this.getSearchSessionGuid();
+        const store = storage_1.asyncLocalStorage.getStore();
+        const replay = store?.get('replay') ?? {};
+        if (ssGuid in replay) {
+            return JSON.parse(replay[ssGuid]);
+        }
+        // Use server-side JSONB conditional set operation with replay storage
+        const newValue = await this.search.updateContext(this.jobId, {
+            '@context:setIfNotExists': JSON.stringify({ path, value }),
+            [ssGuid]: '', // Pass replay ID to hash module
+        });
+        return newValue;
+    }
+    /**
+     * @private
+     */
+    deepMerge(target, source) {
+        if (!source)
+            return target;
+        const output = { ...target };
+        Object.keys(source).forEach(key => {
+            if (source[key] instanceof Object && key in target) {
+                output[key] = this.deepMerge(target[key], source[key]);
+            }
+            else {
+                output[key] = source[key];
+            }
+        });
+        return output;
+    }
+}
+exports.Context = Context;

package/build/services/memflow/exporter.d.ts

@@ -0,0 +1,51 @@
+import { ILogger } from '../logger';
+import { StoreService } from '../store';
+import { ExportOptions, MemFlowJobExport, TimelineType, TransitionType, ExportFields } from '../../types/exporter';
+import { ProviderClient, ProviderTransaction } from '../../types/provider';
+import { StringStringType, Symbols } from '../../types/serializer';
+declare class ExporterService {
+    appId: string;
+    logger: ILogger;
+    store: StoreService<ProviderClient, ProviderTransaction>;
+    symbols: Promise<Symbols> | Symbols;
+    private static symbols;
+    constructor(appId: string, store: StoreService<ProviderClient, ProviderTransaction>, logger: ILogger);
+    /**
+     * Convert the job hash from its compiles format into a MemFlowJobExport object with
+     * facets that describe the workflow in terms relevant to narrative storytelling.
+     */
+    export(jobId: string, options?: ExportOptions): Promise<MemFlowJobExport>;
+    /**
+     * Inflates the job data from Redis into a MemFlowJobExport object
+     * @param jobHash - the job data from Redis
+     * @param dependencyList - the list of dependencies for the job
+     * @returns - the inflated job data
+     */
+    inflate(jobHash: StringStringType, options: ExportOptions): MemFlowJobExport;
+    resolveValue(raw: string, withValues: boolean): Record<string, any> | string | number | null;
+    /**
+     * Inflates the key from Redis, 3-character symbol
+     * into a human-readable JSON path, reflecting the
+     * tree-like structure of the unidimensional Hash
+     * @private
+     */
+    inflateKey(key: string): string;
+    filterFields(fullObject: MemFlowJobExport, block?: ExportFields[], allow?: ExportFields[]): Partial<MemFlowJobExport>;
+    inflateTransition(match: RegExpMatchArray, value: string, transitionsObject: Record<string, TransitionType>): void;
+    sortEntriesByCreated(obj: {
+        [key: string]: TransitionType;
+    }): TransitionType[];
+    /**
+     * marker names are overloaded with details like sequence, type, etc
+     */
+    keyToObject(key: string): {
+        index: number;
+        dimension?: string;
+        secondary?: number;
+    };
+    /**
+     * idem list has a complicated sort order based on indexes and dimensions
+     */
+    sortParts(parts: TimelineType[]): TimelineType[];
+}
+export { ExporterService };