@arvo-tools/postgres 1.0.0

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

@@ -0,0 +1,88 @@
+import { type Span } from '@opentelemetry/api';
+import { type IMachineMemory, type MachineMemoryMetadata } from 'arvo-event-handler';
+import type { PostgressMachineMemoryV1Param } from './types';
+type VersionedData<T extends Record<string, unknown>> = T & {
+    __postgres_version_counter_data_$$__: number;
+};
+/**
+ * PostgreSQL-backed implementation of IMachineMemory for distributed workflow state management.
+ *
+ * This class provides persistent storage for workflow instances using PostgreSQL with the following features:
+ * - Optimistic locking via version tracking to prevent concurrent state modifications
+ * - Distributed lock management with TTL-based expiration to prevent deadlocks
+ * - Hierarchical workflow tracking for parent-child relationship queries
+ * - Optional cleanup of completed workflows
+ * - Optional OpenTelemetry instrumentation for observability
+ *
+ * The implementation uses three database tables:
+ * - State table: Stores workflow data, versions, execution status, and metadata
+ * - Lock table: Manages distributed locks with automatic expiration
+ * - Hierarchy table: Tracks workflow parent-child relationships and root subjects
+ */
+export declare class PostgressMachineMemoryV1<T extends Record<string, unknown>> implements IMachineMemory<T> {
+    private readonly tables;
+    private readonly lockConfig;
+    private readonly enableCleanup;
+    private readonly enableOtel;
+    private readonly pool;
+    constructor(param: PostgressMachineMemoryV1Param);
+    close(): Promise<void>;
+    private delay;
+    validateTableStructure(): Promise<void>;
+    otel<R>({ name, fn }: {
+        name: string;
+        fn: (span?: Span) => Promise<R>;
+    }): Promise<R>;
+    read(id: string): Promise<T | null>;
+    write(id: string, data: T, prevData: VersionedData<T> | null, { source, initiator }: MachineMemoryMetadata): Promise<void>;
+    lock(id: string): Promise<boolean>;
+    unlock(id: string): Promise<boolean>;
+    cleanup(id: string): Promise<void>;
+    /**
+     * Retrieves all child workflow subjects belonging to a specific root workflow.
+     *
+     * This method queries the hierarchy table to find all workflows that are descendants
+     * of the specified root workflow. The root subject itself is excluded from the results.
+     *
+     * @param rootSubject - The subject identifier of the root workflow
+     * @returns Array of subject identifiers for all child workflows (excluding the root itself)
+     *
+     * @example
+     * ```typescript
+     * const subject = 'some_string'
+     * const children = await memory.getSubjectsByRoot(subject);
+     * console.log(`Found ${children.length} child workflows subjects`);
+     * ```
+     */
+    getSubjectsByRoot(rootSubject: string): Promise<string[]>;
+    /**
+     * Retrieves the root workflow subject for a given workflow instance.
+     *
+     * This method queries the hierarchy table to find the root workflow subject
+     * associated with the specified workflow. Every workflow in the hierarchy has
+     * a root_subject field that points to the top-level workflow that initiated
+     * the entire workflow tree.
+     *
+     * @param subject - The subject identifier of the workflow to look up
+     * @returns The root subject identifier, or null if the subject is not found in the hierarchy table
+     *
+     * @example
+     * ```typescript
+     * const subject = 'some_string'
+     * const root = await memory.getRootSubject(subject);
+     * if (root) {
+     *   console.log(`Root workflow subject: ${root}`);
+     *   if (root === subject) {
+     *     console.log('This is a root workflow');
+     *   } else {
+     *     console.log('This is a child workflow');
+     *   }
+     * } else {
+     *   console.log('Workflow not found in hierarchy');
+     * }
+     * ```
+     */
+    getRootSubject(subject: string): Promise<string | null>;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/v1/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAkB,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,qBAAqB,EAAgB,MAAM,oBAAoB,CAAC;AAGnG,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,SAAS,CAAC;AAE7D,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG;IAC1D,oCAAoC,EAAE,MAAM,CAAC;CAC9C,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACrE,YAAW,cAAc,CAAC,CAAC,CAAC;IAE5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAEzB;IACF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAE5B;IACF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAEzB;IACF,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAO;gBAEhB,KAAK,EAAE,6BAA6B;IAsC1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAId,KAAK;IAIb,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAavC,IAAI,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE;IAWvE,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAmCnC,KAAK,CACT,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,EACjC,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,qBAAqB,GAC3C,OAAO,CAAC,IAAI,CAAC;IAuFV,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyDlC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBpC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoCxC;;;;;;;;;;;;;;;OAeG;IACG,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA+B/D;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAkC9D"}