@okikio/observables 1.0.2 → 1.3.0

package/esm/helpers/utils.js

@@ -1,4 +1,5 @@
 import { ObservableError } from "../error.js";
+import { Observable } from "../observable.js";
 /**
  * Type guard to check if options is a TransformStreamOptions
  *
@@ -118,6 +119,173 @@ export function toStream(iterable) {
         },
     });
 }
+/**
+ * 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 function fromStreamPair(createPair) {
+    return (source) => source.pipeThrough(createPair());
+}
+/**
+ * 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 function streamAsObservable(stream) {
+    return new Observable((observer) => {
+        const reader = stream.getReader();
+        let cancelled = false;
+        void (async () => {
+            try {
+                while (!cancelled && !observer.closed) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        break;
+                    }
+                    observer.next(value);
+                }
+                if (!cancelled && !observer.closed) {
+                    observer.complete();
+                }
+            }
+            catch (err) {
+                if (!cancelled && !observer.closed) {
+                    observer.error(err);
+                }
+            }
+            finally {
+                try {
+                    reader.releaseLock();
+                }
+                catch {
+                    // Releasing the reader is best-effort during teardown.
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            void reader.cancel();
+        };
+    });
+}
+/**
+ * Returns true when a value exposes a direct `subscribe()` method.
+ *
+ * Many Observable libraries return subscribable objects that are usable without
+ * first going through this library's `Observable.from()`. Detecting that shape
+ * lets interop stay direct for outputs such as RxJS Observables.
+ */
+function hasSubscribe(input) {
+    return typeof input === "object" && input !== null &&
+        typeof input.subscribe === "function";
+}
+/**
+ * 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 function observableInputToStream(input, errorContext) {
+    let subscription;
+    return new ReadableStream({
+        start(controller) {
+            const source = hasSubscribe(input) ? input : Observable.from(input);
+            subscription = source.subscribe({
+                next(value) {
+                    try {
+                        controller.enqueue(value);
+                    }
+                    catch {
+                        // Downstream cancellation already decided the stream outcome.
+                    }
+                },
+                error(error) {
+                    try {
+                        controller.enqueue(ObservableError.from(error, errorContext));
+                        controller.close();
+                    }
+                    catch {
+                        // Downstream cancellation already decided the stream outcome.
+                    }
+                },
+                complete() {
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        // Downstream cancellation already decided the stream outcome.
+                    }
+                },
+            });
+        },
+        cancel() {
+            subscription?.unsubscribe?.();
+            subscription = undefined;
+        },
+    });
+}
+/**
+ * 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 function fromObservableOperator(operator, options) {
+    return (source) => {
+        const observableSource = streamAsObservable(source);
+        const foreignSource = options?.sourceAdapter
+            ? options.sourceAdapter(observableSource)
+            : observableSource;
+        const output = operator(foreignSource);
+        return observableInputToStream(output, options?.errorContext ?? "operator:fromObservableOperator:output");
+    };
+}
 /**
  * Creates a TransformStream that injects an error at the start and passes through all original data.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okikio/observables",
-  "version": "1.0.2",
+  "version": "1.3.0",
   "description": "A spec-faithful yet ergonomic TC39-inspired Observable library with detailed types, tsdocs and examples.",
   "keywords": [
     "observable",

package/script/helpers/_types.d.ts

@@ -1,5 +1,6 @@
 import type { ObservableError } from "../error.js";
 import type { Observable } from "../observable.js";
+import type { SpecObservable } from "../_spec.js";
 /**
  * Type representing a stream operator function
  * Transforms a ReadableStream of type In to a ReadableStream of type Out
@@ -67,6 +68,67 @@ export interface BaseTransformOptions {
      */
     name?: string;
 }
