@arvo-tools/postgres 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { connectPostgresMachineMemory, createPostgresMachineMemoryTables, releasePostgressMachineMemory, } from './memory/factory';
+export type { ConnectPostgresMachineMemoryParam, PostgresMachineMemory, } from './memory/factory/type';
+export type { PostgressConnectionConfig } from './memory/types';
+export { PostgressMachineMemoryV1 } from './memory/v1';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,iCAAiC,EACjC,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

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgressMachineMemoryV1 = exports.releasePostgressMachineMemory = exports.createPostgresMachineMemoryTables = exports.connectPostgresMachineMemory = void 0;
+var factory_1 = require("./memory/factory");
+Object.defineProperty(exports, "connectPostgresMachineMemory", { enumerable: true, get: function () { return factory_1.connectPostgresMachineMemory; } });
+Object.defineProperty(exports, "createPostgresMachineMemoryTables", { enumerable: true, get: function () { return factory_1.createPostgresMachineMemoryTables; } });
+Object.defineProperty(exports, "releasePostgressMachineMemory", { enumerable: true, get: function () { return factory_1.releasePostgressMachineMemory; } });
+var v1_1 = require("./memory/v1");
+Object.defineProperty(exports, "PostgressMachineMemoryV1", { enumerable: true, get: function () { return v1_1.PostgressMachineMemoryV1; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,4CAI0B;AAHxB,uHAAA,4BAA4B,OAAA;AAC5B,4HAAA,iCAAiC,OAAA;AACjC,wHAAA,6BAA6B,OAAA;AAO/B,kCAAuD;AAA9C,8GAAA,wBAAwB,OAAA"}

package/dist/memory/factory/defaults.d.ts

@@ -0,0 +1,5 @@
+import type { ConnectPostgresMachineMemoryParam } from './type';
+export declare const DEFAULT_V1_TABLE_NAMES: NonNullable<Extract<ConnectPostgresMachineMemoryParam, {
+    version: 1;
+}>['tables']>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/memory/factory/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../../src/memory/factory/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,QAAQ,CAAC;AAEhE,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAC9C,OAAO,CAAC,iCAAiC,EAAE;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC,QAAQ,CAAC,CAKrE,CAAC"}

package/dist/memory/factory/defaults.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_V1_TABLE_NAMES = void 0;
+exports.DEFAULT_V1_TABLE_NAMES = {
+    state: 'arvopg_mm_state',
+    lock: 'arvopg_mm_lock',
+    hierarchy: 'arvopg_mm_hierarchy',
+};
+//# sourceMappingURL=defaults.js.map

package/dist/memory/factory/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../../src/memory/factory/defaults.ts"],"names":[],"mappings":";;;AAEa,QAAA,sBAAsB,GAE/B;IACF,KAAK,EAAE,iBAAiB;IACxB,IAAI,EAAE,gBAAgB;IACtB,SAAS,EAAE,qBAAqB;CACjC,CAAC"}

package/dist/memory/factory/index.d.ts

@@ -0,0 +1,117 @@
+import type { ConnectPostgresMachineMemoryParam, PostgresMachineMemory } from './type';
+/**
+ * Connects to and validates a PostgreSQL-backed machine memory instance.
+ *
+ * This function establishes a PostgreSQL connection pool, validates that the required
+ * database tables exist with the correct schema, and returns a ready-to-use machine
+ * memory instance for workflow state management.
+ *
+ * The connection pool will remain open until explicitly closed via `releasePostgressMachineMemory`.
+ *
+ * @param params - Configuration including version, table names, and connection settings
+ * @returns A validated PostgreSQL machine memory instance with an active connection pool
+ *
+ * @throws Error if the specified version is not supported
+ * @throws Error if table validation fails (missing tables or incorrect schema)
+ * @throws Error if database connection fails
+ *
+ * @example
+ * ```typescript
+ * const memory = await connectPostgresMachineMemory({
+ *   version: 1,
+ *   tables: {
+ *     state: 'machine_memory_state',
+ *     lock: 'machine_memory_lock',
+ *     hierarchy: 'machine_memory_hierarchy'
+ *   },
+ *   config: {
+ *     connectionString: 'postgresql://user:pass@localhost:5432/mydb',
+ *     enableCleanup: true,
+ *     lockConfig: {
+ *       maxRetries: 3,
+ *       ttlMs: 120000
+ *     }
+ *   }
+ * });
+ *
+ * // Use the memory instance...
+ *
+ * // Clean up when done
+ * await releasePostgressMachineMemory(memory);
+ * ```
+ */
+export declare const connectPostgresMachineMemory: <T extends Record<string, unknown> = Record<string, unknown>>({ version, tables, config, }: ConnectPostgresMachineMemoryParam) => Promise<PostgresMachineMemory<T>>;
+/**
+ * Releases all resources held by a PostgreSQL machine memory instance.
+ *
+ * This function gracefully closes the underlying connection pool, releasing all database
+ * connections and terminating any idle connections. Should be called when the machine
+ * memory instance is no longer needed to prevent connection leaks and ensure proper
+ * resource cleanup.
+ *
+ * After calling this function, the memory instance should not be used for any further operations.
+ *
+ * @param memory - The PostgreSQL machine memory instance to release
+ */
+export declare const releasePostgressMachineMemory: (memory: PostgresMachineMemory) => Promise<void>;
+/**
+ * Creates PostgreSQL machine memory tables with the specified schema version.
+ *
+ * ⚠️ **WARNING**: Setting `dangerouslyDropTablesIfExist` to true will DROP existing tables and ALL their data.
+ * Use this option with extreme caution, and never in production environments.
+ *
+ * This utility function creates the required database tables (state, lock, and hierarchy) for the
+ * PostgreSQL machine memory implementation. It supports version-specific schema creation and
+ * optionally drops existing tables before recreating them (useful for testing and development).
+ *
+ * @param connectionString - PostgreSQL connection string (e.g., "postgresql://user:pass@localhost:5432/mydb")
+ * @param config - Table creation configuration
+ * @param config.version - Schema version to use (currently only version 1 is supported)
+ * @param config.tables - Custom table names configuration
+ * @param config.tables.state - Name for the state table (stores workflow data, versions, execution status, metadata)
+ * @param config.tables.lock - Name for the lock table (manages distributed locks with TTL-based expiration)
+ * @param config.tables.hierarchy - Name for the hierarchy table (tracks workflow parent-child relationships)
+ * @param config.dangerouslyDropTablesIfExist - If true, drops existing tables before creating them (⚠️ DANGEROUS - causes data loss)
+ *
+ * @throws Error if the specified version is not supported
+ * @throws Error if database connection fails
+ * @throws Error if table creation fails
+ *
+ * @example
+ * ```typescript
+ * // Create tables with default behavior (doesn't drop existing tables)
+ * await createPostgresMachineMemoryTables(connectionString, {
+ *   version: 1,
+ *   tables: {
+ *     state: 'machine_memory_state',
+ *     lock: 'machine_memory_lock',
+ *     hierarchy: 'machine_memory_hierarchy'
+ *   }
+ * });
+ *
+ * // DANGEROUS: Drop and recreate tables (useful for testing and development)
+ * await createPostgresMachineMemoryTables(connectionString, {
+ *   version: 1,
+ *   tables: {
+ *     state: 'machine_memory_state',
+ *     lock: 'machine_memory_lock',
+ *     hierarchy: 'machine_memory_hierarchy'
+ *   },
+ *   dangerouslyDropTablesIfExist: true // ⚠️ This will delete all existing data!
+ * });
+ *
+ * // Use custom table names
+ * await createPostgresMachineMemoryTables(connectionString, {
+ *   version: 1,
+ *   tables: {
+ *     state: 'my_workflow_state',
+ *     lock: 'my_workflow_locks',
+ *     hierarchy: 'my_workflow_hierarchy'
+ *   }
+ * });
+ * ```
+ */
+export declare const createPostgresMachineMemoryTables: (connectionString: string, config: Pick<ConnectPostgresMachineMemoryParam, "version" | "tables"> & {
+    dangerouslyDropTablesIfExist?: boolean;
+}) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/factory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/factory/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iCAAiC,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,4BAA4B,GACvC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,8BAIC,iCAAiC,KAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAUtE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,GAAU,QAAQ,qBAAqB,kBAEhF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,eAAO,MAAM,iCAAiC,GAC5C,kBAAkB,MAAM,EACxB,QAAQ,IAAI,CAAC,iCAAiC,EAAE,SAAS,GAAG,QAAQ,CAAC,GAAG;IACtE,4BAA4B,CAAC,EAAE,OAAO,CAAC;CACxC,kBAUF,CAAC"}

package/dist/memory/factory/index.js

@@ -0,0 +1,202 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPostgresMachineMemoryTables = exports.releasePostgressMachineMemory = exports.connectPostgresMachineMemory = void 0;
+var v1_1 = require("../v1");
+var helper_1 = require("../v1/helper");
+var defaults_1 = require("./defaults");
+/**
+ * Connects to and validates a PostgreSQL-backed machine memory instance.
+ *
+ * This function establishes a PostgreSQL connection pool, validates that the required
+ * database tables exist with the correct schema, and returns a ready-to-use machine
+ * memory instance for workflow state management.
+ *
+ * The connection pool will remain open until explicitly closed via `releasePostgressMachineMemory`.
+ *
+ * @param params - Configuration including version, table names, and connection settings
+ * @returns A validated PostgreSQL machine memory instance with an active connection pool
+ *
+ * @throws Error if the specified version is not supported
+ * @throws Error if table validation fails (missing tables or incorrect schema)
+ * @throws Error if database connection fails
+ *
+ * @example
+ * ```typescript
+ * const memory = await connectPostgresMachineMemory({
+ *   version: 1,
+ *   tables: {
+ *     state: 'machine_memory_state',
+ *     lock: 'machine_memory_lock',
+ *     hierarchy: 'machine_memory_hierarchy'
+ *   },
+ *   config: {
+ *     connectionString: 'postgresql://user:pass@localhost:5432/mydb',
+ *     enableCleanup: true,
+ *     lockConfig: {
+ *       maxRetries: 3,
+ *       ttlMs: 120000
+ *     }
+ *   }
+ * });
+ *
+ * // Use the memory instance...
+ *
+ * // Clean up when done
+ * await releasePostgressMachineMemory(memory);
+ * ```
+ */
+var connectPostgresMachineMemory = function (_a) { return __awaiter(void 0, [_a], void 0, function (_b) {
+    var memory;
+    var version = _b.version, tables = _b.tables, config = _b.config;
+    return __generator(this, function (_c) {
+        switch (_c.label) {
+            case 0:
+                if (!(version === 1)) return [3 /*break*/, 2];
+                memory = new v1_1.PostgressMachineMemoryV1({
+                    tables: tables !== null && tables !== void 0 ? tables : defaults_1.DEFAULT_V1_TABLE_NAMES,
+                    config: config,
+                });
+                return [4 /*yield*/, memory.validateTableStructure()];
+            case 1:
+                _c.sent();
+                return [2 /*return*/, memory];
+            case 2: throw new Error("Unsupported PostgreSQL machine memory version: ".concat(version));
+        }
+    });
+}); };
+exports.connectPostgresMachineMemory = connectPostgresMachineMemory;
+/**
+ * Releases all resources held by a PostgreSQL machine memory instance.
+ *
+ * This function gracefully closes the underlying connection pool, releasing all database
+ * connections and terminating any idle connections. Should be called when the machine
+ * memory instance is no longer needed to prevent connection leaks and ensure proper
+ * resource cleanup.
+ *
+ * After calling this function, the memory instance should not be used for any further operations.
+ *
+ * @param memory - The PostgreSQL machine memory instance to release
+ */
+var releasePostgressMachineMemory = function (memory) { return __awaiter(void 0, void 0, void 0, function () {
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0: return [4 /*yield*/, memory.close()];
+            case 1:
+                _a.sent();
+                return [2 /*return*/];
+        }
+    });
+}); };
+exports.releasePostgressMachineMemory = releasePostgressMachineMemory;
+/**
+ * Creates PostgreSQL machine memory tables with the specified schema version.
+ *
+ * ⚠️ **WARNING**: Setting `dangerouslyDropTablesIfExist` to true will DROP existing tables and ALL their data.
+ * Use this option with extreme caution, and never in production environments.
+ *
+ * This utility function creates the required database tables (state, lock, and hierarchy) for the
+ * PostgreSQL machine memory implementation. It supports version-specific schema creation and
+ * optionally drops existing tables before recreating them (useful for testing and development).
+ *
+ * @param connectionString - PostgreSQL connection string (e.g., "postgresql://user:pass@localhost:5432/mydb")
+ * @param config - Table creation configuration
+ * @param config.version - Schema version to use (currently only version 1 is supported)
+ * @param config.tables - Custom table names configuration
+ * @param config.tables.state - Name for the state table (stores workflow data, versions, execution status, metadata)
+ * @param config.tables.lock - Name for the lock table (manages distributed locks with TTL-based expiration)
+ * @param config.tables.hierarchy - Name for the hierarchy table (tracks workflow parent-child relationships)
+ * @param config.dangerouslyDropTablesIfExist - If true, drops existing tables before creating them (⚠️ DANGEROUS - causes data loss)
+ *
+ * @throws Error if the specified version is not supported
+ * @throws Error if database connection fails
+ * @throws Error if table creation fails
+ *
+ * @example
+ * ```typescript
+ * // Create tables with default behavior (doesn't drop existing tables)
+ * await createPostgresMachineMemoryTables(connectionString, {
+ *   version: 1,
+ *   tables: {
+ *     state: 'machine_memory_state',
+ *     lock: 'machine_memory_lock',
+ *     hierarchy: 'machine_memory_hierarchy'
+ *   }
+ * });
+ *
+ * // DANGEROUS: Drop and recreate tables (useful for testing and development)
+ * await createPostgresMachineMemoryTables(connectionString, {
+ *   version: 1,
+ *   tables: {
+ *     state: 'machine_memory_state',
+ *     lock: 'machine_memory_lock',
+ *     hierarchy: 'machine_memory_hierarchy'
+ *   },
+ *   dangerouslyDropTablesIfExist: true // ⚠️ This will delete all existing data!
+ * });
+ *
+ * // Use custom table names
+ * await createPostgresMachineMemoryTables(connectionString, {
+ *   version: 1,
+ *   tables: {
+ *     state: 'my_workflow_state',
+ *     lock: 'my_workflow_locks',
+ *     hierarchy: 'my_workflow_hierarchy'
+ *   }
+ * });
+ * ```
+ */
+var createPostgresMachineMemoryTables = function (connectionString, config) { return __awaiter(void 0, void 0, void 0, function () {
+    var _a;
+    return __generator(this, function (_b) {
+        switch (_b.label) {
+            case 0:
+                if (!(config.version === 1)) return [3 /*break*/, 2];
+                return [4 /*yield*/, (0, helper_1.createTableV1)(connectionString, {
+                        dropIfExist: config.dangerouslyDropTablesIfExist,
+                        tables: (_a = config.tables) !== null && _a !== void 0 ? _a : defaults_1.DEFAULT_V1_TABLE_NAMES,
+                    })];
+            case 1:
+                _b.sent();
+                return [2 /*return*/];
+            case 2: throw new Error("Unsupported PostgreSQL machine memory version: ".concat(config.version));
+        }
+    });
+}); };
+exports.createPostgresMachineMemoryTables = createPostgresMachineMemoryTables;
+//# sourceMappingURL=index.js.map

