@okikio/observables 1.0.2

package/esm/helpers/operations/conditional.js

@@ -0,0 +1,280 @@
+/**
+ * Predicate and decision-oriented operators for Observable streams.
+ *
+ * This entrypoint exports the operators that answer questions about a stream or
+ * gate values based on a condition. These are the Observable equivalents of
+ * array helpers such as `every()`, `some()`, and `find()`, plus utilities that
+ * stop early once a decision has been reached.
+ *
+ * Reach for this module when you care about whether a stream contains a match,
+ * whether every value passes a rule, or when processing should stop as soon as
+ * the answer is known.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import { createStatefulOperator } from "../operators.js";
+/**
+ * Checks if every item in the stream passes a test.
+ *
+ * Like `Array.prototype.every()`, it stops and returns `false` on the first
+ * failure. If the stream completes without any failures, it returns `true`.
+ *
+ * @example
+ * ```ts
+ * import { pipe, every, from } from "./helpers/mod.ts";
+ *
+ * // Array behavior
+ * const allEven = [2, 4, 6].every(n => n % 2 === 0); // true
+ * const someOdd = [2, 4, 5].every(n => n % 2 === 0); // false
+ *
+ * // Stream behavior
+ * const allEvenStream = from([2, 4, 6]);
+ * const result1 = await pipe(allEvenStream, every(n => n % 2 === 0)).toPromise(); // true
+ *
+ * const someOddStream = from([2, 4, 5]);
+ * const result2 = await pipe(someOddStream, every(n => n % 2 === 0)).toPromise(); // false
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `every` to verify that all items in a stream meet a certain condition,
+ * such as ensuring all uploaded files are of the correct type or that all
+ * API responses were successful.
+ *
+ * ## Key Insight
+ *
+ * `every` provides a definitive boolean answer for the entire stream, making
+ * it a final, summary operation.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param predicate - Function to test each value
+ * @returns A stream operator that tests all values
+ */
+export function every(predicate) {
+    return createStatefulOperator({
+        name: "every",
+        createState: () => ({ index: 0, finished: false }),
+        transform(chunk, state, controller) {
+            if (state.finished)
+                return;
+            const result = predicate(chunk, state.index++);
+            // If the predicate fails, emit false and complete
+            if (!result) {
+                state.finished = true;
+                controller.enqueue(false);
+                controller.terminate();
+            }
+        },
+        // If the stream completes and we haven't emitted yet, emit true
+        flush(state, controller) {
+            if (!state.finished) {
+                controller.enqueue(true);
+            }
+        },
+    });
+}
+/**
+ * Checks if at least one item in the stream passes a test.
+ *
+ * Like `Array.prototype.some()`, it stops and returns `true` on the first
+ * success. If the stream completes without any successes, it returns `false`.
+ *
+ * @example
+ * ```ts
+ * import { pipe, some, from } from "./helpers/mod.ts";
+ *
+ * // Array behavior
+ * const hasEven = [1, 3, 4].some(n => n % 2 === 0); // true
+ * const noEven = [1, 3, 5].some(n => n % 2 === 0); // false
+ *
+ * // Stream behavior
+ * const hasEvenStream = from([1, 3, 4]);
+ * const result1 = await pipe(hasEvenStream, some(n => n % 2 === 0)).toPromise(); // true
+ *
+ * const noEvenStream = from([1, 3, 5]);
+ * const result2 = await pipe(noEvenStream, some(n => n % 2 === 0)).toPromise(); // false
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `some` to quickly determine if a condition is met by any item in a
+ * stream, such as checking for the existence of a specific user permission or
+ * detecting if any item in a batch has an error.
+ *
+ * ## Key Insight
+ *
+ * `some` is an efficient way to get a "yes" or "no" answer from a stream
+ * without processing all the items.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param predicate - Function to test each value
+ * @returns A stream operator that tests for any matching value
+ */
+export function some(predicate) {
+    return createStatefulOperator({
+        name: "some",
+        createState: () => ({ index: 0, finished: false }),
+        transform(chunk, state, controller) {
+            if (state.finished)
+                return;
+            const result = predicate(chunk, state.index++);
+            // If the predicate passes, emit true and complete
+            if (result) {
+                state.finished = true;
+                controller.enqueue(true);
+                controller.terminate();
+            }
+        },
+        // If the stream completes and we haven't emitted yet, emit false
+        flush(state, controller) {
+            if (!state.finished) {
+                controller.enqueue(false);
+            }
+        },
+    });
+}
+/**
+ * Finds the first item in the stream that passes a test.
+ *
+ * Like `Array.prototype.find()`, it stops and emits the first matching item,
+ * then immediately completes the stream.
+ *
+ * @example
+ * ```ts
+ * import { pipe, find, from } from "./helpers/mod.ts";
+ *
+ * // Array behavior
+ * const firstEven = [1, 3, 4, 6].find(n => n % 2 === 0); // 4
+ *
+ * // Stream behavior
+ * const numberStream = from([1, 3, 4, 6]);
+ * const result = await pipe(numberStream, find(n => n % 2 === 0)).toPromise(); // 4
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `find` to locate a specific record or event in a stream without needing
+ * to process the entire dataset, such as finding the first available time slot
+ * or the first user to log in.
+ *
+ * ## Key Insight
+ *
+ * `find` is an efficient shortcut to get the first item you care about from a
+ * potentially long stream.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param predicate - Function to test each value
+ * @returns A stream operator that finds the first matching value
+ */
+export function find(predicate) {
+    return createStatefulOperator({
+        name: "find",
+        createState: () => ({ index: 0 }),
+        transform(chunk, state, controller) {
+            const result = predicate(chunk, state.index++);
+            // If the predicate passes, emit the value and complete
+            if (result) {
+                controller.enqueue(chunk);
+                controller.terminate();
+            }
+        },
+    });
+}
+/**
+ * Removes duplicate values from the stream, keeping only the first occurrence.
+ *
+ * Like creating a `new Set()` from an array, but for async streams. You can
+ * provide a `keySelector` to determine uniqueness based on an object property.
+ *
+ * @example
+ * ```ts
+ * import { pipe, unique, from } from "./helpers/mod.ts";
+ *
+ * // Array behavior
+ * const uniqueNumbers = [...new Set([1, 2, 2, 3, 1])]; // [1, 2, 3]
+ *
+ * // Stream behavior
+ * const numberStream = from([1, 2, 2, 3, 1]);
+ * const uniqueStream = pipe(numberStream, unique()); // Emits 1, 2, 3
+ *
+ * // With a key selector
+ * const users = [{ id: 1, name: 'A' }, { id: 2, name: 'B' }, { id: 1, name: 'C' }];
+ * const userStream = from(users);
+ * const uniqueUserStream = pipe(userStream, unique(user => user.id)); // Emits { id: 1, name: 'A' }, { id: 2, name: 'B' }
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `unique` to de-duplicate a stream of events or data, such as processing
+ * a list of user IDs where some may appear multiple times, or handling event
+ * streams that might emit the same event more than once.
+ *
+ * ## Key Insight
+ *
+ * `unique` simplifies de-duplication in asynchronous pipelines, ensuring that
+ * downstream operations only run once for each unique item.
+ *
+ * @typeParam T The type of items in the stream.
+ * @typeParam K The type of the key used for uniqueness checks.
+ * @param keySelector An optional function to extract a key for uniqueness comparison.
+ * @returns An operator that filters out duplicate values.
+ */
+export function unique(keySelector) {
+    return createStatefulOperator({
+        name: "unique",
+        createState: () => ({ seen: new Set() }),
+        transform(chunk, state, controller) {
+            const key = keySelector
+                ? keySelector(chunk)
+                : chunk;
+            if (!state.seen.has(key)) {
+                state.seen.add(key);
+                controller.enqueue(chunk);
+            }
+        },
+    });
+}
+/**
+ * Emits an item only if it is different from the previous one.
+ *
+ * This is useful for streams where values can be emitted repeatedly, but you
+ * only care about the changes.
+ *
+ * @example
+ * ```ts
+ * import { pipe, changed, from } from "./helpers/mod.ts";
+ *
+ * // No direct Array equivalent, as it depends on sequence.
+ *
+ * // Stream behavior
+ * const valueStream = from([1, 1, 2, 2, 2, 1, 3]);
+ * const changedStream = pipe(valueStream, changed()); // Emits 1, 2, 1, 3
+ *
+ * // With a key selector
+ * const userStream = from([
+ *   { id: 1, status: 'active' },
+ *   { id: 1, status: 'active' },
+ *   { id: 1, status: 'inactive' }
+ * ]);
+ * const statusChangeStream = pipe(userStream, changed(user => user.status));
+ * // Emits { id: 1, status: 'active' }, { id: 1, status: 'inactive' }
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `changed` to monitor a stream of state updates and only react when the
+ * state actually changes. This is common in UI programming for tracking user
+ * input or state management.
+ *
+ * ## Key Insight
+ *
+ * `changed` filters out noise from repetitive values, allowing you to focus
+ * on the moments when something actually changes.
+ *
+ * @typeParam T The type of items in the stream.
+ * @typeParam K The type of the key used for comparison.
+ * @param keySelector An optional function to extract a key for comparison.
+ * @param compare An optional function to compare two keys for equality.
+ * @returns An operator that filters out consecutive duplicate values.
+ */

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