+/**
+ * Structural readable/writable pair used by platform transforms such as
+ * `CompressionStream`.
+ */
+export interface StreamPair<TIn, TOut> {
+    /** Readable side exposed by the transform-like object. */
+    readable: ReadableStream<TOut>;
+    /** Writable side exposed by the transform-like object. */
+    writable: WritableStream<TIn>;
+}
+/**
+ * Minimal subscribable shape used by foreign Observable implementations.
+ */
+export interface SubscribableLike<T> {
+    /** Subscribe to values from the foreign Observable-like object. */
+    subscribe(observer: {
+        next?(value: T): void;
+        error?(error: unknown): void;
+        complete?(): void;
+    }): {
+        unsubscribe?(): void;
+    } | void;
+}
+/**
+ * Observable-like values that can be converted through `Observable.from()`.
+ */
+export type ObservableInputLike<T> = SpecObservable<T> | AsyncIterable<T> | Iterable<T> | PromiseLike<T>;
+/**
+ * Wider Observable-like values accepted by interop helpers that adapt foreign
+ * operator ecosystems.
+ *
+ * This is intentionally wider than `ObservableInputLike<T>`. `Observable.from()`
+ * stays aligned with the library's spec-facing conversion contract, while
+ * interop helpers may also need to consume direct subscribables returned by
+ * third-party libraries such as RxJS.
+ */
+export type ObservableInteropInputLike<T> = ObservableInputLike<T> | SubscribableLike<T>;
+/**
+ * Foreign operator shape used by libraries that transform one Observable-like
+ * source into another Observable-like result.
+ */
+export type ObservableOperatorInterop<TIn, TOut, TSource = Observable<TIn>> = (source: TSource) => ObservableInteropInputLike<TOut>;
+/**
+ * Configuration for adapting foreign Observable-style operators.
+ *
+ * Some libraries, such as RxJS, require their own Observable class on the
+ * input side even when the returned operator shape is still `(source) =>
+ * output`. `sourceAdapter` lets callers convert this library's Observable into
+ * that foreign source type before the operator runs.
+ */
+export interface ObservableOperatorInteropOptions<TIn, TSource = Observable<TIn>> {
+    /**
+     * Converts this library's Observable into the source type expected by the
+     * foreign operator.
+     */
+    sourceAdapter?: (source: Observable<TIn>) => TSource;
+    /**
+     * Context label used when the foreign output reports an error.
+     */
+    errorContext?: string;
+}
 /**
  * Options for using an existing TransformStream
  */

package/script/helpers/_types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_types.d.ts","sourceRoot":"","sources":["../../src/helpers/_types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,EAAE,EAAE,GAAG,IAAI,CAC9B,MAAM,EAAE,cAAc,CAAC,EAAE,CAAC,KACvB,cAAc,CAAC,GAAG,CAAC,CAAC;AAEzB;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;AAE1D;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,SAAS,OAAO,IAAI,OAAO,SAC5D,UAAU,CAAC,OAAO,CAAC,GAAG,mBAAmB,CAAC,OAAO,CAAC,GAChD,OAAO,SAAS,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,GAC5C,2BAA2B,CAAC,OAAO,CAAC,GACtC,OAAO,CAAC;AAEZ;;GAEG;AACH,MAAM,MAAM,2BAA2B,CACrC,OAAO,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,IACpC,UAAU,CAAC,OAAO,CAAC,SAAS,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,OAAO,SAAS,UAAU,CAAC,OAAO,CAAC,IACjE,OAAO,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,MAAM,SAAS,SAAS,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,IACxE,MAAM,CAAC,CAAC,CAAC,CAAC;AAEZ;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,SAAS,GAAG,EAAE,IAAI,CAAC,SAC5D;IAAC,GAAG,MAAM,CAAC;IAAE,MAAM,CAAC;CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpC;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,IACpD,oBAAoB,CAAC,CAAC,CAAC,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,GAClD,oBAAoB,CAAC,CAAC,CAAC,GACvB,KAAK,CAAC;AAEZ;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAC5B,KAAK,SAAS,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,CAAC,IAC3E,UAAU,CAAC,2BAA2B,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,oBAAoB;IACxE;;OAEG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACvE;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,oBAAoB;IAC1E;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAE9B;;;;;OAKG;IACH,SAAS,EAAE,CACT,KAAK,EAAE,CAAC,EACR,UAAU,EAAE,gCAAgC,CAAC,CAAC,CAAC,KAC5C,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IAExE;;;;OAIG;IACH,KAAK,CAAC,EAAE,CACN,UAAU,EAAE,gCAAgC,CAAC,CAAC,CAAC,KAC5C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;OAGG;IACH,KAAK,CAAC,EAAE,CACN,UAAU,EAAE,gCAAgC,CAAC,CAAC,CAAC,KAC5C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,EAAE,CAAC,IAClC,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAMnC;;GAEG;AACH,MAAM,WAAW,gCAAgC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CACvD,SAAQ,oBAAoB;IAC5B;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAE9B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC,CAAC;IAErB;;;;;OAKG;IACH,SAAS,EAAE,CACT,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,CAAC,EACR,UAAU,EAAE,gCAAgC,CAAC,CAAC,CAAC,KAC5C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,CACN,KAAK,EAAE,CAAC,EACR,UAAU,EAAE,gCAAgC,CAAC,CAAC,CAAC,KAC5C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,CACN,KAAK,EAAE,CAAC,EACR,UAAU,EAAE,gCAAgC,CAAC,CAAC,CAAC,KAC5C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,EAAE,CACP,KAAK,EAAE,CAAC,EACR,MAAM,CAAC,EAAE,OAAO,KACb,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,OAAO,GAAG,SAAS;IACpE;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,CAAC,CAAC;CACX"}
+{"version":3,"file":"_types.d.ts","sourceRoot":"","sources":["../../src/helpers/_types.ts"],"names":[],"mappings":"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"}

