@nlozgachev/pipelined 0.49.0 → 0.51.0

package/README.md

@@ -15,11 +15,13 @@ npm add @nlozgachev/pipelined
 ## Possibly maybe
 
 In mainstream TypeScript, code is often burdened by implicit control flow: unchecked exceptions,
-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` and `Stream`, the library helps disentangle business logic from control
-mechanics.
+manual null propagation, unhandled asynchronous failures, UI state race conditions, and deeply
+nested spread operators. `pipelined` turns these complex runtime states into transparent, composable
+data structures.
+
+By representing optionality as `Maybe`, failures as `Result`, multi-field errors as `Validation`,
+lazy asynchronous workflows as `Task.Result`, request concurrency as `Op`, and event pipelines as
+`Stream`, the library disentangles 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 16 KB gzipped, and the
@@ -30,7 +32,11 @@ environments.
 
 Full guides and API reference at **[pipelined.lozgachev.dev](https://pipelined.lozgachev.dev)**.
 
-## Example: composing optional values
+---
+
+## Examples
+
+### Composing optional values
 
 `null` checks accumulate fast. Each one is a conditional branch that the type system can't help you
 forget. `Maybe<A>` turns absence into a value that composes — the same operations apply whether or
@@ -45,7 +51,7 @@ const parseDiscount = (raw: string): string =>
   pipe(
     raw,
     Str.trim,
-    Num.parse, // "10" → Some(10), "abc" → None
+    Num.parse, // "15" → Some(15), "abc" → None
     Maybe.filter((n) => n >= 0 && n <= 100), // out of range → None
     Maybe.map((n) => `${n}% off`),
     Maybe.getOrElse(() => "No discount"),
@@ -58,7 +64,7 @@ parseDiscount("abc"); // "No discount"
 
 Every step that sees `None` is skipped. The fallback runs once, at the end.
 
-## Example: typed async errors
+### Typed async errors and cancellation
 
 In JavaScript, asynchronous exceptions bypass the static type system, leaving unhandled rejections
 as invisible runtime risks. `Task.Result<E, A>` represents fallible asynchronous computations as
@@ -69,6 +75,8 @@ function signature, ensuring that failures are handled before compile time:
 import { pipe } from "@nlozgachev/pipelined/composition";
 import { Result, Task } from "@nlozgachev/pipelined/core";
 
+type User = { id: string; name: string };
+type Post = { id: string; title: string };
 type ApiError = { status: number; message: string };
 
 const fetchUser = (id: string): Task.Result<ApiError, User> =>
@@ -78,14 +86,14 @@ const fetchUser = (id: string): Task.Result<ApiError, User> =>
         if (!r.ok) throw { status: r.status, message: r.statusText };
         return r.json() as Promise<User>;
       }),
-    (e) => e as ApiError,
+    { onError: (e) => e as ApiError },
   );
 
 const fetchPosts = (userId: string): Task.Result<ApiError, Post[]> =>
   Task.Result.tryCatch(
     (signal) =>
       fetch(`/users/${userId}/posts`, { signal }).then((r) => r.json()),
-    (e) => e as ApiError,
+    { onError: (e) => e as ApiError },
   );
 
 // Chain two requests — the AbortSignal propagates to both automatically
@@ -116,7 +124,7 @@ if (Result.is.ok(result)) {
 }
 ```
 
-## Example: transforming data
+### Transforming data collections
 
 Standard JavaScript arrays and records routinely return `undefined` on out-of-bounds access or
 missing keys. The utility modules in `pipelined` wrap these operations with data-last, curried
@@ -156,7 +164,83 @@ replaces a `map` followed by a `filter`. `Arr.head` returns `Maybe<Item>` rather
 `Item | undefined`, so the absence is explicit in the type and the rest of the pipeline handles it
 the same way.
 
