@okikio/observables 1.0.2 → 1.3.0

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

@@ -14,7 +14,7 @@
  */
 import "../../_dnt.polyfills.js";
 import type { ExcludeError, Operator } from "../_types.js";
-import type { ObservableError } from "../../error.js";
+import { ObservableError } from "../../error.js";
 /**
  * Checks if every item in the stream passes a test.
  *
@@ -125,6 +125,45 @@ export declare function some<T>(predicate: (value: ExcludeError<T>, index: numbe
  * @returns A stream operator that finds the first matching value
  */
 export declare function find<T>(predicate: (value: ExcludeError<T>, index: number) => boolean): Operator<T | ObservableError, T | ObservableError>;
+/**
+ * Finds the index of the first item in the stream that passes a test.
+ *
+ * This mirrors `Array.prototype.findIndex()`: it emits the zero-based index of
+ * the first matching value, or `-1` if the stream completes without a match.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param predicate - Function to test each value
+ * @returns An operator that emits the first matching index or `-1`
+ */
+export declare function findIndex<T>(predicate: (value: ExcludeError<T>, index: number) => boolean): Operator<T | ObservableError, number | ObservableError>;
+/**
+ * Emits the value at a specific zero-based source index.
+ *
+ * Unlike arrays, streams cannot jump to a position directly, so this operator
+ * reads and counts values until it reaches the requested slot. If the stream
+ * completes first, it emits nothing.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param targetIndex - Zero-based index to emit
+ * @returns An operator that emits at most one value from the requested index
+ */
+export declare function elementAt<T>(targetIndex: number): Operator<T | ObservableError, T | ObservableError>;
+/**
+ * Emits the first value in the stream, optionally constrained by a predicate.
+ *
+ * Without a predicate this is the Observable equivalent of reading index `0`.
+ * With a predicate it behaves like `find()`, but the name is useful when the
+ * caller wants to emphasize "take the first match" rather than "search".
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param predicate - Optional test that the first emitted value must satisfy
+ * @returns An operator that emits at most one matching value
+ */
+export declare function first<T>(): Operator<T | ObservableError, T | ObservableError>;
+/**
+ * Emits the first value that satisfies the provided predicate.
+ */
+export declare function first<T>(predicate: (value: ExcludeError<T>, index: number) => boolean): Operator<T | ObservableError, T | ObservableError>;
 /**
  * Removes duplicate values from the stream, keeping only the first occurrence.
  *
@@ -165,12 +204,48 @@ export declare function find<T>(predicate: (value: ExcludeError<T>, index: numbe
  * @returns An operator that filters out duplicate values.
  */
 export declare function unique<T, K = T>(keySelector?: (value: ExcludeError<T>) => K): Operator<T | ObservableError, ExcludeError<T> | ObservableError>;
+/**
+ * Configuration for `changed()`.
+ *
+ * `by` lets you compare on a derived key instead of the full value.
+ * For example, you may want to emit only when `user.id` changes.
+ */
+export interface ChangedOptions<T, K = ExcludeError<T>> {
+    /**
+     * Pick the value that should be compared.
+     *
+     * By default, the full value is compared.
+     */
+    by?: (value: ExcludeError<T>, index: number) => K;
+    /**
+     * Decide whether two comparison keys should be treated as the same.
+     *
+     * By default, `Object.is()` is used.
+     */
+    equals?: (previous: K, current: K) => boolean;
+    /**
+     * Whether the first non-error value should be emitted.
+     *
+     * This defaults to `true`, which is usually what people expect from a
+     * "changed" operator.
+     */
+    emitFirst?: boolean;
+}
 /**
  * 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 1:
+ *   source: 1, 1, 2, 2, 3
+ *   output: 1, 2, 3
+ *
+ * Example 2:
+ *   source: { id: 1, name: "A" }, { id: 1, name: "B" }, { id: 2, name: "C" }
+ *   changed({ by: value => value.id })
+ *   output: first item, then the item with id 2
+ *
  * @example
  * ```ts
  * import { pipe, changed, from } from "./helpers/mod.ts";
@@ -208,4 +283,5 @@ export declare function unique<T, K = T>(keySelector?: (value: ExcludeError<T>)
  * @param compare An optional function to compare two keys for equality.
  * @returns An operator that filters out consecutive duplicate values.
  */