package/script/helpers/operations/combination.d.ts

@@ -18,6 +18,51 @@ import "../../_dnt.polyfills.js";
 import type { SpecObservable } from "../../_spec.js";
 import type { ExcludeError, Operator } from "../_types.js";
 import { ObservableError } from "../../error.js";
+/**
+ * Creates a follow-up Observable for each source value.
+ *
+ * These higher-order operators all work in two stages:
+ * they read an outer source value, then use this callback to start an inner
+ * Observable whose values are forwarded according to the operator's policy.
+ *
+ * ```text
+ * outer value ---> createFollowUp(value, index) ---> inner Observable
+ * ```
+ *
+ * The operators in this module differ in what they do after that point:
+ *
+ * ```text
+ * mergeMap   -> keep many inners running at once
+ * concatMap  -> queue inners and run one at a time
+ * switchMap  -> cancel the old inner and keep only the latest one
+ * ```
+ *
+ * @typeParam T - Value type from the outer source
+ * @typeParam R - Value type emitted by each follow-up Observable
+ */
+export type FollowUpProject<T, R> = (value: ExcludeError<T>, index: number) => SpecObservable<R>;
+/**
+ * Tuple of values emitted by a source and one or more companion Observables.
+ *
+ * Operators such as `withLatestFrom`, `combineLatestWith`, and `zipWith`
+ * return tuples so callers can decide how to shape the combined values in a
+ * later `map()` step without losing type information.
+ *
+ * @typeParam T - Value type from the primary source
+ * @typeParam TOthers - Value types from the companion Observables
+ */
+export type CombinationTuple<T, TOthers extends readonly unknown[]> = [
+    T,
+    ...TOthers
+];
+/**
+ * Tuple-shaped list of companion Observables used by the combination helpers.
+ *
+ * @typeParam TValues - Value types emitted by each companion Observable
+ */
+export type CombinationSources<TValues extends readonly unknown[]> = {
+    [K in keyof TValues]: SpecObservable<TValues[K]>;
+};
 /**
  * Transforms each item into a new stream and merges their outputs, running
  * them in parallel.
@@ -63,7 +108,7 @@ import { ObservableError } from "../../error.js";
  * to concurrently. Default is Infinity.
  * @returns An operator function that maps and flattens values
  */
-export declare function mergeMap<T, R>(project: (value: ExcludeError<T>, index: number) => SpecObservable<R>, concurrent?: number): Operator<T | ObservableError, R | ObservableError>;
+export declare function mergeMap<T, R>(project: FollowUpProject<T, R>, concurrent?: number): Operator<T | ObservableError, R | ObservableError>;
 /**
  * Transforms each item into a new stream and runs them one after another, in
  * strict order.
@@ -113,7 +158,7 @@ export declare function mergeMap<T, R>(project: (value: ExcludeError<T>, index:
  * @param project - Function that maps a source value to an Observable
  * @returns An operator function that maps and concatenates values
  */
-export declare function concatMap<T, R>(project: (value: ExcludeError<T>, index: number) => SpecObservable<R>): Operator<T | ObservableError, R | ObservableError>;
+export declare function concatMap<T, R>(project: FollowUpProject<T, R>): Operator<T | ObservableError, R | ObservableError>;
 /**
  * Transforms items into new streams, but cancels the previous stream when a new
  * item arrives.
@@ -158,5 +203,69 @@ export declare function concatMap<T, R>(project: (value: ExcludeError<T>, index:
  * @param project - Function that maps a source value to an Observable
  * @returns An operator function that maps and switches between values
  */
