@flowcore/pathways 0.2.1 → 0.2.3

package/script/pathways/builder.js

@@ -6,10 +6,43 @@ const rxjs_1 = require("rxjs");
 const flowcore_transformer_core_sdk_js_1 = require("../compatibility/flowcore-transformer-core.sdk.js");
 const internal_pathway_state_js_1 = require("./internal-pathway.state.js");
 const logger_js_1 = require("./logger.js");
+/**
+ * Default timeout for pathway processing in milliseconds (10 seconds)
+ */
 const DEFAULT_PATHWAY_TIMEOUT_MS = 10000;
+/**
+ * Default maximum number of retry attempts for failed pathway processing
+ */
 const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Default delay between retry attempts in milliseconds
+ */
 const DEFAULT_RETRY_DELAY_MS = 500;
+/**
+ * Main builder class for creating and managing Flowcore pathways
+ *
+ * The PathwaysBuilder provides an interface for:
+ * - Registering pathways with type-safe schemas
+ * - Handling events sent to pathways
+ * - Writing data to pathways
+ * - Managing event processing and retries
+ * - Observing event lifecycle (before/after/error)
+ * - Audit logging of pathway operations
+ *
+ * @template TPathway Record type that maps pathway keys to their payload types
+ * @template TWritablePaths Union type of pathway keys that can be written to
+ */
 class PathwaysBuilder {
+    /**
+     * Creates a new PathwaysBuilder instance
+     * @param options Configuration options for the PathwaysBuilder
+     * @param options.baseUrl The base URL for the Flowcore API
+     * @param options.tenant The tenant name
+     * @param options.dataCore The data core name
+     * @param options.apiKey The API key for authentication
+     * @param options.pathwayTimeoutMs Optional timeout for pathway processing in milliseconds
+     * @param options.logger Optional logger instance
+     */
     constructor({ baseUrl, tenant, dataCore, apiKey, pathwayTimeoutMs, logger, }) {
         Object.defineProperty(this, "pathways", {
             enumerable: true,
@@ -150,6 +183,11 @@ class PathwaysBuilder {
             this.pathwayTimeoutMs = pathwayTimeoutMs;
         }
     }
+    /**
+     * Configures the PathwaysBuilder to use a custom pathway state implementation
+     * @param state The PathwayState implementation to use
+     * @returns The PathwaysBuilder instance with custom state configured
+     */
     withPathwayState(state) {
         this.logger.debug('Setting custom pathway state');
         this.pathwayState = state;
@@ -227,10 +265,9 @@ class PathwaysBuilder {
                 catch (error) {
                     // Create error object if needed
                     const errorObj = error instanceof Error ? error : new Error(String(error));
-                    this.logger.error(`Error processing pathway event`, {
+                    this.logger.error(`Error processing pathway event`, errorObj, {
                         pathway: pathwayStr,
                         eventId: data.eventId,
-                        error: errorObj.message,
                         retryCount,
                         maxRetries
                     });
@@ -280,6 +317,15 @@ class PathwaysBuilder {
             await this.pathwayState.setProcessed(data.eventId);
         }
     }
+    /**
+     * Registers a new pathway with the given contract
+     * @template F The flow type string
+     * @template E The event type string
+     * @template S The schema type extending TSchema
+     * @template W Boolean indicating if the pathway is writable (defaults to true)
+     * @param contract The pathway contract describing the pathway
+     * @returns The PathwaysBuilder instance with the new pathway registered
+     */
     register(contract) {
         const path = `${contract.flowType}/${contract.eventType}`;
         const writable = contract.writable ?? true;
@@ -328,10 +374,28 @@ class PathwaysBuilder {
         });
         return this;
     }
+    /**
+     * Gets a pathway instance by its path
+     *
+     * @template TPath The specific pathway key to retrieve
+     * @param path The pathway key to get
+     * @returns The pathway instance
+     */
     get(path) {
         this.logger.debug(`Getting pathway`, { pathway: String(path) });
         return this.pathways[path];
     }
+    /**
+     * Sets a handler function for a pathway
+     *
+     * This handler will be called whenever an event is received for the specified pathway.
+     * Only one handler can be registered per pathway in a given PathwaysBuilder instance.
+     *
+     * @template TPath The specific pathway key to handle
+     * @param path The pathway key to handle
+     * @param handler The function that will process events for this pathway
+     * @throws Error if the pathway doesn't exist or already has a handler
+     */
     handle(path, handler) {
         const pathStr = String(path);
         this.logger.debug(`Setting handler for pathway`, { pathway: pathStr });
@@ -436,12 +500,12 @@ class PathwaysBuilder {
         }
         const schema = this.schemas[path];
         if (!value_1.Value.Check(schema, data)) {
-            const error = `Invalid data for pathway ${pathStr}`;
-            this.logger.error(error, {
+            const errorMessage = `Invalid data for pathway ${pathStr}`;
+            this.logger.error(errorMessage, new Error(errorMessage), {
                 pathway: pathStr,
                 schema: schema.toString()
             });
-            throw new Error(error);
+            throw new Error(errorMessage);
         }
         // Create a copy of the metadata to avoid modifying the original
         const finalMetadata = metadata ? { ...metadata } : {};
@@ -493,6 +557,17 @@ class PathwaysBuilder {
         }
         return eventIds;
     }
+    /**
+     * Waits for a specific event to be processed
+     *
+     * This method polls the pathway state to check if an event has been processed,
+     * with a configurable timeout. It will throw an error if the timeout is exceeded.
+     *
+     * @private
+     * @param eventId The ID of the event to wait for
+     * @returns Promise that resolves when the event is processed
+     * @throws Error if the timeout is exceeded
+     */
     async waitForPathwayToBeProcessed(eventId) {
         const startTime = Date.now();
         const timeoutMs = this.timeouts[eventId] ?? this.pathwayTimeoutMs;
@@ -505,14 +580,14 @@ class PathwaysBuilder {
             attempts++;
             const elapsedTime = Date.now() - startTime;
             if (elapsedTime > timeoutMs) {
-                const error = `Pathway processing timed out after ${timeoutMs}ms for event ${eventId}`;
-                this.logger.error(error, {
+                const errorMessage = `Pathway processing timed out after ${timeoutMs}ms for event ${eventId}`;
+                this.logger.error(errorMessage, new Error(errorMessage), {
                     eventId,
                     timeoutMs,
                     elapsedTime,
                     attempts
                 });
-                throw new Error(error);
+                throw new Error(errorMessage);
             }
             if (attempts % 10 === 0) { // Log every 10 attempts (1 second)
                 this.logger.debug(`Still waiting for event to be processed`, {

package/script/pathways/index.d.ts

@@ -7,6 +7,8 @@
  * - Storage adapters (KV, Postgres)
  * - Logging
  * - Type definitions
+ *
+ * @module
  */
 export * from "./builder.js";
 export * from "./internal-pathway.state.js";

package/script/pathways/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pathways/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pathways/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}

package/script/pathways/index.js

@@ -23,6 +23,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * - Storage adapters (KV, Postgres)
  * - Logging
  * - Type definitions
+ *
+ * @module
  */
 __exportStar(require("./builder.js"), exports);
 __exportStar(require("./internal-pathway.state.js"), exports);

package/script/pathways/internal-pathway.state.d.ts

@@ -2,8 +2,6 @@ import type { PathwayState } from "./types.js";
 /**
  * Internal implementation of PathwayState interface that uses KV storage
  * for tracking processed events to prevent duplicate processing
- *
- * @implements {PathwayState}
  */
 export declare class InternalPathwayState implements PathwayState {
     /**
@@ -20,21 +18,21 @@ export declare class InternalPathwayState implements PathwayState {
      * Gets or initializes the KV adapter
      *
      * @private
-     * @returns {Promise<KvAdapter>} The KV adapter instance
+     * @returns The KV adapter instance
      */
     private getKv;
     /**
      * Checks if an event has already been processed
      *
-     * @param {string} eventId - The ID of the event to check
-     * @returns {Promise<boolean>} True if the event has been processed, false otherwise
+     * @param eventId The ID of the event to check
+     * @returns True if the event has been processed, false otherwise
      */
     isProcessed(eventId: string): Promise<boolean>;
     /**
      * Marks an event as processed
      *
-     * @param {string} eventId - The ID of the event to mark as processed
-     * @returns {Promise<void>}
+     * @param eventId The ID of the event to mark as processed
+     * @returns Promise that resolves when the operation completes
      */
     setProcessed(eventId: string): Promise<void>;
 }

package/script/pathways/internal-pathway.state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-pathway.state.d.ts","sourceRoot":"","sources":["../../src/pathways/internal-pathway.state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEvD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAA0B;IAEpC;;;;;OAKG;YACW,KAAK;IAOnB;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMpD;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAInD"}
+{"version":3,"file":"internal-pathway.state.d.ts","sourceRoot":"","sources":["../../src/pathways/internal-pathway.state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEvD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAA0B;IAEpC;;;;;OAKG;YACW,KAAK;IAOnB;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMpD;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAInD"}

package/script/pathways/internal-pathway.state.js

@@ -5,8 +5,6 @@ const kv_adapter_js_1 = require("./kv/kv-adapter.js");
 /**
  * Internal implementation of PathwayState interface that uses KV storage
  * for tracking processed events to prevent duplicate processing
- *
- * @implements {PathwayState}
  */
 class InternalPathwayState {
     constructor() {
@@ -25,7 +23,7 @@ class InternalPathwayState {
      * Gets or initializes the KV adapter
      *
      * @private
-     * @returns {Promise<KvAdapter>} The KV adapter instance
+     * @returns The KV adapter instance
      */
     async getKv() {
         if (!this.kv) {
@@ -36,8 +34,8 @@ class InternalPathwayState {
     /**
      * Checks if an event has already been processed
      *
-     * @param {string} eventId - The ID of the event to check
-     * @returns {Promise<boolean>} True if the event has been processed, false otherwise
+     * @param eventId The ID of the event to check
+     * @returns True if the event has been processed, false otherwise
      */
     async isProcessed(eventId) {
         const kv = await this.getKv();
@@ -47,8 +45,8 @@ class InternalPathwayState {
     /**
      * Marks an event as processed
      *
-     * @param {string} eventId - The ID of the event to mark as processed
-     * @returns {Promise<void>}
+     * @param eventId The ID of the event to mark as processed
+     * @returns Promise that resolves when the operation completes
      */
     async setProcessed(eventId) {
         const kv = await this.getKv();

package/script/pathways/kv/bun-kv-adapter.d.ts

@@ -3,8 +3,6 @@ import type { KvAdapter } from "./kv-adapter.js";
  * KV adapter implementation for Bun runtime
  *
  * Uses Bun's SQLite-based key-value store for storage
- *
- * @implements {KvAdapter}
  */
 export declare class BunKvAdapter implements KvAdapter {
     /**
@@ -20,16 +18,16 @@ export declare class BunKvAdapter implements KvAdapter {
      * Retrieves a value from the Bun KV store
      *
      * @template T The expected type of the stored value
-     * @param {string} key The key to retrieve
-     * @returns {T | null} The stored value or null if not found
+     * @param key The key to retrieve
+     * @returns The stored value or null if not found
      */
     get<T>(key: string): T | null;
     /**
      * Stores a value in the Bun KV store with the specified TTL
      *
-     * @param {string} key The key to store the value under
-     * @param {unknown} value The value to store
-     * @param {number} ttlMs Time-to-live in milliseconds
+     * @param key The key to store the value under
+     * @param value The value to store
+     * @param ttlMs Time-to-live in milliseconds
      */
     set(key: string, value: unknown, ttlMs: number): void;
 }

package/script/pathways/kv/bun-kv-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun-kv-adapter.d.ts","sourceRoot":"","sources":["../../../src/pathways/kv/bun-kv-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,SAAS;IAC5C;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAoB;IAEjC;;OAEG;;IAKH;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAK7B;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAGtD"}
+{"version":3,"file":"bun-kv-adapter.d.ts","sourceRoot":"","sources":["../../../src/pathways/kv/bun-kv-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;GAIG;AACH,qBAAa,YAAa,YAAW,SAAS;IAC5C;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAoB;IAEjC;;OAEG;;IAKH;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAK7B;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAGtD"}

package/script/pathways/kv/bun-kv-adapter.js

@@ -6,8 +6,6 @@ const bun_sqlite_key_value_1 = require("bun-sqlite-key-value");
  * KV adapter implementation for Bun runtime
  *
  * Uses Bun's SQLite-based key-value store for storage
- *
- * @implements {KvAdapter}
  */
 class BunKvAdapter {
     /**
@@ -30,8 +28,8 @@ class BunKvAdapter {
      * Retrieves a value from the Bun KV store
      *
      * @template T The expected type of the stored value
-     * @param {string} key The key to retrieve
-     * @returns {T | null} The stored value or null if not found
+     * @param key The key to retrieve
+     * @returns The stored value or null if not found
      */
     get(key) {
         const value = this.store.get(key);
@@ -40,9 +38,9 @@ class BunKvAdapter {
     /**
      * Stores a value in the Bun KV store with the specified TTL
      *
-     * @param {string} key The key to store the value under
-     * @param {unknown} value The value to store
-     * @param {number} ttlMs Time-to-live in milliseconds
+     * @param key The key to store the value under
+     * @param value The value to store
+     * @param ttlMs Time-to-live in milliseconds
      */
     set(key, value, ttlMs) {
         this.store.set(key, value, ttlMs);

package/script/pathways/kv/kv-adapter.d.ts

@@ -9,17 +9,17 @@ export interface KvAdapter {
      * Retrieves a value from storage by key
      *
      * @template T The expected type of the stored value
-     * @param {string} key The key to retrieve
-     * @returns {(Promise<T | null> | T | null)} The stored value or null if not found
+     * @param key The key to retrieve
+     * @returns The stored value or null if not found
      */
     get<T>(key: string): (Promise<T | null> | T | null);
     /**
      * Stores a value in storage with the specified key and TTL
      *
-     * @param {string} key The key to store the value under
-     * @param {unknown} value The value to store
-     * @param {number} ttlMs Time-to-live in milliseconds
-     * @returns {(Promise<void> | void)}
+     * @param key The key to store the value under
+     * @param value The value to store
+     * @param ttlMs Time-to-live in milliseconds
+     * @returns Promise or void when the operation completes
      */
     set(key: string, value: unknown, ttlMs: number): (Promise<void> | void);
 }
@@ -28,7 +28,7 @@ export interface KvAdapter {
  *
  * Attempts to use Bun KV adapter if running in Bun, falls back to Node adapter otherwise
  *
- * @returns {Promise<KvAdapter>} A KV adapter instance
+ * @returns A KV adapter instance for the current runtime
  */
 export declare function createKvAdapter(): Promise<KvAdapter>;
 //# sourceMappingURL=kv-adapter.d.ts.map

package/script/pathways/kv/kv-adapter.js

@@ -29,7 +29,7 @@ exports.createKvAdapter = createKvAdapter;
  *
  * Attempts to use Bun KV adapter if running in Bun, falls back to Node adapter otherwise
  *
- * @returns {Promise<KvAdapter>} A KV adapter instance
+ * @returns A KV adapter instance for the current runtime
  */
 async function createKvAdapter() {
     try {

package/script/pathways/kv/node-kv-adapter.d.ts

@@ -3,8 +3,6 @@ import type { KvAdapter } from "./kv-adapter.js";
  * KV adapter implementation for Node.js runtime
  *
  * Uses node-cache for in-memory key-value storage
- *
- * @implements {KvAdapter}
  */
 export declare class NodeKvAdapter implements KvAdapter {
     /**
@@ -16,17 +14,17 @@ export declare class NodeKvAdapter implements KvAdapter {
      * Retrieves a value from the Node.js cache
      *
      * @template T The expected type of the stored value
-     * @param {string} key The key to retrieve
-     * @returns {Promise<T | null>} The stored value or null if not found
+     * @param key The key to retrieve
+     * @returns The stored value or null if not found
      */
     get<T>(key: string): Promise<T | null>;
     /**
      * Stores a value in the Node.js cache with the specified TTL
      *
-     * @param {string} key The key to store the value under
-     * @param {unknown} value The value to store
-     * @param {number} ttlMs Time-to-live in milliseconds
-     * @returns {Promise<void>}
+     * @param key The key to store the value under
+     * @param value The value to store
+     * @param ttlMs Time-to-live in milliseconds
+     * @returns Promise that resolves when the operation completes
      */
     set(key: string, value: unknown, ttlMs: number): Promise<void>;
 }

package/script/pathways/kv/node-kv-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-kv-adapter.d.ts","sourceRoot":"","sources":["../../../src/pathways/kv/node-kv-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,SAAS;IAC7C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAmB;IAEtC;;;;;;OAMG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAK5C;;;;;;;OAOG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGrE"}
+{"version":3,"file":"node-kv-adapter.d.ts","sourceRoot":"","sources":["../../../src/pathways/kv/node-kv-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;GAIG;AACH,qBAAa,aAAc,YAAW,SAAS;IAC7C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAmB;IAEtC;;;;;;OAMG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAK5C;;;;;;;OAOG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGrE"}

package/script/pathways/kv/node-kv-adapter.js

@@ -9,8 +9,6 @@ const node_cache_1 = __importDefault(require("node-cache"));
  * KV adapter implementation for Node.js runtime
  *
  * Uses node-cache for in-memory key-value storage
- *
- * @implements {KvAdapter}
  */
 class NodeKvAdapter {
     constructor() {
@@ -29,8 +27,8 @@ class NodeKvAdapter {
      * Retrieves a value from the Node.js cache
      *
      * @template T The expected type of the stored value
-     * @param {string} key The key to retrieve
-     * @returns {Promise<T | null>} The stored value or null if not found
+     * @param key The key to retrieve
+     * @returns The stored value or null if not found
      */
     async get(key) {
         const result = await this.kv.get(key);
@@ -39,10 +37,10 @@ class NodeKvAdapter {
     /**
      * Stores a value in the Node.js cache with the specified TTL
      *
-     * @param {string} key The key to store the value under
-     * @param {unknown} value The value to store
-     * @param {number} ttlMs Time-to-live in milliseconds
-     * @returns {Promise<void>}
+     * @param key The key to store the value under
+     * @param value The value to store
+     * @param ttlMs Time-to-live in milliseconds
+     * @returns Promise that resolves when the operation completes
      */
     async set(key, value, ttlMs) {
         await this.kv.set(key, value, (ttlMs / 1000));

package/script/pathways/logger.d.ts

@@ -1,48 +1,101 @@
 /**
  * Logger interface that can be implemented by users to capture logs from pathways
  */
+/**
+ * Metadata interface for logger context
+ */
+export interface LoggerMeta {
+    [key: string]: unknown;
+    label?: never;
+    level?: never;
+    message?: never;
+    timestamp?: never;
+}
 export interface Logger {
     /**
      * Log debug information
      * @param message The message to log
      * @param context Optional context data to include
      */
-    debug(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: LoggerMeta): void;
     /**
      * Log informational messages
      * @param message The message to log
      * @param context Optional context data to include
      */
-    info(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: LoggerMeta): void;
     /**
      * Log warning messages
      * @param message The message to log
      * @param context Optional context data to include
      */
-    warn(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: LoggerMeta): void;
     /**
      * Log error messages
      * @param message The message to log
+     * @param error Optional error object
      * @param context Optional context data to include
      */
-    error(message: string, context?: Record<string, unknown>): void;
+    error(message: string, error?: Error, context?: LoggerMeta): void;
 }
 /**
  * A default console logger that logs to the console
  */
 export declare class ConsoleLogger implements Logger {
-    debug(message: string, context?: Record<string, unknown>): void;
-    info(message: string, context?: Record<string, unknown>): void;
-    warn(message: string, context?: Record<string, unknown>): void;
-    error(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log debug information to the console
+     * @param message The message to log
+     * @param context Optional context data to include
+     */
+    debug(message: string, context?: LoggerMeta): void;
+    /**
+     * Log informational messages to the console
+     * @param message The message to log
+     * @param context Optional context data to include
+     */
+    info(message: string, context?: LoggerMeta): void;
+    /**
+     * Log warning messages to the console
+     * @param message The message to log
+     * @param context Optional context data to include
+     */
+    warn(message: string, context?: LoggerMeta): void;
+    /**
+     * Log error messages to the console
+     * @param message The message to log
+     * @param error Optional error object
+     * @param context Optional context data to include
+     */
+    error(message: string, error?: Error, context?: LoggerMeta): void;
 }
 /**
  * A no-operation logger that does nothing
  */
 export declare class NoopLogger implements Logger {
-    debug(_message: string, _context?: Record<string, unknown>): void;
-    info(_message: string, _context?: Record<string, unknown>): void;
-    warn(_message: string, _context?: Record<string, unknown>): void;
-    error(_message: string, _context?: Record<string, unknown>): void;
+    /**
+     * No-op debug log
+     * @param _message The message to log (ignored)
+     * @param _context Optional context data (ignored)
+     */
+    debug(_message: string, _context?: LoggerMeta): void;
+    /**
+     * No-op info log
+     * @param _message The message to log (ignored)
+     * @param _context Optional context data (ignored)
+     */
+    info(_message: string, _context?: LoggerMeta): void;
+    /**
+     * No-op warning log
+     * @param _message The message to log (ignored)
+     * @param _context Optional context data (ignored)
+     */
+    warn(_message: string, _context?: LoggerMeta): void;
+    /**
+     * No-op error log
+     * @param _message The message to log (ignored)
+     * @param _error Optional error object (ignored)
+     * @param _context Optional context data (ignored)
+     */
+    error(_message: string, _error?: Error, _context?: LoggerMeta): void;
 }
 //# sourceMappingURL=logger.d.ts.map

package/script/pathways/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/pathways/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAE/D;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAE9D;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAE9D;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAChE;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI/D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI9D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI9D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAGhE;AAED;;GAEG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IACjE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAChE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAChE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAClE"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/pathways/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IACtB,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,OAAO,CAAC,EAAE,KAAK,CAAA;IACf,SAAS,CAAC,EAAE,KAAK,CAAA;CAClB;AAED,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAElD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAEjD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAEjD;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;CAClE;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;CAGlE;AAED;;GAEG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,UAAU,GAAG,IAAI;IAEpD;;;;OAIG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,UAAU,GAAG,IAAI;IAEnD;;;;OAIG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,UAAU,GAAG,IAAI;IAEnD;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,UAAU,GAAG,IAAI;CACrE"}

package/script/pathways/logger.js

@@ -1,21 +1,45 @@
 "use strict";
+/**
+ * Logger interface that can be implemented by users to capture logs from pathways
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NoopLogger = exports.ConsoleLogger = void 0;
 /**
  * A default console logger that logs to the console
  */
 class ConsoleLogger {
+    /**
+     * Log debug information to the console
+     * @param message The message to log
+     * @param context Optional context data to include
+     */
     debug(message, context) {
         console.debug(message, context ? JSON.stringify(context) : '');
     }
+    /**
+     * Log informational messages to the console
+     * @param message The message to log
+     * @param context Optional context data to include
+     */
     info(message, context) {
         console.info(message, context ? JSON.stringify(context) : '');
     }
+    /**
+     * Log warning messages to the console
+     * @param message The message to log
+     * @param context Optional context data to include
+     */
     warn(message, context) {
         console.warn(message, context ? JSON.stringify(context) : '');
     }
-    error(message, context) {
-        console.error(message, context ? JSON.stringify(context) : '');
+    /**
+     * Log error messages to the console
+     * @param message The message to log
+     * @param error Optional error object
+     * @param context Optional context data to include
+     */
+    error(message, error, context) {
+        console.error(message, error, context ? JSON.stringify(context) : '');
     }
 }
 exports.ConsoleLogger = ConsoleLogger;
@@ -23,9 +47,30 @@ exports.ConsoleLogger = ConsoleLogger;
  * A no-operation logger that does nothing
  */
 class NoopLogger {
+    /**
+     * No-op debug log
+     * @param _message The message to log (ignored)
+     * @param _context Optional context data (ignored)
+     */
     debug(_message, _context) { }
+    /**
+     * No-op info log
+     * @param _message The message to log (ignored)
+     * @param _context Optional context data (ignored)
+     */
     info(_message, _context) { }
+    /**
+     * No-op warning log
+     * @param _message The message to log (ignored)
+     * @param _context Optional context data (ignored)
+     */
     warn(_message, _context) { }
-    error(_message, _context) { }
+    /**
+     * No-op error log
+     * @param _message The message to log (ignored)
+     * @param _error Optional error object (ignored)
+     * @param _context Optional context data (ignored)
+     */
+    error(_message, _error, _context) { }
 }
 exports.NoopLogger = NoopLogger;