-## Example: retry, timeout, and cancellation
+### Multi-field form validation
+
+In web forms and batch data ingestion, failing fast on the first error produces poor user
+experiences. `Validation<E, A>` accumulates all errors across independent fields simultaneously:
+
+```ts
+import { pipe } from "@nlozgachev/pipelined/composition";
+import { Validation } from "@nlozgachev/pipelined/core";
+import { Str } from "@nlozgachev/pipelined/data";
+
+type SignupForm = { username: string; email: string };
+
+const validateUsername = (name: string): Validation<string, string> =>
+  pipe(
+    name,
+    Str.trim,
+    Validation.from.Predicate(
+      (s) => s.length >= 3,
+      () => "Username must be at least 3 characters",
+    ),
+  );
+
+const validateEmail = (email: string): Validation<string, string> =>
+  pipe(
+    email,
+    Str.trim,
+    Validation.from.Predicate(
+      (s) => s.includes("@"),
+      () => "Email must contain an @ symbol",
+    ),
+  );
+
+const validateSignup = (form: SignupForm) =>
+  Validation.struct({
+    username: validateUsername(form.username),
+    email: validateEmail(form.email),
+  });
+
+const outcome = validateSignup({ username: "a", email: "invalid" });
+
+if (Validation.is.failed(outcome)) {
+  console.log(outcome.errors);
+  // ["Username must be at least 3 characters", "Email must contain an @ symbol"]
+}
+```
+
+### Eliminating impossible UI states
+
+Managing asynchronous data in UI components with separate boolean flags (`isLoading`, `isError`,
+`data`) leads to contradictory combinations (like showing a spinner alongside an error alert).
+`RemoteData` models the complete 4-state lifecycle explicitly:
+
+```ts
+import { pipe } from "@nlozgachev/pipelined/composition";
+import { RemoteData } from "@nlozgachev/pipelined/core";
+
+type UserProfile = { name: string };
+type FetchError = { message: string };
+
+const renderUI = (state: RemoteData<FetchError, UserProfile>): string =>
+  pipe(
+    state,
+    RemoteData.match({
+      notAsked: () => "Click to load profile",
+      loading: () => "Loading...",
+      failure: (err) => `Failed: ${err.message}`,
+      success: (user) => `Welcome, ${user.name}!`,
+    }),
+  );
+
+renderUI(RemoteData.make.notAsked()); // "Click to load profile"
+renderUI(RemoteData.make.loading()); // "Loading..."
+renderUI(RemoteData.make.failure({ message: "Network down" })); // "Failed: Network down"
+renderUI(RemoteData.make.success({ name: "Alice" })); // "Welcome, Alice!"
+```
+
+### Managing request lifecycles, retries, and timeouts
 
 Handling robust network interactions — including retry attempts, backoff timing, timeouts, and
 signal-driven cancellation — typically requires complex, stateful code that is highly prone to
