@hotmeshio/hotmesh 0.12.1 → 0.14.0

package/build/services/activities/worker.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Worker = void 0;
-const errors_1 = require("../../modules/errors");
 const utils_1 = require("../../modules/utils");
 const collator_1 = require("../collator");
 const pipe_1 = require("../pipe");
@@ -74,7 +73,7 @@ const activity_1 = require("./activity");
  * ## Retry Policy
  *
  * Retry behavior is configured at the **worker level** (not in YAML) via
- * the `retryPolicy` option. Failed callbacks are retried with exponential
+ * the `retry` option. Failed callbacks are retried with exponential
  * backoff until `maximumAttempts` is exhausted. The `maximumInterval` caps
  * the delay between retries.
  *
@@ -85,7 +84,7 @@ const activity_1 = require("./activity");
  *   workers: [{
  *     topic: 'work.backoff',
  *     connection,
- *     retryPolicy: {
+ *     retry: {
  *       maximumAttempts: 5,          // retry up to 5 times
  *       backoffCoefficient: 2,       // exponential: 2^0, 2^1, 2^2, ... seconds
  *       maximumInterval: '30s',      // cap delay at 30 seconds
@@ -115,10 +114,6 @@ const activity_1 = require("./activity");
  * @see {@link WorkerActivity} for the TypeScript interface
  */
 class Worker extends activity_1.Activity {
-    constructor(config, data, metadata, hook, engine, context) {
-        super(config, data, metadata, hook, engine, context);
-    }
-    //********  INITIAL ENTRY POINT (A)  ********//
     async process() {
         this.logger.debug('worker-process', {
             jid: this.context.metadata.jid,
@@ -131,15 +126,12 @@ class Worker extends activity_1.Activity {
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
             this.mapInputData();
-            //save state and mark Leg1 complete
             const transaction = this.store.transact();
-            //todo: await this.registerTimeout();
             const messageId = await this.execActivity(transaction);
             await collator_1.CollatorService.notarizeLeg1Completion(this, transaction);
             await this.setState(transaction);
             await this.setStatus(0, transaction);
             const txResponse = (await transaction.exec());
-            //telemetry
             telemetry.mapActivityAttributes();
             const jobStatus = this.resolveStatus(txResponse);
             telemetry.setActivityAttributes({
@@ -149,34 +141,8 @@ class Worker extends activity_1.Activity {
             return this.context.metadata.aid;
         }
         catch (error) {
-            if (error instanceof errors_1.InactiveJobError) {
-                this.logger.error('await-inactive-job-error', { error });
-                return;
-            }
-            else if (error instanceof errors_1.GenerationalError) {
-                this.logger.info('process-event-generational-job-error', { error });
-                return;
-            }
-            else if (error instanceof errors_1.GetStateError) {
-                this.logger.error('worker-get-state-error', { error });
-                return;
-            }
-            else if (error instanceof errors_1.CollationError) {
-                if (error.fault === 'duplicate') {
-                    this.logger.info('worker-collation-overage', {
-                        job_id: this.context.metadata.jid,
-                        guid: this.context.metadata.guid,
-                    });
-                    return;
-                }
-                //unknown collation error
-                this.logger.error('worker-collation-error', { error });
-            }
-            else {
-                this.logger.error('worker-process-error', { error });
-            }
-            telemetry?.setActivityError(error.message);
-            throw error;
+            this.handleProcessError(error, telemetry, 'worker');
+            return;
         }
         finally {
             telemetry?.endActivitySpan();
@@ -189,11 +155,9 @@ class Worker extends activity_1.Activity {
     }
     async execActivity(transaction) {
         const topic = pipe_1.Pipe.resolve(this.config.subtype, this.context);
-        // Extract workflow name from job data (set by durable client) or derive from subscribes
         const jobData = this.context.data;
         let wfn = jobData?.workflowName || '';
         if (!wfn && this.config.subscribes) {
-            // Fallback: derive from subscribes by removing topic prefix
             wfn = this.config.subscribes.startsWith(`${topic}-`)
                 ? this.config.subscribes.substring(topic.length + 1)
                 : this.config.subscribes;

package/build/services/connector/factory.d.ts

@@ -11,6 +11,12 @@ export declare class ConnectorService {
     static connectClient(ProviderConfig: ProviderConfig, taskQueue?: string): Promise<ProviderNativeClient>;
     /**
      * Initialize `store`, `stream`, and `subscription` clients for any provider.
+     *
+     * When the target has `workerCredentials`, the `user` and `password`
+     * in all connection options are overridden with the scoped Postgres
+     * role credentials, and `securedWorker` is set so downstream stream
+     * services use SECURITY DEFINER stored procedures.
+     *
      * @private
      */
     static initClients(target: HotMeshEngine | HotMeshWorker): Promise<void>;

package/build/services/connector/factory.js

@@ -22,6 +22,12 @@ class ConnectorService {
     }
     /**
      * Initialize `store`, `stream`, and `subscription` clients for any provider.
+     *
+     * When the target has `workerCredentials`, the `user` and `password`
+     * in all connection options are overridden with the scoped Postgres
+     * role credentials, and `securedWorker` is set so downstream stream
+     * services use SECURITY DEFINER stored procedures.
+     *
      * @private
      */
     static async initClients(target) {
@@ -34,6 +40,24 @@ class ConnectorService {
                 sub: { ...connection },
             };
         }
+        // Apply scoped worker credentials to stream/sub only.
+        // The `store` connection retains full credentials because it is
+        // used by the engine for schema deployment, job-state reads, and
+        // other operations that require direct table access. Only the
+        // `stream` (dequeue/ack/respond) and `sub` (LISTEN/UNLISTEN)
+        // connections are scoped to the least-privilege worker role.
+        const workerCreds = target.workerCredentials;
+        if (workerCreds) {
+            for (const key of ['stream', 'sub']) {
+                if (connection[key]?.options) {
+                    connection[key].options = {
+                        ...connection[key].options,
+                        user: workerCreds.user,
+                        password: workerCreds.password,
+                    };
+                }
+            }
+        }
         // Extract taskQueue from target for connection pooling
         const taskQueue = target.taskQueue;
         // Expanded form

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

@@ -29,7 +29,7 @@ import { PostgresClientType } from '../../types/postgres';
  * from completed jobs while preserving:
  * - `jdata` — workflow return data
  * - `udata` — user-searchable data
- * - `jmark` — timeline markers needed for Temporal-compatible export
+ * - `jmark` — timeline markers needed for workflow execution export
  *
  * Set `keepHmark: true` to also preserve `hmark` (activity state markers).
  *
@@ -63,11 +63,14 @@ import { PostgresClientType } from '../../types/postgres';
  *   jobs: false, streams: false, attributes: true,
  * });
  *
- * // Cron 2 — Hourly: remove processed stream messages older than 24h
+ * // Cron 2 — Hourly: aggressive engine stream cleanup, conservative worker streams
  * await DBA.prune({
  *   appId: 'myapp', connection,
- *   expire: '24 hours',
- *   jobs: false, streams: true,
+ *   jobs: false, attributes: false,
+ *   engineStreams: true,
+ *   engineStreamsExpire: '24 hours',
+ *   workerStreams: true,
+ *   workerStreamsExpire: '90 days',  // preserve for export fidelity
  * });
  *
  * // Cron 3 — Weekly: remove expired 'book' jobs older than 30 days
@@ -101,6 +104,13 @@ import { PostgresClientType } from '../../types/postgres';
  *
  * -- Prune everything older than 7 days and strip attributes
  * SELECT * FROM myapp.prune('7 days', true, true, true);
+ *
+ * -- Independent stream retention: engine 24h, worker 90 days
+ * SELECT * FROM myapp.prune(
+ *   '7 days', true, false, false, NULL, false, false,
+ *   true, true,                          -- prune_engine_streams, prune_worker_streams
+ *   INTERVAL '24 hours', INTERVAL '90 days'  -- per-table retention
+ * );
  * ```
  */
 declare class DBA {

package/build/services/dba/index.js

@@ -32,7 +32,7 @@ const postgres_1 = require("../connector/providers/postgres");
  * from completed jobs while preserving:
  * - `jdata` — workflow return data
  * - `udata` — user-searchable data
- * - `jmark` — timeline markers needed for Temporal-compatible export
+ * - `jmark` — timeline markers needed for workflow execution export
  *
  * Set `keepHmark: true` to also preserve `hmark` (activity state markers).
  *
@@ -66,11 +66,14 @@ const postgres_1 = require("../connector/providers/postgres");
  *   jobs: false, streams: false, attributes: true,
  * });
  *
- * // Cron 2 — Hourly: remove processed stream messages older than 24h
+ * // Cron 2 — Hourly: aggressive engine stream cleanup, conservative worker streams
  * await DBA.prune({
  *   appId: 'myapp', connection,
- *   expire: '24 hours',
- *   jobs: false, streams: true,
+ *   jobs: false, attributes: false,
+ *   engineStreams: true,
+ *   engineStreamsExpire: '24 hours',
+ *   workerStreams: true,
+ *   workerStreamsExpire: '90 days',  // preserve for export fidelity
  * });
  *
  * // Cron 3 — Weekly: remove expired 'book' jobs older than 30 days
@@ -104,6 +107,13 @@ const postgres_1 = require("../connector/providers/postgres");
  *
  * -- Prune everything older than 7 days and strip attributes
  * SELECT * FROM myapp.prune('7 days', true, true, true);
+ *
+ * -- Independent stream retention: engine 24h, worker 90 days
+ * SELECT * FROM myapp.prune(
+ *   '7 days', true, false, false, NULL, false, false,
+ *   true, true,                          -- prune_engine_streams, prune_worker_streams
+ *   INTERVAL '24 hours', INTERVAL '90 days'  -- per-table retention
+ * );
  * ```
  */
 class DBA {
@@ -172,11 +182,17 @@ class DBA {
         strip_attributes BOOLEAN DEFAULT FALSE,
         entity_list TEXT[] DEFAULT NULL,
         prune_transient BOOLEAN DEFAULT FALSE,
-        keep_hmark BOOLEAN DEFAULT FALSE
+        keep_hmark BOOLEAN DEFAULT FALSE,
+        prune_engine_streams BOOLEAN DEFAULT NULL,
+        prune_worker_streams BOOLEAN DEFAULT NULL,
+        engine_streams_retention INTERVAL DEFAULT NULL,
+        worker_streams_retention INTERVAL DEFAULT NULL
       )
       RETURNS TABLE(
         deleted_jobs BIGINT,
         deleted_streams BIGINT,
+        deleted_engine_streams BIGINT,
+        deleted_worker_streams BIGINT,
         stripped_attributes BIGINT,
         deleted_transient BIGINT,
         marked_pruned BIGINT
@@ -185,12 +201,22 @@ class DBA {
       AS $$
       DECLARE
         v_deleted_jobs BIGINT := 0;
-        v_deleted_streams BIGINT := 0;
+        v_deleted_engine_streams BIGINT := 0;
+        v_deleted_worker_streams BIGINT := 0;
         v_stripped_attributes BIGINT := 0;
         v_deleted_transient BIGINT := 0;
         v_marked_pruned BIGINT := 0;
-        v_temp_count BIGINT := 0;
+        v_do_engine BOOLEAN;
+        v_do_worker BOOLEAN;
+        v_engine_retention INTERVAL;
+        v_worker_retention INTERVAL;
       BEGIN
+        -- Resolve per-table overrides (fall back to legacy prune_streams + retention)
+        v_do_engine := COALESCE(prune_engine_streams, prune_streams);
+        v_do_worker := COALESCE(prune_worker_streams, prune_streams);
+        v_engine_retention := COALESCE(engine_streams_retention, retention);
+        v_worker_retention := COALESCE(worker_streams_retention, retention);
+
         -- 1. Hard-delete expired jobs older than the retention window.
         --    FK CASCADE on jobs_attributes handles attribute cleanup.
         --    Optionally scoped to an entity allowlist.
@@ -211,22 +237,23 @@ class DBA {
           GET DIAGNOSTICS v_deleted_transient = ROW_COUNT;
         END IF;
 
-        -- 3. Hard-delete expired stream messages older than the retention window.
-        --    Deletes from both engine_streams and worker_streams tables.
-        IF prune_streams THEN
+        -- 3. Hard-delete expired engine stream messages.
+        IF v_do_engine THEN
           DELETE FROM ${schema}.engine_streams
           WHERE expired_at IS NOT NULL
-            AND expired_at < NOW() - retention;
-          GET DIAGNOSTICS v_deleted_streams = ROW_COUNT;
+            AND expired_at < NOW() - v_engine_retention;
+          GET DIAGNOSTICS v_deleted_engine_streams = ROW_COUNT;
+        END IF;
 
+        -- 4. Hard-delete expired worker stream messages.
+        IF v_do_worker THEN
           DELETE FROM ${schema}.worker_streams
           WHERE expired_at IS NOT NULL
-            AND expired_at < NOW() - retention;
-          GET DIAGNOSTICS v_temp_count = ROW_COUNT;
-          v_deleted_streams := v_deleted_streams + v_temp_count;
+            AND expired_at < NOW() - v_worker_retention;
+          GET DIAGNOSTICS v_deleted_worker_streams = ROW_COUNT;
         END IF;
 
-        -- 4. Strip execution artifacts from completed, live, un-pruned jobs.
+        -- 5. Strip execution artifacts from completed, live, un-pruned jobs.
         --    Always preserves: jdata, udata, jmark (timeline/export history).
         --    Optionally preserves: hmark (when keep_hmark is true).
         IF strip_attributes THEN
@@ -261,7 +288,9 @@ class DBA {
         END IF;
 
         deleted_jobs := v_deleted_jobs;
-        deleted_streams := v_deleted_streams;
+        deleted_streams := v_deleted_engine_streams + v_deleted_worker_streams;
+        deleted_engine_streams := v_deleted_engine_streams;
+        deleted_worker_streams := v_deleted_worker_streams;
         stripped_attributes := v_stripped_attributes;
         deleted_transient := v_deleted_transient;
         marked_pruned := v_marked_pruned;
@@ -357,14 +386,24 @@ class DBA {
         const entities = options.entities ?? null;
         const pruneTransient = options.pruneTransient ?? false;
         const keepHmark = options.keepHmark ?? false;
+        // Per-table overrides (NULL = fall back to streams/expire in SQL)
+        const engineStreams = options.engineStreams ?? null;
+        const workerStreams = options.workerStreams ?? null;
+        const engineStreamsExpire = options.engineStreamsExpire ?? null;
+        const workerStreamsExpire = options.workerStreamsExpire ?? null;
         await DBA.deploy(options.connection, options.appId);
         const { client, release } = await DBA.getClient(options.connection);
         try {
-            const result = await client.query(`SELECT * FROM ${schema}.prune($1::interval, $2::boolean, $3::boolean, $4::boolean, $5::text[], $6::boolean, $7::boolean)`, [expire, jobs, streams, attributes, entities, pruneTransient, keepHmark]);
+            const result = await client.query(`SELECT * FROM ${schema}.prune($1::interval, $2::boolean, $3::boolean, $4::boolean, $5::text[], $6::boolean, $7::boolean, $8::boolean, $9::boolean, $10::interval, $11::interval)`, [
+                expire, jobs, streams, attributes, entities, pruneTransient, keepHmark,
+                engineStreams, workerStreams, engineStreamsExpire, workerStreamsExpire,
+            ]);
             const row = result.rows[0];
             return {
                 jobs: Number(row.deleted_jobs),
                 streams: Number(row.deleted_streams),
+                engineStreams: Number(row.deleted_engine_streams),
+                workerStreams: Number(row.deleted_worker_streams),
                 attributes: Number(row.stripped_attributes),
                 transient: Number(row.deleted_transient),
                 marked: Number(row.marked_pruned),

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

@@ -0,0 +1,30 @@
+import { DurableActivityContext } from '../../types/durable';
+/**
+ * The activity-internal API surface, exposed as `Durable.activity`. Methods
+ * on this class are designed to be called **inside** an activity function —
+ * they read from the activity's `AsyncLocalStorage` context that is populated
+ * by the activity worker before invoking the user's function.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * export async function processData(data: string): Promise<string> {
+ *   const ctx = Durable.activity.getContext();
+ *   console.log(`Activity ${ctx.activityName} for workflow ${ctx.workflowId}`);
+ *   console.log(`Metadata:`, ctx.headers);
+ *   return `Processed: ${data}`;
+ * }
+ * ```
+ */
+export declare class ActivityService {
+    /**
+     * Returns the current activity's execution context. Only available
+     * inside an activity function invoked by the durable activity worker.
+     *
+     * @returns The activity context including name, args, metadata, and parent workflow info.
+     * @throws If called outside of an activity execution context.
+     */
+    static getContext(): DurableActivityContext;
+}

package/build/services/durable/activity.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActivityService = void 0;
+const storage_1 = require("../../modules/storage");
+/**
+ * The activity-internal API surface, exposed as `Durable.activity`. Methods
+ * on this class are designed to be called **inside** an activity function —
+ * they read from the activity's `AsyncLocalStorage` context that is populated
+ * by the activity worker before invoking the user's function.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * export async function processData(data: string): Promise<string> {
+ *   const ctx = Durable.activity.getContext();
+ *   console.log(`Activity ${ctx.activityName} for workflow ${ctx.workflowId}`);
+ *   console.log(`Metadata:`, ctx.headers);
+ *   return `Processed: ${data}`;
+ * }
+ * ```
+ */
+class ActivityService {
+    /**
+     * Returns the current activity's execution context. Only available
+     * inside an activity function invoked by the durable activity worker.
+     *
+     * @returns The activity context including name, args, metadata, and parent workflow info.
+     * @throws If called outside of an activity execution context.
+     */
+    static getContext() {
+        const store = storage_1.activityAsyncLocalStorage.getStore();
+        if (!store) {
+            throw new Error('Durable.activity.getContext() called outside of an activity execution context');
+        }
+        return {
+            activityName: store.get('activityName'),
+            arguments: store.get('arguments'),
+            headers: store.get('headers') ?? {},
+            workflowId: store.get('workflowId'),
+            workflowTopic: store.get('workflowTopic'),
+        };
+    }
+}
+exports.ActivityService = ActivityService;

package/build/services/durable/client.d.ts

@@ -1,39 +1,34 @@
 import { HotMesh } from '../hotmesh';
 import { ClientConfig, ClientWorkflow, Connection, WorkflowOptions } from '../../types/durable';
 /**
- * The Durable `Client` service is functionally
- * equivalent to the Temporal `Client` service.
- * Start a new workflow execution by calling
- * `workflow.start`. Note the direct connection to
- * Postgres.
+ * Workflow client. Starts workflows, sends signals, and reads results.
  *
- * NATS can be used as the message broker if advanced
- * messaging is required (i.e, patterned subscriptions).
  * @example
-
  * ```typescript
- * //client.ts
- * import { Client, HotMesh } from '@hotmeshio/hotmesh';
+ * import { Durable } from '@hotmeshio/hotmesh';
  * import { Client as Postgres } from 'pg';
-
- * async function run(): Promise<string> {
- *   const client = new Client({
- *     connection: {
- *       class: Postgres,
- *       options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *     }
- *   });
-
- *   const handle = await client.workflow.start({
- *     args: ['HotMesh'],
- *     taskQueue: 'default',
- *     workflowName: 'example',
- *     workflowId: HotMesh.guid()
- *   });
-
- *   return await handle.result();
- *   //returns ['Hello HotMesh', '¡Hola, HotMesh!']
- * }
+ *
+ * const client = new Durable.Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ *   },
+ * });
+ *
+ * // Start a workflow and await its result
+ * const handle = await client.workflow.start({
+ *   args: ['order-123'],
+ *   taskQueue: 'orders',
+ *   workflowName: 'orderWorkflow',
+ *   workflowId: Durable.guid(),
+ * });
+ * const result = await handle.result();
+ *
+ * // Send a signal to a running workflow
+ * await handle.signal('approval', { approved: true });
+ *
+ * // Cancel a running workflow
+ * await handle.cancel();
  * ```
  */
 export declare class ClientService {
@@ -81,8 +76,8 @@ export declare class ClientService {
      */
     search: (hotMeshClient: HotMesh, index: string, query: string[]) => Promise<string[]>;
     /**
-     * The Durable `Client` service is functionally
-     * equivalent to the Temporal `Client` service.
+     * The Durable `Client` service provides methods for
+     * starting, signaling, and querying workflows.
      * Starting a workflow is the primary use case and
      * is accessed by calling workflow.start().
      */

package/build/services/durable/client.js

@@ -11,39 +11,34 @@ const search_1 = require("./search");
 const handle_1 = require("./handle");
 const factory_1 = require("./schemas/factory");
 /**
- * The Durable `Client` service is functionally
- * equivalent to the Temporal `Client` service.
- * Start a new workflow execution by calling
- * `workflow.start`. Note the direct connection to
- * Postgres.
+ * Workflow client. Starts workflows, sends signals, and reads results.
  *
- * NATS can be used as the message broker if advanced
- * messaging is required (i.e, patterned subscriptions).
  * @example
-
  * ```typescript
- * //client.ts
- * import { Client, HotMesh } from '@hotmeshio/hotmesh';
+ * import { Durable } from '@hotmeshio/hotmesh';
  * import { Client as Postgres } from 'pg';
-
- * async function run(): Promise<string> {
- *   const client = new Client({
- *     connection: {
- *       class: Postgres,
- *       options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' }
- *     }
- *   });
-
- *   const handle = await client.workflow.start({
- *     args: ['HotMesh'],
- *     taskQueue: 'default',
- *     workflowName: 'example',
- *     workflowId: HotMesh.guid()
- *   });
-
- *   return await handle.result();
- *   //returns ['Hello HotMesh', '¡Hola, HotMesh!']
- * }
+ *
+ * const client = new Durable.Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ *   },
+ * });
+ *
+ * // Start a workflow and await its result
+ * const handle = await client.workflow.start({
+ *   args: ['order-123'],
+ *   taskQueue: 'orders',
+ *   workflowName: 'orderWorkflow',
+ *   workflowId: Durable.guid(),
+ * });
+ * const result = await handle.result();
+ *
+ * // Send a signal to a running workflow
+ * await handle.signal('approval', { approved: true });
+ *
+ * // Cancel a running workflow
+ * await handle.cancel();
  * ```
  */
 class ClientService {
@@ -114,8 +109,8 @@ class ClientService {
             return await searchClient.sendIndexedQuery(index, query);
         };
         /**
-         * The Durable `Client` service is functionally
-         * equivalent to the Temporal `Client` service.
+         * The Durable `Client` service provides methods for
+         * starting, signaling, and querying workflows.
          * Starting a workflow is the primary use case and
          * is accessed by calling workflow.start().
          */

package/build/services/durable/connection.d.ts

@@ -1,13 +1,12 @@
 import { Connection } from '../../types/durable';
 import { ProviderConfig, ProvidersConfig } from '../../types/provider';
 /**
- * The Connection service is used to declare the class
- * and connection options but does not connect quite yet. Connection
- * happens at a later lifecycle stage when a workflow
- * is started by the Durable Client module (`(new Durable.Client())).start()`).
+ * Declares connection configuration (driver class + options) without
+ * opening a connection. The actual Postgres connection is established
+ * lazily when a Worker or Client is started.
  *
- * The config options optionall support a multi-connection setup
- * where the `store` connection explicitly defined along with `stream`, `sub`, etc.
+ * Supports both single-connection and split-connection layouts (separate
+ * `store`, `stream`, and `sub` connections for advanced deployments).
  */
 export declare class ConnectionService {
     /**
@@ -15,7 +14,14 @@ export declare class ConnectionService {
      */
     constructor();
     /**
-     * Instance initializer
+     * Create a connection configuration object.
+     *
+     * @param config - Single `{ class, options }` or split `{ store, stream, sub }`.
+     * @returns The normalized connection configuration.
      */
     static connect(config: ProviderConfig | ProvidersConfig): Promise<Connection>;
+    /**
+     * Alias for {@link connect}.
+     */
+    static create: typeof ConnectionService.connect;
 }

package/build/services/durable/connection.js

@@ -2,13 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectionService = void 0;
 /**
- * The Connection service is used to declare the class
- * and connection options but does not connect quite yet. Connection
- * happens at a later lifecycle stage when a workflow
- * is started by the Durable Client module (`(new Durable.Client())).start()`).
+ * Declares connection configuration (driver class + options) without
+ * opening a connection. The actual Postgres connection is established
+ * lazily when a Worker or Client is started.
  *
- * The config options optionall support a multi-connection setup
- * where the `store` connection explicitly defined along with `stream`, `sub`, etc.
+ * Supports both single-connection and split-connection layouts (separate
+ * `store`, `stream`, and `sub` connections for advanced deployments).
  */
 class ConnectionService {
     /**
@@ -16,7 +15,10 @@ class ConnectionService {
      */
     constructor() { }
     /**
-     * Instance initializer
+     * Create a connection configuration object.
+     *
+     * @param config - Single `{ class, options }` or split `{ store, stream, sub }`.
+     * @returns The normalized connection configuration.
      */
     static async connect(config) {
         return 'store' in config
@@ -28,4 +30,8 @@ class ConnectionService {
             };
     }
 }
+/**
+ * Alias for {@link connect}.
+ */
+ConnectionService.create = ConnectionService.connect;
 exports.ConnectionService = ConnectionService;