@okikio/observables 1.0.2

package/esm/helpers/operations/core.js

@@ -0,0 +1,264 @@
+import "../../_dnt.polyfills.js";
+import { createOperator, createStatefulOperator } from "../operators.js";
+/**
+ * Core transformation and terminal operators for everyday stream work.
+ *
+ * This module is the closest match to familiar array helpers. It exports the
+ * operators you reach for first when you want to transform values, filter them,
+ * accumulate state, or stop after a condition has been met. In practice, this
+ * is where most pipelines start before you add timing or concurrency behavior.
+ *
+ * The important difference from arrays is error handling. These operators are
+ * designed to work with the library's pass-through model, so your callbacks see
+ * clean data values while `ObservableError` instances continue downstream
+ * unchanged until a dedicated error-handling step decides what to do with them.
+ *
+ * @module
+ */
+/**
+ * Transforms each data item, automatically skipping errors.
+ *
+ * Like `Array.map()`, but errors flow through unchanged:
+ *
+ * ```ts
+ * // Array.map() transforms everything
+ * [1, 2, 3].map(n => n * 2)  // [2, 4, 6]
+ *
+ * // Stream map() transforms only data
+ * pipe([1, Error, 3], map(n => n * 2))  // [2, Error, 6]
+ * ```
+ *
+ * Your function only receives clean data, never errors:
+ *
+ * ```ts
+ * pipe(
+ *   userIds,
+ *   map(id => fetchUser(id)),        // Some API calls fail
+ *   map(user => user.name),          // Only runs on real users
+ *   map(name => name.toUpperCase())  // Only runs on real names
+ * );
+ * // Result: [Name, Error, Name] - clean transformations, errors preserved
+ * ```
+ *
+ * @param project - Function that transforms each data item
+ */
+export function map(project) {
+    return createStatefulOperator({
+        name: "map",
+        createState: () => ({ index: 0 }),
+        transform(chunk, state, controller) {
+            const result = project(chunk, state.index++);
+            controller.enqueue(result);
+        },
+    });
+}
+/**
+ * Keeps data items that pass your test, always preserves errors.
+ *
+ * Like `Array.filter()`, but errors automatically pass through:
+ *
+ * ```ts
+ * // Array.filter() tests everything
+ * [1, 2, 3, 4].filter(n => n > 2)  // [3, 4]
+ *
+ * // Stream filter() tests only data
+ * pipe([1, Error, 3, 4], filter(n => n > 2))  // [Error, 3, 4]
+ * ```
+ *
+ * Your test function only receives clean data:
+ *
+ * ```ts
+ * pipe(
+ *   users,
+ *   filter(user => user.isActive),       // Only tests real users
+ *   filter(user => user.age >= 18)       // Chain multiple filters
+ * );
+ * // Result: filtered users + all errors preserved
+ * ```
+ *
+ * @param predicate - Test function that decides which data items to keep
+ */
+export function filter(predicate) {
+    return createStatefulOperator({
+        name: "filter",
+        createState: () => ({ index: 0 }),
+        transform(chunk, state, controller) {
+            if (predicate(chunk, state.index++)) {
+                controller.enqueue(chunk);
+            }
+        },
+    });
+}
+/**
+ * Takes the first N data items, errors don't count toward the limit.
+ *
+ * Like `Array.slice(0, N)`, but counts only successful data:
+ *
+ * ```ts
+ * // Array.slice() counts everything
+ * [1, "error", 2, 3].slice(0, 2)  // [1, "error"] - 2 items total
+ *
+ * // Stream take() counts only data
+ * pipe([1, Error, 2, 3], take(2))  // [1, Error, 2] - 2 data items
+ * ```
+ *
+ * Perfect for pagination and "top N" scenarios:
+ *
+ * ```ts
+ * pipe(
+ *   productIds,
+ *   map(id => fetchProduct(id)),    // Some API calls fail
+ *   filter(p => p.rating > 4),      // Only high-rated products
+ *   take(10)                        // Exactly 10 products + any errors
+ * );
+ * // Guarantees 10 actual products for your UI
+ * ```
+ *
+ * Stream stops immediately after collecting N data items.
+ *
+ * @param count - How many data items to take
+ */
+export function take(count) {
+    return createStatefulOperator({
+        name: "take",
+        createState: () => ({ taken: 0 }),
+        transform(chunk, state, controller) {
+            if (state.taken < count) {
+                controller.enqueue(chunk);
+                state.taken++;
+                // If we've taken enough values, terminate the stream
+                if (state.taken >= count) {
+                    controller.terminate();
+                }
+            }
+        },
+    });
+}
+/**
+ * Skips the first N data items, errors don't count toward the skip count.
+ *
+ * Like `Array.slice(N)`, but counts only successful data:
+ *
+ * ```ts
+ * // Array.slice() counts everything
+ * [1, "error", 2, 3].slice(2)  // [2, 3] - skipped first 2 items
+ *
+ * // Stream drop() counts only data
+ * pipe([1, Error, 2, 3], drop(2))  // [Error, 3] - skipped first 2 data items
+ * ```
+ *
+ * Perfect for pagination - skip to the right page regardless of errors:
+ *
+ * ```ts
+ * // Page 2: skip first 20 successful products
+ * pipe(
+ *   productIds,
+ *   map(id => fetchProduct(id)),    // Some API calls fail
+ *   drop(20),                       // Skip first 20 real products
+ *   take(20)                        // Next 20 products
+ * );
+ * // Errors flow through immediately, don't affect page positioning
+ * ```
+ *
+ * @param count - How many data items to skip
+ */
+export function drop(count) {
+    return createStatefulOperator({
+        name: "drop",
+        createState: () => ({ dropped: 0 }),
+        transform(chunk, state, controller) {
+            if (state.dropped < count) {
+                state.dropped++;
+            }
+            else {
+                controller.enqueue(chunk);
+            }
+        },
+    });
+}
+/**
+ * Runs side effects on data items, automatically skipping errors.
+ *
+ * Like adding `console.log()` to debug, but only logs clean data:
+ *
+ * ```ts
+ * // Regular debugging sees everything (messy)
+ * data.map(x => { console.log('Item:', x); return transform(x); })
+ *
+ * // Stream tap() sees only data (clean)
+ * pipe(
+ *   data,
+ *   map(x => transform(x)),
+ *   tap(x => console.log('Processed:', x))  // Only logs real data
+ * )
+ * ```
+ *
+ * Perfect for logging, analytics, caching, progress tracking:
+ *
+ * ```ts
+ * pipe(
+ *   userIds,
+ *   map(id => fetchUser(id)),                // Some API calls fail
+ *   tap(user => console.log('Loaded:', user.name)),  // Clean logs
+ *   tap(user => analytics.track('user_loaded')),     // Business events only
+ *   filter(user => user.isActive)
+ * );
+ * // Logs show only successful operations, errors flow silently
+ * ```
+ *
+ * Data flows through unchanged - `tap` just observes.
+ *
+ * @param fn - Function to run on each data item (for side effects)
+ */
+export function tap(fn) {
+    return createOperator({
+        name: "tap",
+        transform(chunk, controller) {
+            fn(chunk);
+            controller.enqueue(chunk);
+        },
+    });
+}
+/**
+ * Builds running totals from data, automatically skipping errors.
+ *
+ * Like `Array.reduce()`, but shows each step and handles errors:
+ *
+ * ```ts
+ * // Array.reduce() gives final result only
+ * [1, 2, 3].reduce((sum, n) => sum + n, 0)  // 6
+ *
+ * // Stream scan() shows progressive results
+ * pipe([1, Error, 3], scan((sum, n) => sum + n, 0))  // [0, 1, Error, 4]
+ * ```
+ *
+ * Perfect for running totals, counters, building objects:
+ *
+ * ```ts
+ * pipe(
+ *   productIds,
+ *   map(id => fetchPrice(id)),              // Some API calls fail
+ *   scan((total, price) => total + price, 0) // Running cart total
+ * );
+ * // Result: [0, 10, Error, 35, 40] - total ignores errors
+ * ```
+ *
+ * Always starts by emitting your initial value immediately.
+ *
+ * @param accumulator - Function that combines current total with new data
+ * @param seed - Starting value (emitted first)
+ */
+export function scan(accumulator, seed) {
+    return createStatefulOperator({
+        name: "scan",
+        createState: () => ({ acc: seed, index: 0 }),
+        start(state, controller) {
+            // Emit the seed value immediately
+            controller.enqueue(state.acc);
+        },
+        transform(chunk, state, controller) {
+            state.acc = accumulator(state.acc, chunk, state.index++);
+            controller.enqueue(state.acc);
+        },
+    });
+}

