@hotmeshio/hotmesh 0.4.0 → 0.4.2

package/build/modules/utils.js

@@ -0,0 +1,374 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.arrayToHash = exports.isStreamMessage = exports.parseStreamMessage = exports.s = exports.isValidCron = exports.restoreHierarchy = exports.getValueByPath = exports.getIndexedHash = exports.getSymVal = exports.getSymKey = exports.formatISODate = exports.getTimeSeries = exports.getSubscriptionTopic = exports.findSubscriptionForTrigger = exports.findTopKey = exports.matchesStatus = exports.matchesStatusCode = exports.polyfill = exports.identifyProvider = exports.XSleepFor = exports.sleepImmediate = exports.sleepFor = exports.guid = exports.deterministicRandom = exports.deepCopy = exports.getSystemHealth = exports.hashOptions = void 0;
+const os_1 = __importDefault(require("os"));
+const crypto_1 = require("crypto");
+const nanoid_1 = require("nanoid");
+const ms_1 = __importDefault(require("ms"));
+const logger_1 = require("../services/logger");
+const enums_1 = require("./enums");
+const logger = new logger_1.LoggerService('hotmesh', 'utils');
+/**
+ * @private
+ */
+const hashOptions = (options) => {
+    const str = JSON.stringify(options);
+    return (0, crypto_1.createHash)('sha256').update(str).digest('hex');
+};
+exports.hashOptions = hashOptions;
+async function getSystemHealth() {
+    const totalMemory = os_1.default.totalmem();
+    const freeMemory = os_1.default.freemem();
+    const usedMemory = totalMemory - freeMemory;
+    const systemHealth = {
+        TotalMemoryGB: `${(totalMemory / 1024 / 1024 / 1024).toFixed(2)} GB`,
+        FreeMemoryGB: `${(freeMemory / 1024 / 1024 / 1024).toFixed(2)} GB`,
+        UsedMemoryGB: `${(usedMemory / 1024 / 1024 / 1024).toFixed(2)} GB`,
+        CPULoad: [],
+        NetworkStats: [],
+    };
+    return systemHealth;
+}
+exports.getSystemHealth = getSystemHealth;
+function deepCopy(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+exports.deepCopy = deepCopy;
+function deterministicRandom(seed) {
+    const x = Math.sin(seed) * 10000;
+    return x - Math.floor(x);
+}
+exports.deterministicRandom = deterministicRandom;
+function guid(size = enums_1.HMSH_GUID_SIZE) {
+    return `H` + (0, nanoid_1.nanoid)(size);
+}
+exports.guid = guid;
+async function sleepFor(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+exports.sleepFor = sleepFor;
+function sleepImmediate() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+exports.sleepImmediate = sleepImmediate;
+function XSleepFor(ms) {
+    //can be interrupted with `clearTimeout`
+    let timerId;
+    const promise = new Promise((resolve) => {
+        timerId = setTimeout(resolve, ms);
+    });
+    return { promise, timerId };
+}
+exports.XSleepFor = XSleepFor;
+/**
+ * Identies the provider type based on the provider object. Customers may
+ * explicitly set the provider type in the configuration. But this is a
+ * convenience method to automatically identify the provider type.
+ * @private
+ */
+function identifyProvider(provider) {
+    const prototype = Object.getPrototypeOf(provider);
+    if (provider.Query?.prototype ||
+        Object.keys(provider).includes('database') ||
+        prototype.name === 'Pool') {
+        return 'postgres';
+    }
+    else if (provider.toString().toLowerCase().includes('nats')) {
+        return 'nats';
+    }
+    else if ('defineCommand' in prototype ||
+        Object.keys(prototype).includes('multi')) {
+        return 'ioredis';
+    }
+    else if (Object.keys(prototype).includes('Multi')) {
+        return 'redis';
+    }
+    if (provider.constructor) {
+        if (provider.constructor.name === 'Redis' ||
+            provider.constructor.name === 'EventEmitter') {
+            if ('hset' in provider) {
+                return 'ioredis';
+            }
+        }
+        else if (provider.constructor.name === 'ProviderClient' ||
+            provider.constructor.name === 'Commander') {
+            if ('HSET' in provider) {
+                return 'redis';
+            }
+        }
+    }
+    let type = null;
+    if (Object.keys(provider).includes('connection') ||
+        !isNaN(provider.totalCount) && !isNaN(provider.idleCount)) {
+        type = 'postgres';
+    }
+    else if (Object.keys(provider).includes('Pipeline')) {
+        type = 'ioredis';
+    }
+    else if (Object.keys(provider).includes('createClient')) {
+        type = 'redis';
+    }
+    else if (prototype.constructor.toString().includes('NatsConnectionImpl')) {
+        type = 'nats';
+    }
+    return type;
+}
+exports.identifyProvider = identifyProvider;
+/**
+ * @private
+ */
+exports.polyfill = {
+    /**
+     * `redis` is deprecated; `connection` is the generic replacement
+     */
+    providerConfig(obj) {
+        return obj?.connection ?? obj?.redis ?? obj?.connections;
+    },
+    /**
+     * NOTE: `redisClass and redisOptions` input parameters are deprecated; use `connection` for all configuration inputs
+     */
+    meshDataConfig(obj) {
+        return { ...obj.connection };
+    },
+};
+/**
+ * @private
+ */
+function matchesStatusCode(code, pattern) {
+    if (typeof pattern === 'string') {
+        // Convert '*' wildcard to its regex equivalent (\d)
+        const regexPattern = `^${pattern.replace(/\*/g, '\\d')}$`;
+        return new RegExp(regexPattern).test(code.toString());
+    }
+    return pattern.test(code.toString());
+}
+exports.matchesStatusCode = matchesStatusCode;
+/**
+ * @private
+ */
+function matchesStatus(status, targetStatus) {
+    return status === targetStatus;
+}
+exports.matchesStatus = matchesStatus;
+/**
+ * @private
+ */
+function findTopKey(obj, input) {
+    for (const [key, value] of Object.entries(obj)) {
+        if (value.hasOwnProperty(input)) {
+            const parentKey = findTopKey(obj, key.replace(/^\./, ''));
+            return (parentKey || key).replace(/^\./, '');
+        }
+    }
+    return null;
+}
+exports.findTopKey = findTopKey;
+/**
+ * @private
+ */
+function findSubscriptionForTrigger(obj, value) {
+    for (const [key, itemValue] of Object.entries(obj)) {
+        if (itemValue === value) {
+            return key;
+        }
+    }
+    return null;
+}
+exports.findSubscriptionForTrigger = findSubscriptionForTrigger;
+/**
+ * Get the subscription topic for the flow to which activityId belongs.
+ * @private
+ */
+async function getSubscriptionTopic(activityId, store, appVID) {
+    const appTransitions = await store.getTransitions(appVID);
+    const appSubscriptions = await store.getSubscriptions(appVID);
+    const triggerId = findTopKey(appTransitions, activityId);
+    const topic = findSubscriptionForTrigger(appSubscriptions, triggerId);
+    return topic;
+}
+exports.getSubscriptionTopic = getSubscriptionTopic;
+/**
+ * returns the 12-digit format of the iso timestamp (e.g, 202101010000); returns
+ * an empty string if overridden by the user to not segment by time (infinity).
+ * @private
+ */
+function getTimeSeries(granularity) {
+    if (granularity.toString() === 'infinity') {
+        return '0';
+    }
+    const now = new Date();
+    const granularityUnit = granularity.slice(-1);
+    const granularityValue = parseInt(granularity.slice(0, -1), 10);
+    if (granularityUnit === 'm') {
+        const minute = Math.floor(now.getMinutes() / granularityValue) * granularityValue;
+        now.setUTCMinutes(minute, 0, 0);
+    }
+    else if (granularityUnit === 'h') {
+        now.setUTCMinutes(0, 0, 0);
+    }
+    return now
+        .toISOString()
+        .replace(/:\d\d\..+|-|T/g, '')
+        .replace(':', '');
+}
+exports.getTimeSeries = getTimeSeries;
+/**
+ * @private
+ */
+function formatISODate(input) {
+    const date = input instanceof Date ? input : new Date(input);
+    return date.toISOString().replace(/[:TZ-]/g, '');
+}
+exports.formatISODate = formatISODate;
+/**
+ * @private
+ */
+function getSymKey(number) {
+    const alphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+    const base = alphabet.length;
+    if (number < 0 || number >= Math.pow(base, 3)) {
+        throw new Error('Number out of range');
+    }
+    const [q1, r1] = divmod(number, base);
+    const [q2, r2] = divmod(q1, base);
+    return alphabet[q2] + alphabet[r1] + alphabet[r2];
+}
+exports.getSymKey = getSymKey;
+/**
+ * @private
+ */
+function getSymVal(number) {
+    const alphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+    const base = alphabet.length;
+    if (number < 0 || number >= Math.pow(base, 2)) {
+        throw new Error('Number out of range');
+    }
+    const [q, r] = divmod(number, base);
+    return alphabet[q] + alphabet[r];
+}
+exports.getSymVal = getSymVal;
+/**
+ * @private
+ */
+function divmod(m, n) {
+    return [Math.floor(m / n), m % n];
+}
+/**
+ * @private
+ */
+function getIndexedHash(hash, target) {
+    const index = hash[target] || 0;
+    const newHash = { ...hash };
+    delete newHash[target];
+    return [index, newHash];
+}
+exports.getIndexedHash = getIndexedHash;
+/**
+ * @private
+ */
+function getValueByPath(obj, path) {
+    const pathParts = path.split('/');
+    let currentValue = obj;
+    for (const part of pathParts) {
+        if (currentValue[part] !== undefined) {
+            currentValue = currentValue[part];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return currentValue;
+}
+exports.getValueByPath = getValueByPath;
+/**
+ * @private
+ */
+function restoreHierarchy(obj) {
+    const result = {};
+    for (const key in obj) {
+        if (obj[key] === undefined)
+            continue;
+        const keys = key.split('/');
+        let current = result;
+        for (let i = 0; i < keys.length; i++) {
+            if (i === keys.length - 1) {
+                current[keys[i]] = obj[key];
+            }
+            else {
+                current[keys[i]] = current[keys[i]] || {};
+                current = current[keys[i]];
+            }
+        }
+    }
+    return result;
+}
+exports.restoreHierarchy = restoreHierarchy;
+/**
+ * @private
+ */
+function isValidCron(cronExpression) {
+    const cronRegex = /^(\*|([0-5]?\d)) (\*|([01]?\d|2[0-3])) (\*|([12]?\d|3[01])) (\*|([1-9]|1[0-2])) (\*|([0-6](?:-[0-6])?(?:,[0-6])?))$/;
+    return cronRegex.test(cronExpression);
+}
+exports.isValidCron = isValidCron;
+/**
+ * Returns the number of seconds for a string using the milliseconds format
+ * used by the `ms` npm package as the input.
+ */
+const s = (input) => {
+    return (0, ms_1.default)(input) / 1000;
+};
+exports.s = s;
+/**
+ * @private
+ */
+const parseStreamMessage = (message) => {
+    try {
+        return JSON.parse(message);
+    }
+    catch (error) {
+        logger.error('Error parsing Stream message', { error });
+        throw error;
+    }
+};
+exports.parseStreamMessage = parseStreamMessage;
+/**
+ * @private
+ */
+const isStreamMessage = (result) => {
+    return Array.isArray(result) && Array.isArray(result[0]);
+};
+exports.isStreamMessage = isStreamMessage;
+/**
+ * Transforms  an array of arrays to an array of objects.
+ */
+const arrayToHash = (response) => {
+    const results = [];
+    let key;
+    for (let i = 1; i < response.length; i++) {
+        // ignore count
+        const row = response[i];
+        const result = {};
+        if (Array.isArray(row)) {
+            // Check if row is an array
+            for (let j = 0; j < row.length; j += 2) {
+                const key = row[j];
+                const value = row[j + 1];
+                result[key] = value;
+            }
+            if (key) {
+                result.$ = key;
+            }
+            results.push(result);
+            key = undefined;
+        }
+        else {
+            key = row;
+        }
+    }
+    return results;
+};
+exports.arrayToHash = arrayToHash;

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.4.0",
+    "version": "0.4.2",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",

package/build/services/activities/activity.d.ts

@@ -0,0 +1,104 @@
+import { EngineService } from '../engine';
+import { ILogger } from '../logger';
+import { StoreService } from '../store';
+import { TelemetryService } from '../telemetry';
+import { ActivityData, ActivityLeg, ActivityMetadata, ActivityType } from '../../types/activity';
+import { ProviderClient, ProviderTransaction, TransactionResultList } from '../../types/provider';
+import { JobState, JobStatus } from '../../types/job';
+import { StringAnyType } from '../../types/serializer';
+import { StreamCode, StreamData, StreamStatus } from '../../types/stream';
+/**
+ * The base class for all activities
+ */
+declare class Activity {
+    config: ActivityType;
+    data: ActivityData;
+    hook: ActivityData;
+    metadata: ActivityMetadata;
+    store: StoreService<ProviderClient, ProviderTransaction>;
+    context: JobState;
+    engine: EngineService;
+    logger: ILogger;
+    status: StreamStatus;
+    code: StreamCode;
+    leg: ActivityLeg;
+    adjacencyList: StreamData[];
+    adjacentIndex: number;
+    constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
+    setLeg(leg: ActivityLeg): void;
+    /**
+     * A job is assumed to be complete when its status (a semaphore)
+     * reaches `0`. A different threshold can be set in the
+     * activity YAML, in support of Dynamic Activation Control.
+     */
+    mapStatusThreshold(): number;
+    /**
+     * Upon entering leg 1 of a duplexed activity
+     */
+    verifyEntry(): Promise<void>;
+    /**
+     * Upon entering leg 2 of a duplexed activity
+     */
+    verifyReentry(): Promise<number>;
+    processEvent(status?: StreamStatus, code?: StreamCode, type?: 'hook' | 'output'): Promise<void>;
+    processPending(type: 'hook' | 'output'): Promise<TransactionResultList>;
+    processSuccess(type: 'hook' | 'output'): Promise<TransactionResultList>;
+    processError(): Promise<TransactionResultList>;
+    transitionAdjacent(multiResponse: TransactionResultList, telemetry: TelemetryService): Promise<void>;
+    resolveStatus(multiResponse: TransactionResultList): number;
+    mapJobData(): void;
+    mapInputData(): void;
+    mapOutputData(): void;
+    registerTimeout(): Promise<void>;
+    /**
+     * Any StreamMessage with a status of ERROR is bound to the activity
+     */
+    bindActivityError(data: Record<string, unknown>): void;
+    /**
+     * unhandled activity errors (activities that return an ERROR StreamMessage
+     * status and have no adjacent children to transition to) are bound to the job
+     */
+    bindJobError(data: Record<string, unknown>): void;
+    getTriggerConfig(): Promise<ActivityType>;
+    getJobStatus(): null | number;
+    setStatus(amount: number, transaction?: ProviderTransaction): Promise<void | any>;
+    authorizeEntry(state: StringAnyType): string[];
+    bindDimensionalAddress(state: StringAnyType): void;
+    setState(transaction?: ProviderTransaction): Promise<string>;
+    bindJobMetadata(): void;
+    bindActivityMetadata(): void;
+    bindJobState(state: StringAnyType): Promise<void>;
+    bindActivityState(state: StringAnyType): void;
+    bindJobMetadataPaths(): string[];
+    bindActivityMetadataPaths(): string[];
+    getState(): Promise<void>;
+    /**
+     * if the job is created/deleted/created with the same key,
+     * the 'gid' ensures no stale messages (such as sleep delays)
+     * enter the workstream. Any message with a mismatched gid
+     * belongs to a prior job and can safely be ignored/dropped.
+     */
+    assertGenerationalId(jobGID: string, msgGID?: string): void;
+    initDimensionalAddress(dad: string): void;
+    initSelf(context: StringAnyType): JobState;
+    initPolicies(context: JobState): void;
+    bindActivityData(type: 'output' | 'hook'): void;
+    resolveDad(): string;
+    resolveAdjacentDad(): string;
+    filterAdjacent(): Promise<StreamData[]>;
+    isJobComplete(jobStatus: JobStatus): boolean;
+    shouldEmit(): boolean;
+    /**
+     * emits the job completed event while leaving the job active, allowing
+     * a `main` thread to exit while other threads continue to run.
+     * @private
+     */
+    shouldPersistJob(): boolean;
+    transition(adjacencyList: StreamData[], jobStatus: JobStatus): Promise<string[]>;
+    /**
+     * A job with a vale < -100_000_000 is considered interrupted,
+     * as the interruption event decrements the job status by 1billion.
+     */
+    jobWasInterrupted(jobStatus: JobStatus): boolean;
+}
+export { Activity, ActivityType };