-export declare function switchMap<T, R>(project: (value: ExcludeError<T>, index: number) => SpecObservable<R>): Operator<T | ObservableError, R | ObservableError>;
+export declare function switchMap<T, R>(project: FollowUpProject<T, R>): Operator<T | ObservableError, R | ObservableError>;
+/**
+ * Emits each source value together with the latest value from every companion
+ * Observable.
+ *
+ * This operator waits until every companion Observable has produced at least
+ * one value. After that gate opens, each new source value emits a tuple that
+ * includes the source value followed by the most recent companion values.
+ *
+ * ```text
+ * companion A: ---a----b-------c--
+ * companion B: -----x-------y-----
+ * source:      ------1--2------3--
+ * output:      ------[1,a,x][2,b,x][3,c,y]
+ * ```
+ *
+ * The source still decides when outputs happen. Companion Observables only
+ * update the remembered latest values.
+ *
+ * @typeParam T - Value type from the primary source
+ * @typeParam TOthers - Value types from the companion Observables
+ * @param others - Companion Observables whose latest values should be attached
+ * @returns An operator that emits tuples of the source value and latest others
+ */
+export declare function withLatestFrom<T, TOthers extends readonly unknown[]>(...others: CombinationSources<TOthers>): Operator<T | ObservableError, CombinationTuple<ExcludeError<T>, TOthers> | ObservableError>;
+/**
+ * Combines the source with companion Observables using combine-latest timing.
+ *
+ * Once every source has emitted at least one value, any new value from the
+ * primary source or a companion Observable emits a new tuple containing the
+ * latest value from each source.
+ *
+ * @typeParam T - Value type from the primary source
+ * @typeParam TOthers - Value types from the companion Observables
+ * @param others - Companion Observables that participate in the latest-value set
+ * @returns An operator that emits tuples of the latest value from every source
+ */
+export declare function combineLatestWith<T, TOthers extends readonly unknown[]>(...others: CombinationSources<TOthers>): Operator<T | ObservableError, CombinationTuple<ExcludeError<T>, TOthers> | ObservableError>;
+/**
+ * Pairs source values with companion values in strict arrival order.
+ *
+ * `zipWith` waits until it has one value from the source and one value from
+ * each companion. It then emits a tuple and removes those values from the
+ * queues before waiting for the next full set.
+ *
+ * @typeParam T - Value type from the primary source
+ * @typeParam TOthers - Value types from the companion Observables
+ * @param others - Companion Observables to align by arrival order
+ * @returns An operator that emits tuples aligned by position instead of time
+ */
+export declare function zipWith<T, TOthers extends readonly unknown[]>(...others: CombinationSources<TOthers>): Operator<T | ObservableError, CombinationTuple<ExcludeError<T>, TOthers> | ObservableError>;
+/**
+ * Mirrors whichever Observable emits first: the source or one of the
+ * companions.
+ *
+ * If the primary source wins, future source values keep flowing and companion
+ * Observables are cancelled. If a companion wins, the source is ignored from
+ * that point on and the winning companion continues to drive the output.
+ *
+ * @typeParam T - Value type from the primary source
+ * @typeParam TOthers - Value types from the companion Observables
+ * @param others - Companion Observables racing against the source
+ * @returns An operator that mirrors the winning Observable
+ */
+export declare function raceWith<T, TOthers extends readonly unknown[]>(...others: CombinationSources<TOthers>): Operator<T | ObservableError, ExcludeError<T> | TOthers[number] | ObservableError>;
 //# sourceMappingURL=combination.d.ts.map

package/script/helpers/operations/combination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"combination.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/combination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAG3D,OAAO,EAAqB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAC3B,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,EACrE,UAAU,GAAE,MAAiB,GAC5B,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAkHpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAC5B,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,GACpE,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAGpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAC5B,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,cAAc,CAAC,CAAC,CAAC,GACpE,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAyIpD"}
+{"version":3,"file":"combination.d.ts","sourceRoot":"","sources":["../../../src/helpers/operations/combination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAI3D,OAAO,EAAqB,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAWpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAClC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EACtB,KAAK,EAAE,MAAM,KACV,cAAc,CAAC,CAAC,CAAC,CAAC;AAEvB;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,OAAO,SAAS,SAAS,OAAO,EAAE,IAAI;IACpE,CAAC;IACD,GAAG,OAAO;CACX,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,OAAO,SAAS,SAAS,OAAO,EAAE,IAAI;KAClE,CAAC,IAAI,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CACjD,CAAC;AA+NF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAC3B,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAC9B,UAAU,GAAE,MAAiB,GAC5B,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CA+KpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAC5B,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAGpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAC5B,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,CAmJpD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,SAAS,SAAS,OAAO,EAAE,EAClE,GAAG,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,GACrC,QAAQ,CACT,CAAC,GAAG,eAAe,EACnB,gBAAgB,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,eAAe,CAC7D,CAmGA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,SAAS,SAAS,OAAO,EAAE,EACrE,GAAG,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,GACrC,QAAQ,CACT,CAAC,GAAG,eAAe,EACnB,gBAAgB,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,eAAe,CAC7D,CA+HA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,SAAS,SAAS,OAAO,EAAE,EAC3D,GAAG,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,GACrC,QAAQ,CACT,CAAC,GAAG,eAAe,EACnB,gBAAgB,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,eAAe,CAC7D,CAsKA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,SAAS,SAAS,OAAO,EAAE,EAC5D,GAAG,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,GACrC,QAAQ,CAAC,CAAC,GAAG,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,CAqHpF"}