package/dist/memory/factory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/factory/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,4BAAiD;AACjD,uCAA6C;AAC7C,uCAAoD;AAGpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACI,IAAM,4BAA4B,GAAG,iEAE1C,EAIkC;;QAHlC,OAAO,aAAA,EACP,MAAM,YAAA,EACN,MAAM,YAAA;;;;qBAEF,CAAA,OAAO,KAAK,CAAC,CAAA,EAAb,wBAAa;gBACT,MAAM,GAAG,IAAI,6BAAwB,CAAI;oBAC7C,MAAM,EAAE,MAAM,aAAN,MAAM,cAAN,MAAM,GAAI,iCAAsB;oBACxC,MAAM,QAAA;iBACP,CAAC,CAAC;gBACH,qBAAM,MAAM,CAAC,sBAAsB,EAAE,EAAA;;gBAArC,SAAqC,CAAC;gBACtC,sBAAO,MAAM,EAAC;oBAEhB,MAAM,IAAI,KAAK,CAAC,yDAAkD,OAAO,CAAE,CAAC,CAAC;;;KAC9E,CAAC;AAhBW,QAAA,4BAA4B,gCAgBvC;AAEF;;;;;;;;;;;GAWG;AACI,IAAM,6BAA6B,GAAG,UAAO,MAA6B;;;oBAC/E,qBAAM,MAAM,CAAC,KAAK,EAAE,EAAA;;gBAApB,SAAoB,CAAC;;;;KACtB,CAAC;AAFW,QAAA,6BAA6B,iCAExC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACI,IAAM,iCAAiC,GAAG,UAC/C,gBAAwB,EACxB,MAEC;;;;;qBAEG,CAAA,MAAM,CAAC,OAAO,KAAK,CAAC,CAAA,EAApB,wBAAoB;gBACtB,qBAAM,IAAA,sBAAa,EAAC,gBAAgB,EAAE;wBACpC,WAAW,EAAE,MAAM,CAAC,4BAA4B;wBAChD,MAAM,EAAE,MAAA,MAAM,CAAC,MAAM,mCAAI,iCAAsB;qBAChD,CAAC,EAAA;;gBAHF,SAGE,CAAC;gBACH,sBAAO;oBAET,MAAM,IAAI,KAAK,CAAC,yDAAkD,MAAM,CAAC,OAAO,CAAE,CAAC,CAAC;;;KACrF,CAAC;AAdW,QAAA,iCAAiC,qCAc5C"}

