@nlozgachev/pipelined 0.47.0 → 0.49.0

package/dist/core.d.mts

@@ -1,7 +1,8 @@
-import { M as Maybe, R as Result, T as Task } from './Validation-v38R0qH-.mjs';
-export { E as Equality, a as Err, F as Failed, N as None, O as Ok, b as Ordering, P as Passed, S as Some, c as TaskMaybe, d as TaskResult, e as TaskValidation, V as Validation } from './Validation-v38R0qH-.mjs';
-import { o as WithValue, i as WithLog, D as Deferred, h as WithKind, e as WithError, R as RetryOptions, b as TimeoutOptions, n as WithTimeout, j as WithMinInterval, c as WithCooldown, W as WithConcurrency, m as WithSize, d as WithDuration, k as WithN, g as WithFirst, l as WithSecond } from './InternalTypes-CLE7qlOc.mjs';
-import { Duration } from './types.mjs';
+import { M as Maybe, R as Result, T as Task } from './Validation-D-aARYlP.mjs';
+export { E as Equality, a as Err, F as Failed, N as None, O as Ok, b as Ordering, P as Passed, S as Some, c as TaskMaybe, d as TaskResult, e as TaskValidation, V as Validation } from './Validation-D-aARYlP.mjs';
+import { o as WithValue, i as WithLog, D as Deferred, h as WithKind, e as WithError, R as RetryOptions, b as TimeoutOptions, n as WithTimeout, j as WithMinInterval, c as WithCooldown, W as WithConcurrency, m as WithSize, d as WithDuration, k as WithN, g as WithFirst, l as WithSecond } from './InternalTypes-CDiDBAY4.mjs';
+import { D as Duration } from './Duration-B8joKzro.mjs';
+import './types.mjs';
 
 /**
  * A type that can combine two values of type `A` into one, with a neutral starting value.
@@ -96,6 +97,18 @@ declare namespace Combinable {
      * ```
      */
     const fold: <A>(c: Combinable<A>) => (data: readonly A[]) => A;
+    /**
+     * Derives a `Combinable` for a record of fields from field-level `Combinable` instances.
+     *
+     * @example
+     * ```ts
+     * const StatsCombinable = Combinable.struct({
+     *   count: Combinable.sum,
+     *   tags: Combinable.array<string>(),
+     * });
+     * ```
+     */
+    const struct: <R extends Record<string, unknown>>(fields: { [K in keyof R]: Combinable<R[K]>; }) => Combinable<R>;
 }
 
 /**
@@ -432,6 +445,17 @@ declare namespace Logged {
      * ```
      */
     const bind: <K extends string, W, A, B>(key: K, f: (a: A) => Logged<W, B>) => (data: Logged<W, A>) => Logged<W, A & { [P in K]: B; }>;
