@nlozgachev/pipelined 0.47.0 → 0.49.0

package/README.md

@@ -18,11 +18,12 @@ In mainstream TypeScript, code is often burdened by implicit control flow: unche
 manual null propagation, and unhandled asynchronous failures. `pipelined` turns these complex
 runtime states into simple, transparent data structures that compose. By representing optionality as
 `Maybe`, failures as `Result`, lazy asynchronous pipelines as `Task.Result`, and repeated stateful
-interactions as `Op`, the library helps disentangle business logic from control mechanics.
+interactions as `Op` and `Stream`, the library helps disentangle business logic from control
+mechanics.
 
 To support these patterns without introducing bloat, the library is designed to be lightweight,
-zero-dependency, and fully tree-shakeable. The core module (`/core`) is under 14 KB gzipped, and the
-entire toolkit is under 21 KB gzipped, making it equally suitable for client and server
+zero-dependency, and fully tree-shakeable. The core module (`/core`) is under 16 KB gzipped, and the
+entire toolkit is under 25 KB gzipped, making it equally suitable for client and server
 environments.
 
 ## Documentation
@@ -303,6 +304,57 @@ The system supports a variety of built-in strategies — `restartable`, `exclusi
 `throttled`, `queue`, `buffered`, `concurrent`, `keyed`, and `once` — making the integration of
 complex async scenarios highly predictable.
 
+## Example: typed event streaming and sequence reduction
+
+Decoupling event producers from stateful event consumers often leads to untyped event emitters or
+complex ad-hoc state machines. `Stream` models event pipelines with typed message schemas, sequence
+pattern matching, and state reduction:
+
+```ts
+import { Stream } from "@nlozgachev/pipelined/core";
+
+type UserFlowMessages = {
+  sessionStarted: { sessionId: string };
+  stepCompleted: { stepName: string };
+  flowFinished: { totalTimeMs: number };
+};
+
+const flowStream = Stream.make<UserFlowMessages>();
+
+// Match sequence: sessionStarted -> stepCompleted -> flowFinished
+const sub = Stream.listen(
+  flowStream,
+  ["sessionStarted", "stepCompleted", "flowFinished"],
+  { ordered: true },
+).reduce(
+  (msg, state) => {
+    if (msg.kind === "flowFinished") {
+      return { completedFlows: state.completedFlows + 1 };
+    }
+    return state;
+  },
+  { completedFlows: 0 },
+);
+
+// Emit typed messages to the stream
+Stream.emit(flowStream, {
+  kind: "sessionStarted",
+  value: { sessionId: "sess-101" },
+});
+
+Stream.emit(flowStream, {
+  kind: "stepCompleted",
+  value: { stepName: "onboarding" },
+});
+
+Stream.emit(flowStream, {
+  kind: "flowFinished",
+  value: { totalTimeMs: 4200 },
+});
+
+sub.getState(); // { completedFlows: 1 }
+```
+
 ## What is included
 
 The library covers the full spectrum of state and control flow scenarios encountered in production
@@ -322,8 +374,9 @@ provides a strongly-typed, immutable two-element pair.
 handled by `Task.Result`, `Task.Maybe`, and `Task.Validation`. For managing stateful, recurring
 asynchronous operations with complex scheduling, `Op` implements named concurrency strategies such
 as `restartable`, `exclusive`, `debounced`, `throttled`, and `queue`, handling retries, timeouts,
-and signal propagation automatically. `Deferred` represents a lightweight, infallible asynchronous
-value that is guaranteed to always resolve without rejection.
+and signal propagation automatically. `Stream` provides typed event streaming, sequence pattern
+matching, state reduction, and structural forwarding across channels. `Deferred` represents a
+lightweight, infallible asynchronous value that is guaranteed to always resolve without rejection.
 
 ### Optics and environment state
 

package/dist/Duration-B8joKzro.d.mts

@@ -0,0 +1,181 @@
+declare const _brand: unique symbol;
+/**
+ * Brand<K, T> creates a nominal type by tagging T with a phantom brand K.
+ * Prevents accidentally mixing up values that share the same underlying type.
+ *
+ * @example
+ * ```ts
+ * type UserId = Brand<"UserId", string>;
+ * type ProductId = Brand<"ProductId", string>;
+ *
+ * const toUserId = Brand.wrap<"UserId", string>();
+ * const toProductId = Brand.wrap<"ProductId", string>();
+ *
+ * const userId: UserId = toUserId("user-123");
+ * const productId: ProductId = toProductId("prod-456");
+ *
+ * // Type error: ProductId is not assignable to UserId
+ * // const wrong: UserId = productId;
+ * ```
+ */
+type Brand<K extends string, T> = T & {
+    readonly [_brand]: K;
+};
+declare namespace Brand {
+    /**
+     * Returns a constructor that wraps a value of type T in brand K.
+     * The resulting function performs an unchecked cast — only use when the raw
+     * value is known to satisfy the brand's invariants.
+     *
+     * @example
+     * ```ts
+     * type PositiveNumber = Brand<"PositiveNumber", number>;
+     * const toPositiveNumber = Brand.wrap<"PositiveNumber", number>();
+     *
+     * const n: PositiveNumber = toPositiveNumber(42);
+     * ```
+     */
+    const wrap: <K extends string, T>() => (value: T) => Brand<K, T>;
+    /**
+     * Strips the brand and returns the underlying value.
+     * Since Brand<K, T> extends T this is rarely needed, but can improve readability.
+     *
+     * @example
+     * ```ts
+     * type UserId = Brand<"UserId", string>;
+     * const toUserId = Brand.wrap<"UserId", string>();
+     * const userId: UserId = toUserId("user-123");
+     * const raw: string = Brand.unwrap(userId); // "user-123"
+     * ```
+     */
+    const unwrap: <K extends string, T>(branded: Brand<K, T>) => T;
+}
+
+/**
+ * A branded nominal type representing a duration of time in milliseconds.
+ * Use Duration to ensure safe time-based operators and clear unit conversions.
+ *
+ * @example
+ * ```ts
+ * const halfSecond = Duration.milliseconds(500);
+ * const twoSeconds = Duration.seconds(2);
+ * const total = pipe(halfSecond, Duration.add(twoSeconds));
+ *
+ * Duration.to.seconds(total); // 2.5
+ * ```
+ */
+type Duration = Brand<"Duration", number>;
+declare namespace Duration {
+    /**
+     * Creates a Duration from milliseconds.
+     *
+     * @example
+     * ```ts
+     * Duration.milliseconds(500); // 500ms Duration
+     * ```
+     */
+    const milliseconds: (ms: number) => Duration;
+    /**
+     * Creates a Duration from seconds.
+     *
+     * @example
+     * ```ts
+     * Duration.seconds(2); // 2000ms Duration
+     * ```
+     */
+    const seconds: (s: number) => Duration;
+    /**
+     * Creates a Duration from minutes.
+     *
+     * @example
+     * ```ts
+     * Duration.minutes(5); // 300000ms Duration
+     * ```
+     */
+    const minutes: (m: number) => Duration;
+    /**
+     * Creates a Duration from hours.
+     *
+     * @example
+     * ```ts
+     * Duration.hours(1); // 3600000ms Duration
+     * ```
+     */
+    const hours: (h: number) => Duration;
+    /**
+     * Creates a Duration from days.
+     *
+     * @example
+     * ```ts
+     * Duration.days(1); // 86400000ms Duration
+     * ```
+     */
+    const days: (d: number) => Duration;
+    namespace to {
+        /**
+         * Converts a Duration back to raw milliseconds.
+         *
+         * @example
+         * ```ts
+         * Duration.to.milliseconds(Duration.seconds(2)); // 2000
+         * ```
+         */
+        const milliseconds: (d: Duration) => number;
+        /**
+         * Converts a Duration to seconds.
+         *
+         * @example
+         * ```ts
+         * Duration.to.seconds(Duration.milliseconds(2500)); // 2.5
+         * ```
+         */
+        const seconds: (d: Duration) => number;
+        /**
+         * Converts a Duration to minutes.
+         *
+         * @example
+         * ```ts
+         * Duration.to.minutes(Duration.seconds(120)); // 2
+         * ```
+         */
+        const minutes: (d: Duration) => number;
+        /**
+         * Converts a Duration to hours.
+         *
+         * @example
+         * ```ts
+         * Duration.to.hours(Duration.minutes(90)); // 1.5
+         * ```
+         */
+        const hours: (d: Duration) => number;
+        /**
+         * Converts a Duration to days.
+         *
+         * @example
+         * ```ts
+         * Duration.to.days(Duration.hours(36)); // 1.5
+         * ```
+         */
+        const days: (d: Duration) => number;
+    }
+    /**
+     * Adds two Durations together.
+     *
+     * @example
+     * ```ts
+     * pipe(Duration.seconds(1), Duration.add(Duration.milliseconds(500))); // 1500ms
+     * ```
+     */
+    const add: (other: Duration) => (self: Duration) => Duration;
+    /**
+     * Subtracts the other Duration from this one.
+     *
+     * @example
+     * ```ts
+     * pipe(Duration.seconds(1), Duration.subtract(Duration.milliseconds(500))); // 500ms
+     * ```
+     */
+    const subtract: (other: Duration) => (self: Duration) => Duration;
+}
+
+export { Brand as B, Duration as D };

package/dist/Duration-B8joKzro.d.ts

@@ -0,0 +1,181 @@
+declare const _brand: unique symbol;
+/**
+ * Brand<K, T> creates a nominal type by tagging T with a phantom brand K.
+ * Prevents accidentally mixing up values that share the same underlying type.
+ *
+ * @example
+ * ```ts
+ * type UserId = Brand<"UserId", string>;
+ * type ProductId = Brand<"ProductId", string>;
+ *
+ * const toUserId = Brand.wrap<"UserId", string>();
+ * const toProductId = Brand.wrap<"ProductId", string>();
+ *
+ * const userId: UserId = toUserId("user-123");
+ * const productId: ProductId = toProductId("prod-456");
+ *
+ * // Type error: ProductId is not assignable to UserId
+ * // const wrong: UserId = productId;
+ * ```
+ */
+type Brand<K extends string, T> = T & {
+    readonly [_brand]: K;
+};
+declare namespace Brand {
+    /**
+     * Returns a constructor that wraps a value of type T in brand K.
+     * The resulting function performs an unchecked cast — only use when the raw
+     * value is known to satisfy the brand's invariants.
+     *
+     * @example
+     * ```ts
+     * type PositiveNumber = Brand<"PositiveNumber", number>;
+     * const toPositiveNumber = Brand.wrap<"PositiveNumber", number>();
+     *
+     * const n: PositiveNumber = toPositiveNumber(42);
+     * ```
+     */
+    const wrap: <K extends string, T>() => (value: T) => Brand<K, T>;
+    /**
+     * Strips the brand and returns the underlying value.
+     * Since Brand<K, T> extends T this is rarely needed, but can improve readability.
+     *
+     * @example
+     * ```ts
+     * type UserId = Brand<"UserId", string>;
+     * const toUserId = Brand.wrap<"UserId", string>();
+     * const userId: UserId = toUserId("user-123");
+     * const raw: string = Brand.unwrap(userId); // "user-123"
+     * ```
+     */
+    const unwrap: <K extends string, T>(branded: Brand<K, T>) => T;
+}
+
+/**
+ * A branded nominal type representing a duration of time in milliseconds.
+ * Use Duration to ensure safe time-based operators and clear unit conversions.
+ *
+ * @example
+ * ```ts
+ * const halfSecond = Duration.milliseconds(500);
+ * const twoSeconds = Duration.seconds(2);
+ * const total = pipe(halfSecond, Duration.add(twoSeconds));
+ *
+ * Duration.to.seconds(total); // 2.5
+ * ```
+ */
+type Duration = Brand<"Duration", number>;
+declare namespace Duration {
+    /**
+     * Creates a Duration from milliseconds.
+     *
+     * @example
+     * ```ts
+     * Duration.milliseconds(500); // 500ms Duration
+     * ```
+     */
+    const milliseconds: (ms: number) => Duration;
+    /**
+     * Creates a Duration from seconds.
+     *
+     * @example
+     * ```ts
+     * Duration.seconds(2); // 2000ms Duration
+     * ```
+     */
+    const seconds: (s: number) => Duration;
+    /**
+     * Creates a Duration from minutes.
+     *
+     * @example
+     * ```ts
+     * Duration.minutes(5); // 300000ms Duration
+     * ```
+     */
+    const minutes: (m: number) => Duration;
+    /**
+     * Creates a Duration from hours.
+     *
+     * @example
+     * ```ts
+     * Duration.hours(1); // 3600000ms Duration
+     * ```
+     */
+    const hours: (h: number) => Duration;
+    /**
+     * Creates a Duration from days.
+     *
+     * @example
+     * ```ts
+     * Duration.days(1); // 86400000ms Duration
+     * ```
+     */
+    const days: (d: number) => Duration;
+    namespace to {
+        /**
+         * Converts a Duration back to raw milliseconds.
+         *
+         * @example
+         * ```ts
+         * Duration.to.milliseconds(Duration.seconds(2)); // 2000
+         * ```
+         */
+        const milliseconds: (d: Duration) => number;
+        /**
+         * Converts a Duration to seconds.
+         *
+         * @example
+         * ```ts
+         * Duration.to.seconds(Duration.milliseconds(2500)); // 2.5
+         * ```
+         */
+        const seconds: (d: Duration) => number;
+        /**
+         * Converts a Duration to minutes.
+         *
+         * @example
+         * ```ts
+         * Duration.to.minutes(Duration.seconds(120)); // 2
+         * ```
+         */
+        const minutes: (d: Duration) => number;
+        /**
+         * Converts a Duration to hours.
+         *
+         * @example
+         * ```ts
+         * Duration.to.hours(Duration.minutes(90)); // 1.5
+         * ```
+         */
+        const hours: (d: Duration) => number;
+        /**
+         * Converts a Duration to days.
+         *
+         * @example
+         * ```ts
+         * Duration.to.days(Duration.hours(36)); // 1.5
+         * ```
+         */
+        const days: (d: Duration) => number;
+    }
+    /**
+     * Adds two Durations together.
+     *
+     * @example
+     * ```ts
+     * pipe(Duration.seconds(1), Duration.add(Duration.milliseconds(500))); // 1500ms
+     * ```
+     */
+    const add: (other: Duration) => (self: Duration) => Duration;
+    /**
+     * Subtracts the other Duration from this one.
+     *
+     * @example
+     * ```ts
+     * pipe(Duration.seconds(1), Duration.subtract(Duration.milliseconds(500))); // 500ms
+     * ```
+     */
+    const subtract: (other: Duration) => (self: Duration) => Duration;
+}
+
+export { Brand as B, Duration as D };

package/dist/{InternalTypes-Mssktd7z.d.ts → InternalTypes-CDiDBAY4.d.mts}

@@ -1,4 +1,4 @@
-import { Duration } from './types.js';
+import { D as Duration } from './Duration-B8joKzro.mjs';
 
 declare const _deferred: unique symbol;
 /**
@@ -54,6 +54,25 @@ declare namespace Deferred {
          */
         const Promise: <A>(d: Deferred<A>) => globalThis.Promise<A>;
     }
+    /**
+     * Combines an array or tuple of `Deferred` values into a single `Deferred` of a tuple.
+     * Resolves when all input `Deferred`s resolve.
+     *
+     * @example
+     * ```ts
+     * const [a, b] = await Deferred.all([d1, d2]);
+     * ```
+     */
+    const all: <T extends readonly Deferred<unknown>[]>(deferreds: T) => Deferred<{ [K in keyof T]: T[K] extends Deferred<infer A> ? A : never; }>;
+    /**
+     * Races multiple `Deferred` values and resolves with the first one to settle.
+     *
+     * @example
+     * ```ts
+     * const winner = await Deferred.race([d1, d2]);
+     * ```
+     */
+    const race: <A>(deferreds: ReadonlyArray<Deferred<A>>) => Deferred<A>;
 }
 
 /**

package/dist/{InternalTypes-CLE7qlOc.d.mts → InternalTypes-LdhLQx3N.d.ts}

@@ -1,4 +1,4 @@
-import { Duration } from './types.mjs';
+import { D as Duration } from './Duration-B8joKzro.js';
 
 declare const _deferred: unique symbol;
 /**
@@ -54,6 +54,25 @@ declare namespace Deferred {
          */
         const Promise: <A>(d: Deferred<A>) => globalThis.Promise<A>;
     }
+    /**
+     * Combines an array or tuple of `Deferred` values into a single `Deferred` of a tuple.
+     * Resolves when all input `Deferred`s resolve.
+     *
+     * @example
+     * ```ts
+     * const [a, b] = await Deferred.all([d1, d2]);
+     * ```
+     */
+    const all: <T extends readonly Deferred<unknown>[]>(deferreds: T) => Deferred<{ [K in keyof T]: T[K] extends Deferred<infer A> ? A : never; }>;
+    /**
+     * Races multiple `Deferred` values and resolves with the first one to settle.
+     *
+     * @example
+     * ```ts
+     * const winner = await Deferred.race([d1, d2]);
+     * ```
+     */
+    const race: <A>(deferreds: ReadonlyArray<Deferred<A>>) => Deferred<A>;
 }
 
 /**