package/dist/memory/factory/type.d.ts

@@ -0,0 +1,29 @@
+import type { PostgressConnectionConfig } from '../types';
+import type { PostgressMachineMemoryV1 } from '../v1';
+import type { PostgressMachineMemoryV1Param } from '../v1/types';
+/**
+ * Configuration parameters for connecting a PostgreSQL-backed machine memory instance.
+ */
+export type ConnectPostgresMachineMemoryParam = {
+    /**
+     * Schema version of the PostgreSQL machine memory implementation.
+     * Currently only version 1 is supported.
+     */
+    version: 1;
+    /**
+     * Names of the PostgreSQL tables used by the machine memory.
+     * These tables must exist and match the expected schema structure.
+     */
+    tables?: PostgressMachineMemoryV1Param['tables'];
+} & {
+    /** PostgreSQL connection and behavioral configuration. Optional, uses defaults if not provided */
+    config?: PostgressConnectionConfig;
+};
+/**
+ * Type alias for PostgreSQL-backed machine memory instances.
+ *
+ * Provides a version-agnostic interface for PostgreSQL machine memory,
+ * abstracting the underlying implementation version from consumers.
+ */
+export type PostgresMachineMemory<T extends Record<string, unknown> = Record<string, unknown>> = PostgressMachineMemoryV1<T>;
+//# sourceMappingURL=type.d.ts.map