+export declare function changed<T, K = ExcludeError<T>>(options?: ChangedOptions<T, K>): Operator<T | ObservableError, T | ObservableError>;
 //# sourceMappingURL=conditional.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"conditional.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/conditional.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAItD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,KAAK,CAAC,CAAC,EACrB,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAC5D,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,OAAO,GAAG,eAAe,CAAC,CA2B1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAC5D,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,OAAO,GAAG,eAAe,CAAC,CA2B1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAC5D,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAcpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAC7B,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,GAC1C,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAqBlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG"}
+{"version":3,"file":"conditional.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/conditional.ts"],"names":[],"mappings":"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"}

package/esm/helpers/operations/conditional.js

@@ -13,6 +13,7 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
+import { isObservableError, ObservableError } from "../../error.js";
 import { createStatefulOperator } from "../operators.js";
 /**
  * Checks if every item in the stream passes a test.
@@ -181,6 +182,74 @@ export function find(predicate) {
         },
     });
 }
+/**
+ * Finds the index of the first item in the stream that passes a test.
+ *
+ * This mirrors `Array.prototype.findIndex()`: it emits the zero-based index of
+ * the first matching value, or `-1` if the stream completes without a match.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param predicate - Function to test each value
+ * @returns An operator that emits the first matching index or `-1`
+ */
+export function findIndex(predicate) {
+    return createStatefulOperator({
+        name: "findIndex",
+        createState: () => ({ index: 0, finished: false }),
+        transform(chunk, state, controller) {
+            if (state.finished) {
+                return;
+            }
+            const currentIndex = state.index;
+            const result = predicate(chunk, currentIndex);
+            state.index++;
+            if (result) {
+                state.finished = true;
+                controller.enqueue(currentIndex);
+                controller.terminate();
+            }
+        },
+        flush(state, controller) {
+            if (!state.finished) {
+                controller.enqueue(-1);
+            }
+        },
+    });
+}
+/**
+ * Emits the value at a specific zero-based source index.
+ *
+ * Unlike arrays, streams cannot jump to a position directly, so this operator
+ * reads and counts values until it reaches the requested slot. If the stream
+ * completes first, it emits nothing.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param targetIndex - Zero-based index to emit
+ * @returns An operator that emits at most one value from the requested index
+ */
+export function elementAt(targetIndex) {
+    if (!Number.isInteger(targetIndex) || targetIndex < 0) {
+        throw new RangeError("elementAt: targetIndex must be a non-negative integer");
+    }
+    return createStatefulOperator({
+        name: "elementAt",
+        createState: () => ({ index: 0 }),
+        transform(chunk, state, controller) {
+            if (state.index === targetIndex) {
+                controller.enqueue(chunk);
+                controller.terminate();
+                return;
+            }
+            state.index++;
+        },
+    });
+}
+export function first(predicate) {
+    if (!predicate) {
+        return elementAt(0);
+    }
+    return find(predicate);
+}
 /**
  * Removes duplicate values from the stream, keeping only the first occurrence.
  *
@@ -235,12 +304,27 @@ export function unique(keySelector) {
         },
     });
 }
+function defaultBy(value) {
+    return value;
+}
+function defaultEquals(previous, current) {
+    return Object.is(previous, current);
+}
 /**
  * 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 1:
+ *   source: 1, 1, 2, 2, 3
+ *   output: 1, 2, 3
+ *
+ * Example 2:
+ *   source: { id: 1, name: "A" }, { id: 1, name: "B" }, { id: 2, name: "C" }
+ *   changed({ by: value => value.id })
+ *   output: first item, then the item with id 2
+ *
  * @example
  * ```ts
  * import { pipe, changed, from } from "./helpers/mod.ts";
@@ -278,3 +362,58 @@ export function unique(keySelector) {
  * @param compare An optional function to compare two keys for equality.
  * @returns An operator that filters out consecutive duplicate values.
  */