@@ -236,13 +320,11 @@ if (Op.isOk(outcome)) {
 fetchUser.abort();
 ```
 
-## Example: repeated UI interactions
+### Repeated UI interactions and concurrency strategies
 
 User interfaces frequently trigger repeated asynchronous events: a search input firing on every
-keystroke, a submit button clicked multiple times, or a polling loop that must terminate when a
-newer request starts. Managing these concurrency scenarios traditionally requires complex, ad-hoc
-state machines. `Op` simplifies this by allowing developers to declare the concurrency strategy as a
-simple configuration choice:
+keystroke, a submit button clicked multiple times, or background draft auto-saving. `Op` lets you
+declare the concurrency strategy as a clean configuration choice:
 
 **Search — cancel the previous call when the user types:**
 
@@ -259,7 +341,7 @@ const searchOp = Op.create(
 );
 
 const search = Op.interpret(searchOp, {
-  strategy: "restartable", // new call cancels the previous one
+  strategy: "restartable", // new call cancels the previous in-flight request
   retry: { attempts: 2, backoff: Duration.milliseconds(300) },
 });
 
@@ -273,7 +355,7 @@ search.subscribe((state) => {
 input.addEventListener("input", (e) => search.run(e.currentTarget.value));
 ```
 
-**Form submit — drop concurrent submissions:**
+**Form submit — drop concurrent duplicate submissions:**
 
 ```ts
 const submitOp = Op.create(
@@ -301,14 +383,13 @@ form.addEventListener("submit", (e) => {
 ```
 
 The system supports a variety of built-in strategies — `restartable`, `exclusive`, `debounced`,
-`throttled`, `queue`, `buffered`, `concurrent`, `keyed`, and `once` — making the integration of
-complex async scenarios highly predictable.
+`throttled`, `queue`, `buffered`, `concurrent`, `keyed`, and `once`.
 
-## Example: typed event streaming and sequence reduction
+### Event streaming, sequence funnels, and queue safety
 
 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:
+recursive call stack crashes during event cascades. `Stream` models in-memory event pipelines with
+typed message schemas, multi-step sequence pattern matching, and causal FIFO queue dispatching:
 
 ```ts
 import { Stream } from "@nlozgachev/pipelined/core";
@@ -317,15 +398,16 @@ type UserFlowMessages = {
   sessionStarted: { sessionId: string };
   stepCompleted: { stepName: string };
   flowFinished: { totalTimeMs: number };
+  flowCancelled: { reason: string };
 };
 
 const flowStream = Stream.make<UserFlowMessages>();
 
-// Match sequence: sessionStarted -> stepCompleted -> flowFinished
+// Pattern-match the complete multi-step funnel
 const sub = Stream.listen(
   flowStream,
   ["sessionStarted", "stepCompleted", "flowFinished"],
-  { ordered: true },
+  { ordered: true, reset: "flowCancelled" },
 ).reduce(
   (msg, state) => {
     if (msg.kind === "flowFinished") {
@@ -355,62 +437,135 @@ Stream.emit(flowStream, {
 sub.getState(); // { completedFlows: 1 }
 ```
 
-## What is included
+`Stream` executes cascading events iteratively using an internal queue with $O(1)$ stack overhead,
+completely preventing stack overflow crashes and out-of-order re-entrant execution.
+
+### Deep immutable updates without spread boilerplate
 
-The library covers the full spectrum of state and control flow scenarios encountered in production
-applications.
+Modifying deeply nested properties in state trees normally requires tedious spread syntax. `Lens`
+and `Optional` turn nested paths into first-class values:
 
-### Core context containers
+```ts
+import { pipe } from "@nlozgachev/pipelined/composition";
+import { Lens } from "@nlozgachev/pipelined/core";
+
+type Address = { city: string; zip: string };
+type User = { name: string; address: Address };
+
+const user: User = {
+  name: "Alice",
+  address: { city: "Berlin", zip: "10115" },
+};
+
+const addressLens = Lens.from.property<User>()("address");
+const cityLens = Lens.from.property<Address>()("city");
+const userCityLens = pipe(addressLens, Lens.andThen(cityLens));
 
-`Maybe` represents explicit optionality without null checks. `Result` handles synchronous, typed
-success and failure, while `Validation` accumulates multiple errors. `RemoteData` tracks the four
-states of an asynchronous data fetch (`NotAsked`, `Loading`, `Failure`, `Success`), `These` handles
-inclusive-OR scenarios containing a first value, a second, or both simultaneously, and `Tuple`
-provides a strongly-typed, immutable two-element pair.
+// Immutably modify deep property in one line
+const updatedUser = pipe(
+  user,
+  Lens.modify(userCityLens)((c) => c.toUpperCase()),
+);
 
-### Asynchronous operations
+updatedUser.address.city; // "BERLIN"
+```
 
-`Task` represents a lazy, infallible asynchronous computation. Fallible asynchronous workflows are
-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. `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.
+### Nominal type safety and security boundaries
 
-### Optics and environment state
+TypeScript's structural typing allows accidental parameter swapping (such as passing an `OrderId`
+into a `UserId` slot). `Brand` creates nominal types with smart constructor validation gates at zero
+runtime cost:
 
-`Lens` and `Optional` provide a simple concrete interface for safe, nested immutable data updates.
-Environment-dependent calculations and explicit state threading are supported by the `Reader` and
-`State` abstractions, while `Logged` enables side-effect-free data logging, and `Lazy` implements
-synchronous memoized thunks.
+```ts
+import { pipe } from "@nlozgachev/pipelined/composition";
+import { Result } from "@nlozgachev/pipelined/core";
+import { Brand } from "@nlozgachev/pipelined/types";
 
-### Algebraic and logic abstractions
+type UserId = Brand<"UserId", string>;
+type OrderId = Brand<"OrderId", string>;
+type Email = Brand<"Email", string>;
 
-For general type-safe comparisons and algebraic operations, the library includes `Equality` for
-composable object and primitive comparisons, `Ordering` for sorting comparators, and `Combinable`
-for structural monoids (allowing folding collections with a neutral starting point). Composable
-boolean checks and type guards are supported by `Predicate` and `Refinement` abstractions.
+const parseEmail = (raw: string): Result<string, Email> =>
+  raw.includes("@")
+    ? Result.make.ok(raw as Email)
+    : Result.make.err("Invalid email address");
 
-### Optimized utilities
+const sendReceipt = (userId: UserId, orderId: OrderId, email: Email) =>
+  `Sent to ${email} for order ${orderId} by user ${userId}`;
 
-Custom, performance-optimized utility modules (`Arr`, `Rec`, `Dict`, `Uniq`, `Num`, `Str`) wrap
-standard JavaScript types to return explicit types like `Maybe` and support data-last currying.
-Functions are composed using `pipe` and `flow`, which are enriched with high-level composition
-helpers like `when`, `unless`, `either`, `safe`, and `async` to support robust, expressive
-pipelines.
+const user = "usr_100" as UserId;
+const order = "ord_500" as OrderId;
+const email = parseEmail("alice@example.com");
 
-### Nominal branding, durations, and non-empty collections
+if (Result.is.ok(email)) {
+  sendReceipt(user, order, email.value);
+  // Type checker prevents: sendReceipt(order, user, email.value)
+}
+```
 
-Compile-time nominal typing with zero runtime overhead is provided by `Brand`. `Duration` safely
-models and converts time durations (seconds, milliseconds, etc.). `Arr.NonEmpty` and `Rec.NonEmpty`
-guarantee that an array or record is never empty, eliminating defensive length/emptiness checks at
-runtime.
+---
+
+## Quick Reference
+
+| Problem to Solve                                              | Module                        | Import Path                         |
+| ------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
+| Optional values without `null` / `undefined` checks           | `Maybe`                       | `@nlozgachev/pipelined/core`        |
+| Synchronous typed errors without `try`/`catch`                | `Result`                      | `@nlozgachev/pipelined/core`        |
+| Multi-field form and batch validation error accumulation      | `Validation`                  | `@nlozgachev/pipelined/core`        |
+| Lazy async workflows with automatic `AbortSignal`             | `Task.Result`, `Task`         | `@nlozgachev/pipelined/core`        |
+| Infallible async return container for tasks                   | `Deferred`                    | `@nlozgachev/pipelined/core`        |
+| Eliminating impossible UI loading/error/data states           | `RemoteData`                  | `@nlozgachev/pipelined/core`        |
+| Managing request race conditions, retries, and locks          | `Op`                          | `@nlozgachev/pipelined/core`        |
+| In-memory event streaming, sequence funnels & queue safety    | `Stream`                      | `@nlozgachev/pipelined/core`        |
+| Deep nested immutable updates without spread boilerplate      | `Lens`, `Optional`            | `@nlozgachev/pipelined/core`        |
+| Implicit dependency injection without prop drilling           | `Reader`                      | `@nlozgachev/pipelined/core`        |
+| Pure state transitions, tokenizers, and parsers               | `State`                       | `@nlozgachev/pipelined/core`        |
+| Deterministic bracket cleanup (DB pools, file locks)          | `Resource`                    | `@nlozgachev/pipelined/core`        |
+| Deferred computation memoized on first access                 | `Lazy`                        | `@nlozgachev/pipelined/core`        |
+| Pure calculation audit trails and decision logging            | `Logged`                      | `@nlozgachev/pipelined/core`        |
+| Inclusive-OR data modeling and two-way sync diffs             | `These`                       | `@nlozgachev/pipelined/core`        |
+| Deep structural equality & React component memoization        | `Equality`                    | `@nlozgachev/pipelined/core`        |
+| Multi-column table sorting with tiebreakers                   | `Ordering`                    | `@nlozgachev/pipelined/core`        |
+| Composable boolean filter pipelines & authorization policies  | `Predicate`                   | `@nlozgachev/pipelined/core`        |
+| Runtime type narrowing & custom type guard composition        | `Refinement`                  | `@nlozgachev/pipelined/core`        |
+| Merging configurations & metric structures (Monoids)          | `Combinable`                  | `@nlozgachev/pipelined/core`        |
+| Strongly-typed immutable pair manipulation                    | `Tuple`                       | `@nlozgachev/pipelined/core`        |
+| Point-free, bounds-safe array transformations                 | `Arr`, `Arr.NonEmpty`         | `@nlozgachev/pipelined/data`        |
+| Type-safe object manipulation & key migration                 | `Rec`, `Rec.NonEmpty`         | `@nlozgachev/pipelined/data`        |
+| Insertion-ordered maps with non-string keys                   | `Dict`, `Dict.NonEmpty`       | `@nlozgachev/pipelined/data`        |
+| Immutable sets & role/permission algebra                      | `Uniq`                        | `@nlozgachev/pipelined/data`        |
+| String sanitization, numeric conversion & slug parsing        | `Str`                         | `@nlozgachev/pipelined/data`        |
+| Boundary clamping & division-by-zero protection               | `Num`                         | `@nlozgachev/pipelined/data`        |
+| Financial ledger arithmetic without float precision drift     | `BigNum`                      | `@nlozgachev/pipelined/data`        |
+| Safe JSON parsing & circular reference protection             | `Json`                        | `@nlozgachev/pipelined/data`        |
+| Nominal typing & security boundary gates                      | `Brand`                       | `@nlozgachev/pipelined/types`       |
+| Explicit, unit-safe time spans & timeout policies             | `Duration`, `RetryPolicy`     | `@nlozgachev/pipelined/types`       |
+| Left-to-right value pipeline execution                        | `pipe`                        | `@nlozgachev/pipelined/composition` |
+| Left-to-right and right-to-left function composition          | `flow`, `compose`             | `@nlozgachev/pipelined/composition` |
+| Currying, uncurrying, and argument flipping                   | `curry`, `uncurry`, `flip`    | `@nlozgachev/pipelined/composition` |
+| Multi-branch argument routing and combining                   | `converge`, `juxt`, `on`      | `@nlozgachev/pipelined/composition` |
+| Pure function memoization, predicates & pipeline side-effects | `memoize`, `tap`, `not`, `fn` | `@nlozgachev/pipelined/composition` |
+
+---
+
+## Package Architecture and Performance
+
+`pipelined` is structured into 4 isolated, tree-shakeable entry points:
+
+- **`@nlozgachev/pipelined/core`**: Core context containers, async runtimes, optics, and logic
+  abstractions (<16 KB gzipped).
+- **`@nlozgachev/pipelined/data`**: Curried, data-last utilities for collections, numbers, strings,
+  and JSON (<13 KB gzipped).
+- **`@nlozgachev/pipelined/composition`**: Pure higher-order function combinators (`pipe`, `flow`,
+  `compose`, `curry`, `uncurry`, `converge`, `juxt`, `memoize`, `tap`, `on`, `not`, `flip`, `fn`)
+  (<4 KB gzipped).
+- **`@nlozgachev/pipelined/types`**: Type-level utilities (`Brand`, `Duration`, `RetryPolicy`) (<2
+  KB gzipped).
 
 Every utility in the library is benchmarked against its native equivalent. The data-last currying
-adds a small function call overhead, which is the expected cost of composability. For operations
-where native overhead is significant, custom implementations are used that often run faster than
-their native counterparts.
+adds a negligible function call overhead, which is the expected cost of composability. For
+operations where native overhead is significant, custom implementations are used that often run
+faster than their native counterparts.
 
 ## License
 

package/dist/{chunk-EPT3GYGN.mjs → chunk-6N27QZFK.mjs}

@@ -4,7 +4,7 @@ import {
   Result,
   Task,
   isNonEmptyArr
-} from "./chunk-IHLH2XYQ.mjs";
+} from "./chunk-U64ASY7P.mjs";
 
 // src/Data/Arr.ts
 var ArrMaybe;

package/dist/{chunk-IHLH2XYQ.mjs → chunk-U64ASY7P.mjs}

@@ -1737,22 +1737,35 @@ var Stream;
 ((Stream2) => {
   Stream2.make = (options) => ({
     options,
-    _listeners: /* @__PURE__ */ new Set()
+    _listeners: /* @__PURE__ */ new Set(),
+    _queue: [],
+    _isEmitting: false
   });
   Stream2.emit = (target, message) => {
     const targets = Array.isArray(target) ? target : [target];
     const msg = message;
     for (const stream of targets) {
-      const listeners = Array.from(stream._listeners);
-      for (const listener of listeners) {
+      stream._queue.push(msg);
+      if (!stream._isEmitting) {
+        stream._isEmitting = true;
         try {
-          listener(msg);
-        } catch (err2) {
-          if (stream.options?.onError) {
-            stream.options.onError(err2);
-          } else {
-            throw err2;
+          while (stream._queue.length > 0) {
+            const nextMsg = stream._queue.shift();
+            const listeners = Array.from(stream._listeners);
+            for (const listener of listeners) {
+              try {
+                listener(nextMsg);
+              } catch (err2) {
+                if (stream.options?.onError) {
+                  stream.options.onError(err2);
+                } else {
+                  throw err2;
+                }
+              }
+            }
           }
+        } finally {
+          stream._isEmitting = false;
         }
       }
     }
@@ -1779,6 +1792,7 @@ var Stream;
     const isStrict = options?.strict ?? false;
     const isOnce = options?.once ?? false;
     const resetKinds = options?.reset ? new Set(Array.isArray(options.reset) ? options.reset : [options.reset]) : null;
+    const optionalKinds = options?.optional ? new Set(Array.isArray(options.optional) ? options.optional : [options.optional]) : null;
     const createMatcher = (onMatch) => {
       let sequenceIndex = 0;
       return (msg) => {
@@ -1792,7 +1806,17 @@ var Stream;
           }
           return;
         }
-        const expectedKind = eventList[sequenceIndex];
+        let expectedKind = eventList[sequenceIndex];
+        if (expectedKind !== msg.kind && optionalKinds !== null) {
+          let lookaheadIndex = sequenceIndex;
+          while (lookaheadIndex < eventList.length && optionalKinds.has(eventList[lookaheadIndex]) && eventList[lookaheadIndex] !== msg.kind) {
+            lookaheadIndex++;
+          }
+          if (lookaheadIndex < eventList.length && eventList[lookaheadIndex] === msg.kind) {
+            sequenceIndex = lookaheadIndex;
+            expectedKind = eventList[sequenceIndex];
+          }
+        }
         if (msg.kind === expectedKind) {
           sequenceIndex++;
           if (sequenceIndex === eventList.length) {

package/dist/core.d.mts

@@ -2490,6 +2490,10 @@ type Stream<S extends Record<string, unknown>> = {
     readonly options?: Stream.Options;
     /** @internal */
     readonly _listeners: Set<(msg: Stream.Message<S>) => void>;
+    /** @internal */
+    readonly _queue: Array<Stream.Message<S>>;
+    /** @internal */
+    _isEmitting: boolean;
 };
 declare namespace Stream {
     /**
@@ -2517,6 +2521,8 @@ declare namespace Stream {
         readonly once?: boolean;
         /** Event kind(s) that reset sequence tracking to index 0. */
         readonly reset?: (keyof S & string) | ReadonlyArray<keyof S & string>;
+        /** Event kind(s) in the sequence that may be present or skipped. */
+        readonly optional?: (keyof S & string) | ReadonlyArray<keyof S & string>;
     };
     /**
      * Handle for an active stateful subscription.
@@ -2558,6 +2564,8 @@ declare namespace Stream {
     /**
      * Emits a message payload to one or more target streams.
      *
+     * Uses a synchronous breadth-first trampoline queue to handle re-entrant emissions deterministically.
+     *
      * @example
      * ```ts
      * Stream.emit(streamA, {

package/dist/core.d.ts

@@ -2490,6 +2490,10 @@ type Stream<S extends Record<string, unknown>> = {
     readonly options?: Stream.Options;
     /** @internal */
     readonly _listeners: Set<(msg: Stream.Message<S>) => void>;
+    /** @internal */
+    readonly _queue: Array<Stream.Message<S>>;
+    /** @internal */
+    _isEmitting: boolean;
 };
 declare namespace Stream {
     /**
@@ -2517,6 +2521,8 @@ declare namespace Stream {
         readonly once?: boolean;
         /** Event kind(s) that reset sequence tracking to index 0. */
         readonly reset?: (keyof S & string) | ReadonlyArray<keyof S & string>;
+        /** Event kind(s) in the sequence that may be present or skipped. */
+        readonly optional?: (keyof S & string) | ReadonlyArray<keyof S & string>;
     };
     /**
      * Handle for an active stateful subscription.
@@ -2558,6 +2564,8 @@ declare namespace Stream {
     /**
      * Emits a message payload to one or more target streams.
      *
+     * Uses a synchronous breadth-first trampoline queue to handle re-entrant emissions deterministically.
+     *
      * @example
      * ```ts
      * Stream.emit(streamA, {

package/dist/core.js

@@ -1811,22 +1811,35 @@ var Stream;
 ((Stream2) => {
   Stream2.make = (options) => ({
     options,
-    _listeners: /* @__PURE__ */ new Set()
+    _listeners: /* @__PURE__ */ new Set(),
+    _queue: [],
+    _isEmitting: false
   });
   Stream2.emit = (target, message) => {
     const targets = Array.isArray(target) ? target : [target];
     const msg = message;
     for (const stream of targets) {
-      const listeners = Array.from(stream._listeners);
-      for (const listener of listeners) {
+      stream._queue.push(msg);
+      if (!stream._isEmitting) {
+        stream._isEmitting = true;
         try {
-          listener(msg);
-        } catch (err2) {
-          if (stream.options?.onError) {
-            stream.options.onError(err2);
-          } else {
-            throw err2;
+          while (stream._queue.length > 0) {
+            const nextMsg = stream._queue.shift();
+            const listeners = Array.from(stream._listeners);
+            for (const listener of listeners) {
+              try {
+                listener(nextMsg);
+              } catch (err2) {
+                if (stream.options?.onError) {
+                  stream.options.onError(err2);
+                } else {
+                  throw err2;
+                }
+              }
+            }
           }
+        } finally {
+          stream._isEmitting = false;
         }
       }
     }
@@ -1853,6 +1866,7 @@ var Stream;
     const isStrict = options?.strict ?? false;
     const isOnce = options?.once ?? false;
     const resetKinds = options?.reset ? new Set(Array.isArray(options.reset) ? options.reset : [options.reset]) : null;
+    const optionalKinds = options?.optional ? new Set(Array.isArray(options.optional) ? options.optional : [options.optional]) : null;
     const createMatcher = (onMatch) => {
       let sequenceIndex = 0;
       return (msg) => {
@@ -1866,7 +1880,17 @@ var Stream;
           }
           return;
         }
-        const expectedKind = eventList[sequenceIndex];
+        let expectedKind = eventList[sequenceIndex];
+        if (expectedKind !== msg.kind && optionalKinds !== null) {
+          let lookaheadIndex = sequenceIndex;
+          while (lookaheadIndex < eventList.length && optionalKinds.has(eventList[lookaheadIndex]) && eventList[lookaheadIndex] !== msg.kind) {
+            lookaheadIndex++;
+          }
+          if (lookaheadIndex < eventList.length && eventList[lookaheadIndex] === msg.kind) {
+            sequenceIndex = lookaheadIndex;
+            expectedKind = eventList[sequenceIndex];
+          }
+        }
         if (msg.kind === expectedKind) {
           sequenceIndex++;
           if (sequenceIndex === eventList.length) {

package/dist/core.mjs

@@ -24,7 +24,7 @@ import {
   These,
   Tuple,
   Validation
-} from "./chunk-IHLH2XYQ.mjs";
+} from "./chunk-U64ASY7P.mjs";
 import "./chunk-DENXUTKL.mjs";
 export {
   Combinable,

package/dist/data.mjs

@@ -7,8 +7,8 @@ import {
   Rec,
   Str,
   Uniq
-} from "./chunk-EPT3GYGN.mjs";
-import "./chunk-IHLH2XYQ.mjs";
+} from "./chunk-6N27QZFK.mjs";
+import "./chunk-U64ASY7P.mjs";
 import "./chunk-DENXUTKL.mjs";
 export {
   Arr,

package/dist/index.js

@@ -2293,22 +2293,35 @@ var Stream;
 ((Stream2) => {
   Stream2.make = (options) => ({
     options,
-    _listeners: /* @__PURE__ */ new Set()
+    _listeners: /* @__PURE__ */ new Set(),
+    _queue: [],
+    _isEmitting: false
   });
   Stream2.emit = (target, message) => {
     const targets = Array.isArray(target) ? target : [target];
     const msg = message;
     for (const stream of targets) {
-      const listeners = Array.from(stream._listeners);
-      for (const listener of listeners) {
+      stream._queue.push(msg);
+      if (!stream._isEmitting) {
+        stream._isEmitting = true;
         try {
-          listener(msg);
-        } catch (err2) {
-          if (stream.options?.onError) {
-            stream.options.onError(err2);
-          } else {
-            throw err2;
+          while (stream._queue.length > 0) {
+            const nextMsg = stream._queue.shift();
+            const listeners = Array.from(stream._listeners);
+            for (const listener of listeners) {
+              try {
+                listener(nextMsg);
+              } catch (err2) {
+                if (stream.options?.onError) {
+                  stream.options.onError(err2);
+                } else {
+                  throw err2;
+                }
+              }
+            }
           }
+        } finally {
+          stream._isEmitting = false;
         }
       }
     }
@@ -2335,6 +2348,7 @@ var Stream;
     const isStrict = options?.strict ?? false;
     const isOnce = options?.once ?? false;
     const resetKinds = options?.reset ? new Set(Array.isArray(options.reset) ? options.reset : [options.reset]) : null;
+    const optionalKinds = options?.optional ? new Set(Array.isArray(options.optional) ? options.optional : [options.optional]) : null;
     const createMatcher = (onMatch) => {
       let sequenceIndex = 0;
       return (msg) => {
@@ -2348,7 +2362,17 @@ var Stream;
           }
           return;
         }
-        const expectedKind = eventList[sequenceIndex];
+        let expectedKind = eventList[sequenceIndex];
+        if (expectedKind !== msg.kind && optionalKinds !== null) {
+          let lookaheadIndex = sequenceIndex;
+          while (lookaheadIndex < eventList.length && optionalKinds.has(eventList[lookaheadIndex]) && eventList[lookaheadIndex] !== msg.kind) {
+            lookaheadIndex++;
+          }
+          if (lookaheadIndex < eventList.length && eventList[lookaheadIndex] === msg.kind) {
+            sequenceIndex = lookaheadIndex;
+            expectedKind = eventList[sequenceIndex];
+          }
+        }
         if (msg.kind === expectedKind) {
           sequenceIndex++;
           if (sequenceIndex === eventList.length) {

package/dist/index.mjs

@@ -39,7 +39,7 @@ import {
   Rec,
   Str,
   Uniq
-} from "./chunk-EPT3GYGN.mjs";
+} from "./chunk-6N27QZFK.mjs";
 import {
   Combinable,
   Deferred,
@@ -66,7 +66,7 @@ import {
   These,
   Tuple,
   Validation
-} from "./chunk-IHLH2XYQ.mjs";
+} from "./chunk-U64ASY7P.mjs";
 import {
   Brand,
   Duration,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nlozgachev/pipelined",
-	"version": "0.49.0",
+	"version": "0.51.0",
 	"description": "Opinionated functional abstractions for TypeScript",
 	"license": "BSD-3-Clause",
 	"homepage": "https://pipelined.lozgachev.dev",
@@ -18,7 +18,7 @@
 	"types": "./dist/index.d.ts",
 	"sideEffects": false,
 	"engines": {
-		"node": ">=24"
+		"node": ">=24.19.0"
 	},
 	"files": [
 		"dist"
@@ -55,6 +55,7 @@
 	"scripts": {
 		"build": "tsup",
 		"test": "vitest run",
+		"test:coverage": "vitest run --coverage",
 		"bench": "vitest bench",
 		"size": "size-limit",
 		"typecheck": "tsc --noEmit",
@@ -68,24 +69,44 @@
 		"docs:build": "pnpm --filter pipelined-docs build"
 	},
 	"devDependencies": {
-		"@size-limit/file": "12.1.0",
-		"@types/node": "25.9.3",
-		"@vitest/coverage-v8": "4.1.8",
-		"bumpp": "11.1.0",
-		"dprint": "0.54.0",
-		"fast-check": "4.8.0",
-		"oxlint": "1.69.0",
-		"size-limit": "12.1.0",
+		"@size-limit/file": "13.0.3",
+		"@types/node": "26.2.0",
+		"@vitest/coverage-v8": "4.1.10",
+		"bumpp": "12.2.0",
+		"dprint": "0.55.2",
+		"fast-check": "4.9.0",
+		"oxlint": "1.78.0",
+		"size-limit": "13.0.3",
 		"tsup": "8.5.1",
 		"typescript": "6.0.3",
-		"vitest": "4.1.8"
+		"vitest": "4.1.10"
 	},
 	"size-limit": [
-		{ "path": "dist/index.js", "limit": "25 KB", "gzip": true },
-		{ "path": "dist/core.js", "limit": "16 KB", "gzip": true },
-		{ "path": "dist/composition.js", "limit": "4 KB", "gzip": true },
-		{ "path": "dist/data.js", "limit": "13 KB", "gzip": true },
-		{ "path": "dist/types.js", "limit": "2 KB", "gzip": true }
+		{
+			"path": "dist/index.js",
+			"limit": "25 KB",
+			"gzip": true
+		},
+		{
+			"path": "dist/core.js",
+			"limit": "16 KB",
+			"gzip": true
+		},
+		{
+			"path": "dist/composition.js",
+			"limit": "4 KB",
+			"gzip": true
+		},
+		{
+			"path": "dist/data.js",
+			"limit": "13 KB",
+			"gzip": true
+		},
+		{
+			"path": "dist/types.js",
+			"limit": "2 KB",
+			"gzip": true
+		}
 	],
 	"packageManager": "pnpm@11.6.0+sha512.9a36518224080c6fe5165afdcfe79bfa118c29be703f3f462b1e32efe1e98e47e8750b148e08286250aad4113cc7993ca413c4e2cd447752708c2ee5751bc95f"
 }