+    /**
+     * Focuses a Logged computation's value transformation using a Lens.
+     *
+     * @example
+     * ```ts
+     * const nameLens = Lens.from.property<{ name: string }>()("name");
+     * const logged = Logged.from.value<string, { name: string }>({ name: "alice" });
+     * pipe(logged, Logged.focus(nameLens)(s => s.toUpperCase()));
+     * ```
+     */
+    const focus: <S, A>(lens: Lens<S, A>) => <W>(f: (a: A) => A) => (data: Logged<W, S>) => Logged<W, S>;
 }
 
 type MaybeRetry<E, O> = O extends {
@@ -1465,6 +1489,23 @@ declare namespace Predicate {
          */
         const Refinement: <A, B extends A>(r: Refinement<A, B>) => Predicate<A>;
     }
+    /**
+     * Performs declarative conditional branching over `[predicate, handler]` pairs,
+     * returning the handler result of the first matching predicate or evaluating the fallback.
+     *
+     * @example
+     * ```ts
+     * const classifyNumber = Predicate.match(
+     *   [
+     *     [(n: number) => n < 0, () => "negative"],
+     *     [(n: number) => n === 0, () => "zero"],
+     *   ],
+     *   () => "positive",
+     * );
+     * classifyNumber(-5); // "negative"
+     * ```
+     */
+    const match: <A, B>(branches: ReadonlyArray<readonly [Predicate<A>, (a: A) => B]>, fallback: (a: A) => B) => (a: A) => B;
 }
 
 /**
@@ -1813,36 +1854,88 @@ declare namespace RemoteData {
     namespace make {
         /**
          * Creates a NotAsked RemoteData.
+         *
+         * @example
+         * ```ts
+         * RemoteData.make.notAsked(); // NotAsked
+         * ```
          */
         const notAsked: () => NotAsked;
         /**
          * Creates a Loading RemoteData.
+         *
+         * @example
+         * ```ts
+         * RemoteData.make.loading(); // Loading
+         * ```
          */
         const loading: () => Loading;
         /**
          * Creates a Failure RemoteData with the given error.
+         *
+         * @example
+         * ```ts
+         * RemoteData.make.failure("Network error"); // Failure("Network error")
+         * ```
          */
         const failure: <E>(error: E) => Failure<E>;
         /**
          * Creates a Success RemoteData with the given value.
+         *
+         * @example
+         * ```ts
+         * RemoteData.make.success(42); // Success(42)
+         * ```
          */
         const success: <A>(value: A) => Success<A>;
     }
     namespace is {
         /**
          * Type guard that checks if a RemoteData is NotAsked.
+         *
+         * @example
+         * ```ts
+         * const data = RemoteData.make.notAsked();
+         * if (RemoteData.is.notAsked(data)) {
+         *   console.log("Data fetch not initiated");
+         * }
+         * ```
          */
         const notAsked: <E, A>(data: RemoteData<E, A>) => data is NotAsked;
         /**
          * Type guard that checks if a RemoteData is Loading.
+         *
+         * @example
+         * ```ts
+         * const data = RemoteData.make.loading();
+         * if (RemoteData.is.loading(data)) {
+         *   console.log("Data is loading");
+         * }
+         * ```
          */
         const loading: <E, A>(data: RemoteData<E, A>) => data is Loading;
         /**
          * Type guard that checks if a RemoteData is Failure.
+         *
+         * @example
+         * ```ts
+         * const data = RemoteData.make.failure("Failed");
+         * if (RemoteData.is.failure(data)) {
+         *   console.log(data.error); // "Failed"
+         * }
+         * ```
          */
         const failure: <E, A>(data: RemoteData<E, A>) => data is Failure<E>;
         /**
          * Type guard that checks if a RemoteData is Success.
+         *
+         * @example
+         * ```ts
+         * const data = RemoteData.make.success(42);
+         * if (RemoteData.is.success(data)) {
+         *   console.log(data.value); // 42
+         * }
+         * ```
          */
         const success: <E, A>(data: RemoteData<E, A>) => data is Success<A>;
     }
@@ -1877,7 +1970,7 @@ declare namespace RemoteData {
      * );
      * ```
      */
-    const chain: <E, A, B>(f: (a: A) => RemoteData<E, B>) => (data: RemoteData<E, A>) => RemoteData<E, B>;
+    const chain: <E1, E2, A, B>(f: (a: A) => RemoteData<E2, B>) => (data: RemoteData<E1, A>) => RemoteData<E1 | E2, B>;
     /**
      * Applies a function wrapped in a RemoteData to a value wrapped in a RemoteData.
      *
@@ -2003,7 +2096,7 @@ declare namespace RemoteData {
          *
          * @example
          * ```ts
-         * const result = await Task.Result.tryCatch(fetchUser, String)();
+         * const result = await Task.Result.tryCatch(fetchUser, { onError: String })();
          * setState(RemoteData.from.Result(result)); // Success(user) or Failure(msg)
          * ```
          */
@@ -2053,7 +2146,7 @@ declare namespace RemoteData {
  * @example
  * ```ts
  * const dbResource = Resource.from.handlers(
- *   Task.Result.tryCatch(() => openConnection(config), (e) => new DbError(e)),
+ *   Task.Result.tryCatch(() => openConnection(config), { onError: (e) => new DbError(e) }),
  *   (conn) => Task.from.Promise(() => conn.close())
  * );
  *