+export function changed(options = {}) {
+    const by = (options.by ??
+        defaultBy);
+    const equals = (options.equals ??
+        defaultEquals);
+    const emitFirst = options.emitFirst ?? true;
+    return createStatefulOperator({
+        name: "changed",
+        createState: () => ({
+            hasPrevious: false,
+            previousKey: undefined,
+            index: 0,
+        }),
+        transform(chunk, state, controller) {
+            if (isObservableError(chunk)) {
+                controller.enqueue(chunk);
+                return;
+            }
+            const value = chunk;
+            let currentKey;
+            try {
+                currentKey = by(value, state.index++);
+            }
+            catch (err) {
+                controller.enqueue(ObservableError.from(err, "operator:stateful:changed:by", value));
+                return;
+            }
+            if (!state.hasPrevious) {
+                state.hasPrevious = true;
+                state.previousKey = currentKey;
+                if (emitFirst) {
+                    controller.enqueue(value);
+                }
+                return;
+            }
+            let isSame;
+            try {
+                isSame = equals(state.previousKey, currentKey);
+            }
+            catch (err) {
+                controller.enqueue(ObservableError.from(err, "operator:stateful:changed:equals", value));
+                return;
+            }
+            state.previousKey = currentKey;
+            if (!isSame) {
+                controller.enqueue(value);
+            }
+        },
+        cancel(state) {
+            state.hasPrevious = false;
+            state.previousKey = undefined;
+            state.index = 0;
+        },
+    });
+}

package/esm/helpers/operators.d.ts