package/esm/helpers/operations/errors.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Error-focused operators for recovering from or reshaping stream failures.
+ *
+ * This entrypoint is for pipelines that expect some work to fail and want to
+ * keep going. It exports helpers for dropping wrapped errors, mapping them to
+ * fallback values, logging them, or converting them into a shape that fits the
+ * rest of the pipeline.
+ *
+ * These operators are most useful with the library's pass-through error mode,
+ * where failures travel as `ObservableError` values instead of immediately
+ * terminating the whole stream.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import type { ExcludeError, Operator } from "../_types.js";
+import { ObservableError } from "../../error.js";
+/**
+ * Removes all errors from the stream, keeping only successful data.
+ *
+ * Like a filter that only allows non-error values to pass. It's a simple way
+ * to clean up a stream when you don't need to handle failures.
+ *
+ * @example
+ * ```ts
+ * import { pipe, ignoreErrors, from } from "./helpers/mod.ts";
+ *
+ * // Array behavior (conceptual)
+ * const mixedData = [1, new Error("fail"), 2, 3];
+ * const goodData = mixedData.filter(item => !(item instanceof Error)); // [1, 2, 3]
+ *
+ * // Stream behavior
+ * const sourceStream = from([1, new ObservableError("fail"), 2, 3]);
+ * const cleanStream = pipe(sourceStream, ignoreErrors()); // Emits 1, 2, 3
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `ignoreErrors` when processing a batch of items where some failures are
+ * expected and acceptable. For example, fetching a list of URLs where some
+ * might be broken. You only want to process the ones that work.
+ *
+ * ## Key Insight
+ *
+ * `ignoreErrors` provides a "fire-and-forget" approach to error handling. It's
+ * useful for non-critical tasks or when partial success is sufficient.
+ *
+ * @template T The type of good data in your stream
+ * @returns A stream operator that silently removes all errors
+ */
+export declare function ignoreErrors<T>(): Operator<T | ObservableError, ExcludeError<T>>;
+/**
+ * Replaces any error in the stream with a fallback value.
+ *
+ * Like a `try...catch` block for each item in a stream, but instead of just
+ * handling the error, you provide a default value to take its place.
+ *
+ * @example
+ * ```ts
+ * import { pipe, catchErrors, from } from "./helpers/mod.ts";
+ *
+ * // Conceptual equivalent
+ * function process(item) {
+ *   try {
+ *     if (item instanceof Error) throw item;
+ *     return item;
+ *   } catch {
+ *     return "default";
+ *   }
+ * }
+ * const results = [1, new Error("fail")].map(process); // [1, "default"]
+ *
+ * // Stream behavior
+ * const sourceStream = from([1, new ObservableError("fail")]);
+ * const safeStream = pipe(sourceStream, catchErrors("default")); // Emits 1, "default"
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `catchErrors` to provide a default state or value when an operation
+ * fails. For example, if fetching a user's profile fails, you could return a
+ * default "Guest" profile instead of letting the error propagate.
+ *
+ * ## Key Insight
+ *
+ * `catchErrors` ensures your stream continues with a predictable structure,
+ * even when individual operations fail. It maintains the flow of data by
+ * substituting errors with safe, default values.
+ *
+ * @template T The type of data in your stream.
+ * @template R The type of the fallback value.
+ * @param fallback The value to use whenever an error occurs.
+ * @returns A stream operator that replaces errors with a fallback value.
+ */
+export declare function catchErrors<T, R>(fallback: R): Operator<T | ObservableError, ExcludeError<T> | R>;
+/**
+ * Transforms errors into custom values using a mapping function.
+ *
+ * This is a more powerful version of `catchErrors`. Instead of a single
+ * fallback, you can inspect each error and decide what to replace it with.
+ *
+ * @example
+ * ```ts
+ * import { pipe, mapErrors, from } from "./helpers/mod.ts";
+ *
+ * // Stream behavior
+ * const sourceStream = from([
+ *   1,
+ *   new ObservableError("Not Found"),
+ *   new ObservableError("Server Error")
+ * ]);
+ *
+ * const handledStream = pipe(
+ *   sourceStream,
+ *   mapErrors(err => {
+ *     if (err.message === "Not Found") return { status: 404 };
+ *     return { status: 500 };
+ *   })
+ * );
+ * // Emits 1, { status: 404 }, { status: 500 }
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `mapErrors` to convert different types of errors into meaningful data.
+ * For example, a "Not Found" error could be mapped to `null`, while a "Server
+ * Error" could be mapped to an object that triggers a retry mechanism.
+ *
+ * ## Key Insight
+ *
+ * `mapErrors` treats errors as data. It allows you to create a resilient
+ * stream that can intelligently respond to different failure modes without
+ * stopping.
+ *
+ * @template T The type of successful data in your stream.
+ * @template E The type your errors will be mapped to.
+ * @param errorMapper A function that receives an error and returns a new value.
+ * @returns A stream operator that transforms errors.
+ */
+export declare function mapErrors<T, E>(errorMapper: (error: ObservableError) => E): Operator<T | ObservableError, ExcludeError<T> | E>;
+/**
+ * Keeps only the errors from the stream, discarding successful data.
+ *
+ * This is the inverse of `ignoreErrors`. It's useful for creating a dedicated
+ * error-handling pipeline.
+ *
+ * @example
+ * ```ts
+ * import { pipe, onlyErrors, from } from "./helpers/mod.ts";
+ *
+ * // Stream behavior
+ * const sourceStream = from([1, new ObservableError("fail"), 2]);
+ * const errorStream = pipe(sourceStream, onlyErrors()); // Emits ObservableError("fail")
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `onlyErrors` to separate the error stream from the data stream. You can
+ * then log these errors, send them to a monitoring service, or trigger alerts
+ * without interfering with the main data processing flow.
+ *
+ * ## Key Insight
+ *
+ * `onlyErrors` allows you to create a side-channel for failures, enabling
+ * robust monitoring and debugging.
+ *
+ * @template T The type of data in the source stream.
+ * @returns An operator that filters for errors.
+ */
+export declare function onlyErrors<T>(): Operator<T | ObservableError, ObservableError>;
+/**
+ * Summarizes the stream into a final count of successes and errors.
+ *
+ * This operator waits for the stream to complete and then emits a single
+ * object with the total counts.
+ *
+ * @example
+ * ```ts
+ * import { pipe, summarizeErrors, from } from "./helpers/mod.ts";
+ *
+ * // Stream behavior
+ * const sourceStream = from([1, new ObservableError("fail"), 2, 3]);
+ * const summary = await pipe(sourceStream, summarizeErrors()).toPromise();
+ * // { successCount: 3, errorCount: 1, totalProcessed: 4, successRate: 0.75 }
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `summarizeErrors` at the end of a batch processing job to get a report
+ * on how many items were processed successfully and how many failed. This is
+
+ * useful for logging, monitoring, and generating reports.
+ *
+ * ## Key Insight
+ *
+ * `summarizeErrors` is a terminal operator that provides a high-level overview
+ * of a stream's health and completeness.
+ *
+ * @template T The type of data in the source stream.
+ * @returns An operator that emits a summary of successes and errors.
+ */
+export declare function summarizeErrors<T>(): Operator<T | ObservableError, {
+    successCount: number;
+    errorCount: number;
+    totalProcessed: number;
+    successRate: number;
+}>;
+/**
+ * Performs a side effect for each error without modifying the stream.
+ *
+ * Like `Array.prototype.forEach` but only for errors. It's useful for logging
+ * or debugging without altering the data flow.
+ *
+ * @example
+ * ```ts
+ * import { pipe, tapError, from } from "./helpers/mod.ts";
+ *
+ * // Stream behavior
+ * const sourceStream = from([1, new ObservableError("fail")]);
+ * const tappedStream = pipe(
+ *   sourceStream,
+ *   tapError(err => console.error("Found an error:", err))
+ * );
+ * // Logs the error, then emits 1 and the error object.
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `tapError` to log errors to the console or a monitoring service as they
+ * happen, without stopping or changing the stream. This is invaluable for
+ * real-time debugging.
+ *
+ * ## Key Insight
+ *
+ * `tapError` gives you a window into the stream's errors without affecting the
+ * stream itself.
+ *
+ * @template T The type of data in the stream.
+ * @param sideEffect A function to call for each error.
+ * @returns An operator that performs a side effect on errors.
+ */
+export declare function tapError<T>(sideEffect: (error: ObservableError) => void): Operator<T | ObservableError, T | ObservableError>;
+/**
+ * Throws an error if it encounters one in the stream.
+ *
+ * This operator is useful for enforcing strict error handling. If an error is
+ * encountered, it will throw immediately, stopping the iteration.
+ *
+ * @example
+ * ```ts
+ * import { pipe, throwErrors, from } from "./helpers/mod.ts";
+ *
+ * // Stream behavior
+ * const sourceStream = from([1, new ObservableError("fail"), 2]);
+ * const throwingStream = pipe(sourceStream, throwErrors());
+ *
+ * for await (const item of throwingStream) {
+ *   console.log(item); // Will log 1, then throw on "fail"
+ * }
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `throwErrors` when you want to ensure that any error in the stream is
+ * treated as a critical failure. This is useful in scenarios where errors must
+ * be handled immediately and cannot be ignored.
+ *
+ * ## Key Insight
+ *
+ * `throwErrors` provides a way to enforce strict error handling in streams,
+ * ensuring that no errors go unnoticed.
+ *
+ * @template T The type of data in the stream.
+ * @returns An operator that throws on errors.
+ */
+export declare function throwErrors<T>(): Operator<T | ObservableError, T>;
+//# sourceMappingURL=errors.d.ts.map

package/esm/helpers/operations/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAqB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,YAAY,CAAC,CAAC,KAAK,QAAQ,CACzC,CAAC,GAAG,eAAe,EACnB,YAAY,CAAC,CAAC,CAAC,CAChB,CASA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAC9B,QAAQ,EAAE,CAAC,GACV,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAYpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAC5B,WAAW,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,CAAC,GACzC,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CA6BpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,CAAC,KAAK,QAAQ,CACvC,CAAC,GAAG,eAAe,EACnB,eAAe,CAChB,CAWA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,eAAe,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CA2BD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,UAAU,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAC3C,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAgBpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,CAAC,CASjE"}