package/dist/memory/factory/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/memory/factory/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,iCAAiC,GAAG;IAC9C;;;OAGG;IACH,OAAO,EAAE,CAAC,CAAC;IACX;;;OAGG;IACH,MAAM,CAAC,EAAE,6BAA6B,CAAC,QAAQ,CAAC,CAAC;CAClD,GAAG;IACF,kGAAkG;IAClG,MAAM,CAAC,EAAE,yBAAyB,CAAC;CACpC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAC3F,wBAAwB,CAAC,CAAC,CAAC,CAAC"}

package/dist/memory/factory/type.js

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

package/dist/memory/factory/type.js.map

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

package/dist/memory/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * PostgreSQL connection configuration for machine memory.
+ *
+ * Supports two connection modes:
+ * - Connection string: A single URL containing all connection parameters
+ * - Individual parameters: Separate host, port, user, password, and database fields
+ */
+export type PostgressConnectionConfig = ({
+    /** PostgreSQL connection string (e.g., "postgresql://user:password@localhost:5432/dbname") */
+    connectionString: string;
+} | {
+    /** Database host address. Defaults to "localhost" */
+    host?: string;
+    /** Database port. Defaults to 5432 */
+    port?: number;
+    /** Database user. Defaults to "postgres" */
+    user?: string;
+    /** Database password. Defaults to "postgres" */
+    password?: string;
+    /** Database name. Defaults to "postgres" */
+    database?: string;
+}) & {
+    /** Maximum number of clients in the connection pool. Defaults to 10 */
+    max?: number;
+    /** Time in milliseconds a client must sit idle before being removed from pool. Defaults to 30000 (30 seconds) */
+    idleTimeoutMillis?: number;
+    /** Time in milliseconds to wait for a connection from the pool. Defaults to 5000 (5 seconds) */
+    connectionTimeoutMillis?: number;
+    /** Time in milliseconds before a statement in a query is cancelled. Optional */
+    statementTimeoutMillis?: number;
+    /** Time in milliseconds before a query is cancelled. Optional */
+    queryTimeoutMillis?: number;
+    /** Configuration for distributed locking behavior */
+    lockConfig?: {
+        /** Maximum number of lock acquisition retry attempts. Defaults to 3 */
+        maxRetries?: number;
+        /** Initial delay in milliseconds before first retry. Defaults to 100 */
+        initialDelayMs?: number;
+        /** Exponential backoff multiplier for subsequent retries. Defaults to 1.5 */
+        backoffExponent?: number;
+        /** Lock time-to-live in milliseconds. Prevents deadlocks via automatic expiration. Defaults to 120000 (2 minutes) */
+        ttlMs?: number;
+    };
+    /** Whether to enable automatic cleanup of completed workflows. Defaults to false */
+    enableCleanup?: boolean;
+    /** Whether to enable OpenTelemetry tracing. Defaults to false */
+    enableOtel?: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACpC;IACE,8FAA8F;IAC9F,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GACD;IACE,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CACJ,GAAG;IACF,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iHAAiH;IACjH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gGAAgG;IAChG,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,gFAAgF;IAChF,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,UAAU,CAAC,EAAE;QACX,uEAAuE;QACvE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,wEAAwE;QACxE,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,6EAA6E;QAC7E,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,qHAAqH;QACrH,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,oFAAoF;IACpF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC"}

package/dist/memory/types.js

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

package/dist/memory/types.js.map

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

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

@@ -0,0 +1,9 @@
+export declare function createTableV1(connectionString: string, config: {
+    tables: {
+        state: string;
+        lock: string;
+        hierarchy: string;
+    };
+    dropIfExist?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=helper.d.ts.map

package/dist/memory/v1/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../src/memory/v1/helper.ts"],"names":[],"mappings":"AAEA,wBAAsB,aAAa,CACjC,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE;IACN,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GACA,OAAO,CAAC,IAAI,CAAC,CA8Cf"}

package/dist/memory/v1/helper.js

@@ -0,0 +1,84 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTableV1 = createTableV1;
+var pg_1 = require("pg");
+function createTableV1(connectionString, config) {
+    return __awaiter(this, void 0, void 0, function () {
+        var client;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    client = new pg_1.Client({ connectionString: connectionString });
+                    return [4 /*yield*/, client.connect()];
+                case 1:
+                    _a.sent();
+                    _a.label = 2;
+                case 2:
+                    _a.trys.push([2, , 10, 12]);
+                    if (!(config === null || config === void 0 ? void 0 : config.dropIfExist)) return [3 /*break*/, 6];
+                    return [4 /*yield*/, client.query("DROP TABLE IF EXISTS ".concat(config.tables.state, ";"))];
+                case 3:
+                    _a.sent();
+                    return [4 /*yield*/, client.query("DROP TABLE IF EXISTS ".concat(config.tables.lock, ";"))];
+                case 4:
+                    _a.sent();
+                    return [4 /*yield*/, client.query("DROP TABLE IF EXISTS ".concat(config.tables.hierarchy, ";"))];
+                case 5:
+                    _a.sent();
+                    _a.label = 6;
+                case 6: return [4 /*yield*/, client.query("\n      CREATE TABLE IF NOT EXISTS ".concat(config.tables.state, " (\n        subject VARCHAR(255) PRIMARY KEY,\n        data JSONB NOT NULL,\n        version INTEGER NOT NULL DEFAULT 1,\n        execution_status VARCHAR(255) NOT NULL,\n        parent_subject VARCHAR(255),\n        initiator VARCHAR(255),\n        source VARCHAR(255) NOT NULL,\n        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n      );\n    "))];
+                case 7:
+                    _a.sent();
+                    return [4 /*yield*/, client.query("\n      CREATE TABLE IF NOT EXISTS ".concat(config.tables.lock, " (\n        subject VARCHAR(255) PRIMARY KEY,\n        locked_at TIMESTAMP NOT NULL,\n        expires_at TIMESTAMP NOT NULL,\n        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n      );\n    "))];
+                case 8:
+                    _a.sent();
+                    return [4 /*yield*/, client.query("\n      CREATE TABLE IF NOT EXISTS ".concat(config.tables.hierarchy, " (\n        subject VARCHAR(255) PRIMARY KEY,\n        parent_subject VARCHAR(255),\n        root_subject VARCHAR(255) NOT NULL,\n        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n      );\n    "))];
+                case 9:
+                    _a.sent();
+                    return [3 /*break*/, 12];
+                case 10: return [4 /*yield*/, client.end()];
+                case 11:
+                    _a.sent();
+                    return [7 /*endfinally*/];
+                case 12: return [2 /*return*/];
+            }
+        });
+    });
+}
+//# sourceMappingURL=helper.js.map

