@flowcore/pathways 0.7.0 → 0.9.0

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

@@ -27,9 +27,39 @@ exports.createKvAdapter = createKvAdapter;
 /**
  * Creates an appropriate KV adapter based on the runtime environment
  *
- * Attempts to use Bun KV adapter if running in Bun, falls back to Node adapter otherwise
+ * This function automatically detects the current runtime environment and creates
+ * the most suitable KV adapter implementation:
+ *
+ * - In Bun: Returns a BunKvAdapter using Bun's built-in KV store
+ * - In Deno with KV access: Returns a DenoKvAdapter
+ * - Otherwise: Returns a NodeKvAdapter using an in-memory cache
+ *
+ * Using this factory function rather than directly instantiating a specific adapter
+ * implementation makes your code more portable across different JavaScript runtimes.
+ *
+ * The adapter is lazily initialized, so any necessary setup only happens when
+ * you first interact with the adapter.
  *
  * @returns A KV adapter instance for the current runtime
+ *
+ * @example
+ * ```typescript
+ * // Create a runtime-specific KV adapter
+ * const kv = await createKvAdapter();
+ *
+ * // Use with PathwaysBuilder for session user resolvers
+ * const pathways = new PathwaysBuilder({
+ *   baseUrl: "https://api.flowcore.io",
+ *   tenant: "my-tenant",
+ *   dataCore: "my-data-core",
+ *   apiKey: "my-api-key",
+ *   sessionUserResolvers: kv
+ * });
+ *
+ * // Use as a general-purpose key-value store
+ * await kv.set("cache:user:123", userData, 60 * 60 * 1000); // 1 hour TTL
+ * const cachedUser = await kv.get("cache:user:123");
+ * ```
  */
 async function createKvAdapter() {
     try {

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

@@ -53,6 +53,47 @@ export type PostgresPathwayStateConfig = PostgresPathwayStateConnectionStringCon
  *
  * This class provides persistent storage of pathway state using a PostgreSQL database,
  * which allows for state to be shared across multiple instances of the application.
+ *
+ * Key features:
+ * - Persistent storage of pathway processing state across application restarts
+ * - Automatic table and index creation
+ * - Configurable TTL (time-to-live) for processed events
+ * - Automatic cleanup of expired records
+ * - Support for horizontal scaling across multiple instances
+ * - Connection pooling for efficient database usage
+ *
+ * Use cases:
+ * - Production deployments that require durability and persistence
+ * - Distributed systems where multiple instances process events
+ * - Applications with high reliability requirements
+ * - Scenarios where in-memory state is insufficient
+ *
+ * @example
+ * ```typescript
+ * // Create PostgreSQL pathway state with connection string
+ * const postgresState = createPostgresPathwayState({
+ *   connectionString: "postgres://user:password@localhost:5432/mydb",
+ *   tableName: "event_processing_state", // Optional
+ *   ttlMs: 24 * 60 * 60 * 1000 // 24 hours (optional)
+ * });
+ *
+ * // Or with individual parameters
+ * const postgresState = createPostgresPathwayState({
+ *   host: "localhost",
+ *   port: 5432,
+ *   user: "postgres",
+ *   password: "postgres",
+ *   database: "mydb",
+ *   ssl: false,
+ *   tableName: "event_processing_state", // Optional
+ *   ttlMs: 30 * 60 * 1000 // 30 minutes (optional)
+ * });
+ *
+ * // Use with PathwaysBuilder
+ * const pathways = new PathwaysBuilder({
+ *   // ... other config
+ * }).withPathwayState(postgresState);
+ * ```
  */
 export declare class PostgresPathwayState implements PathwayState {
     private config;
@@ -102,15 +143,66 @@ export declare class PostgresPathwayState implements PathwayState {
     /**
      * Checks if an event has already been processed
      *
+     * This method checks the PostgreSQL database to determine if an event with the given ID
+     * has been marked as processed. If the event exists in the database and is marked as processed,
+     * the method returns true.
+     *
+     * Before performing the check, this method also triggers cleanup of expired event records
+     * to maintain database performance.
+     *
      * @param {string} eventId - The ID of the event to check
      * @returns {Promise<boolean>} True if the event has been processed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Check if an event has been processed
+     * const processed = await postgresState.isProcessed("event-123");
+     * if (processed) {
+     *   console.log("Event has already been processed, skipping");
+     * } else {
+     *   console.log("Processing event for the first time");
+     *   // Process the event
+     *   await processEvent(event);
+     *   // Mark as processed
+     *   await postgresState.setProcessed("event-123");
+     * }
+     * ```
      */
     isProcessed(eventId: string): Promise<boolean>;
     /**
      * Marks an event as processed
      *
+     * This method inserts or updates a record in the PostgreSQL database to mark an event
+     * as processed. If the event already exists in the database, the record is updated;
+     * otherwise, a new record is created.
+     *
+     * Each processed event is stored with an expiration timestamp based on the configured TTL.
+     * After this time elapses, the record may be automatically removed during cleanup operations.
+     *
      * @param {string} eventId - The ID of the event to mark as processed
      * @returns {Promise<void>}
+     *
+     * @example
+     * ```typescript
+     * // Process an event and mark it as processed
+     * async function handleEvent(event) {
+     *   // Check if already processed to implement idempotency
+     *   if (await postgresState.isProcessed(event.id)) {
+     *     return; // Skip already processed events
+     *   }
+     *
+     *   try {
+     *     // Process the event
+     *     await processEvent(event);
+     *
+     *     // Mark as processed after successful processing
+     *     await postgresState.setProcessed(event.id);
+     *   } catch (error) {
+     *     console.error("Failed to process event:", error);
+     *     // Not marking as processed, so it can be retried
+     *   }
+     * }
+     * ```
      */
     setProcessed(eventId: string): Promise<void>;
     /**
@@ -130,8 +222,46 @@ export declare class PostgresPathwayState implements PathwayState {
 /**
  * Creates a new PostgreSQL pathway state instance
  *
- * @param config The PostgreSQL configuration
+ * This is a factory function that simplifies the creation of PostgresPathwayState instances.
+ * It accepts either a connection string or individual connection parameters, along with
+ * optional configuration for table name and TTL.
+ *
+ * The PostgresPathwayState is lazily initialized, meaning the database connection and
+ * table creation only happen when the first operation is performed. This makes it safe
+ * to create instances early in the application lifecycle.
+ *
+ * @param config The PostgreSQL configuration (connection string or parameters)
  * @returns A new PostgresPathwayState instance
+ *
+ * @example
+ * ```typescript
+ * // With connection string
+ * const state = createPostgresPathwayState({
+ *   connectionString: "postgres://user:pass@localhost:5432/db?sslmode=require"
+ * });
+ *
+ * // With individual parameters
+ * const state = createPostgresPathwayState({
+ *   host: "localhost",
+ *   port: 5432,
+ *   user: "postgres",
+ *   password: "secret",
+ *   database: "events_db",
+ *   ssl: true
+ * });
+ *
+ * // With custom table name and TTL
+ * const state = createPostgresPathwayState({
+ *   connectionString: "postgres://user:pass@localhost:5432/db",
+ *   tableName: "my_custom_event_state",
+ *   ttlMs: 7 * 24 * 60 * 60 * 1000 // 1 week
+ * });
+ *
+ * // Use with PathwaysBuilder
+ * const pathways = new PathwaysBuilder({
+ *   // Other config
+ * }).withPathwayState(state);
+ * ```
  */
 export declare function createPostgresPathwayState(config: PostgresPathwayStateConfig): PostgresPathwayState;
 //# sourceMappingURL=postgres-pathway-state.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"postgres-pathway-state.d.ts","sourceRoot":"","sources":["../../../src/pathways/postgres/postgres-pathway-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD;;GAEG;AACH,MAAM,WAAW,0CAA0C;IACzD,gHAAgH;IAChH,gBAAgB,EAAE,MAAM,CAAC;IAEzB,yEAAyE;IACzE,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,GAAG,CAAC,EAAE,KAAK,CAAC;IAEZ,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oCAAoC;IACnD,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,KAAK,CAAC;IAEzB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,OAAO,CAAC;IAEd,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,0BAA0B,GAAG,0CAA0C,GAAG,oCAAoC,CAAC;AAE3H;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IA0C3C,OAAO,CAAC,MAAM;IAzC1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEvD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAmB;IAE7D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAkB;IAElC;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAS;IAEtB;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;gBACiB,MAAM,EAAE,0BAA0B;IAMtD;;;;;OAKG;YACW,UAAU;IA0CxB;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAcpD;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelD;;;;;OAKG;YACW,cAAc;IAQ5B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,0BAA0B,GAAG,oBAAoB,CAGnG"}
+{"version":3,"file":"postgres-pathway-state.d.ts","sourceRoot":"","sources":["../../../src/pathways/postgres/postgres-pathway-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD;;GAEG;AACH,MAAM,WAAW,0CAA0C;IACzD,gHAAgH;IAChH,gBAAgB,EAAE,MAAM,CAAC;IAEzB,yEAAyE;IACzE,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,GAAG,CAAC,EAAE,KAAK,CAAC;IAEZ,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oCAAoC;IACnD,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,KAAK,CAAC;IAEzB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,OAAO,CAAC;IAEd,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,0BAA0B,GAAG,0CAA0C,GAAG,oCAAoC,CAAC;AAE3H;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IA0C3C,OAAO,CAAC,MAAM;IAzC1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEvD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAmB;IAE7D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAkB;IAElC;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAS;IAEtB;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;gBACiB,MAAM,EAAE,0BAA0B;IAMtD;;;;;OAKG;YACW,UAAU;IA0CxB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAcpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelD;;;;;OAKG;YACW,cAAc;IAQ5B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,0BAA0B,GAAG,oBAAoB,CAGnG"}

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

@@ -8,6 +8,47 @@ const postgres_adapter_js_1 = require("./postgres-adapter.js");
  *
  * This class provides persistent storage of pathway state using a PostgreSQL database,
  * which allows for state to be shared across multiple instances of the application.
+ *
+ * Key features:
+ * - Persistent storage of pathway processing state across application restarts
+ * - Automatic table and index creation
+ * - Configurable TTL (time-to-live) for processed events
+ * - Automatic cleanup of expired records
+ * - Support for horizontal scaling across multiple instances
+ * - Connection pooling for efficient database usage
+ *
+ * Use cases:
+ * - Production deployments that require durability and persistence
+ * - Distributed systems where multiple instances process events
+ * - Applications with high reliability requirements
+ * - Scenarios where in-memory state is insufficient
+ *
+ * @example
+ * ```typescript
+ * // Create PostgreSQL pathway state with connection string
+ * const postgresState = createPostgresPathwayState({
+ *   connectionString: "postgres://user:password@localhost:5432/mydb",
+ *   tableName: "event_processing_state", // Optional
+ *   ttlMs: 24 * 60 * 60 * 1000 // 24 hours (optional)
+ * });
+ *
+ * // Or with individual parameters
+ * const postgresState = createPostgresPathwayState({
+ *   host: "localhost",
+ *   port: 5432,
+ *   user: "postgres",
+ *   password: "postgres",
+ *   database: "mydb",
+ *   ssl: false,
+ *   tableName: "event_processing_state", // Optional
+ *   ttlMs: 30 * 60 * 1000 // 30 minutes (optional)
+ * });
+ *
+ * // Use with PathwaysBuilder
+ * const pathways = new PathwaysBuilder({
+ *   // ... other config
+ * }).withPathwayState(postgresState);
+ * ```
  */
 class PostgresPathwayState {
     /**
@@ -113,8 +154,30 @@ class PostgresPathwayState {
     /**
      * Checks if an event has already been processed
      *
+     * This method checks the PostgreSQL database to determine if an event with the given ID
+     * has been marked as processed. If the event exists in the database and is marked as processed,
+     * the method returns true.
+     *
+     * Before performing the check, this method also triggers cleanup of expired event records
+     * to maintain database performance.
+     *
      * @param {string} eventId - The ID of the event to check
      * @returns {Promise<boolean>} True if the event has been processed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Check if an event has been processed
+     * const processed = await postgresState.isProcessed("event-123");
+     * if (processed) {
+     *   console.log("Event has already been processed, skipping");
+     * } else {
+     *   console.log("Processing event for the first time");
+     *   // Process the event
+     *   await processEvent(event);
+     *   // Mark as processed
+     *   await postgresState.setProcessed("event-123");
+     * }
+     * ```
      */
     async isProcessed(eventId) {
         await this.initialize();
@@ -129,8 +192,37 @@ class PostgresPathwayState {
     /**
      * Marks an event as processed
      *
+     * This method inserts or updates a record in the PostgreSQL database to mark an event
+     * as processed. If the event already exists in the database, the record is updated;
+     * otherwise, a new record is created.
+     *
+     * Each processed event is stored with an expiration timestamp based on the configured TTL.
+     * After this time elapses, the record may be automatically removed during cleanup operations.
+     *
      * @param {string} eventId - The ID of the event to mark as processed
      * @returns {Promise<void>}
+     *
+     * @example
+     * ```typescript
+     * // Process an event and mark it as processed
+     * async function handleEvent(event) {
+     *   // Check if already processed to implement idempotency
+     *   if (await postgresState.isProcessed(event.id)) {
+     *     return; // Skip already processed events
+     *   }
+     *
+     *   try {
+     *     // Process the event
+     *     await processEvent(event);
+     *
+     *     // Mark as processed after successful processing
+     *     await postgresState.setProcessed(event.id);
+     *   } catch (error) {
+     *     console.error("Failed to process event:", error);
+     *     // Not marking as processed, so it can be retried
+     *   }
+     * }
+     * ```
      */
     async setProcessed(eventId) {
         await this.initialize();
@@ -193,8 +285,46 @@ Object.defineProperty(PostgresPathwayState, "DEFAULT_TABLE_NAME", {
 /**
  * Creates a new PostgreSQL pathway state instance
  *
- * @param config The PostgreSQL configuration
+ * This is a factory function that simplifies the creation of PostgresPathwayState instances.
+ * It accepts either a connection string or individual connection parameters, along with
+ * optional configuration for table name and TTL.
+ *
+ * The PostgresPathwayState is lazily initialized, meaning the database connection and
+ * table creation only happen when the first operation is performed. This makes it safe
+ * to create instances early in the application lifecycle.
+ *
+ * @param config The PostgreSQL configuration (connection string or parameters)
  * @returns A new PostgresPathwayState instance
+ *
+ * @example
+ * ```typescript
+ * // With connection string
+ * const state = createPostgresPathwayState({
+ *   connectionString: "postgres://user:pass@localhost:5432/db?sslmode=require"
+ * });
+ *
+ * // With individual parameters
+ * const state = createPostgresPathwayState({
+ *   host: "localhost",
+ *   port: 5432,
+ *   user: "postgres",
+ *   password: "secret",
+ *   database: "events_db",
+ *   ssl: true
+ * });
+ *
+ * // With custom table name and TTL
+ * const state = createPostgresPathwayState({
+ *   connectionString: "postgres://user:pass@localhost:5432/db",
+ *   tableName: "my_custom_event_state",
+ *   ttlMs: 7 * 24 * 60 * 60 * 1000 // 1 week
+ * });
+ *
+ * // Use with PathwaysBuilder
+ * const pathways = new PathwaysBuilder({
+ *   // Other config
+ * }).withPathwayState(state);
+ * ```
  */
 function createPostgresPathwayState(config) {
     const state = new PostgresPathwayState(config);

package/script/pathways/session-pathway.d.ts

@@ -0,0 +1,99 @@
+import type { PathwaysBuilder, UserIdResolver } from "./builder.js";
+import type { EventMetadata, PathwayWriteOptions } from "./types.js";
+/**
+ * SessionPathwayBuilder wraps a PathwaysBuilder instance and automatically
+ * associates a session ID with all pathway writes.
+ *
+ * This provides a convenient way to track operations within a user session
+ * by automatically including the session ID in metadata.
+ *
+ * Key features:
+ * - Automatic session ID generation if none is provided
+ * - Cross-platform UUID generation (works in Deno, Bun, and Node.js)
+ * - Simple API for accessing the current session ID
+ * - Convenient integration with session-specific user resolvers
+ * - Automatic inclusion of session ID in all write operations
+ * - Support for overriding the session ID on specific writes
+ *
+ * Use cases:
+ * - Tracking user actions across multiple pathway writes
+ * - Connecting related events in a single user session
+ * - Supporting multi-user environments where different users' operations need to be tracked separately
+ * - Building user activity logs with session grouping
+ *
+ * @example
+ * ```typescript
+ * // Create a session pathway with auto-generated ID
+ * const session = new SessionPathwayBuilder(pathwaysBuilder);
+ *
+ * // Get the auto-generated session ID
+ * const sessionId = session.getSessionId();
+ *
+ * // Register a user resolver for this session
+ * session.withUserResolver(async () => getCurrentUserId());
+ *
+ * // Write events with session context
+ * await session.write("order/placed", orderData);
+ * await session.write("user/action", actionData);
+ *
+ * // All events will be associated with the same session ID
+ * ```
+ */
+export declare class SessionPathwayBuilder<TPathway extends Record<string, unknown> = {}, TWritablePaths extends keyof TPathway = never> {
+    private readonly pathwaysBuilder;
+    private readonly sessionId;
+    /**
+     * Creates a new SessionPathwayBuilder
+     *
+     * @param pathwaysBuilder The configured PathwaysBuilder instance to wrap
+     * @param sessionId Optional session ID to associate with all operations. If not provided, one will be generated automatically.
+     */
+    constructor(pathwaysBuilder: PathwaysBuilder<TPathway, TWritablePaths>, sessionId?: string);
+    /**
+     * Gets the current session ID
+     *
+     * @returns The session ID associated with this instance
+     */
+    getSessionId(): string;
+    /**
+     * Registers a user resolver for this session
+     *
+     * This is a convenience method that calls `pathwaysBuilder.withSessionUserResolver`
+     * with the current session ID, allowing you to set up a resolver specific to this session
+     * without having to manually pass the session ID.
+     *
+     * The resolver will be called whenever events are written through this session,
+     * and the resolved user ID will be included in the event metadata.
+     *
+     * @param resolver The function that resolves to the user ID for this session
+     * @returns The SessionPathwayBuilder instance for chaining
+     *
+     * @throws Error if the underlying PathwaysBuilder does not have session user resolvers configured
+     *
+     * @example
+     * ```typescript
+     * const session = new SessionPathwayBuilder(pathwaysBuilder);
+     *
+     * // Register a user resolver for this session
+     * session.withUserResolver(async () => {
+     *   // Get the user ID associated with this session
+     *   return getUserIdFromSession();
+     * });
+     *
+     * // When writing events, the user ID will be automatically included
+     * await session.write("user/action", actionData);
+     * ```
+     */
+    withUserResolver(resolver: UserIdResolver): this;
+    /**
+     * Writes data to a pathway, proxying to the underlying PathwaysBuilder
+     *
+     * @param path The pathway to write to
+     * @param data The data to write
+     * @param metadata Optional metadata to include with the event
+     * @param options Optional write options
+     * @returns A promise that resolves to the event ID(s)
+     */
+    write<TPath extends TWritablePaths>(path: TPath, data: TPathway[TPath], metadata?: EventMetadata, options?: PathwayWriteOptions): Promise<string | string[]>;
+}
+//# sourceMappingURL=session-pathway.d.ts.map

package/script/pathways/session-pathway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-pathway.d.ts","sourceRoot":"","sources":["../../src/pathways/session-pathway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAqBrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,qBAAqB,CAEhC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,EAC7C,cAAc,SAAS,MAAM,QAAQ,GAAG,KAAK;IAE7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA4C;IAC5E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;;;;OAKG;gBAED,eAAe,EAAE,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC,EAC1D,SAAS,CAAC,EAAE,MAAM;IAMpB;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAKhD;;;;;;;;OAQG;IACG,KAAK,CAAC,KAAK,SAAS,cAAc,EACtC,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,EACrB,QAAQ,CAAC,EAAE,aAAa,EACxB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;CAU9B"}

package/script/pathways/session-pathway.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionPathwayBuilder = void 0;
+/**
+ * Generates a UUID v4 in a cross-platform compatible way (Deno, Bun, Node.js)
+ * @returns A random UUID v4 string
+ */
+function generateUUID() {
+    // Check for Deno or browser crypto.randomUUID support
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback to manual UUID generation (compatible with all platforms)
+    // Implementation based on RFC4122 version 4
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = Math.random() * 16 | 0;
+        const v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}
+/**
+ * SessionPathwayBuilder wraps a PathwaysBuilder instance and automatically
+ * associates a session ID with all pathway writes.
+ *
+ * This provides a convenient way to track operations within a user session
+ * by automatically including the session ID in metadata.
+ *
+ * Key features:
+ * - Automatic session ID generation if none is provided
+ * - Cross-platform UUID generation (works in Deno, Bun, and Node.js)
+ * - Simple API for accessing the current session ID
+ * - Convenient integration with session-specific user resolvers
+ * - Automatic inclusion of session ID in all write operations
+ * - Support for overriding the session ID on specific writes
+ *
+ * Use cases:
+ * - Tracking user actions across multiple pathway writes
+ * - Connecting related events in a single user session
+ * - Supporting multi-user environments where different users' operations need to be tracked separately
+ * - Building user activity logs with session grouping
+ *
+ * @example
+ * ```typescript
+ * // Create a session pathway with auto-generated ID
+ * const session = new SessionPathwayBuilder(pathwaysBuilder);
+ *
+ * // Get the auto-generated session ID
+ * const sessionId = session.getSessionId();
+ *
+ * // Register a user resolver for this session
+ * session.withUserResolver(async () => getCurrentUserId());
+ *
+ * // Write events with session context
+ * await session.write("order/placed", orderData);
+ * await session.write("user/action", actionData);
+ *
+ * // All events will be associated with the same session ID
+ * ```
+ */
+class SessionPathwayBuilder {
+    /**
+     * Creates a new SessionPathwayBuilder
+     *
+     * @param pathwaysBuilder The configured PathwaysBuilder instance to wrap
+     * @param sessionId Optional session ID to associate with all operations. If not provided, one will be generated automatically.
+     */
+    constructor(pathwaysBuilder, sessionId) {
+        Object.defineProperty(this, "pathwaysBuilder", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "sessionId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.pathwaysBuilder = pathwaysBuilder;
+        this.sessionId = sessionId ?? generateUUID();
+    }
+    /**
+     * Gets the current session ID
+     *
+     * @returns The session ID associated with this instance
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Registers a user resolver for this session
+     *
+     * This is a convenience method that calls `pathwaysBuilder.withSessionUserResolver`
+     * with the current session ID, allowing you to set up a resolver specific to this session
+     * without having to manually pass the session ID.
+     *
+     * The resolver will be called whenever events are written through this session,
+     * and the resolved user ID will be included in the event metadata.
+     *
+     * @param resolver The function that resolves to the user ID for this session
+     * @returns The SessionPathwayBuilder instance for chaining
+     *
+     * @throws Error if the underlying PathwaysBuilder does not have session user resolvers configured
+     *
+     * @example
+     * ```typescript
+     * const session = new SessionPathwayBuilder(pathwaysBuilder);
+     *
+     * // Register a user resolver for this session
+     * session.withUserResolver(async () => {
+     *   // Get the user ID associated with this session
+     *   return getUserIdFromSession();
+     * });
+     *
+     * // When writing events, the user ID will be automatically included
+     * await session.write("user/action", actionData);
+     * ```
+     */
+    withUserResolver(resolver) {
+        this.pathwaysBuilder.withSessionUserResolver(this.sessionId, resolver);
+        return this;
+    }
+    /**
+     * Writes data to a pathway, proxying to the underlying PathwaysBuilder
+     *
+     * @param path The pathway to write to
+     * @param data The data to write
+     * @param metadata Optional metadata to include with the event
+     * @param options Optional write options
+     * @returns A promise that resolves to the event ID(s)
+     */
+    async write(path, data, metadata, options) {
+        // Create new options object with session ID
+        const finalOptions = options ? { ...options } : {};
+        // Always include the session ID in the options
+        finalOptions.sessionId = options?.sessionId ?? this.sessionId;
+        // The PathwaysBuilder will handle session-specific user resolvers
+        return await this.pathwaysBuilder.write(path, data, metadata, finalOptions);
+    }
+}
+exports.SessionPathwayBuilder = SessionPathwayBuilder;

package/script/pathways/types.d.ts

@@ -132,6 +132,11 @@ export type PathwayWriteOptions = WebhookSendOptions & {
      * @default "user"
      */
     auditMode?: "user" | "system";
+    /**
+     * Session ID for this write operation
+     * Used to associate the operation with a specific session
+     */
+    sessionId?: string;
 };
 export {};
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pathways/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAEzF;;;GAGG;AACH,KAAK,uBAAuB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IACnD,QAAQ,CAAC,yBAAyB,EAAE,wGAAwG,CAAA;CAC7I,CAAA;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO;IACpF;;OAEG;IACH,QAAQ,EAAE,CAAC,CAAA;IAEX;;OAEG;IACH,SAAS,EAAE,CAAC,CAAA;IAEZ;;OAEG;IACH,MAAM,EAAE,CAAC,CAAA;IAET;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAE3B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,CAAA;AAExE;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAAG;AAEjE;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,YAAY,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAE1I;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;AAElI;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,UAAU,SAAS,OAAO,IAAI,UAAU,SAAS,KAAK,GAAG,uBAAuB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAErI;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;OAIG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;IAE9D;;;OAGG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;CAC1D,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG;IACrD;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IAEvB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEhC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;CAC9B,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pathways/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAEzF;;;GAGG;AACH,KAAK,uBAAuB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IACnD,QAAQ,CAAC,yBAAyB,EAAE,wGAAwG,CAAA;CAC7I,CAAA;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO;IACpF;;OAEG;IACH,QAAQ,EAAE,CAAC,CAAA;IAEX;;OAEG;IACH,SAAS,EAAE,CAAC,CAAA;IAEZ;;OAEG;IACH,MAAM,EAAE,CAAC,CAAA;IAET;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAE3B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,CAAA;AAExE;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAAG;AAEjE;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,YAAY,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAE1I;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;AAElI;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,UAAU,SAAS,OAAO,IAAI,UAAU,SAAS,KAAK,GAAG,uBAAuB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAErI;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;OAIG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;IAE9D;;;OAGG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;CAC1D,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG;IACrD;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IAEvB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEhC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAE7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA"}