@@ -2076,7 +2169,7 @@ declare namespace Resource {
          * @example
          * ```ts
          * const fileResource = Resource.from.handlers(
-         *   Task.Result.tryCatch(() => fs.promises.open("data.csv", "r"), toFileError),
+         *   Task.Result.tryCatch(() => fs.promises.open("data.csv", "r"), { onError: toFileError }),
          *   (handle) => Task.from.Promise(() => handle.close())
          * );
          * ```
@@ -2344,6 +2437,170 @@ declare namespace State {
      * ```
      */
     const bind: <K extends string, S, A, B>(key: K, f: (a: A) => State<S, B>) => (data: State<S, A>) => State<S, A & { [P in K]: B; }>;
+    /**
+     * Focuses a State computation on a sub-state using a Lens.
+     *
+     * @example
+     * ```ts
+     * type AppState = { count: number; name: string };
+     * const countLens = Lens.from.property<AppState>()("count");
+     * const increment = State.modify((c: number) => c + 1);
+     * const focusedProgram = pipe(increment, State.focus(countLens));
+     * ```
+     */
+    const focus: <S, A>(lens: Lens<S, A>) => <B>(stateOp: State<A, B>) => State<S, B>;
+}
+
+/**
+ * An event stream pipeline for a typed message schema `S`.
+ *
+ * `Stream` provides typed event emission, sequence matching, state reduction,
+ * and structural stream forwarding.
+ *
+ * @example
+ * ```ts
+ * type AppMessages = {
+ *   userLoggedIn: { userId: string };
+ *   checkoutStarted: { amount: number };
+ * };
+ *
+ * const appStream = Stream.make<AppMessages>();
+ *
+ * const subscription = Stream.listen(
+ *   appStream,
+ *   ["userLoggedIn", "checkoutStarted"],
+ *   { ordered: true }
+ * ).reduce(
+ *   (msg, state) => {
+ *     if (msg.kind === "checkoutStarted") {
+ *       return { count: state.count + 1 };
+ *     }
+ *     return state;
+ *   },
+ *   { count: 0 }
+ * );
+ *
+ * Stream.emit(appStream, {
+ *   kind: "userLoggedIn",
+ *   value: { userId: "user-1" },
+ * });
+ * ```
+ */
+type Stream<S extends Record<string, unknown>> = {
+    readonly options?: Stream.Options;
+    /** @internal */
+    readonly _listeners: Set<(msg: Stream.Message<S>) => void>;
+};
+declare namespace Stream {
+    /**
+     * Message payload emitted across a Stream.
+     */
+    type Message<S extends Record<string, unknown>> = {
+        [K in keyof S & string]: WithKind<K> & WithValue<S[K]>;
+    }[keyof S & string];
+    /**
+     * Options for constructing a `Stream` instance.
+     */
+    type Options = {
+        readonly name?: string;
+        readonly onError?: (error: unknown) => void;
+    };
+    /**
+     * Options for sequence matching and listener execution.
+     */
+    type SequenceOptions<S extends Record<string, unknown>> = {
+        /** Match events in exact array sequence order (default: false). */
+        readonly ordered?: boolean;
+        /** Match sequence strictly consecutively without intermediary events (default: false). */
+        readonly strict?: boolean;
+        /** Automatically unsubscribe after the first match/cycle completes (default: false). */
+        readonly once?: boolean;
+        /** Event kind(s) that reset sequence tracking to index 0. */
+        readonly reset?: (keyof S & string) | ReadonlyArray<keyof S & string>;
+    };
+    /**
+     * Handle for an active stateful subscription.
+     */
+    type Subscription<State> = {
+        readonly unsubscribe: () => void;
+        readonly getState: () => State;
+    };
+    /**
+     * Options for structural stream forwarding.
+     */
+    type ForwardOptions<S extends Record<string, unknown>> = {
+        readonly from: Stream<S>;
+        readonly to: Stream<S> | ReadonlyArray<Stream<S>>;
+        readonly only?: ReadonlyArray<keyof S & string>;
+    };
+    /**
+     * Builder handle returned by `Stream.listen`.
+     */
+    type ListenerBuilder<S extends Record<string, unknown>> = {
+        /**
+         * Stateful reduction over events/sequences.
+         */
+        readonly reduce: <State>(reducer: (msg: Message<S>, state: State) => State, initialState: State) => Subscription<State>;
+        /**
+         * Stateless side-effect execution.
+         */
+        readonly tap: (effect: (msg: Message<S>) => void) => () => void;
+    };
+    /**
+     * Constructs a new `Stream` instance.
+     *
+     * @example
+     * ```ts
+     * const stream = Stream.make<AppMessages>({ name: "app" });
+     * ```
+     */
+    const make: <S extends Record<string, unknown>>(options?: Options) => Stream<S>;
+    /**
+     * Emits a message payload to one or more target streams.
+     *
+     * @example
+     * ```ts
+     * Stream.emit(streamA, {
+     *   kind: "userLoggedIn",
+     *   value: { userId: "user-1" },
+     * });
+     *
+     * Stream.emit([streamA, streamB], {
+     *   kind: "userLoggedIn",
+     *   value: { userId: "user-1" },
+     * });
+     * ```
+     */
+    const emit: <S extends Record<string, unknown>, K extends keyof S & string>(target: Stream<S> | ReadonlyArray<Stream<S>>, message: WithKind<K> & WithValue<S[K]>) => void;
+    /**
+     * Forwards messages from one stream to another (or multiple).
+     *
+     * @example
+     * ```ts
+     * const stop = Stream.forward({
+     *   from: authStream,
+     *   to: analyticsStream,
+     *   only: ["userLoggedIn"],
+     * });
+     * ```
+     */
+    const forward: <S extends Record<string, unknown>>(options: ForwardOptions<S>) => () => void;
+    /**
+     * Initiates listener registration on a stream for specific event kind(s) or sequence.
+     *
+     * @example
+     * ```ts
+     * const sub = Stream.listen(
+     *   appStream,
+     *   ["userLoggedIn", "checkoutStarted"],
+     *   { ordered: true }
+     * ).reduce(
+     *   (msg, state) => ({ count: state.count + 1 }),
+     *   { count: 0 }
+     * );
+     * ```
+     */
+    const listen: <S extends Record<string, unknown>, K extends keyof S & string>(stream: Stream<S>, events: K | ReadonlyArray<K>, options?: SequenceOptions<S>) => ListenerBuilder<S>;
 }
 
 type TheseFirst<T> = WithKind<"First"> & WithFirst<T>;
@@ -2406,23 +2663,61 @@ declare namespace These {
     namespace is {
         /**
          * Type guard — checks if a These holds only a first value.
+         *
+         * @example
+         * ```ts
+         * const val = These.make.first(42);
+         * if (These.is.first(val)) {
+         *   console.log(val.first); // 42
+         * }
+         * ```
          */
         const first: <A, B>(data: These<A, B>) => data is TheseFirst<A>;
         /**
          * Type guard — checks if a These holds only a second value.
+         *
+         * @example
+         * ```ts
+         * const val = These.make.second("warning");
+         * if (These.is.second(val)) {
+         *   console.log(val.second); // "warning"
+         * }
+         * ```
          */
         const second: <A, B>(data: These<A, B>) => data is TheseSecond<B>;
         /**
          * Type guard — checks if a These holds both values simultaneously.
+         *
+         * @example
+         * ```ts
+         * const val = These.make.both(42, "warning");
+         * if (These.is.both(val)) {
+         *   console.log(val.first, val.second); // 42 "warning"
+         * }
+         * ```
          */
         const both: <A, B>(data: These<A, B>) => data is TheseBoth<A, B>;
     }
     /**
      * Returns true if the These contains a first value (First or Both).
+     *
+     * @example
+     * ```ts
+     * These.hasFirst(These.make.first(42));       // true
+     * These.hasFirst(These.make.both(42, "warn"));// true
+     * These.hasFirst(These.make.second("warn"));  // false
+     * ```
      */
     const hasFirst: <A, B>(data: These<A, B>) => data is TheseFirst<A> | TheseBoth<A, B>;
     /**
      * Returns true if the These contains a second value (Second or Both).
+     *
+     * @example
+     * ```ts
+     * These.hasSecond(These.make.second("warn"));  // true
+     * These.hasSecond(These.make.both(42, "warn"));// true
+     * These.hasSecond(These.make.first(42));       // false
+     * ```
      */
     const hasSecond: <A, B>(data: These<A, B>) => data is TheseSecond<B> | TheseBoth<A, B>;
     /**
@@ -2716,4 +3011,4 @@ declare namespace Tuple {
     const tap: <A, B>(f: (a: A, b: B) => void) => (tuple: Tuple<A, B>) => Tuple<A, B>;
 }
 
-export { Combinable, Deferred, type Failure, Lazy, Lens, type Loading, Logged, Maybe, type NotAsked, Op, Optional, Predicate, Reader, Refinement, RemoteData, Resource, Result, State, type Success, Task, These, type TheseBoth, type TheseFirst, type TheseSecond, Tuple };
+export { Combinable, Deferred, type Failure, Lazy, Lens, type Loading, Logged, Maybe, type NotAsked, Op, Optional, Predicate, Reader, Refinement, RemoteData, Resource, Result, State, Stream, type Success, Task, These, type TheseBoth, type TheseFirst, type TheseSecond, Tuple };