package/dist/memory/v1/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../../../src/memory/v1/helper.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,sCAwDC;AA1DD,yBAA4B;AAE5B,SAAsB,aAAa,CACjC,gBAAwB,EACxB,MAOC;;;;;;oBAEK,MAAM,GAAG,IAAI,WAAM,CAAC,EAAE,gBAAgB,kBAAA,EAAE,CAAC,CAAC;oBAEhD,qBAAM,MAAM,CAAC,OAAO,EAAE,EAAA;;oBAAtB,SAAsB,CAAC;;;;yBAGjB,CAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,WAAW,CAAA,EAAnB,wBAAmB;oBACrB,qBAAM,MAAM,CAAC,KAAK,CAAC,+BAAwB,MAAM,CAAC,MAAM,CAAC,KAAK,MAAG,CAAC,EAAA;;oBAAlE,SAAkE,CAAC;oBACnE,qBAAM,MAAM,CAAC,KAAK,CAAC,+BAAwB,MAAM,CAAC,MAAM,CAAC,IAAI,MAAG,CAAC,EAAA;;oBAAjE,SAAiE,CAAC;oBAClE,qBAAM,MAAM,CAAC,KAAK,CAAC,+BAAwB,MAAM,CAAC,MAAM,CAAC,SAAS,MAAG,CAAC,EAAA;;oBAAtE,SAAsE,CAAC;;wBAGzE,qBAAM,MAAM,CAAC,KAAK,CAAC,6CACY,MAAM,CAAC,MAAM,CAAC,KAAK,6ZAWjD,CAAC,EAAA;;oBAZF,SAYE,CAAC;oBAEH,qBAAM,MAAM,CAAC,KAAK,CAAC,6CACY,MAAM,CAAC,MAAM,CAAC,IAAI,yMAMhD,CAAC,EAAA;;oBAPF,SAOE,CAAC;oBAEH,qBAAM,MAAM,CAAC,KAAK,CAAC,6CACY,MAAM,CAAC,MAAM,CAAC,SAAS,6MAMrD,CAAC,EAAA;;oBAPF,SAOE,CAAC;;yBAEH,qBAAM,MAAM,CAAC,GAAG,EAAE,EAAA;;oBAAlB,SAAkB,CAAC;;;;;;CAEtB"}