@hotmeshio/hotmesh 0.9.0 → 0.10.0

package/build/modules/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SetStateError = exports.RegisterTimeoutError = exports.MapDataError = exports.InactiveJobError = exports.GetStateError = exports.GenerationalError = exports.ExecActivityError = exports.DuplicateJobError = exports.MemFlowWaitForError = exports.MemFlowWaitForAllError = exports.MemFlowTimeoutError = exports.MemFlowSleepError = exports.MemFlowRetryError = exports.MemFlowProxyError = exports.MemFlowMaxedError = exports.MemFlowFatalError = exports.MemFlowChildError = exports.CollationError = void 0;
+exports.SetStateError = exports.RegisterTimeoutError = exports.MapDataError = exports.InactiveJobError = exports.GetStateError = exports.GenerationalError = exports.ExecActivityError = exports.DuplicateJobError = exports.DurableWaitForError = exports.DurableWaitForAllError = exports.DurableTimeoutError = exports.DurableSleepError = exports.DurableRetryError = exports.DurableProxyError = exports.DurableMaxedError = exports.DurableFatalError = exports.DurableChildError = exports.CollationError = void 0;
 const enums_1 = require("./enums");
 class GetStateError extends Error {
     constructor(jobId) {
@@ -16,21 +16,21 @@ class SetStateError extends Error {
     }
 }
 exports.SetStateError = SetStateError;
-class MemFlowWaitForError extends Error {
+class DurableWaitForError extends Error {
     constructor(params) {
         super(`WaitFor Interruption`);
-        this.type = 'MemFlowWaitForError';
+        this.type = 'DurableWaitForError';
         this.signalId = params.signalId;
         this.index = params.index;
         this.workflowDimension = params.workflowDimension;
-        this.code = enums_1.HMSH_CODE_MEMFLOW_WAIT;
+        this.code = enums_1.HMSH_CODE_DURABLE_WAIT;
     }
 }
-exports.MemFlowWaitForError = MemFlowWaitForError;
-class MemFlowProxyError extends Error {
+exports.DurableWaitForError = DurableWaitForError;
+class DurableProxyError extends Error {
     constructor(params) {
         super(`ProxyActivity Interruption`);
-        this.type = 'MemFlowProxyError';
+        this.type = 'DurableProxyError';
         this.arguments = params.arguments;
         this.workflowId = params.workflowId;
         this.workflowTopic = params.workflowTopic;
@@ -43,14 +43,14 @@ class MemFlowProxyError extends Error {
         this.backoffCoefficient = params.backoffCoefficient;
         this.maximumAttempts = params.maximumAttempts;
         this.maximumInterval = params.maximumInterval;
-        this.code = enums_1.HMSH_CODE_MEMFLOW_PROXY;
+        this.code = enums_1.HMSH_CODE_DURABLE_PROXY;
     }
 }
-exports.MemFlowProxyError = MemFlowProxyError;
-class MemFlowChildError extends Error {
+exports.DurableProxyError = DurableProxyError;
+class DurableChildError extends Error {
     constructor(params) {
         super(`ExecChild Interruption`);
-        this.type = 'MemFlowChildError';
+        this.type = 'DurableChildError';
         this.arguments = params.arguments;
         this.workflowId = params.workflowId;
         this.workflowTopic = params.workflowTopic;
@@ -62,18 +62,18 @@ class MemFlowChildError extends Error {
         this.entity = params.entity;
         this.index = params.index;
         this.workflowDimension = params.workflowDimension;
-        this.code = enums_1.HMSH_CODE_MEMFLOW_CHILD;
+        this.code = enums_1.HMSH_CODE_DURABLE_CHILD;
         this.await = params.await;
         this.backoffCoefficient = params.backoffCoefficient;
         this.maximumAttempts = params.maximumAttempts;
         this.maximumInterval = params.maximumInterval;
     }
 }
-exports.MemFlowChildError = MemFlowChildError;
-class MemFlowWaitForAllError extends Error {
+exports.DurableChildError = DurableChildError;
+class DurableWaitForAllError extends Error {
     constructor(params) {
         super(`Collation Interruption`);
-        this.type = 'MemFlowWaitForAllError';
+        this.type = 'DurableWaitForAllError';
         this.items = params.items;
         this.size = params.size;
         this.workflowId = params.workflowId;
@@ -82,66 +82,66 @@ class MemFlowWaitForAllError extends Error {
         this.originJobId = params.originJobId;
         this.index = params.index;
         this.workflowDimension = params.workflowDimension;
-        this.code = enums_1.HMSH_CODE_MEMFLOW_ALL;
+        this.code = enums_1.HMSH_CODE_DURABLE_ALL;
     }
 }
-exports.MemFlowWaitForAllError = MemFlowWaitForAllError;
-class MemFlowSleepError extends Error {
+exports.DurableWaitForAllError = DurableWaitForAllError;
+class DurableSleepError extends Error {
     constructor(params) {
         super(`SleepFor Interruption`);
-        this.type = 'MemFlowSleepError';
+        this.type = 'DurableSleepError';
         this.duration = params.duration;
         this.workflowId = params.workflowId;
         this.index = params.index;
         this.workflowDimension = params.workflowDimension;
-        this.code = enums_1.HMSH_CODE_MEMFLOW_SLEEP;
+        this.code = enums_1.HMSH_CODE_DURABLE_SLEEP;
     }
 }
-exports.MemFlowSleepError = MemFlowSleepError;
-class MemFlowTimeoutError extends Error {
+exports.DurableSleepError = DurableSleepError;
+class DurableTimeoutError extends Error {
     constructor(message, stack) {
         super(message);
-        this.type = 'MemFlowTimeoutError';
+        this.type = 'DurableTimeoutError';
         if (this.stack) {
             this.stack = stack;
         }
-        this.code = enums_1.HMSH_CODE_MEMFLOW_TIMEOUT;
+        this.code = enums_1.HMSH_CODE_DURABLE_TIMEOUT;
     }
 }
-exports.MemFlowTimeoutError = MemFlowTimeoutError;
-class MemFlowMaxedError extends Error {
+exports.DurableTimeoutError = DurableTimeoutError;
+class DurableMaxedError extends Error {
     constructor(message, stackTrace) {
         super(message);
-        this.type = 'MemFlowMaxedError';
+        this.type = 'DurableMaxedError';
         if (stackTrace) {
             this.stack = stackTrace;
         }
-        this.code = enums_1.HMSH_CODE_MEMFLOW_MAXED;
+        this.code = enums_1.HMSH_CODE_DURABLE_MAXED;
     }
 }
-exports.MemFlowMaxedError = MemFlowMaxedError;
-class MemFlowFatalError extends Error {
+exports.DurableMaxedError = DurableMaxedError;
+class DurableFatalError extends Error {
     constructor(message, stackTrace) {
         super(message);
-        this.type = 'MemFlowFatalError';
+        this.type = 'DurableFatalError';
         if (stackTrace) {
             this.stack = stackTrace;
         }
-        this.code = enums_1.HMSH_CODE_MEMFLOW_FATAL;
+        this.code = enums_1.HMSH_CODE_DURABLE_FATAL;
     }
 }
-exports.MemFlowFatalError = MemFlowFatalError;
-class MemFlowRetryError extends Error {
+exports.DurableFatalError = DurableFatalError;
+class DurableRetryError extends Error {
     constructor(message, stackTrace) {
         super(message);
-        this.type = 'MemFlowRetryError';
+        this.type = 'DurableRetryError';
         if (stackTrace) {
             this.stack = stackTrace;
         }
-        this.code = enums_1.HMSH_CODE_MEMFLOW_RETRYABLE;
+        this.code = enums_1.HMSH_CODE_DURABLE_RETRYABLE;
     }
 }
-exports.MemFlowRetryError = MemFlowRetryError;
+exports.DurableRetryError = DurableRetryError;
 class MapDataError extends Error {
     constructor() {
         super('Error occurred while mapping data');

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.9.0",
+    "version": "0.10.0",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -26,26 +26,27 @@
         "test:connect": "vitest run tests/unit/services/connector",
         "test:connect:postgres": "vitest run tests/unit/services/connector/providers/postgres.test.ts",
         "test:connect:nats": "vitest run tests/unit/services/connector/providers/nats.test.ts",
-        "test:memflow": "vitest run tests/memflow",
-        "test:memflow:postgres": "HMSH_LOGLEVEL=info vitest run tests/memflow",
-        "test:memflow:basic": "HMSH_LOGLEVEL=info vitest run tests/memflow/basic/postgres.test.ts",
-        "test:memflow:collision": "vitest run tests/memflow/collision/postgres.test.ts",
-        "test:memflow:fatal": "vitest run tests/memflow/fatal",
-        "test:memflow:goodbye": "HMSH_LOGLEVEL=debug vitest run tests/memflow/goodbye/postgres.test.ts",
-        "test:memflow:interceptor": "HMSH_LOGLEVEL=info vitest run tests/memflow/interceptor/postgres.test.ts",
-        "test:memflow:entity": "HMSH_LOGLEVEL=debug vitest run tests/memflow/entity/postgres.test.ts",
-        "test:memflow:agent": "HMSH_LOGLEVEL=debug vitest run tests/memflow/agent/postgres.test.ts",
-        "test:memflow:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=info vitest run tests/memflow/helloworld/postgres.test.ts",
-        "test:memflow:hook": "vitest run tests/memflow/hook/postgres.test.ts",
-        "test:memflow:interrupt": "vitest run tests/memflow/interrupt/postgres.test.ts",
-        "test:memflow:loopactivity": "vitest run tests/memflow/loopactivity/postgres.test.ts",
-        "test:memflow:nested": "vitest run tests/memflow/nested/postgres.test.ts",
-        "test:memflow:pipeline": "vitest run tests/memflow/pipeline/postgres.test.ts",
-        "test:memflow:retry": "vitest run tests/memflow/retry/postgres.test.ts",
-        "test:memflow:retrypolicy": "vitest run tests/memflow/retry-policy",
-        "test:memflow:sleep": "vitest run tests/memflow/sleep/postgres.test.ts",
-        "test:memflow:signal": "vitest run tests/memflow/signal/postgres.test.ts",
-        "test:memflow:unknown": "vitest run tests/memflow/unknown/postgres.test.ts",
+        "test:durable": "vitest run tests/durable",
+        "test:durable:postgres": "HMSH_LOGLEVEL=info vitest run tests/durable",
+        "test:durable:basic": "HMSH_LOGLEVEL=info vitest run tests/durable/basic/postgres.test.ts",
+        "test:durable:collision": "vitest run tests/durable/collision/postgres.test.ts",
+        "test:durable:fatal": "vitest run tests/durable/fatal",
+        "test:durable:goodbye": "HMSH_LOGLEVEL=debug vitest run tests/durable/goodbye/postgres.test.ts",
+        "test:durable:interceptor": "HMSH_LOGLEVEL=info vitest run tests/durable/interceptor/postgres.test.ts",
+        "test:durable:entity": "HMSH_LOGLEVEL=debug vitest run tests/durable/entity/postgres.test.ts",
+        "test:durable:agent": "HMSH_LOGLEVEL=debug vitest run tests/durable/agent/postgres.test.ts",
+        "test:durable:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=info vitest run tests/durable/helloworld/postgres.test.ts",
+        "test:durable:hook": "vitest run tests/durable/hook/postgres.test.ts",
+        "test:durable:interrupt": "vitest run tests/durable/interrupt/postgres.test.ts",
+        "test:durable:loopactivity": "vitest run tests/durable/loopactivity/postgres.test.ts",
+        "test:durable:nested": "vitest run tests/durable/nested/postgres.test.ts",
+        "test:durable:pipeline": "vitest run tests/durable/pipeline/postgres.test.ts",
+        "test:durable:retry": "vitest run tests/durable/retry/postgres.test.ts",
+        "test:durable:retrypolicy": "vitest run tests/durable/retry-policy",
+        "test:durable:sleep": "vitest run tests/durable/sleep/postgres.test.ts",
+        "test:durable:signal": "vitest run tests/durable/signal/postgres.test.ts",
+        "test:durable:unknown": "vitest run tests/durable/unknown/postgres.test.ts",
+        "test:dba": "vitest run tests/dba",
         "test:cycle": "vitest run tests/functional/cycle",
         "test:functional": "vitest run tests/functional",
         "test:emit": "vitest run tests/functional/emit",
@@ -72,7 +73,7 @@
         "test:sub:postgres": "vitest run tests/functional/sub/providers/postgres/postgres.test.ts",
         "test:sub:nats": "vitest run tests/functional/sub/providers/nats/nats.test.ts",
         "test:trigger": "vitest run tests/unit/services/activities/trigger.test.ts",
-        "test:meshcall": "vitest run tests/meshcall",
+        "test:virtual": "vitest run tests/virtual",
         "test:unit": "vitest run tests/unit"
     },
     "keywords": [

package/build/services/activities/activity.js

@@ -195,7 +195,7 @@ class Activity {
                 this.context.data.done = true;
                 this.context.data.$error = {
                     message: this.data?.message || 'unknown error',
-                    code: enums_1.HMSH_CODE_MEMFLOW_MAXED,
+                    code: enums_1.HMSH_CODE_DURABLE_MAXED,
                     stack: this.data?.stack,
                 };
             }

package/build/services/dba/index.d.ts

@@ -0,0 +1,171 @@
+import { PruneOptions, PruneResult } from '../../types/dba';
+import { PostgresClientType } from '../../types/postgres';
+/**
+ * Database maintenance operations for HotMesh's Postgres backend.
+ *
+ * HotMesh uses soft-delete patterns: expired jobs and stream messages
+ * retain their rows with `expired_at` set but are never physically
+ * removed during normal operation. Over time, three tables accumulate
+ * dead rows:
+ *
+ * | Table | What accumulates |
+ * |---|---|
+ * | `{appId}.jobs` | Completed/expired jobs with `expired_at` set |
+ * | `{appId}.jobs_attributes` | Execution artifacts (`adata`, `hmark`, `jmark`, `status`, `other`) that are only needed during workflow execution |
+ * | `{appId}.streams` | Processed stream messages with `expired_at` set |
+ *
+ * The `DBA` service addresses this with two methods:
+ *
+ * - {@link DBA.prune | prune()} — Targets any combination of jobs,
+ *   streams, and attributes independently. Each table can be pruned on
+ *   its own schedule with its own retention window.
+ * - {@link DBA.deploy | deploy()} — Pre-deploys the Postgres function
+ *   (e.g., during CI/CD migrations) without running a prune.
+ *
+ * ## Independent cron schedules (TypeScript)
+ *
+ * Each table can be targeted independently, allowing different retention
+ * windows and schedules:
+ *
+ * @example
+ * ```typescript
+ * import { Client as Postgres } from 'pg';
+ * import { DBA } from '@hotmeshio/hotmesh';
+ *
+ * const connection = {
+ *   class: Postgres,
+ *   options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ * };
+ *
+ * // Cron 1 — Nightly: strip execution artifacts from completed jobs
+ * //          Keeps all jobs and their jdata/udata; keeps all streams.
+ * await DBA.prune({
+ *   appId: 'myapp', connection,
+ *   jobs: false, streams: false, attributes: true,
+ * });
+ *
+ * // Cron 2 — Hourly: remove processed stream messages older than 24h
+ * await DBA.prune({
+ *   appId: 'myapp', connection,
+ *   expire: '24 hours',
+ *   jobs: false, streams: true,
+ * });
+ *
+ * // Cron 3 — Weekly: remove expired jobs older than 30 days
+ * await DBA.prune({
+ *   appId: 'myapp', connection,
+ *   expire: '30 days',
+ *   jobs: true, streams: false,
+ * });
+ * ```
+ *
+ * ## Direct SQL (schedulable via pg_cron)
+ *
+ * The underlying Postgres function can be called directly, without
+ * the TypeScript SDK. Schedule it via `pg_cron`, `crontab`, or any
+ * SQL client:
+ *
+ * ```sql
+ * -- Strip attributes only (keep all jobs and streams)
+ * SELECT * FROM myapp.prune('0 seconds', false, false, true);
+ *
+ * -- Prune streams older than 24 hours (keep jobs)
+ * SELECT * FROM myapp.prune('24 hours', false, true, false);
+ *
+ * -- Prune expired jobs older than 30 days (keep streams)
+ * SELECT * FROM myapp.prune('30 days', true, false, false);
+ *
+ * -- Prune everything older than 7 days and strip attributes
+ * SELECT * FROM myapp.prune('7 days', true, true, true);
+ * ```
+ */
+declare class DBA {
+    /**
+     * @private
+     */
+    constructor();
+    /**
+     * Sanitizes an appId for use as a Postgres schema name.
+     * Mirrors the naming logic used during table deployment.
+     * @private
+     */
+    static safeName(input: string): string;
+    /**
+     * Acquires a Postgres client from the connection config.
+     * @private
+     */
+    static getClient(connection: PruneOptions['connection']): Promise<{
+        client: PostgresClientType;
+        release: () => Promise<void>;
+    }>;
+    /**
+     * Returns the SQL for the server-side `prune()` function.
+     * @private
+     */
+    static getPruneFunctionSQL(schema: string): string;
+    /**
+     * Deploys the `prune()` Postgres function into the target schema.
+     * Idempotent — uses `CREATE OR REPLACE` and can be called repeatedly.
+     *
+     * The function is automatically deployed when {@link DBA.prune} is called,
+     * but this method is exposed for explicit control (e.g., CI/CD
+     * migration scripts that provision database objects before the
+     * application starts).
+     *
+     * @param connection - Postgres provider configuration
+     * @param appId - Application identifier (schema name)
+     *
+     * @example
+     * ```typescript
+     * import { Client as Postgres } from 'pg';
+     * import { DBA } from '@hotmeshio/hotmesh';
+     *
+     * // Pre-deploy during CI/CD migration
+     * await DBA.deploy(
+     *   {
+     *     class: Postgres,
+     *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+     *   },
+     *   'myapp',
+     * );
+     * ```
+     */
+    static deploy(connection: PruneOptions['connection'], appId: string): Promise<void>;
+    /**
+     * Prunes expired data and/or strips execution artifacts from
+     * completed jobs. Each operation is independently controlled,
+     * so callers can target a single table per cron schedule.
+     *
+     * Operations (each enabled individually):
+     * 1. **jobs** — Hard-deletes expired jobs older than the retention
+     *    window (FK CASCADE removes their attributes automatically)
+     * 2. **streams** — Hard-deletes expired stream messages older than
+     *    the retention window
+     * 3. **attributes** — Strips non-essential attributes (`adata`,
+     *    `hmark`, `jmark`, `status`, `other`) from completed jobs,
+     *    retaining only `jdata` and `udata`
+     *
+     * @param options - Prune configuration
+     * @returns Counts of deleted/stripped rows
+     *
+     * @example
+     * ```typescript
+     * import { Client as Postgres } from 'pg';
+     * import { DBA } from '@hotmeshio/hotmesh';
+     *
+     * // Strip attributes only — keep all jobs and streams
+     * await DBA.prune({
+     *   appId: 'myapp',
+     *   connection: {
+     *     class: Postgres,
+     *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
+     *   },
+     *   jobs: false,
+     *   streams: false,
+     *   attributes: true,
+     * });
+     * ```
+     */
+    static prune(options: PruneOptions): Promise<PruneResult>;
+}
+export { DBA };