@@ -436,6 +436,63 @@ export declare function handleStart<T, O, S extends unknown = undefined>(errorMo
  * @returns A function suitable for TransformStream's `flush` property, or undefined
  */
 export declare function handleFlush<T, O, S extends unknown = undefined>(errorMode: OperatorErrorMode, flush?: TransformFunctionOptions<T, O>["flush"] | StatefulTransformFunctionOptions<T, O, S>["flush"], context?: TransformHandlerContext<S>): Transformer<T, O>["flush"];
+/**
+ * Lifecycle handling for downstream cancellation cleanup.
+ *
+ * `flush()` runs when the source ends normally. `cancel()` runs when a consumer
+ * stops early, for example by unsubscribing, breaking out of `for await`, or
+ * otherwise cancelling the pipeline before the source completes.
+ *
+ * ```text
+ * source completes normally  -> flush()
+ * consumer stops early       -> cancel(reason)
+ * ```
+ *
+ * That distinction matters for operators that hold timers, inner
+ * subscriptions, or abort controllers. Those resources should be released when
+ * the consumer goes away, even if the source never reached completion.
+ *
+ * Cleanup here is intentionally not treated like transform output. If the
+ * cleanup callback fails, the cancellation promise rejects, but no
+ * `ObservableError` is emitted into the stream because the consumer has already
+ * said it is no longer interested in more values.
+ *
+ * @typeParam T - Input chunk type
+ * @typeParam O - Output chunk type
+ * @typeParam S - State type (for stateful operators)
+ * @param _errorMode - Unused here. Cancellation cleanup does not route through
+ * the operator error modes because it is teardown, not part of the data path.
+ * @param cancel - Your cancellation handler (stateless or stateful, optional)
+ * @param context - Info about the operator, including name and state
+ * @returns A function suitable for a ReadableStream `cancel` hook, or undefined
+ */
+export declare function handleCancel<T, O, S extends unknown = undefined>(_errorMode: OperatorErrorMode, cancel?: TransformFunctionOptions<T, O>["cancel"] | StatefulTransformFunctionOptions<T, O, S>["cancel"], context?: TransformHandlerContext<S>): ((reason?: unknown) => Promise<void>) | undefined;
+/**
+ * Wraps a transformed stream so operator-level cleanup runs when a downstream
+ * consumer stops early.
+ *
+ * This wrapper has a deliberately narrow job: it forwards readable-side
+ * cancellation to an operator cleanup callback while preserving the chunks
+ * coming from the wrapped stream. It does not try to redefine TransformStream
+ * semantics or reinterpret cancellation as a normal data-path error.
+ *
+ * ```text
+ * source -> TransformStream -> wrapped readable -> consumer
+ *                                |
+ *                                +-> cancel(reason)
+ * ```
+ *
+ * @typeParam T - Output chunk type of the wrapped stream
+ * @param stream - The transformed stream to expose downstream
+ * @param options - Cancellation behavior for the wrapped stream
+ * @returns A readable stream that preserves output values and forwards cancel
+ */
+export declare function wrapStreamWithCancel<T>(stream: ReadableStream<T>, options?: {
+    /**
+     * Cleanup to run if the consumer cancels the stream before it completes.
+     */
+    cancel?: (reason?: unknown) => void | Promise<void>;
+}): ReadableStream<T>;
 /**
  * Creates operators that maintain state across stream chunks
  *

package/esm/helpers/operators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operators.d.ts","sourceRoot":"","sources":["../../src/helpers/operators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2NG;AAEH,OAAO,KAAK,EAEV,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,gCAAgC,EAChC,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAqB,eAAe,EAAE,MAAM,aAAa,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,wBAAgB,cAAc,CAC5B,CAAC,EACD,CAAC,EACD,CAAC,SAAS,CAAC,GAAG,eAAe,GAAG,CAAC,GAAG,eAAe,EAEnD,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,cAAc,CAAA;CAAE,GACvE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAClB;;GAEG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EACD,CAAC,EACD,CAAC,SAAS,CAAC,GAAG,eAAe,GAAG,CAAC,GAAG,eAAe,EAEnD,OAAO,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,cAAc,CAAA;CAAE,GACrE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAElB;;GAEG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EACD,CAAC,EACD,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAE3C,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,QAAQ,CAAA;CAAE,GAChE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAClB;;GAEG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EACD,CAAC,EACD,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAE3C,OAAO,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,QAAQ,CAAA;CAAE,GAC9D,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAElB;;GAEG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EACD,CAAC,EACD,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAE3C,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAC/D,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAClB;;GAEG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EACD,CAAC,EACD,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAE3C,OAAO,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAC7D,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAElB;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EACxC,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,QAAQ,CAAA;CAAE,GAChE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAClB;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EACxC,OAAO,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,QAAQ,CAAA;CAAE,GAC9D,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAsDlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,EAC7C,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EACL,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,GAC3C,gCAAgC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,EAC1D,OAAO,GAAE,uBAAuB,CAAC,CAAC,CAAM,GACvC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAuHhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,OAAO,GAAG,SAAS,EAC7D,SAAS,EAAE,iBAAiB,EAC5B,KAAK,CAAC,EACF,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GACvC,gCAAgC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EACtD,OAAO,GAAE,uBAAuB,CAAC,CAAC,CAAM,GACvC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CA0C5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,OAAO,GAAG,SAAS,EAC7D,SAAS,EAAE,iBAAiB,EAC5B,KAAK,CAAC,EACF,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GACvC,gCAAgC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EACtD,OAAO,GAAE,uBAAuB,CAAC,CAAC,CAAM,GACvC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CA0C5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAGH,wBAAgB,sBAAsB,CACpC,CAAC,EACD,CAAC,EACD,CAAC,EACD,CAAC,SAAS,CAAC,GAAG,eAAe,GAAG,CAAC,GAAG,eAAe,EAEnD,OAAO,EAAE,gCAAgC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG;IACnD,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B,GACA,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAElB;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,EACD,CAAC,EACD,CAAC,EACD,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAE3C,OAAO,EAAE,gCAAgC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,QAAQ,CAAA;CAAE,GAC3E,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAElB;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,EACD,CAAC,EACD,CAAC,EACD,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAE3C,OAAO,EAAE,gCAAgC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAC1E,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAElB;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EACnD,OAAO,EAAE,gCAAgC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG;IAAE,SAAS,EAAE,QAAQ,CAAA;CAAE,GAC3E,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"operators.d.ts","sourceRoot":"","sources":["../../src/helpers/operators.ts"],"names":[],"mappings":"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"}

package/esm/helpers/operators.js

@@ -230,6 +230,7 @@ export function createOperator(options) {
     const transform = options?.transform;
     const start = options?.start;
     const flush = options?.flush;
+    const cancel = options?.cancel;
     return (source) => {
         try {
             // Create a transform stream with the provided options
@@ -243,8 +244,10 @@ export function createOperator(options) {
                     // Flush function called when the input is done
                     flush: handleFlush(errorMode, flush, { operatorName }),
                 }, { highWaterMark: 1 }, { highWaterMark: 0 });
-            // Pipe the source through the transform
-            return source.pipeThrough(transformStream);
+            // Pipe the source through the transform and bind downstream cancellation
+            return wrapStreamWithCancel(source.pipeThrough(transformStream), {
+                cancel: handleCancel(errorMode, cancel, { operatorName }),
+            });
         }
         catch (err) {
             // If setup fails, return a stream that errors immediately
@@ -501,6 +504,131 @@ export function handleFlush(errorMode, flush, context = {}) {
         }
     };
 }
+/**
+ * Lifecycle handling for downstream cancellation cleanup.
+ *
+ * `flush()` runs when the source ends normally. `cancel()` runs when a consumer
+ * stops early, for example by unsubscribing, breaking out of `for await`, or
+ * otherwise cancelling the pipeline before the source completes.
+ *
+ * ```text
+ * source completes normally  -> flush()
+ * consumer stops early       -> cancel(reason)
+ * ```
+ *
+ * That distinction matters for operators that hold timers, inner
+ * subscriptions, or abort controllers. Those resources should be released when
+ * the consumer goes away, even if the source never reached completion.
+ *
+ * Cleanup here is intentionally not treated like transform output. If the
+ * cleanup callback fails, the cancellation promise rejects, but no
+ * `ObservableError` is emitted into the stream because the consumer has already
+ * said it is no longer interested in more values.
+ *
+ * @typeParam T - Input chunk type
+ * @typeParam O - Output chunk type
+ * @typeParam S - State type (for stateful operators)
+ * @param _errorMode - Unused here. Cancellation cleanup does not route through
+ * the operator error modes because it is teardown, not part of the data path.
+ * @param cancel - Your cancellation handler (stateless or stateful, optional)
+ * @param context - Info about the operator, including name and state
+ * @returns A function suitable for a ReadableStream `cancel` hook, or undefined
+ */
+export function handleCancel(_errorMode, cancel, context = {}) {
+    if (!cancel)
+        return;
+    const operatorName = context.operatorName || `operator:unknown`;
+    const isStateful = context.isStateful || false;
+    const state = context.state;
+    return async function (reason) {
+        try {
+            if (isStateful) {
+                await cancel(state, reason);
+                return;
+            }
+            await cancel(reason);
+        }
+        catch (err) {
+            throw ObservableError.from(err, `${operatorName}:cancel`, reason);
+        }
+    };
+}
+/**
+ * Wraps a transformed stream so operator-level cleanup runs when a downstream
+ * consumer stops early.
+ *
+ * This wrapper has a deliberately narrow job: it forwards readable-side
+ * cancellation to an operator cleanup callback while preserving the chunks
+ * coming from the wrapped stream. It does not try to redefine TransformStream
+ * semantics or reinterpret cancellation as a normal data-path error.
+ *
+ * ```text
+ * source -> TransformStream -> wrapped readable -> consumer
+ *                                |
+ *                                +-> cancel(reason)
+ * ```
+ *
+ * @typeParam T - Output chunk type of the wrapped stream
+ * @param stream - The transformed stream to expose downstream
+ * @param options - Cancellation behavior for the wrapped stream
+ * @returns A readable stream that preserves output values and forwards cancel
+ */
+export function wrapStreamWithCancel(stream, options = {}) {
+    if (!options.cancel)
+        return stream;
+    const reader = stream.getReader();
+    let settled = false;
+    // The wrapper acquires an exclusive reader, so releasing it exactly once
+    // keeps teardown predictable even when both cancel and read completion race.
+    const release = () => {
+        if (settled)
+            return;
+        settled = true;
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // Releasing the reader is best-effort during teardown.
+        }
+    };
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                // Forward chunks one-by-one so downstream backpressure still controls
+                // how quickly we read from the wrapped stream.
+                const { done, value } = await reader.read();
+                if (done) {
+                    release();
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(value);
+            }
+            catch (err) {
+                release();
+                controller.error(err);
+            }
+        },
+        async cancel(reason) {
+            try {
+                // Run operator cleanup first so resources such as timers or inner
+                // subscriptions are released before we cancel the wrapped reader.
+                await options.cancel?.(reason);
+            }
+            finally {
+                try {
+                    // Cancelling the reader tells the wrapped stream that nobody wants
+                    // more output. Any rejection here is surfaced through the returned
+                    // cancellation promise instead of being emitted as a chunk.
+                    await reader.cancel(reason);
+                }
+                finally {
+                    release();
+                }
+            }
+        },
+    });
+}
 // Default case
 export function createStatefulOperator(options) {
     // Extract operator name from options or the function name for better error reporting
@@ -512,6 +640,7 @@ export function createStatefulOperator(options) {
         ?.transform;
     const start = options?.start;
     const flush = options?.flush;
+    const cancel = options?.cancel;
     return (source) => {
         try {
             // Create state only when the stream is used
@@ -552,8 +681,14 @@ export function createStatefulOperator(options) {
                     state,
                 }),
             }, { highWaterMark: 1 }, { highWaterMark: 0 });
-            // Pipe the source through the transform
-            return source.pipeThrough(transformStream);
+            // Pipe the source through the transform and bind downstream cancellation
+            return wrapStreamWithCancel(source.pipeThrough(transformStream), {
+                cancel: handleCancel(errorMode, cancel, {
+                    operatorName,
+                    isStateful: true,
+                    state,
+                }),
+            });
         }
         catch (err) {
             // If setup fails, return a stream that errors immediately

package/esm/helpers/utils.d.ts

@@ -1,6 +1,7 @@
-import type { TransformFunctionOptions, TransformStreamOptions } from "./_types.js";
+import type { ObservableInteropInputLike, ObservableOperatorInterop, ObservableOperatorInteropOptions, TransformFunctionOptions, StreamPair, TransformStreamOptions } from "./_types.js";
 import type { CreateOperatorOptions, Operator } from "./_types.js";
 import { ObservableError } from "../error.js";
+import { Observable } from "../observable.js";
 /**
  * Type guard to check if options is a TransformStreamOptions
  *
@@ -73,6 +74,77 @@ export declare function applyOperator(input: ReadableStream<unknown>, operator:
  * ```
  */
 export declare function toStream<T>(iterable: Iterable<T> | AsyncIterable<T>): ReadableStream<T | ObservableError>;
+/**
+ * Adapts a readable/writable stream pair into an Observable operator.
+ *
+ * Some platform transforms, such as `CompressionStream`, expose a writable side
+ * and a readable side without being created through this library's operator
+ * builders. This helper turns that pair into a normal `Operator` so it can be
+ * used inside `pipe()` like any built-in operator.
+ *
+ * A fresh pair is created for each operator application. That preserves the
+ * cold semantics of the surrounding Observable pipeline and avoids reusing a
+ * consumed stream pair across subscriptions.
+ *
+ * @typeParam TIn - Chunk type written into the pair
+ * @typeParam TOut - Chunk type read from the pair
+ * @param createPair - Factory that returns a fresh readable/writable pair
+ * @returns An operator that pipes input through the created pair
+ *
+ * @example
+ * ```ts
+ * const gzip = fromStreamPair<Uint8Array, Uint8Array>(
+ *   () => new CompressionStream('gzip')
+ * );
+ * ```
+ */
+export declare function fromStreamPair<TIn, TOut>(createPair: () => StreamPair<TIn, TOut>): Operator<TIn, TOut>;
+/**
+ * Wraps a `ReadableStream` as an Observable so foreign Observable-style
+ * operators can subscribe to it directly.
+ *
+ * This avoids first converting the stream into an async-iterable Observable via
+ * `Observable.from()`, which would add an extra adaptation layer before the
+ * foreign operator even starts running.
+ */
+export declare function streamAsObservable<T>(stream: ReadableStream<T>): Observable<T>;
+/**
+ * Subscribes to an Observable-like output and exposes it as a ReadableStream.
+ *
+ * Foreign operators are allowed to return either a normal `Observable.from()`
+ * input or a direct subscribable from another Observable implementation.
+ * Converting the result with a direct subscription avoids the extra
+ * async-generator and stream layers that `pull(...)+toStream()` would add.
+ */
+export declare function observableInputToStream<T>(input: ObservableInteropInputLike<T>, errorContext: string): ReadableStream<T | ObservableError>;
+/**
+ * Adapts a foreign Observable-style operator into a stream operator.
+ *
+ * Libraries such as RxJS model operators as functions from one Observable-like
+ * source to another Observable-like result. This helper bridges that shape into
+ * this library's `Operator` contract by:
+ *
+ * 1. wrapping the input stream as an Observable-like source
+ * 2. calling the foreign operator
+ * 3. converting the resulting Observable-like output back into a stream
+ *
+ * The result keeps this library's buffered error behavior by converting the
+ * foreign output into a `ReadableStream` that enqueues wrapped
+ * `ObservableError` values instead of failing the readable side outright.
+ *
+ * @typeParam TIn - Value type accepted by the foreign operator
+ * @typeParam TOut - Value type produced by the foreign operator
+ * @param operator - Foreign operator function to adapt
+ * @returns An operator compatible with this library's `pipe()`
+ *
+ * @example
+ * ```ts
+ * const foreignTakeOne = fromObservableOperator<number, number>((source) =>
+ *   rxTake(1)(source)
+ * , { sourceAdapter: (source) => rxFrom(source) });
+ * ```
+ */
+export declare function fromObservableOperator<TIn, TOut, TSource = Observable<TIn>>(operator: ObservableOperatorInterop<TIn, TOut, TSource>, options?: ObservableOperatorInteropOptions<TIn, TSource>): Operator<TIn, TOut | ObservableError>;
 /**
  * Creates a TransformStream that injects an error at the start and passes through all original data.
  *

package/esm/helpers/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/helpers/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,CAAC,EAC3C,OAAO,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,GACnC,OAAO,IAAI,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CAEzC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,CAAC,EAC7C,OAAO,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,GACnC,OAAO,IAAI,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,CAE3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,EAE9B,QAAQ,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAC5B,EAAE,OAAyB,EAAE;;CAAK,GACjC,cAAc,CAAC,OAAO,CAAC,CAOzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GACvC,cAAc,CAAC,CAAC,GAAG,eAAe,CAAC,CAkCrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,OAAO,GAAG,OAAO,EAAE,EAC7C,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,OAAO,GACd,eAAe,CAAC,CAAC,EAAE,eAAe,CAAC,CAOrC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/helpers/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,gCAAgC,EAChC,wBAAwB,EACxB,UAAU,EACV,sBAAsB,EACvB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,CAAC,EAC3C,OAAO,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,GACnC,OAAO,IAAI,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CAEzC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,CAAC,EAC7C,OAAO,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,GACnC,OAAO,IAAI,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,CAE3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,EAE9B,QAAQ,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EAC5B,EAAE,OAAyB,EAAE;;CAAK,GACjC,cAAc,CAAC,OAAO,CAAC,CAOzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GACvC,cAAc,CAAC,CAAC,GAAG,eAAe,CAAC,CAkCrC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,IAAI,EACtC,UAAU,EAAE,MAAM,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GACtC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAErB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAsC9E;AAsBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,KAAK,EAAE,0BAA0B,CAAC,CAAC,CAAC,EACpC,YAAY,EAAE,MAAM,GACnB,cAAc,CAAC,CAAC,GAAG,eAAe,CAAC,CAqCrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,EACzE,QAAQ,EAAE,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,EACvD,OAAO,CAAC,EAAE,gCAAgC,CAAC,GAAG,EAAE,OAAO,CAAC,GACvD,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG,eAAe,CAAC,CAcvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,OAAO,GAAG,OAAO,EAAE,EAC7C,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,OAAO,GACd,eAAe,CAAC,CAAC,EAAE,eAAe,CAAC,CAOrC"}