@@ -0,0 +1,198 @@
+import "../../_dnt.polyfills.js";
+import type { ExcludeError, Operator } from "../_types.js";
+import type { ObservableError } from "../../error.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 declare function map<T, R>(project: (value: ExcludeError<T>, index: number) => R): Operator<T | ObservableError, R | ObservableError>;
+/**
+ * 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 declare function filter<T>(predicate: (value: ExcludeError<T>, index: number) => boolean): Operator<T | ObservableError, ExcludeError<T> | ObservableError>;
+/**
+ * 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 declare function take<T>(count: number): Operator<T | ObservableError, ExcludeError<T> | ObservableError>;
+/**
+ * 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 declare function drop<T>(count: number): Operator<T | ObservableError, ExcludeError<T> | ObservableError>;
+/**
+ * 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 declare function tap<T>(fn: (value: ExcludeError<T>) => void): Operator<T | ObservableError, T | ObservableError>;
+/**
+ * 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 declare function scan<T, R>(accumulator: (acc: R, value: ExcludeError<T>, index: number) => R, seed: R): Operator<T | ObservableError, R | ObservableError>;
+//# sourceMappingURL=core.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/core.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAItD;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,CAAC,EACtB,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GACpD,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAapD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAC5D,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAclE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,KAAK,EAAE,MAAM,GACZ,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAoBlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,KAAK,EAAE,MAAM,GACZ,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAgBlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,GAAG,CAAC,CAAC,EACnB,EAAE,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,GACnC,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAQpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EACvB,WAAW,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,EACjE,IAAI,EAAE,CAAC,GACN,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAqBpD"}