@arvo-tools/postgres 1.1.0 → 1.2.1

package/dist/broker/types.d.ts

@@ -0,0 +1,96 @@
+import type { QueuePolicy } from 'pg-boss';
+/**
+ * Job-level options that control how individual jobs are processed by PgBoss.
+ * These options are applied when sending jobs to queues.
+ */
+export type WorkerJobOptions = {
+    /** Job priority. Higher numbers have higher priority */
+    priority?: number;
+    /** Number of retries to complete a job. Default: 2 */
+    retryLimit?: number;
+    /** Delay between retries of failed jobs, in seconds. Default: 0 */
+    retryDelay?: number;
+    /** Enables exponential backoff retries based on retryDelay. Default: false */
+    retryBackoff?: boolean;
+    /** Maximum delay between retries when retryBackoff is true, in seconds */
+    retryDelayMax?: number;
+    /** How many seconds a job may be in active state before being retried or failed. Default: 15 minutes */
+    expireInSeconds?: number;
+    /** How many seconds a job may be in created or retry state before deletion. Default: 14 days */
+    retentionSeconds?: number;
+    /** How long a job should be retained after completion, in seconds. Default: 7 days */
+    deleteAfterSeconds?: number;
+    /** Delay job execution. Can be seconds (number), ISO 8601 string, or Date object */
+    startAfter?: number | string | Date;
+    /** Throttle to one job per time slot, in seconds */
+    singletonSeconds?: number;
+    /** Schedule throttled job for next time slot. Default: false */
+    singletonNextSlot?: boolean;
+    /** Extend throttling to allow one job per key within the time slot */
+    singletonKey?: string;
+};
+/**
+ * Worker-level configuration options that control how the worker processes jobs.
+ * These options are not sent with individual jobs.
+ */
+export type WorkerConfigOptions = {
+    /** Polling interval for checking new jobs, in seconds. Default: 2 */
+    pollingIntervalSeconds?: number;
+    /** Number of concurrent worker instances to spawn for this handler. Default: 1 */
+    concurrency?: number;
+};
+/**
+ * Combined worker options including both configuration and job-level settings.
+ */
+export type WorkerOptions = WorkerConfigOptions & WorkerJobOptions;
+/**
+ * Queue configuration options that define queue behavior and policies.
+ */
+export type QueueOptions = {
+    /** Queue policy determining job uniqueness and processing behavior */
+    policy?: QueuePolicy;
+    /** Enable queue partitioning for scalability */
+    partition?: boolean;
+    /** Name of the dead letter queue for failed jobs */
+    deadLetter?: string;
+    /** Queue size threshold for warnings */
+    warningQueueSize?: number;
+};
+/**
+ * Options for registering an event handler with the ArvoPgBoss system.
+ */
+export type HandlerRegistrationOptions = {
+    /** Delete and recreate the queue before registration. Default: false */
+    recreateQueue?: boolean;
+    /** Queue-level configuration options */
+    queue?: QueueOptions;
+    /** Worker-level configuration and job options */
+    worker?: WorkerOptions;
+};
+/**
+ * Logger interface for broker operations.
+ *
+ * Allows users to inject their own logging implementation (Winston, Pino, etc.)
+ * or use the default console logger. All broker operational logs use this interface.
+ */
+export interface ILogger {
+    /**
+     * Log informational messages about broker operations.
+     * @param message - Primary log message
+     * @param optionalParams - Additional context or data
+     */
+    log(message?: any, ...optionalParams: any[]): void;
+    /**
+     * Log error messages for failures or exceptions.
+     * @param message - Error message or description
+     * @param optionalParams - Error object or additional context
+     */
+    error(message?: any, ...optionalParams: any[]): void;
+    /**
+     * Log informational messages (alias for log).
+     * @param message - Primary log message
+     * @param optionalParams - Additional context or data
+     */
+    info(message?: any, ...optionalParams: any[]): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/broker/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/broker/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wGAAwG;IACxG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,qEAAqE;IACrE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,sEAAsE;IACtE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gDAAgD;IAChD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,wEAAwE;IACxE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wCAAwC;IACxC,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,iDAAiD;IACjD,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IAEH,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAEnD;;;;OAIG;IAEH,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAErD;;;;OAIG;IAEH,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;CACrD"}

package/dist/broker/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/broker/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/broker/types.ts"],"names":[],"mappings":""}

package/dist/broker/utils.d.ts

@@ -0,0 +1,11 @@
+import { ArvoEvent } from 'arvo-core';
+import type { Job } from 'pg-boss';
+export declare const createArvoEventFromJob: (job: Job<ReturnType<ArvoEvent["toJSON"]>>) => ArvoEvent;
+/**
+ * Extracts and creates an OpenTelemetry context from an ArvoEvent's traceparent.
+ *
+ * @param event - The ArvoEvent containing trace information
+ * @returns OpenTelemetry context with the event's trace information
+ */
+export declare const otelParentContext: (event: ArvoEvent) => import("@opentelemetry/api").Context;
+//# sourceMappingURL=utils.d.ts.map

package/dist/broker/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/broker/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAEnC,eAAO,MAAM,sBAAsB,GAAI,KAAK,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAG,SA2ClF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,yCAejD,CAAC"}

package/dist/broker/utils.js

@@ -0,0 +1,78 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.otelParentContext = exports.createArvoEventFromJob = void 0;
+var api_1 = require("@opentelemetry/api");
+var arvo_core_1 = require("arvo-core");
+var createArvoEventFromJob = function (job) {
+    var _a = job.data, id = _a.id, source = _a.source, type = _a.type, subject = _a.subject, time = _a.time, specversion = _a.specversion, datacontenttype = _a.datacontenttype, dataschema = _a.dataschema, to = _a.to, accesscontrol = _a.accesscontrol, redirectto = _a.redirectto, executionunits = _a.executionunits, parentid = _a.parentid, domain = _a.domain, traceparent = _a.traceparent, tracestate = _a.tracestate, data = _a.data, extensions = __rest(_a, ["id", "source", "type", "subject", "time", "specversion", "datacontenttype", "dataschema", "to", "accesscontrol", "redirectto", "executionunits", "parentid", "domain", "traceparent", "tracestate", "data"]);
+    return new arvo_core_1.ArvoEvent({
+        id: id,
+        source: source,
+        type: type,
+        subject: subject,
+        time: time,
+        specversion: specversion,
+        datacontenttype: datacontenttype,
+        dataschema: dataschema,
+        to: to,
+        accesscontrol: accesscontrol,
+        redirectto: redirectto,
+        executionunits: executionunits,
+        parentid: parentid,
+        domain: domain,
+        traceparent: traceparent,
+        tracestate: tracestate,
+    }, data, extensions !== null && extensions !== void 0 ? extensions : {});
+};
+exports.createArvoEventFromJob = createArvoEventFromJob;
+/**
+ * Extracts and creates an OpenTelemetry context from an ArvoEvent's traceparent.
+ *
+ * @param event - The ArvoEvent containing trace information
+ * @returns OpenTelemetry context with the event's trace information
+ */
+var otelParentContext = function (event) {
+    var parentContext = api_1.context.active();
+    if (event.traceparent) {
+        var parts = event.traceparent.split('-');
+        if (parts.length === 4) {
+            var _a = __read(parts, 4), _ = _a[0], traceId = _a[1], spanId = _a[2], traceFlags = _a[3];
+            var spanContext = {
+                traceId: traceId,
+                spanId: spanId,
+                traceFlags: Number.parseInt(traceFlags, 10),
+            };
+            parentContext = api_1.trace.setSpanContext(api_1.context.active(), spanContext);
+        }
+    }
+    return parentContext;
+};
+exports.otelParentContext = otelParentContext;
+//# sourceMappingURL=utils.js.map

package/dist/broker/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/broker/utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,0CAAsE;AACtE,uCAAsC;AAG/B,IAAM,sBAAsB,GAAG,UAAC,GAAyC;IAC9E,IAAM,KAmBF,GAAG,CAAC,IAAI,EAlBV,EAAE,QAAA,EACF,MAAM,YAAA,EACN,IAAI,UAAA,EACJ,OAAO,aAAA,EACP,IAAI,UAAA,EACJ,WAAW,iBAAA,EACX,eAAe,qBAAA,EACf,UAAU,gBAAA,EACV,EAAE,QAAA,EACF,aAAa,mBAAA,EACb,UAAU,gBAAA,EACV,cAAc,oBAAA,EACd,QAAQ,cAAA,EACR,MAAM,YAAA,EACN,WAAW,iBAAA,EACX,UAAU,gBAAA,EACV,IAAI,UAAA,EACD,UAAU,cAlBT,6MAmBL,CAAW,CAAC;IACb,OAAO,IAAI,qBAAS,CAClB;QACE,EAAE,IAAA;QACF,MAAM,QAAA;QACN,IAAI,MAAA;QACJ,OAAO,SAAA;QACP,IAAI,MAAA;QACJ,WAAW,EAAE,WAAoB;QACjC,eAAe,iBAAA;QACf,UAAU,YAAA;QACV,EAAE,IAAA;QACF,aAAa,eAAA;QACb,UAAU,YAAA;QACV,cAAc,gBAAA;QACd,QAAQ,UAAA;QACR,MAAM,QAAA;QACN,WAAW,aAAA;QACX,UAAU,YAAA;KACX,EACD,IAAI,EACJ,UAAU,aAAV,UAAU,cAAV,UAAU,GAAI,EAAE,CACjB,CAAC;AACJ,CAAC,CAAC;AA3CW,QAAA,sBAAsB,0BA2CjC;AAEF;;;;;GAKG;AACI,IAAM,iBAAiB,GAAG,UAAC,KAAgB;IAChD,IAAI,aAAa,GAAG,aAAO,CAAC,MAAM,EAAE,CAAC;IACrC,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,IAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjB,IAAA,KAAA,OAAmC,KAAK,IAAA,EAAvC,CAAC,QAAA,EAAE,OAAO,QAAA,EAAE,MAAM,QAAA,EAAE,UAAU,QAAS,CAAC;YAC/C,IAAM,WAAW,GAAgB;gBAC/B,OAAO,SAAA;gBACP,MAAM,QAAA;gBACN,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC;aAC5C,CAAC;YACF,aAAa,GAAG,WAAK,CAAC,cAAc,CAAC,aAAO,CAAC,MAAM,EAAE,EAAE,WAAW,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IACD,OAAO,aAAa,CAAC;AACvB,CAAC,CAAC;AAfW,QAAA,iBAAiB,qBAe5B"}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { PostgresEventBroker } from './broker';
+export type { HandlerRegistrationOptions, QueueOptions, WorkerConfigOptions, WorkerJobOptions, WorkerOptions, } from './broker/types';
 export { connectPostgresMachineMemory, releasePostgressMachineMemory, } from './memory/factory';
 export type { ConnectPostgresMachineMemoryParam, PostgresMachineMemory, } from './memory/factory/type';
 export type { PostgressConnectionConfig } from './memory/types';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,iCAAiC,EACjC,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EACV,0BAA0B,EAC1B,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,iCAAiC,EACjC,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PostgressMachineMemoryV1 = exports.releasePostgressMachineMemory = exports.connectPostgresMachineMemory = void 0;
+exports.PostgressMachineMemoryV1 = exports.releasePostgressMachineMemory = exports.connectPostgresMachineMemory = exports.PostgresEventBroker = void 0;
+var broker_1 = require("./broker");
+Object.defineProperty(exports, "PostgresEventBroker", { enumerable: true, get: function () { return broker_1.PostgresEventBroker; } });
 var factory_1 = require("./memory/factory");
 Object.defineProperty(exports, "connectPostgresMachineMemory", { enumerable: true, get: function () { return factory_1.connectPostgresMachineMemory; } });
 Object.defineProperty(exports, "releasePostgressMachineMemory", { enumerable: true, get: function () { return factory_1.releasePostgressMachineMemory; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,4CAG0B;AAFxB,uHAAA,4BAA4B,OAAA;AAC5B,wHAAA,6BAA6B,OAAA;AAO/B,kCAAuD;AAA9C,8GAAA,wBAAwB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAA+C;AAAtC,6GAAA,mBAAmB,OAAA;AAQ5B,4CAG0B;AAFxB,uHAAA,4BAA4B,OAAA;AAC5B,wHAAA,6BAA6B,OAAA;AAO/B,kCAAuD;AAA9C,8GAAA,wBAAwB,OAAA"}

package/dist/memory/v1/schema.d.ts

@@ -95,6 +95,10 @@ declare const tableSchema: {
                 is_nullable: "YES";
             }>;
         }, "strip", z.ZodTypeAny, {
+            source: {
+                data_type: "character varying";
+                is_nullable: "NO";
+            };
             subject: {
                 data_type: "character varying";
                 is_nullable: "NO";
@@ -119,10 +123,6 @@ declare const tableSchema: {
                 data_type: "character varying";
                 is_nullable: "YES";
             };
-            source: {
-                data_type: "character varying";
-                is_nullable: "NO";
-            };
             created_at: {
                 data_type: "timestamp without time zone";
                 is_nullable: "YES";
@@ -132,6 +132,10 @@ declare const tableSchema: {
                 is_nullable: "YES";
             };
         }, {
+            source: {
+                data_type: "character varying";
+                is_nullable: "NO";
+            };
             subject: {
                 data_type: "character varying";
                 is_nullable: "NO";
@@ -156,10 +160,6 @@ declare const tableSchema: {
                 data_type: "character varying";
                 is_nullable: "YES";
             };
-            source: {
-                data_type: "character varying";
-                is_nullable: "NO";
-            };
             created_at: {
                 data_type: "timestamp without time zone";
                 is_nullable: "YES";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arvo-tools/postgres",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "The official package for Arvo's execution components in Postgres",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,6 +29,7 @@
   "dependencies": {
     "arvo-core": "3.0.28",
     "pg": "8.16.3",
+    "pg-boss": "12.5.4",
     "pg-format": "1.0.4",
     "zod": "3.25.76"
   },
@@ -41,7 +42,7 @@
     "vitest": "4.0.13"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.12.0"
   },
   "scripts": {
     "build": "tsc",