From 3ccdc66e708147cc30c4112490b8a451df5b20c3 Mon Sep 17 00:00:00 2001 From: Alexander Harding Date: Mon, 6 Apr 2026 23:46:15 -0600 Subject: [PATCH] Update docs for most libraries focusing on consistency and simplicity. --- all/README.md | 78 +++++-------------------- all/deno.json | 2 +- all/mod.ts | 99 +++++++++++++++++--------------- async-await/README.md | 14 ++--- async-await/deno.json | 2 +- async-await/mod.ts | 8 +-- at/README.md | 9 +-- at/deno.json | 2 +- at/mod.ts | 7 +-- behavior-subject/deno.json | 2 +- behavior-subject/mod.ts | 2 +- broadcast-subject/README.md | 2 +- broadcast-subject/deno.json | 2 +- broadcast-subject/mod.ts | 2 +- catch-error/README.md | 4 +- catch-error/deno.json | 2 +- catch-error/mod.ts | 4 +- debounce/README.md | 19 +++--- debounce/deno.json | 2 +- debounce/mod.ts | 18 +++--- defer/README.md | 2 +- defer/deno.json | 2 +- defer/mod.ts | 7 +-- distinct-until-changed/README.md | 65 +++++++++++++++------ distinct-until-changed/deno.json | 2 +- distinct-until-changed/mod.ts | 87 ++++++++++++++++++++++++++-- distinct/README.md | 6 +- distinct/deno.json | 2 +- distinct/mod.ts | 10 +--- drop/README.md | 9 ++- drop/deno.json | 2 +- drop/mod.ts | 8 ++- each-value-from/README.md | 8 +-- each-value-from/deno.json | 2 +- each-value-from/mod.ts | 11 ++-- empty/README.md | 3 +- empty/deno.json | 2 +- empty/mod.ts | 6 +- exhaust-map/README.md | 12 ++-- exhaust-map/deno.json | 2 +- exhaust-map/mod.ts | 12 ++-- expand/README.md | 9 +-- expand/deno.json | 2 +- expand/mod.ts | 3 +- filter/README.md | 4 +- filter/deno.json | 2 +- filter/mod.ts | 4 +- finalize/README.md | 11 ++-- finalize/deno.json | 2 +- finalize/mod.ts | 10 ++-- flat-map/README.md | 15 ++--- flat-map/deno.json | 2 +- flat-map/mod.ts | 14 ++--- flat/README.md | 45 +++------------ flat/deno.json | 2 +- flat/mod.ts | 42 +++++++------- for-await-of/README.md | 7 +-- for-await-of/deno.json | 2 +- for-await-of/mod.ts | 5 +- for-in/README.md | 7 +-- for-in/deno.json | 2 +- for-in/mod.ts | 5 +- for-of/README.md | 8 +-- for-of/deno.json | 2 +- for-of/mod.ts | 10 ++-- keep-alive/README.md | 1 + keep-alive/deno.json | 2 +- keep-alive/mod.ts | 8 ++- last-value-from/README.md | 16 +++--- last-value-from/deno.json | 2 +- last-value-from/mod.ts | 15 ++--- map/README.md | 4 +- map/deno.json | 2 +- map/mod.ts | 4 +- materialize/README.md | 5 +- materialize/deno.json | 2 +- materialize/mod.ts | 3 +- merge-map/README.md | 3 +- merge-map/deno.json | 2 +- merge-map/mod.ts | 3 +- merge/README.md | 16 +++--- merge/deno.json | 2 +- merge/mod.ts | 23 ++++---- of/README.md | 3 +- of/deno.json | 2 +- of/mod.ts | 5 +- pairwise/README.md | 5 +- pairwise/deno.json | 2 +- pairwise/mod.ts | 15 ++--- race/README.md | 15 +++-- race/deno.json | 2 +- race/mod.ts | 26 ++++----- reduce/README.md | 17 +++--- reduce/deno.json | 2 +- reduce/mod.ts | 17 +++--- repeat/README.md | 19 ++---- repeat/deno.json | 2 +- repeat/mod.ts | 16 ++---- scan/README.md | 14 +++-- scan/deno.json | 2 +- scan/mod.test.ts | 2 +- scan/mod.ts | 15 ++--- share/README.md | 25 ++++---- share/deno.json | 2 +- share/mod.ts | 26 ++++----- switch-map/README.md | 10 +--- switch-map/deno.json | 2 +- switch-map/mod.ts | 10 +--- take-until/README.md | 18 +++--- take-until/deno.json | 2 +- take-until/mod.ts | 17 +++--- take/README.md | 4 +- take/deno.json | 2 +- take/mod.ts | 4 +- tap/README.md | 4 +- tap/deno.json | 2 +- tap/mod.ts | 3 +- throttle/README.md | 31 +++++----- throttle/deno.json | 2 +- throttle/mod.ts | 30 +++++----- timeout/README.md | 4 +- timeout/deno.json | 2 +- timeout/mod.ts | 2 +- 123 files changed, 593 insertions(+), 658 deletions(-) diff --git a/all/README.md b/all/README.md index d9bf25f..d49b0b0 100644 --- a/all/README.md +++ b/all/README.md @@ -2,10 +2,9 @@ [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s an [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) of -the latest values from _all_ of input's -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable)s, in +values from _all_ of the given `observables` in [iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) -order. Each emitted array is a frozen snapshot. +order. ## Build @@ -22,19 +21,19 @@ Run `deno task test` or `deno task test:ci` to execute the unit tests via ## Examples -Array of sources +Array of observables ```ts import { all } from "@observable/all"; import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; -const source1 = forOf([1, 2, 3]); -const source2 = forOf([4, 5, 6]); -const source3 = forOf([7, 8, 9]); - +const observable1 = forOf([1, 2, 3]); +const observable2 = forOf([4, 5, 6]); +const observable3 = forOf([7, 8, 9]); const controller = new AbortController(); -all([source1, source2, source3]).subscribe({ + +all([observable1, observable2, observable3]).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), @@ -48,7 +47,7 @@ all([source1, source2, source3]).subscribe({ // "return" ``` -Empty source ends immediately +Array with an empty observable ```ts import { all } from "@observable/all"; @@ -56,28 +55,11 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; import { empty } from "@observable/empty"; -const source1 = forOf([1, 2, 3]); -const source2 = forOf([7, 8, 9]); - +const observable1 = forOf([1, 2, 3]); +const observable2 = forOf([7, 8, 9]); const controller = new AbortController(); -all([source1, empty, source2]).subscribe({ - signal: controller.signal, - next: (value) => console.log("next", value), - return: () => console.log("return"), - throw: (value) => console.log("throw", value), -}); - -// Console output: -// "return" -``` - -Empty array - -```ts -import { all } from "@observable/all"; -const controller = new AbortController(); -all([]).subscribe({ +all([observable1, empty, observable2]).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), @@ -88,46 +70,14 @@ all([]).subscribe({ // "return" ``` -Iterable of sources +Empty observable array ```ts import { all } from "@observable/all"; -import { Subject } from "@observable/core"; - -const source1 = new Subject(); -const source2 = source1; -const source3 = new Subject(); const controller = new AbortController(); -all(new Set([source1, source2, source3])).subscribe({ - signal: controller.signal, - next: (value) => console.log("next", value), - return: () => console.log("return"), - throw: (value) => console.log("throw", value), -}); -source2.next(1); -source1.next(2); -source3.next(3); // "next" [2, 3] -source1.next(4); // "next" [4, 3] -source2.next(5); // "next" [4, 5] -source1.return(); -source3.return(); // "return" -source2.return(); -``` - -Iterable with empty member -```ts -import { all } from "@observable/all"; -import { forOf } from "@observable/for-of"; -import { pipe } from "@observable/pipe"; -import { empty } from "@observable/empty"; - -const source1 = forOf([1, 2, 3]); -const source2 = forOf([7, 8, 9]); - -const controller = new AbortController(); -all(new Set([source1, empty, source2])).subscribe({ +all([]).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), diff --git a/all/deno.json b/all/deno.json index 86957bd..e3f1987 100644 --- a/all/deno.json +++ b/all/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/all", - "version": "0.14.0", + "version": "0.15.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/all/mod.ts b/all/mod.ts index ee175f6..1259b18 100644 --- a/all/mod.ts +++ b/all/mod.ts @@ -11,22 +11,22 @@ import { takeUntil } from "@observable/take-until"; import { finalize } from "@observable/finalize"; /** - * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s an [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) - * of the latest {@linkcode Values|values} from _all_ of {@linkcode input}'s [`Observable`](https://jsr.io/@observable/core/doc/~/Observable)s, in - * [index](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#array_indices) order. + * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s {@linkcode Values|values} from _all_ of the given + * {@linkcode observables} in [index](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#array_indices) + * order. * @example - * Array of sources + * Array of observables * ```ts * import { all } from "@observable/all"; * import { forOf } from "@observable/for-of"; * import { pipe } from "@observable/pipe"; * - * const source1 = forOf([1, 2, 3]); - * const source2 = forOf([4, 5, 6]); - * const source3 = forOf([7, 8, 9]); - * + * const observable1 = forOf([1, 2, 3]); + * const observable2 = forOf([4, 5, 6]); + * const observable3 = forOf([7, 8, 9]); * const controller = new AbortController(); - * all([source1, source2, source3]).subscribe({ + * + * all([observable1, observable2, observable3]).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), @@ -40,18 +40,18 @@ import { finalize } from "@observable/finalize"; * // "return" * ``` * @example - * Empty source ends immediately + * Array with an empty observable * ```ts * import { all } from "@observable/all"; * import { forOf } from "@observable/for-of"; * import { pipe } from "@observable/pipe"; * import { empty } from "@observable/empty"; * - * const source1 = forOf([1, 2, 3]); - * const source2 = forOf([7, 8, 9]); - * + * const observable1 = forOf([1, 2, 3]); + * const observable2 = forOf([7, 8, 9]); * const controller = new AbortController(); - * all([source1, empty, source2]).subscribe({ + * + * all([observable1, empty, observable2]).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), @@ -62,11 +62,12 @@ import { finalize } from "@observable/finalize"; * // "return" * ``` * @example - * Empty array + * Empty observable array * ```ts * import { all } from "@observable/all"; * * const controller = new AbortController(); + * * all([]).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -79,51 +80,51 @@ import { finalize } from "@observable/finalize"; * ``` */ export function all>( - input: Readonly<{ [Key in keyof Values]: Observable }>, + observables: Readonly<{ [Key in keyof Values]: Observable }>, ): Observable; /** * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s an [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) - * of the latest {@linkcode Value|values} from _all_ of {@linkcode input}'s [`Observable`](https://jsr.io/@observable/core/doc/~/Observable)s, in - * [iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) order. + * of {@linkcode Value|values} from _all_ of the given {@linkcode observables} in [iteration](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) + * order. * @example - * Iterable of sources + * Iterable of observables * ```ts * import { all } from "@observable/all"; * import { Subject } from "@observable/core"; * - * const source1 = new Subject(); - * const source2 = source1; - * const source3 = new Subject(); - * + * const subject1 = new Subject(); + * const subject2 = subject1; + * const subject3 = new Subject(); * const controller = new AbortController(); - * all(new Set([source1, source2, source3])).subscribe({ + * + * all(new Set([subject1, subject2, subject3])).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), * throw: (value) => console.log("throw", value), * }); - * source2.next(1); - * source1.next(2); - * source3.next(3); // "next" [2, 3] - * source1.next(4); // "next" [4, 3] - * source2.next(5); // "next" [4, 5] - * source1.return(); - * source3.return(); // "return" - * source2.return(); + * subject2.next(1); + * subject1.next(2); + * subject3.next(3); // "next" [2, 3] + * subject1.next(4); // "next" [4, 3] + * subject2.next(5); // "next" [4, 5] + * subject1.return(); + * subject3.return(); // "return" + * subject2.return(); * ``` * @example - * Iterable with empty member + * Iterable with an empty observable * ```ts * import { all } from "@observable/all"; * import { forOf } from "@observable/for-of"; * import { pipe } from "@observable/pipe"; * import { empty } from "@observable/empty"; * - * const source1 = forOf([1, 2, 3]); - * const source2 = forOf([7, 8, 9]); - * + * const observable1 = forOf([1, 2, 3]); + * const observable2 = forOf([7, 8, 9]); * const controller = new AbortController(); - * all(new Set([source1, empty, source2])).subscribe({ + * + * all(new Set([observable1, empty, observable2])).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), @@ -134,12 +135,16 @@ export function all>( * // "return" * ``` */ -export function all(input: Iterable>): Observable>; -export function all(input: Iterable>): Observable> { +export function all( + observables: Iterable>, +): Observable>; +export function all( + observables: Iterable>, +): Observable> { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); - if (!isIterable(input)) throw new TypeError("Parameter 1 is not of type 'Iterable'"); + if (!isIterable(observables)) throw new TypeError("Parameter 1 is not of type 'Iterable'"); - if (Array.isArray(input) && !input.length) return empty; + if (Array.isArray(observables) && !observables.length) return empty; // Use defer so we do not start iterating until subscription, we get a fresh iteration for each subscription, // and we get a fresh variable scope for each subscription. @@ -149,15 +154,15 @@ export function all(input: Iterable>): Observable> = Array.isArray(input) - ? input - : Array.from(input); + const observableArray: ReadonlyArray> = Array.isArray(observables) + ? observables + : Array.from(observables); /** * Tracking the expected number of first values that need to be received before the first snapshot is emitted. */ - const expectedFirstValueCount = inputArray.length; + const expectedFirstValueCount = observableArray.length; /** * Tracking a known list of buffered values, so we don't have to clone them while nexting to prevent reentrant behaviors. @@ -175,7 +180,7 @@ export function all(input: Iterable>): Observable(); return pipe( - forOf(inputArray), + forOf(observableArray), mergeMap((observable, index) => { /** * Tracking if the observable is empty to be evaluated by subsequent logic. diff --git a/async-await/README.md b/async-await/README.md index 079c14a..2344325 100644 --- a/async-await/README.md +++ b/async-await/README.md @@ -1,12 +1,8 @@ # [@observable/async-await](https://jsr.io/@observable/async-await) -Uses the -[async function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) -syntax to -[`await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await) the -provided `expression` and [`next`](https://jsr.io/@observable/core/doc/~/Observer.next) it's -resolved value through the returned -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable). +[`Await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await)s the +given `expression`, [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s its resolved +value, and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. ## Build @@ -106,7 +102,9 @@ Use the following prompt with AI assistants to help them understand this library You are helping me with code that uses @observable/async-await from the @observable library ecosystem. WHAT IT DOES: -`asyncAwait(promise)` converts a Promise/PromiseLike into an Observable that emits the resolved value, then calls `return()`. If the promise rejects, it calls `throw()` with the error. +`asyncAwait(expression)` applies `await` to the given expression, then `next`s the resolved value and +`return`s. The argument may be a `Promise`, a thenable, or any other value (same rules as `await` in +an async function — non-thenables are `next`ed as-is). Rejection surfaces as `throw()`. CRITICAL DIFFERENCES FROM RxJS: - Observer uses `return`/`throw` — NOT `complete`/`error` diff --git a/async-await/deno.json b/async-await/deno.json index 7a1c630..5aa19b3 100644 --- a/async-await/deno.json +++ b/async-await/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/async-await", - "version": "0.3.0", + "version": "0.4.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/async-await/mod.ts b/async-await/mod.ts index 4fb2f11..217d659 100644 --- a/async-await/mod.ts +++ b/async-await/mod.ts @@ -1,11 +1,9 @@ import { Observable } from "@observable/core"; /** - * Uses the [async function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) - * syntax to [`await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await) the provided - * {@linkcode expression} and [`next`](https://jsr.io/@observable/core/doc/~/Observer.next) it's resolved value through - * the returned [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). - * @param expression - A [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), a [thenable object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables), or any value to wait for. + * [`Await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await)s the given + * {@linkcode expression}, [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s its resolved value, and then + * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. * @example * Resolved promise * ```ts diff --git a/at/README.md b/at/README.md index aa7c719..b6304d2 100644 --- a/at/README.md +++ b/at/README.md @@ -1,11 +1,8 @@ # [@observable/at](https://jsr.io/@observable/at) -Filters [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to only the -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value at the given `index`. Negative -`indices` count back from the last [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed -value in the sequence. +[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s the first value at the given `index` +and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. Negative indices count +back from the last value in the sequence. ## Build diff --git a/at/deno.json b/at/deno.json index 129e9c3..3b468d6 100644 --- a/at/deno.json +++ b/at/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/at", - "version": "0.5.0", + "version": "0.6.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/at/mod.ts b/at/mod.ts index 7d2cf8a..0a456b8 100644 --- a/at/mod.ts +++ b/at/mod.ts @@ -7,10 +7,9 @@ import { empty } from "@observable/empty"; import { from } from "@observable/from"; /** - * Filters [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from the [source](https://jsr.io/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to only the [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed - * value at the given {@linkcode index}. Negative {@linkcode index|indices} count back from the last - * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value in the sequence. + * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s the first {@linkcode Value|value} at the given + * {@linkcode index} and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. Negative + * {@linkcode index|indices} count back from the last {@linkcode Value|value} in the sequence. * @example * Positive index integer * ```ts diff --git a/behavior-subject/deno.json b/behavior-subject/deno.json index d5ce51d..d31151c 100644 --- a/behavior-subject/deno.json +++ b/behavior-subject/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/behavior-subject", - "version": "0.10.0", + "version": "0.11.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/behavior-subject/mod.ts b/behavior-subject/mod.ts index 53aa595..df684a9 100644 --- a/behavior-subject/mod.ts +++ b/behavior-subject/mod.ts @@ -11,7 +11,7 @@ export type BehaviorSubject = Subject; */ export interface BehaviorSubjectConstructor { /** - * Creates and returns an object that acts as a [`Subject`](https://jsr.io/@observable/core/doc/~/Subject) that keeps track of it's current + * Creates and returns an object that acts as a [`Subject`](https://jsr.io/@observable/core/doc/~/Subject) that keeps track of its current * value and replays it to [`consumers`](https://jsr.io/@observable/core#consumer) upon * [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe). * @example diff --git a/broadcast-subject/README.md b/broadcast-subject/README.md index a7d388e..6cafda6 100644 --- a/broadcast-subject/README.md +++ b/broadcast-subject/README.md @@ -8,7 +8,7 @@ only to [consumers](https://jsr.io/@observable/core#consumer) of _other_ with the same name even if they are in different browsing contexts (e.g. browser tabs). Logically, [consumers](https://jsr.io/@observable/core#consumer) of the [`BroadcastSubject`](https://jsr.io/@observable/broadcast-subject/doc/~/BroadcastSubject) do not -receive it's _own_ [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values. +receive its _own_ [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values. ## Build diff --git a/broadcast-subject/deno.json b/broadcast-subject/deno.json index b2dde5a..ef79f64 100644 --- a/broadcast-subject/deno.json +++ b/broadcast-subject/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/broadcast-subject", - "version": "0.10.0", + "version": "0.11.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/broadcast-subject/mod.ts b/broadcast-subject/mod.ts index abb4a48..a15cb81 100644 --- a/broadcast-subject/mod.ts +++ b/broadcast-subject/mod.ts @@ -13,7 +13,7 @@ export interface BroadcastSubjectConstructor { * Creates and returns an object that acts as a variant of [`Subject`](https://jsr.io/@xan/subject/doc/~/Subject) whose [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed * values are [`structured cloned`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) and sent only to [consumers](https://jsr.io/@observable/core#consumer) * of _other_ {@linkcode BroadcastSubject} instances with the same {@linkcode name} even if they are in different browsing contexts (e.g. browser tabs). Logically, - * [consumers](https://jsr.io/@observable/core#consumer) of the {@linkcode BroadcastSubject} do not receive it's _own_ + * [consumers](https://jsr.io/@observable/core#consumer) of the {@linkcode BroadcastSubject} do not receive its _own_ * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values. * @example * ```ts diff --git a/catch-error/README.md b/catch-error/README.md index 540f963..9826e99 100644 --- a/catch-error/README.md +++ b/catch-error/README.md @@ -1,8 +1,6 @@ # [@observable/catch-error](https://jsr.io/@observable/catch-error) -Projects each [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw)n value from the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to a new +Projects each [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw)n value to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). ## Build diff --git a/catch-error/deno.json b/catch-error/deno.json index 7e5294d..1b00d37 100644 --- a/catch-error/deno.json +++ b/catch-error/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/catch-error", - "version": "0.12.0", + "version": "0.13.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/catch-error/mod.ts b/catch-error/mod.ts index 1b29839..685138f 100644 --- a/catch-error/mod.ts +++ b/catch-error/mod.ts @@ -3,9 +3,7 @@ import { from } from "@observable/from"; /** * {@linkcode project|Projects} each [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw)n - * value from the [source](https://jsr.io/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to a new - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). + * value to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). * @example * ```ts * import { catchError } from "@observable/catch-error"; diff --git a/debounce/README.md b/debounce/README.md index 7c8555e..f4e6357 100644 --- a/debounce/README.md +++ b/debounce/README.md @@ -1,9 +1,6 @@ # [@observable/debounce](https://jsr.io/@observable/debounce) -Debounces the [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) by the specified number of -milliseconds. +Debounces each value by the given number of `milliseconds`. ## Build @@ -28,18 +25,18 @@ import { Subject } from "@observable/core"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); -const source = new Subject(); +const subject = new Subject(); -pipe(source, debounce(100)).subscribe({ +pipe(subject, debounce(100)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), throw: (value) => console.log("throw", value), }); -source.next(1); -source.next(2); -source.next(3); +subject.next(1); +subject.next(2); +subject.next(3); // Console output (after 100ms): // "next" 3 @@ -53,6 +50,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3]), debounce(0)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -75,6 +73,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3]), debounce(-1)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -94,6 +93,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3]), debounce(NaN)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -113,6 +113,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3]), debounce(Infinity)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), diff --git a/debounce/deno.json b/debounce/deno.json index ff28672..7da2d34 100644 --- a/debounce/deno.json +++ b/debounce/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/debounce", - "version": "0.16.0", + "version": "0.17.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/debounce/mod.ts b/debounce/mod.ts index 0c6af95..d27e4c0 100644 --- a/debounce/mod.ts +++ b/debounce/mod.ts @@ -9,9 +9,7 @@ import { flat } from "@observable/flat"; import { of } from "@observable/of"; /** - * Debounces the [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from the - * [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) - * by the specified number of {@linkcode milliseconds}. + * Debounces each {@linkcode Value|value} by the given {@linkcode milliseconds}. * @example * Positive integer milliseconds * ```ts @@ -20,18 +18,18 @@ import { of } from "@observable/of"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); - * const source = new Subject(); + * const subject = new Subject(); * - * pipe(source, debounce(100)).subscribe({ + * pipe(subject, debounce(100)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), * throw: (value) => console.log("throw", value), * }); * - * source.next(1); - * source.next(2); - * source.next(3); + * subject.next(1); + * subject.next(2); + * subject.next(3); * * // Console output (after 100ms): * // "next" 3 @@ -44,6 +42,7 @@ import { of } from "@observable/of"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3]), debounce(0)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -65,6 +64,7 @@ import { of } from "@observable/of"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3]), debounce(-1)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -83,6 +83,7 @@ import { of } from "@observable/of"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3]), debounce(NaN)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -101,6 +102,7 @@ import { of } from "@observable/of"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3]), debounce(Infinity)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), diff --git a/defer/README.md b/defer/README.md index c5ea3b7..999ac0d 100644 --- a/defer/README.md +++ b/defer/README.md @@ -1,6 +1,6 @@ # [@observable/defer](https://jsr.io/@observable/defer) -Creates a new [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) for each +Registers the given `factory` function to be invoked on [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe). ## Build diff --git a/defer/deno.json b/defer/deno.json index c0365f2..f964e39 100644 --- a/defer/deno.json +++ b/defer/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/defer", - "version": "0.14.0", + "version": "0.15.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/defer/mod.ts b/defer/mod.ts index 0d1bc22..52aad9e 100644 --- a/defer/mod.ts +++ b/defer/mod.ts @@ -2,8 +2,7 @@ import { Observable } from "@observable/core"; import { from } from "@observable/from"; /** - * {@linkcode factory|Creates} a new [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) - * for each [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe). + * Registers the given {@linkcode factory} function to be invoked on [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe). * @example * ```ts * import { defer } from "@observable/defer"; @@ -41,9 +40,7 @@ import { from } from "@observable/from"; * // "return" * ``` */ -export function defer( - factory: () => Observable, -): Observable { +export function defer(factory: () => Observable): Observable { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); if (typeof factory !== "function") throw new TypeError("Parameter 1 is not of type 'Function'"); return new Observable((observer) => from(factory()).subscribe(observer)); diff --git a/distinct-until-changed/README.md b/distinct-until-changed/README.md index b962189..769e2c6 100644 --- a/distinct-until-changed/README.md +++ b/distinct-until-changed/README.md @@ -1,10 +1,7 @@ # [@observable/distinct-until-changed](https://jsr.io/@observable/distinct-until-changed) -Only [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s values from the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) that are distinct from the previous -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value according to a specified -comparator function or +Filters each value that is distinct from the previous value according to the given `comparator` +function or [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) if one is not provided. @@ -21,7 +18,9 @@ Automated by `.github\workflows\publish.yml`. Run `deno task test` or `deno task test:ci` to execute the unit tests via [Deno](https://deno.land/). -## Example +## Examples + +Default comparator ```ts import { distinctUntilChanged } from "@observable/distinct-until-changed"; @@ -29,6 +28,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 1, 1, 2, 2, 3]), distinctUntilChanged()).subscribe({ signal: controller.signal, next: (value) => console.log(value), @@ -43,22 +43,47 @@ pipe(forOf([1, 1, 1, 2, 2, 3]), distinctUntilChanged()).subscribe({ // return ``` +Custom comparator + +```ts +import { distinctUntilChanged } from "@observable/distinct-until-changed"; +import { forOf } from "@observable/for-of"; +import { pipe } from "@observable/pipe"; + +const controller = new AbortController(); + +pipe(forOf([{ id: 1 }, { id: 1 }, { id: 2 }]), distinctUntilChanged((a, b) => a.id === b.id)) + .subscribe({ + signal: controller.signal, + next: (value) => console.log("next", value), + return: () => console.log("return"), + throw: (value) => console.log("throw", value), + }); +``` + +// Console output: // "next" { id: 1 } // "next" { id: 2 } // "return" + +``` # AI Prompt Use the following prompt with AI assistants to help them understand this library: +``` -```` -You are helping me with code that uses @observable/distinct-until-changed from the @observable library ecosystem. +You are helping me with code that uses @observable/distinct-until-changed from the @observable +library ecosystem. -WHAT IT DOES: -`distinctUntilChanged(comparator?)` only emits when the current value is different from the previous value. Uses `Object.is` by default, or a custom comparator if provided. +WHAT IT DOES: `distinctUntilChanged(comparator?)` only emits when the current value is different +from the previous value. Uses `Object.is` by default, or a custom comparator if provided (return +`true` when values should be treated as equal / skipped). CRITICAL: This library is NOT RxJS. Key differences: + - Observer uses `return`/`throw` — NOT `complete`/`error` - Unsubscription via `AbortController.abort()` — NOT `subscription.unsubscribe()` - `distinctUntilChanged` is a standalone function used with `pipe()` — NOT a method on Observable USAGE PATTERN: + ```ts import { distinctUntilChanged } from "@observable/distinct-until-changed"; import { forOf } from "@observable/for-of"; @@ -67,34 +92,36 @@ import { pipe } from "@observable/pipe"; const controller = new AbortController(); pipe( - [1, 1, 1, 2, 2, 3, 1], // Note: 1 repeats at end - forOf([1, 1, 1, 2, 2, 3]), - distinctUntilChanged() + forOf([1, 1, 1, 2, 2, 3, 1]), + distinctUntilChanged(), ).subscribe({ signal: controller.signal, - next: (value) => console.log(value), // 1, 2, 3, 1 + next: (value) => console.log(value), // 1, 2, 3, 1 — final 1 repeats after 3, so it emits return: () => console.log("done"), throw: (error) => console.error(error), }); ``` WITH CUSTOM COMPARATOR: + ```ts pipe( - [{ id: 1 }, { id: 1 }, { id: 2 }], - forOf([1, 1, 1, 2, 2, 3]), - distinctUntilChanged((a, b) => a.id === b.id) -).subscribe({ ... }); // { id: 1 }, { id: 2 } + forOf([{ id: 1 }, { id: 1 }, { id: 2 }]), + distinctUntilChanged((a, b) => a.id === b.id), +).subscribe({ ... }); // { id: 1 }, { id: 2 } ``` DIFFERENCE FROM `distinct()`: + - `distinct()` — filters ALL duplicates ever seen - `distinctUntilChanged()` — only filters CONSECUTIVE duplicates SEE ALSO: + - `distinct()` — filters all duplicates across the stream -```` +``` # Glossary And Semantics [@observable/core](https://jsr.io/@observable/core#glossary-and-semantics) +``` diff --git a/distinct-until-changed/deno.json b/distinct-until-changed/deno.json index 3d10cc8..89b7071 100644 --- a/distinct-until-changed/deno.json +++ b/distinct-until-changed/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/distinct-until-changed", - "version": "0.15.0", + "version": "0.16.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/distinct-until-changed/mod.ts b/distinct-until-changed/mod.ts index 68348e1..7dd33a7 100644 --- a/distinct-until-changed/mod.ts +++ b/distinct-until-changed/mod.ts @@ -14,11 +14,8 @@ import { of } from "@observable/of"; const noValue = Symbol("Flag indicating that no value has been emitted yet"); /** - * Only [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s values from the - * [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) - * that are distinct from the previous [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value according - * to a specified {@linkcode comparator} function or [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) - * if one is not provided. + * Filters each {@linkcode Value|value} that is [distinct](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) + * from the previous {@linkcode Value|value}. * @example * ```ts * import { distinctUntilChanged } from "@observable/distinct-until-changed"; @@ -26,6 +23,60 @@ const noValue = Symbol("Flag indicating that no value has been emitted yet"); * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * + * pipe(forOf([1, 1, 1, 2, 2, 3]), distinctUntilChanged()).subscribe({ + * signal: controller.signal, + * next: (value) => console.log(value), + * return: () => console.log("return"), + * throw: (value) => console.log(value), + * }); + * + * // Console output: + * // 1 + * // 2 + * // 3 + * // return + * ``` + */ +export function distinctUntilChanged(): (source: Observable) => Observable; +/** + * Filters each {@linkcode Value|value} that is distinct from the previous {@linkcode Value|value} according to the given {@linkcode comparator} function. + * @example + * ```ts + * import { distinctUntilChanged } from "@observable/distinct-until-changed"; + * import { forOf } from "@observable/for-of"; + * import { pipe } from "@observable/pipe"; + * + * const controller = new AbortController(); + * + * pipe(forOf([{ id: 1 }, { id: 1 }, { id: 2 }]), distinctUntilChanged((a, b) => a.id === b.id)).subscribe({ + * signal: controller.signal, + * next: (value) => console.log("next", value), + * return: () => console.log("return"), + * throw: (value) => console.log("throw", value), + * }); + * ``` + * // Console output: + * // "next" { id: 1 } + * // "next" { id: 2 } + * // "return" + * ``` + */ +export function distinctUntilChanged( + comparator: (previous: Value, current: Value) => boolean, +): (source: Observable) => Observable; +/** + * Filters each {@linkcode Value|value} that is distinct from the previous {@linkcode Value|value} according to the given {@linkcode comparator} + * function or [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) if one is not provided. + * @example + * Default comparator + * ```ts + * import { distinctUntilChanged } from "@observable/distinct-until-changed"; + * import { forOf } from "@observable/for-of"; + * import { pipe } from "@observable/pipe"; + * + * const controller = new AbortController(); + * * pipe(forOf([1, 1, 1, 2, 2, 3]), distinctUntilChanged()).subscribe({ * signal: controller.signal, * next: (value) => console.log(value), @@ -39,9 +90,33 @@ const noValue = Symbol("Flag indicating that no value has been emitted yet"); * // 3 * // return * ``` + * @example + * Custom comparator + * ```ts + * import { distinctUntilChanged } from "@observable/distinct-until-changed"; + * import { forOf } from "@observable/for-of"; + * import { pipe } from "@observable/pipe"; + * + * const controller = new AbortController(); + * + * pipe(forOf([{ id: 1 }, { id: 1 }, { id: 2 }]), distinctUntilChanged((a, b) => a.id === b.id)).subscribe({ + * signal: controller.signal, + * next: (value) => console.log("next", value), + * return: () => console.log("return"), + * throw: (value) => console.log("throw", value), + * }); + * ``` + * // Console output: + * // "next" { id: 1 } + * // "next" { id: 2 } + * // "return" + * ``` */ export function distinctUntilChanged( - // Default to Object.is because it's behavior is more predictable than + comparator?: (previous: Value, current: Value) => boolean, +): (source: Observable) => Observable; +export function distinctUntilChanged( + // Default to Object.is because its behavior is more predictable than // strict equality checks. comparator: (previous: Value, current: Value) => boolean = Object.is, ): (source: Observable) => Observable { diff --git a/distinct/README.md b/distinct/README.md index 798bfc5..c8ebdc4 100644 --- a/distinct/README.md +++ b/distinct/README.md @@ -1,10 +1,8 @@ # [@observable/distinct](https://jsr.io/@observable/distinct) -Only [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s values from the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) that are +Filters values that are [distinct](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) -from all previously [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values. +from all previous values. ## Build diff --git a/distinct/deno.json b/distinct/deno.json index c3c106d..8ab61c4 100644 --- a/distinct/deno.json +++ b/distinct/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/distinct", - "version": "0.12.0", + "version": "0.13.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/distinct/mod.ts b/distinct/mod.ts index 3d1d257..8b04144 100644 --- a/distinct/mod.ts +++ b/distinct/mod.ts @@ -6,10 +6,8 @@ import { tap } from "@observable/tap"; import { filter } from "@observable/filter"; /** - * Only [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s values from the - * [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) - * that are [distinct](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) - * from all previously [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values. + * Filters {@linkcode Value|values} that are [distinct](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) + * from all previous {@linkcode Value|values}. * @example * ```ts * import { distinct } from "@observable/distinct"; @@ -31,9 +29,7 @@ import { filter } from "@observable/filter"; * // "return" * ``` */ -export function distinct(): ( - source: Observable, -) => Observable { +export function distinct(): (source: Observable) => Observable { return function distinctFn(source) { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); if (!isObservable(source)) throw new TypeError("Parameter 1 is not of type 'Observable'"); diff --git a/drop/README.md b/drop/README.md index 8e8449d..cb5a80d 100644 --- a/drop/README.md +++ b/drop/README.md @@ -1,8 +1,6 @@ # [@observable/drop](https://jsr.io/@observable/drop) -Drops the first count of [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from -the [source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable). +Drops the first `count` of values. ## Build @@ -27,6 +25,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3, 4, 5]), drop(2)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -49,6 +48,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3, 4, 5]), drop(2.3)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -71,6 +71,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3, 4, 5]), drop(0)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -95,6 +96,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3, 4, 5]), drop(-1)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -114,6 +116,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3, 4, 5]), drop(NaN)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), diff --git a/drop/deno.json b/drop/deno.json index 71f0bc8..ace1ee0 100644 --- a/drop/deno.json +++ b/drop/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/drop", - "version": "0.11.0", + "version": "0.12.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/drop/mod.ts b/drop/mod.ts index bde3e14..7cae913 100644 --- a/drop/mod.ts +++ b/drop/mod.ts @@ -5,8 +5,7 @@ import { pipe } from "@observable/pipe"; import { filter } from "@observable/filter"; /** - * Drops the first {@linkcode count} of [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed - * values from the [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). + * Drops the first {@linkcode count} of {@linkcode Value|values}. * @example * Positive integer count * ```ts @@ -15,6 +14,7 @@ import { filter } from "@observable/filter"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3, 4, 5]), drop(2)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -36,6 +36,7 @@ import { filter } from "@observable/filter"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3, 4, 5]), drop(2.3)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -57,6 +58,7 @@ import { filter } from "@observable/filter"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3, 4, 5]), drop(0)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -80,6 +82,7 @@ import { filter } from "@observable/filter"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3, 4, 5]), drop(-1)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -98,6 +101,7 @@ import { filter } from "@observable/filter"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3, 4, 5]), drop(NaN)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), diff --git a/each-value-from/README.md b/each-value-from/README.md index a688106..4aa7ab4 100644 --- a/each-value-from/README.md +++ b/each-value-from/README.md @@ -1,9 +1,7 @@ # [@observable/each-value-from](https://jsr.io/@observable/each-value-from) -Projects the provided [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to an -[`AsyncGenerator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator) -that [`yield`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/yield)s -each [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value in order. +[`Yield`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/yield)s each +value in order. ## Examples @@ -62,7 +60,7 @@ for await (const value of eachValueFrom(interval(100))) { // 5 ``` -Empty source +Empty observable ```ts import { eachValueFrom } from "@observable/each-value-from"; diff --git a/each-value-from/deno.json b/each-value-from/deno.json index 01720f3..47ef766 100644 --- a/each-value-from/deno.json +++ b/each-value-from/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/each-value-from", - "version": "0.8.0", + "version": "0.9.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/each-value-from/mod.ts b/each-value-from/mod.ts index 7b68eb3..243274c 100644 --- a/each-value-from/mod.ts +++ b/each-value-from/mod.ts @@ -20,10 +20,7 @@ const doneValue = Symbol("Flag indicating that we are done yielding values."); type Deferred = Omit, "promise">; /** - * Projects the provided {@linkcode observable|Observable} to an - * [`AsyncGenerator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator) - * that [`yield`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/yield)s each - * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed {@linkcode Value|value} in order. + * [`Yield`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/yield)s each {@linkcode Value|value} in order. * @example * Basic usage * ```ts @@ -77,7 +74,7 @@ type Deferred = Omit, "promise">; * // 5 * ``` * @example - * Empty source + * Empty observable * ```ts * import { eachValueFrom } from "@observable/each-value-from"; * import { empty } from "@observable/empty"; @@ -126,9 +123,9 @@ export async function* eachValueFrom( while (true) { // If we already have some values in our buffer, we'll yield the next one. if (buffer.length > 0) yield buffer.shift()!; - // If the source has returned, we're done. + // If the observable has returned, we're done. else if (returned) return; - // If the source has thrown an error, we'll rethrow it. + // If the observable has thrown an error, we'll rethrow it. else if (thrownValue !== notThrown) throw thrownValue; // Otherwise, we'll wait for the next value. else { diff --git a/empty/README.md b/empty/README.md index eb66c09..b311d36 100644 --- a/empty/README.md +++ b/empty/README.md @@ -1,7 +1,6 @@ # [@observable/empty](https://jsr.io/@observable/empty) -Immediately [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s each -[`Observer`](https://jsr.io/@observable/core/doc/~/Observer) on +Immediately [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s on [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe). ## Build diff --git a/empty/deno.json b/empty/deno.json index 789ff4b..0b39a55 100644 --- a/empty/deno.json +++ b/empty/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/empty", - "version": "0.9.0", + "version": "0.10.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/empty/mod.ts b/empty/mod.ts index c7082f2..f1d3a44 100644 --- a/empty/mod.ts +++ b/empty/mod.ts @@ -1,10 +1,8 @@ import { Observable } from "@observable/core"; /** - * Immediately [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s the - * [`Observer`](https://jsr.io/@observable/core/doc/~/Observer) on - * [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe) without - * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ing a value. + * Immediately [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s on + * [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe). * @example * ```ts * import { empty } from "@observable/empty"; diff --git a/exhaust-map/README.md b/exhaust-map/README.md index 5c985c9..f025efd 100644 --- a/exhaust-map/README.md +++ b/exhaust-map/README.md @@ -1,10 +1,8 @@ # [@observable/exhaust-map](https://jsr.io/@observable/exhaust-map) -Projects each [source](https://jsr.io/@observable/core#source) value to an -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) which is merged in the output -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) only if the previous projected -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) has -[`return`](https://jsr.io/@observable/core/doc/~/Observer.return)ed. +Projects each value to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) ignoring +any new values until the projected [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) +[`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. ## Build @@ -29,10 +27,10 @@ import { timeout } from "@observable/timeout"; import { map } from "@observable/map"; const controller = new AbortController(); -const source = forOf([1, 2, 3]); +const observable = forOf([1, 2, 3]); pipe( - source, + observable, exhaustMap((value) => pipe(timeout(100), map(() => value))), ).subscribe({ signal: controller.signal, diff --git a/exhaust-map/deno.json b/exhaust-map/deno.json index 3c2b227..886b1d7 100644 --- a/exhaust-map/deno.json +++ b/exhaust-map/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/exhaust-map", - "version": "0.10.0", + "version": "0.11.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/exhaust-map/mod.ts b/exhaust-map/mod.ts index 5798c7b..439c5ba 100644 --- a/exhaust-map/mod.ts +++ b/exhaust-map/mod.ts @@ -6,11 +6,9 @@ import { switchMap } from "@observable/switch-map"; import { finalize } from "@observable/finalize"; /** - * {@linkcode project|Projects} each [source](https://jsr.io/@observable/core#source) value to an - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) which is merged in the output - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) only if the previous - * {@linkcode project|projected} [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) has - * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)ed. + * {@linkcode project|Projects} each {@linkcode In|value} to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) ignoring any new + * {@linkcode In|values} until the {@linkcode project|projected} [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) + * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. * @example * ```ts * import { exhaustMap } from "@observable/exhaust-map"; @@ -20,10 +18,10 @@ import { finalize } from "@observable/finalize"; * import { map } from "@observable/map"; * * const controller = new AbortController(); - * const source = forOf([1, 2, 3]); + * const observable = forOf([1, 2, 3]); * * pipe( - * source, + * observable, * exhaustMap((value) => pipe(timeout(100), map(() => value))), * ).subscribe({ * signal: controller.signal, diff --git a/expand/README.md b/expand/README.md index 8ca4bf5..b6ce3fd 100644 --- a/expand/README.md +++ b/expand/README.md @@ -1,7 +1,6 @@ # [@observable/expand](https://jsr.io/@observable/expand) -Recursively projects each [source](https://jsr.io/@observable/core#source) value to an -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) which is merged in the output +Recursively projects each value to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). ## Build @@ -102,10 +101,12 @@ WHAT IT DOES: `expand(project)` recursively projects each value to an Observable: 1. Emits the source value 2. Projects it to an inner Observable -3. Emits values from the inner Observable -4. Recursively projects those values too +3. Emits values from the inner Observable (merged into the same output stream) +4. Recursively expands those emissions the same way 5. Continues until all inner Observables return +Inner Observable emissions are merged into one flattened output (not nested streams). + CRITICAL: This library is NOT RxJS. Key differences: - Observer uses `return`/`throw` — NOT `complete`/`error` - Unsubscription via `AbortController.abort()` — NOT `subscription.unsubscribe()` diff --git a/expand/deno.json b/expand/deno.json index 97fc691..b81a5f6 100644 --- a/expand/deno.json +++ b/expand/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/expand", - "version": "0.9.0", + "version": "0.10.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/expand/mod.ts b/expand/mod.ts index 4abb9ae..9e15761 100644 --- a/expand/mod.ts +++ b/expand/mod.ts @@ -7,8 +7,7 @@ import { defer } from "@observable/defer"; import { of } from "@observable/of"; /** - * Recursively {@linkcode project|projects} each [source](https://jsr.io/@observable/core#source) value - * to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) which is merged in the output + * Recursively {@linkcode project|projects} each {@linkcode Value|value} to an * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). * @example * Double until 16 diff --git a/filter/README.md b/filter/README.md index e7bd4ba..c9fe901 100644 --- a/filter/README.md +++ b/filter/README.md @@ -1,7 +1,6 @@ # [@observable/filter](https://jsr.io/@observable/filter) -Filters [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from the -[source](https://jsr.io/@observable/core#source) that satisfy a specified predicate. +Filters values that satisfy the given `predicate` function. ## Build @@ -24,6 +23,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3, 4, 5]), filter((value) => value % 2 === 0)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), diff --git a/filter/deno.json b/filter/deno.json index d176805..bd8961b 100644 --- a/filter/deno.json +++ b/filter/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/filter", - "version": "0.10.0", + "version": "0.11.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/filter/mod.ts b/filter/mod.ts index d6427d3..92f0e32 100644 --- a/filter/mod.ts +++ b/filter/mod.ts @@ -2,8 +2,7 @@ import { isObservable, Observable } from "@observable/core"; import { from } from "@observable/from"; /** - * Filters [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from the - * [source](https://jsr.io/@observable/core#source) that satisfy a specified {@linkcode predicate}. + * Filters {@linkcode Value|values} that satisfy the given {@linkcode predicate} function. * @example * ```ts * import { filter } from "@observable/filter"; @@ -11,6 +10,7 @@ import { from } from "@observable/from"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3, 4, 5]), filter((value) => value % 2 === 0)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), diff --git a/finalize/README.md b/finalize/README.md index aeb1d91..c1066ff 100644 --- a/finalize/README.md +++ b/finalize/README.md @@ -1,7 +1,7 @@ # [@observable/finalize](https://jsr.io/@observable/finalize) -The [consumer](https://jsr.io/@observable/core#consumer) is telling the -[producer](https://jsr.io/@observable/core#producer) it's no longer interested in receiving values. +Registers a `callback` to be invoked on +[`unsubscribe`](https://jsr.io/@observable/core/doc/~/Observer.signal). ## Build @@ -26,6 +26,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3]), finalize(() => console.log("finalized"))).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -51,8 +52,9 @@ import { forOf } from "@observable/for-of"; import { flat } from "@observable/flat"; const controller = new AbortController(); -const source = flat([forOf([1, 2, 3]), throwError(new Error("error"))]); -pipe(source, finalize(() => console.log("finalized"))).subscribe({ +const observable = flat([forOf([1, 2, 3]), throwError(new Error("error"))]); + +pipe(observable, finalize(() => console.log("finalized"))).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), @@ -75,6 +77,7 @@ import { pipe } from "@observable/pipe"; import { never } from "@observable/never"; const controller = new AbortController(); + pipe(never, finalize(() => console.log("finalized"))).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), diff --git a/finalize/deno.json b/finalize/deno.json index d133842..aea5ca6 100644 --- a/finalize/deno.json +++ b/finalize/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/finalize", - "version": "0.12.0", + "version": "0.13.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/finalize/mod.ts b/finalize/mod.ts index 1d48802..44dbe7d 100644 --- a/finalize/mod.ts +++ b/finalize/mod.ts @@ -2,8 +2,7 @@ import { isObservable, Observable } from "@observable/core"; import { from } from "@observable/from"; /** - * The [consumer](https://jsr.io/@observable/core#consumer) is telling the [producer](https://jsr.io/@observable/core#producer) - * it's no longer interested in receiving {@linkcode Value|values}. + * Registers a {@linkcode callback} to be invoked on [`unsubscribe`](https://jsr.io/@observable/core/doc/~/Observer.signal). * @example * Return * ```ts @@ -12,6 +11,7 @@ import { from } from "@observable/from"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3]), finalize(() => console.log("finalized"))).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -36,8 +36,9 @@ import { from } from "@observable/from"; * import { flat } from "@observable/flat"; * * const controller = new AbortController(); - * const source = flat([forOf([1, 2, 3]), throwError(new Error("error"))]); - * pipe(source, finalize(() => console.log("finalized"))).subscribe({ + * const observable = flat([forOf([1, 2, 3]), throwError(new Error("error"))]); + * + * pipe(observable, finalize(() => console.log("finalized"))).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), @@ -59,6 +60,7 @@ import { from } from "@observable/from"; * import { never } from "@observable/never"; * * const controller = new AbortController(); + * * pipe(never, finalize(() => console.log("finalized"))).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), diff --git a/flat-map/README.md b/flat-map/README.md index 3004335..70d5195 100644 --- a/flat-map/README.md +++ b/flat-map/README.md @@ -1,12 +1,9 @@ # [@observable/flat-map](https://jsr.io/@observable/flat-map) -Projects each [source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable)'s -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value to an -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) which is merged in the output -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable), in a serialized fashion waiting -for each one to [`return`](https://jsr.io/@observable/core/doc/~/Observer.return) before merging the -next. +Sequentially projects each value to an +[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) waiting for each projected +[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to +[`return`](https://jsr.io/@observable/core/doc/~/Observer.return) before moving on to the next. ## Build @@ -28,7 +25,7 @@ import { flatMap } from "@observable/flat-map"; import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; -const source = forOf(["a", "b", "c"]); +const observable = forOf(["a", "b", "c"]); const controller = new AbortController(); const observableLookup = { a: forOf([1, 2, 3]), @@ -36,7 +33,7 @@ const observableLookup = { c: forOf([7, 8, 9]), } as const; -pipe(source, flatMap((value) => observableLookup[value])).subscribe({ +pipe(observable, flatMap((value) => observableLookup[value])).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), diff --git a/flat-map/deno.json b/flat-map/deno.json index b82052a..60a6d5f 100644 --- a/flat-map/deno.json +++ b/flat-map/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/flat-map", - "version": "0.10.0", + "version": "0.11.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/flat-map/mod.ts b/flat-map/mod.ts index d7408c7..ada45fb 100644 --- a/flat-map/mod.ts +++ b/flat-map/mod.ts @@ -2,20 +2,16 @@ import { isObservable, Observable } from "@observable/core"; import { from } from "@observable/from"; /** - * {@linkcode project|Projects} each [source](https://jsr.io/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable)'s - * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value to an - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) which is merged in the output - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable), in a serialized fashion - * waiting for each one to [`return`](https://jsr.io/@observable/core/doc/~/Observer.return) before - * merging the next. + * Sequentially {@linkcode project|projects} each {@linkcode In|value} to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) + * waiting for each {@linkcode project|projected} [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) + * to [`return`](https://jsr.io/@observable/core/doc/~/Observer.return) before moving on to the next. * @example * ```ts * import { flatMap } from "@observable/flat-map"; * import { forOf } from "@observable/for-of"; * import { pipe } from "@observable/pipe"; * - * const source = forOf(["a", "b", "c"]); + * const observable = forOf(["a", "b", "c"]); * const controller = new AbortController(); * const observableLookup = { * a: forOf([1, 2, 3]), @@ -23,7 +19,7 @@ import { from } from "@observable/from"; * c: forOf([7, 8, 9]), * } as const; * - * pipe(source, flatMap((value) => observableLookup[value])).subscribe({ + * pipe(observable, flatMap((value) => observableLookup[value])).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), diff --git a/flat/README.md b/flat/README.md index 340473b..5b4ddf8 100644 --- a/flat/README.md +++ b/flat/README.md @@ -1,9 +1,7 @@ # [@observable/flat](https://jsr.io/@observable/flat) -Sequentially [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s all values from the -first given [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) until it -[`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s and then moves on to the next and -so on. +Sequentially mirrors each given `observables` waiting for each one to +[`return`](https://jsr.io/@observable/core/doc/~/Observer.return) before moving on to the next. ## Build @@ -20,20 +18,20 @@ Run `deno task test` or `deno task test:ci` to execute the unit tests via ## Examples -Array of sources +Array of observables ```ts import { flat } from "@observable/flat"; import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; -const source1 = forOf([1, 2, 3]); -const source2 = forOf([4, 5, 6]); -const source3 = forOf([7, 8, 9]); +const observable1 = forOf([1, 2, 3]); +const observable2 = forOf([4, 5, 6]); +const observable3 = forOf([7, 8, 9]); const controller = new AbortController(); -flat([source1, source2, source3]).subscribe({ +flat([observable1, observable2, observable3]).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), @@ -53,35 +51,6 @@ flat([source1, source2, source3]).subscribe({ // "return" ``` -Iterable of sources - -```ts -import { flat } from "@observable/flat"; -import { forOf } from "@observable/for-of"; -import { pipe } from "@observable/pipe"; - -const controller = new AbortController(); -const source1 = forOf([1, 2, 3]); -const source2 = source1; -const source3 = forOf([4, 5, 6]); - -flat(new Set([source1, source2, source3])).subscribe({ - signal: controller.signal, - next: (value) => console.log("next", value), - return: () => console.log("return"), - throw: (value) => console.log("throw", value), -}); - -// Console output: -// "next" 1 -// "next" 2 -// "next" 3 -// "next" 4 -// "next" 5 -// "next" 6 -// "return" -``` - Empty array ```ts diff --git a/flat/deno.json b/flat/deno.json index a15fb43..4066a90 100644 --- a/flat/deno.json +++ b/flat/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/flat", - "version": "0.12.0", + "version": "0.13.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/flat/mod.ts b/flat/mod.ts index 3148b97..cbd1992 100644 --- a/flat/mod.ts +++ b/flat/mod.ts @@ -5,23 +5,22 @@ import { flatMap } from "@observable/flat-map"; import { empty } from "@observable/empty"; /** - * Sequentially [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s all values from the first given - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) until it - * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s and then moves on to the next and so on. + * Sequentially mirrors each given {@linkcode observables} waiting for each one to [`return`](https://jsr.io/@observable/core/doc/~/Observer.return) + * before moving on to the next. * @example - * Array of sources + * Array of observables * ```ts * import { flat } from "@observable/flat"; * import { forOf } from "@observable/for-of"; * import { pipe } from "@observable/pipe"; * - * const source1 = forOf([1, 2, 3]); - * const source2 = forOf([4, 5, 6]); - * const source3 = forOf([7, 8, 9]); + * const observable1 = forOf([1, 2, 3]); + * const observable2 = forOf([4, 5, 6]); + * const observable3 = forOf([7, 8, 9]); * * const controller = new AbortController(); * - * flat([source1, source2, source3]).subscribe({ + * flat([observable1, observable2, observable3]).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), @@ -58,25 +57,24 @@ import { empty } from "@observable/empty"; * ``` */ export function flat>( - sources: Readonly<{ [Key in keyof Values]: Observable }>, + observables: Readonly<{ [Key in keyof Values]: Observable }>, ): Observable; /** - * Sequentially [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s all values from the first given - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) until it - * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s and then moves on to the next and so on. + * Sequentially mirrors each given {@linkcode observables} waiting for each one to [`return`](https://jsr.io/@observable/core/doc/~/Observer.return) + * before moving on to the next. * @example - * Iterable of sources + * Iterable of observables * ```ts * import { flat } from "@observable/flat"; * import { forOf } from "@observable/for-of"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); - * const source1 = forOf([1, 2, 3]); - * const source2 = source1; - * const source3 = forOf([4, 5, 6]); + * const observable1 = forOf([1, 2, 3]); + * const observable2 = observable1; + * const observable3 = forOf([4, 5, 6]); * - * flat(new Set([source1, source2, source3])).subscribe({ + * flat(new Set([observable1, observable2, observable3])).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), @@ -93,12 +91,12 @@ export function flat>( * // "return" * ``` */ -export function flat(sources: Iterable>): Observable; -export function flat(sources: Iterable>): Observable { +export function flat(observables: Iterable>): Observable; +export function flat(observables: Iterable>): Observable { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); - if (!isIterable(sources)) throw new TypeError("Parameter 1 is not of type 'Iterable'"); - if (Array.isArray(sources) && !sources.length) return empty; - return pipe(forOf(sources), flatMap((observable) => observable)); + if (!isIterable(observables)) throw new TypeError("Parameter 1 is not of type 'Iterable'"); + if (Array.isArray(observables) && !observables.length) return empty; + return pipe(forOf(observables), flatMap((observable) => observable)); } /** diff --git a/for-await-of/README.md b/for-await-of/README.md index 30d810d..00cf5c7 100644 --- a/for-await-of/README.md +++ b/for-await-of/README.md @@ -1,9 +1,8 @@ # [@observable/for-await-of](https://jsr.io/@observable/for-await-of) -Projects an -[`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) -to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) that -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each value in order, then +[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each +[`await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await)ed value +of the given `values` in order and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. ## Build diff --git a/for-await-of/deno.json b/for-await-of/deno.json index 0eccb1a..1c024d8 100644 --- a/for-await-of/deno.json +++ b/for-await-of/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/for-await-of", - "version": "0.4.0", + "version": "0.5.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/for-await-of/mod.ts b/for-await-of/mod.ts index 9b98d90..31e69ea 100644 --- a/for-await-of/mod.ts +++ b/for-await-of/mod.ts @@ -1,9 +1,8 @@ import { Observable } from "@observable/core"; /** - * Projects an [`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) - * to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) that [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s - * each {@linkcode Value|value} in order, then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. + * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each [`await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await)ed + * {@linkcode Value|value} of the given {@linkcode values} in order and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. * @example * ```ts * import { forAwaitOf } from "@observable/for-await-of"; diff --git a/for-in/README.md b/for-in/README.md index 81ae750..7cd7272 100644 --- a/for-in/README.md +++ b/for-in/README.md @@ -1,10 +1,7 @@ # [@observable/for-in](https://jsr.io/@observable/for-in) -Projects an -[`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)'s -keys to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) that -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each key in order upon -[`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe). +[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each key of the given `object` in +order and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. ## Build diff --git a/for-in/deno.json b/for-in/deno.json index 2814f83..b7e0bfa 100644 --- a/for-in/deno.json +++ b/for-in/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/for-in", - "version": "0.2.0", + "version": "0.3.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/for-in/mod.ts b/for-in/mod.ts index d6fe412..bad1e87 100644 --- a/for-in/mod.ts +++ b/for-in/mod.ts @@ -1,9 +1,8 @@ import { Observable } from "@observable/core"; /** - * Projects an [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)'s keys - * to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) that [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s - * each key in order upon [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe). + * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each key of the given {@linkcode object} in order and then + * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. * @example * ```ts * import { forIn } from "@observable/for-in"; diff --git a/for-of/README.md b/for-of/README.md index b16dca0..19eafba 100644 --- a/for-of/README.md +++ b/for-of/README.md @@ -1,10 +1,8 @@ # [@observable/for-of](https://jsr.io/@observable/for-of) -Projects an -[`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) -to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) that -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each value in order, then -[`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. +[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each +[iterated](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) +value in order and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. ## Build diff --git a/for-of/deno.json b/for-of/deno.json index 60fb5a5..f9ebf5e 100644 --- a/for-of/deno.json +++ b/for-of/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/for-of", - "version": "0.4.0", + "version": "0.5.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/for-of/mod.ts b/for-of/mod.ts index 1e9b34d..e6d1507 100644 --- a/for-of/mod.ts +++ b/for-of/mod.ts @@ -2,9 +2,8 @@ import { Observable } from "@observable/core"; import { empty } from "@observable/empty"; /** - * Projects an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) - * to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) that [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s - * each {@linkcode Values|value} in order upon [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe). + * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each [iterated](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) + * value in order and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. * @example * Populate array * ```ts @@ -45,9 +44,8 @@ export function forOf>( values: Values, ): Observable; /** - * Projects an [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) - * to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) that [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s - * each {@linkcode Value|value} in order upon [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe). + * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each [iterated](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) + * {@linkcode Value|value} in order and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. * @example * ```ts * import { forOf } from "@observable/for-of"; diff --git a/keep-alive/README.md b/keep-alive/README.md index c613f68..b1856ae 100644 --- a/keep-alive/README.md +++ b/keep-alive/README.md @@ -23,6 +23,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3]), keepAlive()).subscribe({ signal: controller.signal, next: (value) => { diff --git a/keep-alive/deno.json b/keep-alive/deno.json index 8ce536b..5d787fe 100644 --- a/keep-alive/deno.json +++ b/keep-alive/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/keep-alive", - "version": "0.9.0", + "version": "0.10.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/keep-alive/mod.ts b/keep-alive/mod.ts index d2195af..e295462 100644 --- a/keep-alive/mod.ts +++ b/keep-alive/mod.ts @@ -1,6 +1,9 @@ import { isObservable, Observable } from "@observable/core"; import { from } from "@observable/from"; +/** + * @internal Do NOT export. + */ const { signal: noopSignal } = new AbortController(); /** @@ -12,6 +15,7 @@ const { signal: noopSignal } = new AbortController(); * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3]), keepAlive()).subscribe({ * signal: controller.signal, * next: (value) => { @@ -29,9 +33,7 @@ const { signal: noopSignal } = new AbortController(); * // "return" * ``` */ -export function keepAlive(): ( - source: Observable, -) => Observable { +export function keepAlive(): (source: Observable) => Observable { return function keepAliveFn(source) { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); if (!isObservable(source)) throw new TypeError("Parameter 1 is not of type 'Observable'"); diff --git a/last-value-from/README.md b/last-value-from/README.md index d278f01..86ce098 100644 --- a/last-value-from/README.md +++ b/last-value-from/README.md @@ -1,13 +1,15 @@ # [@observable/last-value-from](https://jsr.io/@observable/last-value-from) -Projects the provided [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to a -[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) -that either resolves with the last [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed -value on [`return`](https://jsr.io/@observable/core/doc/~/Observer.return), rejects with a -[`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw)n value, or rejects with a +[`Resolve`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve)s +with the last value of the given `observable` on +[`return`](https://jsr.io/@observable/core/doc/~/Observer.return), +[`reject`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject)s +with a [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw)n value of the given +`observable`, or +[`reject`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject)s +with a [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) -if the the provided [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) -[`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s without +if the given `observable` [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s without [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ing a value. ## Build diff --git a/last-value-from/deno.json b/last-value-from/deno.json index 3077109..f33cb54 100644 --- a/last-value-from/deno.json +++ b/last-value-from/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/last-value-from", - "version": "0.7.0", + "version": "0.8.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/last-value-from/mod.ts b/last-value-from/mod.ts index 6746d05..1b78be2 100644 --- a/last-value-from/mod.ts +++ b/last-value-from/mod.ts @@ -3,13 +3,14 @@ import { pipe } from "@observable/pipe"; import { at } from "@observable/at"; /** - * Projects the {@linkcode observable} to a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) - * that either resolves with the last [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value on - * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return), rejects with a - * [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw)n value, or rejects with a + * [`Resolve`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve)s with the + * last {@linkcode Value|value} of the given {@linkcode observable} on [`return`](https://jsr.io/@observable/core/doc/~/Observer.return), + * [`reject`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject)s with + * a [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw)n value of the given {@linkcode observable}, or + * [`reject`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject)s with a * [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) - * if the {@linkcode observable} [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s - * without [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ing a value. + * if the given {@linkcode observable} [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s + * without [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ing a {@linkcode Value|value}. * @example * Last emitted value * ```ts @@ -85,7 +86,7 @@ export function lastValueFrom( pipe(observable, at(-1)).subscribe( new Observer({ next: (value) => resolve(value), - // Reject on return to avoid hanging promises if the source is empty. + // Reject on return to avoid hanging promises if the observable is empty. return: () => reject(new TypeError("Cannot convert empty Observable to Promise")), throw: (value) => reject(value), }), diff --git a/map/README.md b/map/README.md index d26f9be..6356939 100644 --- a/map/README.md +++ b/map/README.md @@ -1,8 +1,6 @@ # [@observable/map](https://jsr.io/@observable/map) -Projects each [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value from the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to a new value. +Projects each value to another value. ## Build diff --git a/map/deno.json b/map/deno.json index c264b6e..3469f21 100644 --- a/map/deno.json +++ b/map/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/map", - "version": "0.12.0", + "version": "0.13.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/map/mod.ts b/map/mod.ts index d693c7e..acdc8f5 100644 --- a/map/mod.ts +++ b/map/mod.ts @@ -2,9 +2,7 @@ import { isObservable, Observable } from "@observable/core"; import { from } from "@observable/from"; /** - * {@linkcode project|Projects} each [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed - * {@linkcode In|value} from the [source](https://jsr.io/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to a new {@linkcode Out|value}. + * {@linkcode project|Projects} each {@linkcode In|value} to another {@linkcode Out|value}. * @example * ```ts * import { map } from "@observable/map"; diff --git a/materialize/README.md b/materialize/README.md index 057fc80..61f9c1a 100644 --- a/materialize/README.md +++ b/materialize/README.md @@ -1,8 +1,7 @@ # [@observable/materialize](https://jsr.io/@observable/materialize) -Projects all of the [`Observer`](https://jsr.io/@observable/core/doc/~/Observer) -[notification](https://jsr.io/@observable/core#notification) as -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values. +[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s all +[notifications](https://jsr.io/@observable/core#notification) as values. ## Build diff --git a/materialize/deno.json b/materialize/deno.json index 3559fb0..fa4a906 100644 --- a/materialize/deno.json +++ b/materialize/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/materialize", - "version": "0.11.0", + "version": "0.12.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/materialize/mod.ts b/materialize/mod.ts index 29d1004..6d99fde 100644 --- a/materialize/mod.ts +++ b/materialize/mod.ts @@ -12,8 +12,7 @@ export type ObserverNotification = Readonly< >; /** - * Projects all of the [`Observer`](https://jsr.io/@observable/core/doc/~/Observer) [notification](https://jsr.io/@observable/core#notification) - * as [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values. + * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s all [notifications](https://jsr.io/@observable/core#notification) as values. * @example * Notifications as values * ```ts diff --git a/merge-map/README.md b/merge-map/README.md index 410cefd..59c3a09 100644 --- a/merge-map/README.md +++ b/merge-map/README.md @@ -1,7 +1,6 @@ # [@observable/merge-map](https://jsr.io/@observable/merge-map) -Projects each [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value to an -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) which is merged in the output +Concurrently projects each value to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). ## Build diff --git a/merge-map/deno.json b/merge-map/deno.json index 49423a3..f76da9c 100644 --- a/merge-map/deno.json +++ b/merge-map/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/merge-map", - "version": "0.13.0", + "version": "0.14.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/merge-map/mod.ts b/merge-map/mod.ts index aa827f5..e8de3ed 100644 --- a/merge-map/mod.ts +++ b/merge-map/mod.ts @@ -2,8 +2,7 @@ import { isObservable, Observable } from "@observable/core"; import { from } from "@observable/from"; /** - * {@linkcode project|Projects} each [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed - * value to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) which is merged in the output + * Concurrently {@linkcode project|projects} each {@linkcode In|value} to an * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). * @example * ```ts diff --git a/merge/README.md b/merge/README.md index 970401c..516f4f5 100644 --- a/merge/README.md +++ b/merge/README.md @@ -1,8 +1,6 @@ # [@observable/merge](https://jsr.io/@observable/merge) -Concurrently [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s all values from every -given [source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable). +Concurrently mirrors all of the given `observables` ## Build @@ -19,7 +17,7 @@ Run `deno task test` or `deno task test:ci` to execute the unit tests via ## Examples -Array of sources +Array of observables ```ts import { merge } from "@observable/merge"; @@ -47,7 +45,7 @@ source2.return(); source3.return(); // "return" ``` -Iterable of sources +Iterable of observables ```ts import { merge } from "@observable/merge"; @@ -100,7 +98,7 @@ Use the following prompt with AI assistants to help them understand this library You are helping me with code that uses @observable/merge from the @observable library ecosystem. WHAT IT DOES: -`merge(sources)` creates an Observable that concurrently emits all values from every given source Observable. Returns when all sources return. +`merge(observables)` creates an Observable that concurrently emits all values from every given source Observable. Returns when all observables return. CRITICAL: This library is NOT RxJS. Key differences: - Observer uses `return`/`throw` — NOT `complete`/`error` @@ -134,13 +132,13 @@ source3.return(); // logs: "done" (when ALL return) ``` RETURN BEHAVIOR: -- Emits values from all sources as they arrive -- Only calls `return()` when ALL sources have returned +- Emits values from all observables as they arrive +- Only calls `return()` when ALL observables have returned - If any source throws, the merged Observable throws SEE ALSO: - `race` — mirrors only the first source to emit -- `all` — emits arrays of latest values from all sources +- `all` — emits arrays of latest values from all observables ```` # Glossary And Semantics diff --git a/merge/deno.json b/merge/deno.json index de030ff..9445fa4 100644 --- a/merge/deno.json +++ b/merge/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/merge", - "version": "0.12.0", + "version": "0.13.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/merge/mod.ts b/merge/mod.ts index 75f16ea..a596025 100644 --- a/merge/mod.ts +++ b/merge/mod.ts @@ -5,10 +5,9 @@ import { mergeMap } from "@observable/merge-map"; import { empty } from "@observable/empty"; /** - * Concurrently [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s all values from every given - * [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). + * Concurrently mirrors all of the given {@linkcode observables}. * @example - * Array of sources + * Array of observables * ```ts * import { merge } from "@observable/merge"; * import { Subject } from "@observable/core"; @@ -52,13 +51,13 @@ import { empty } from "@observable/empty"; * ``` */ export function merge>( - sources: Readonly<{ [Key in keyof Values]: Observable }>, + observables: Readonly<{ [Key in keyof Values]: Observable }>, ): Observable; /** - * Concurrently [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s all values from every given - * [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). + * Concurrently [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s all values from all + * given {@linkcode observables}. * @example - * Iterable of sources + * Iterable of observables * ```ts * import { merge } from "@observable/merge"; * import { Subject } from "@observable/core"; @@ -85,12 +84,12 @@ export function merge>( * source3.return(); // "return" * ``` */ -export function merge(sources: Iterable>): Observable; -export function merge(sources: Iterable>): Observable { +export function merge(observables: Iterable>): Observable; +export function merge(observables: Iterable>): Observable { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); - if (!isIterable(sources)) throw new TypeError("Parameter 1 is not of type 'Iterable'"); - if (Array.isArray(sources) && !sources.length) return empty; - return pipe(forOf(sources), mergeMap((observable) => observable)); + if (!isIterable(observables)) throw new TypeError("Parameter 1 is not of type 'Iterable'"); + if (Array.isArray(observables) && !observables.length) return empty; + return pipe(forOf(observables), mergeMap((observable) => observable)); } /** diff --git a/of/README.md b/of/README.md index 6632fe1..988b34a 100644 --- a/of/README.md +++ b/of/README.md @@ -1,7 +1,6 @@ # [@observable/of](https://jsr.io/@observable/of) -[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a provided value on -[`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe) and then +[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s the given `value` and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. ## Build diff --git a/of/deno.json b/of/deno.json index 55b4db0..533da22 100644 --- a/of/deno.json +++ b/of/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/of", - "version": "0.10.0", + "version": "0.11.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/of/mod.ts b/of/mod.ts index 56ad6ea..774f60c 100644 --- a/of/mod.ts +++ b/of/mod.ts @@ -2,9 +2,8 @@ import type { Observable } from "@observable/core"; import { forOf } from "@observable/for-of"; /** - * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a provided {@linkcode value} - * on [`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe) and then - * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. + * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s the given {@linkcode value} + * and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. * @example * ```ts * import { of } from "@observable/of"; diff --git a/pairwise/README.md b/pairwise/README.md index b581bce..45f8796 100644 --- a/pairwise/README.md +++ b/pairwise/README.md @@ -1,8 +1,7 @@ # [@observable/pairwise](https://jsr.io/@observable/pairwise) -[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s pairs of consecutive values from the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable). +[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s +[`pair`](https://jsr.io/@observable/pairwise/doc/~/Pair)s of consecutive values. ## Build diff --git a/pairwise/deno.json b/pairwise/deno.json index 3d65b29..234e222 100644 --- a/pairwise/deno.json +++ b/pairwise/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/pairwise", - "version": "0.13.0", + "version": "0.14.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/pairwise/mod.ts b/pairwise/mod.ts index c1d0668..2eb6e0a 100644 --- a/pairwise/mod.ts +++ b/pairwise/mod.ts @@ -1,5 +1,4 @@ import { isObservable, type Observable } from "@observable/core"; -import { from } from "@observable/from"; import { pipe } from "@observable/pipe"; import { filter } from "@observable/filter"; import { scan } from "@observable/scan"; @@ -11,13 +10,12 @@ import { scan } from "@observable/scan"; const noValue = Symbol("Flag indicating that no value has been emitted yet"); /** - * Object type that represents a pair of consecutive values. + * Object type that represents a pair of consecutive {@linkcode Value|values}. */ export type Pair = Readonly<[previous: Value, current: Value]>; /** - * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s {@linkcode Pair|pair}s of consecutive values - * from the [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). + * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s {@linkcode Pair|pair}s of consecutive {@linkcode Value|values}. * @example * ```ts * import { pairwise } from "@observable/pairwise"; @@ -39,17 +37,14 @@ export type Pair = Readonly<[previous: Value, current: Value]>; * // "return" * ``` */ -export function pairwise(): ( - source: Observable, -) => Observable> { +export function pairwise(): (source: Observable) => Observable> { return function pairwiseFn(source) { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); if (!isObservable(source)) throw new TypeError("Parameter 1 is not of type 'Observable'"); - const seed: Pair = [noValue, noValue]; - source = from(source); + const initialValue: Pair = [noValue, noValue]; return pipe( source, - scan(([, previous], current) => [previous, current] as const, seed), + scan(([, previous], current) => [previous, current] as const, initialValue), filter((pair) => pair.every((value) => value !== noValue)), ); }; diff --git a/race/README.md b/race/README.md index 5a1772e..7c3c851 100644 --- a/race/README.md +++ b/race/README.md @@ -1,7 +1,6 @@ # [@observable/race](https://jsr.io/@observable/race) -Mirrors the first [source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to +Mirrors the first of the given `observables` to [`next`](https://jsr.io/@observable/core/doc/~/Observer.next) or [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw) a value. @@ -20,7 +19,7 @@ Run `deno task test` or `deno task test:ci` to execute the unit tests via ## Examples -Array of sources +Array of observables ```ts import { race } from "@observable/race"; @@ -47,7 +46,7 @@ source3.next(5); source2.return(); // "return" ``` -Iterable of sources +Iterable of observables ```ts import { race } from "@observable/race"; @@ -99,7 +98,7 @@ Use the following prompt with AI assistants to help them understand this library You are helping me with code that uses @observable/race from the @observable library ecosystem. WHAT IT DOES: -`race(sources)` creates an Observable that mirrors the first source Observable to emit or throw a value. All other sources are unsubscribed once a winner is determined. +`race(observables)` creates an Observable that mirrors the first source Observable to emit or throw a value. All other observables are unsubscribed once a winner is determined. CRITICAL: This library is NOT RxJS. Key differences: - Observer uses `return`/`throw` — NOT `complete`/`error` @@ -132,12 +131,12 @@ source2.return(); // logs: "done" USE CASES: - Timeout patterns (race between data and timeout) -- First-response-wins from multiple sources +- First-response-wins from multiple observables - Fallback strategies SEE ALSO: -- `merge` — emits from all sources concurrently -- `all` — combines latest values from all sources +- `merge` — emits from all observables concurrently +- `all` — combines latest values from all observables ```` # Glossary And Semantics diff --git a/race/deno.json b/race/deno.json index 089d848..e9efbe9 100644 --- a/race/deno.json +++ b/race/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/race", - "version": "0.14.0", + "version": "0.15.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/race/mod.ts b/race/mod.ts index d75c968..8d9c36d 100644 --- a/race/mod.ts +++ b/race/mod.ts @@ -9,12 +9,11 @@ import { filter } from "@observable/filter"; import { empty } from "@observable/empty"; /** - * Mirrors the first [source](https://jsr.io/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to + * Mirrors the first of the given {@linkcode observables} to * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next) or * [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw) a value. * @example - * Array of sources + * Array of observables * ```ts * import { race } from "@observable/race"; * import { Subject } from "@observable/core"; @@ -57,15 +56,14 @@ import { empty } from "@observable/empty"; * ``` */ export function race>( - sources: Readonly<{ [Key in keyof Values]: Observable }>, + observables: Readonly<{ [Key in keyof Values]: Observable }>, ): Observable; /** - * Mirrors the first [source](https://jsr.io/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) to + * Mirrors the first of the given {@linkcode observables} to * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next) or * [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw) a value. * @example - * Iterable of sources + * Iterable of observables * ```ts * import { race } from "@observable/race"; * import { Subject } from "@observable/core"; @@ -91,21 +89,21 @@ export function race>( * source2.return(); // "return" * ``` */ -export function race(sources: Iterable>): Observable; -export function race(sources: Iterable>): Observable { +export function race(observables: Iterable>): Observable; +export function race(observables: Iterable>): Observable { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); - if (!isIterable(sources)) throw new TypeError("Parameter 1 is not of type 'Iterable'"); + if (!isIterable(observables)) throw new TypeError("Parameter 1 is not of type 'Iterable'"); - if (Array.isArray(sources) && !sources.length) return empty; + if (Array.isArray(observables) && !observables.length) return empty; return defer(() => { const finished = new Subject(); return pipe( - forOf(sources), + forOf(observables), takeUntil(finished), - mergeMap((source, index) => + mergeMap((observable, index) => pipe( - source, + observable, tap(() => { finished.next(index); finished.return(); diff --git a/reduce/README.md b/reduce/README.md index bc22282..e3b4cc1 100644 --- a/reduce/README.md +++ b/reduce/README.md @@ -1,11 +1,7 @@ # [@observable/reduce](https://jsr.io/@observable/reduce) -Reduces the [source](https://jsrio/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable)'s -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values to a single value when the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) -[`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. +Reduces each value to a single value on +[`return`](https://jsr.io/@observable/core/doc/~/Observer.return). ## Build @@ -28,8 +24,9 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); -const source = forOf([1, 2, 3]); -pipe(source, reduce((previous, current) => previous + current, 0)).subscribe({ +const observable = forOf([1, 2, 3]); + +pipe(observable, reduce((previous, current) => previous + current, 0)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), @@ -96,6 +93,10 @@ reduce((previous, current, index) => { EMPTY SOURCE: If the source returns without emitting any values, `reduce` will also return without emitting. + +SEE ALSO: + +- `scan()` — same accumulator, but `next`s every intermediate value (not only the final one) ```` # Glossary And Semantics diff --git a/reduce/deno.json b/reduce/deno.json index 5e2b107..60e2c8d 100644 --- a/reduce/deno.json +++ b/reduce/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/reduce", - "version": "0.10.0", + "version": "0.11.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/reduce/mod.ts b/reduce/mod.ts index 8b0969c..217d6d9 100644 --- a/reduce/mod.ts +++ b/reduce/mod.ts @@ -4,12 +4,8 @@ import { pipe } from "@observable/pipe"; import { at } from "@observable/at"; /** - * {@linkcode reducer|Reduces} the [source](https://jsrio/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable)'s - * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values to a single - * value when the [source](https://jsr.io/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) - * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. + * {@linkcode reducer|Reduces} each {@linkcode In|value} to a single {@linkcode Out|value} on + * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return). * @example * ```ts * import { reduce } from "@observable/reduce"; @@ -17,8 +13,9 @@ import { at } from "@observable/at"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); - * const source = forOf([1, 2, 3]); - * pipe(source, reduce((previous, current) => previous + current, 0)).subscribe({ + * const observable = forOf([1, 2, 3]); + * + * pipe(observable, reduce((previous, current) => previous + current, 0)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), @@ -32,13 +29,13 @@ import { at } from "@observable/at"; */ export function reduce( reducer: (previous: Out, current: In, index: number) => Out, - seed: Out, + initialValue: Out, ): (source: Observable) => Observable { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); if (typeof reducer !== "function") throw new TypeError("Parameter 1 is not of type 'Function'"); return function reduceFn(source) { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); if (!isObservable(source)) throw new TypeError("Parameter 1 is not of type 'Observable'"); - return pipe(source, scan(reducer, seed), at(-1)); + return pipe(source, scan(reducer, initialValue), at(-1)); }; } diff --git a/repeat/README.md b/repeat/README.md index 07839f1..c86db50 100644 --- a/repeat/README.md +++ b/repeat/README.md @@ -1,17 +1,8 @@ # [@observable/repeat](https://jsr.io/@observable/repeat) -Re-[`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe)s to the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) each time it -[`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s, as long as the -[notifier](https://jsr.io/@observable/core#notifier) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) then -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a value. Stops repeating if the -[notifier](https://jsr.io/@observable/core#notifier) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) -[`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s without -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ing a value or it -[`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw)s a value. +Re-[`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe)s on +[`return`](https://jsr.io/@observable/core/doc/~/Observer.return) as long as the given `notifier` +then [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a value. ## Build @@ -36,12 +27,12 @@ import { empty } from "@observable/empty"; import { defer } from "@observable/defer"; import { forOf } from "@observable/for-of"; -const source = forOf([1, 2, 3]); +const observable = forOf([1, 2, 3]); const controller = new AbortController(); const repeated = defer(() => { let count = 0; return pipe( - source, + observable, repeat(defer(() => { console.log("notifier subscribed"); return ++count === 2 ? empty : of(undefined); diff --git a/repeat/deno.json b/repeat/deno.json index 792299e..167ba49 100644 --- a/repeat/deno.json +++ b/repeat/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/repeat", - "version": "0.12.0", + "version": "0.13.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/repeat/mod.ts b/repeat/mod.ts index f0ac012..61eac51 100644 --- a/repeat/mod.ts +++ b/repeat/mod.ts @@ -7,13 +7,9 @@ import { mergeMap } from "@observable/merge-map"; import { of } from "@observable/of"; /** - * Re-[`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe)s to the - * [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) each time it - * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s, as long as the {@linkcode notifier} - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) then [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a value. - * Stops repeating if the {@linkcode notifier} [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) - * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s without [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ing a - * value or it [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw)s a value. + * Re-[`subscribe`](https://jsr.io/@observable/core/doc/~/Observable.subscribe)s on + * [`return`](https://jsr.io/@observable/core/doc/~/Observer.return) as long as the given {@linkcode notifier} + * then [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a value. * @example * ```ts * import { repeat } from "@observable/repeat"; @@ -23,12 +19,12 @@ import { of } from "@observable/of"; * import { defer } from "@observable/defer"; * import { forOf } from "@observable/for-of"; * - * const source = forOf([1, 2, 3]); + * const observable = forOf([1, 2, 3]); * const controller = new AbortController(); * const repeated = defer(() => { * let count = 0; * return pipe( - * source, + * observable, * repeat(defer(() => { * console.log("notifier subscribed"); * return ++count === 2 ? empty : of(undefined); @@ -56,7 +52,7 @@ import { of } from "@observable/of"; * ``` */ export function repeat( - notifier: Observable = of(undefined), + notifier: Observable = of(void 0), ): (source: Observable) => Observable { if (!isObservable(notifier)) throw new TypeError("Parameter 1 is not of type 'Observable'"); notifier = from(notifier); diff --git a/scan/README.md b/scan/README.md index b6e6b8e..54c981e 100644 --- a/scan/README.md +++ b/scan/README.md @@ -1,9 +1,6 @@ # [@observable/scan](https://jsr.io/@observable/scan) -Reduces the [source](https://jsrio/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable)'s -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values to a single value, and -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each intermediate reduced value. +Reduces each value to a single value. ## Build @@ -26,8 +23,9 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); -const source = forOf([1, 2, 3]); -pipe(source, scan((previous, current) => previous + current, 0)).subscribe({ +const observable = forOf([1, 2, 3]); + +pipe(observable, scan((previous, current) => previous + current, 0)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), @@ -93,6 +91,10 @@ scan((previous, current, index) => { return previous + current; }, 0) ``` + +SEE ALSO: + +- `reduce()` — same accumulator idea, but only `next`s the final accumulated value on source `return` ```` # Glossary And Semantics diff --git a/scan/deno.json b/scan/deno.json index 7ce4286..a1e81da 100644 --- a/scan/deno.json +++ b/scan/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/scan", - "version": "0.9.0", + "version": "0.10.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/scan/mod.test.ts b/scan/mod.test.ts index 3316ac7..887282c 100644 --- a/scan/mod.test.ts +++ b/scan/mod.test.ts @@ -10,7 +10,7 @@ import { empty } from "@observable/empty"; import { finalize } from "@observable/finalize"; import { never } from "@observable/never"; -Deno.test("scan should accumulate values with a seed", () => { +Deno.test("scan should accumulate values with an initial value", () => { // Arrange const notifications: Array> = []; const observable = pipe( diff --git a/scan/mod.ts b/scan/mod.ts index 7a6ce0d..ed11608 100644 --- a/scan/mod.ts +++ b/scan/mod.ts @@ -5,11 +5,7 @@ import { pipe } from "@observable/pipe"; import { map } from "@observable/map"; /** - * {@linkcode reducer|Reduces} the [source](https://jsrio/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable)'s - * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values to a single - * value, and [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s each - * intermediate reduced value. + * {@linkcode reducer|Reduces} each {@linkcode In|value} to a single {@linkcode Out|value}. * @example * ```ts * import { scan } from "@observable/scan"; @@ -17,8 +13,9 @@ import { map } from "@observable/map"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); - * const source = forOf([1, 2, 3]); - * pipe(source, scan((previous, current) => previous + current, 0)).subscribe({ + * const observable = forOf([1, 2, 3]); + * + * pipe(observable, scan((previous, current) => previous + current, 0)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), @@ -34,7 +31,7 @@ import { map } from "@observable/map"; */ export function scan( reducer: (previous: Out, current: In, index: number) => Out, - seed: Out, + initialValue: Out, ): (source: Observable) => Observable { if (!arguments.length) throw new TypeError("1 argument required but 0 present"); if (typeof reducer !== "function") throw new TypeError("Parameter 1 is not of type 'Function'"); @@ -43,7 +40,7 @@ export function scan( if (!isObservable(source)) throw new TypeError("Parameter 1 is not of type 'Observable'"); source = from(source); return defer(() => { - let previous = seed; + let previous = initialValue; return pipe( source, map((current, index) => (previous = reducer(previous, current, index))), diff --git a/share/README.md b/share/README.md index ff9cd07..fd382c4 100644 --- a/share/README.md +++ b/share/README.md @@ -1,16 +1,13 @@ # [@observable/share](https://jsr.io/@observable/share) -Shares a single [subscription](https://jsr.io/@observable/core#subscription) to the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable), forwarding +Shares a single [subscription](https://jsr.io/@observable/core#subscription) forwarding [`notifications`](https://jsr.io/@observable/core#notification) to all -[consumers](https://jsr.io/@observable/core#consumer) of the output -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) through a -[`Subject`](https://jsr.io/@observable/core/doc/~/Subject) created by a factory function. Resets on -[`return`](https://jsr.io/@observable/core/doc/~/Observer.return), +[consumers](https://jsr.io/@observable/core#consumer) through a +[`Subject`](https://jsr.io/@observable/core/doc/~/Subject) created by the given `factory` function. +Resets on [`return`](https://jsr.io/@observable/core/doc/~/Observer.return), [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw), or when on all [consumers](https://jsr.io/@observable/core#consumer) -[unsubscribe](https://jsr.io/@observable/core/doc/~/Observer.signal). +[`unsubscribe`](https://jsr.io/@observable/core/doc/~/Observer.signal). ## Build @@ -67,8 +64,8 @@ import { Subject } from "@observable/core"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); -const source = new Subject(); -const shared = pipe(source, share(() => new ReplaySubject(1))); +const subject = new Subject(); +const shared = pipe(subject, share(() => new ReplaySubject(1))); shared.subscribe({ signal: controller.signal, @@ -77,8 +74,8 @@ shared.subscribe({ throw: (value) => console.log("1st throw", value), }); -source.next(1); -source.next(2); +subject.next(1); +subject.next(2); // A second consumer joins and receives the last buffered value (2) immediately. shared.subscribe({ @@ -88,8 +85,8 @@ shared.subscribe({ throw: (value) => console.log("2nd throw", value), }); -source.next(3); -source.return(); +subject.next(3); +subject.return(); // Console output: // "1st" 1 diff --git a/share/deno.json b/share/deno.json index 277c754..d375993 100644 --- a/share/deno.json +++ b/share/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/share", - "version": "0.16.0", + "version": "0.17.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/share/mod.ts b/share/mod.ts index 4cba140..032712c 100644 --- a/share/mod.ts +++ b/share/mod.ts @@ -5,17 +5,13 @@ import { finalize } from "@observable/finalize"; import { defer } from "@observable/defer"; /** - * Shares a single [subscription](https://jsr.io/@observable/core#subscription) to the - * [source](https://jsr.io/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable), forwarding + * Shares a single [subscription](https://jsr.io/@observable/core#subscription) forwarding * [`notifications`](https://jsr.io/@observable/core#notification) to all - * [consumers](https://jsr.io/@observable/core#consumer) of the output - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) through a - * [`Subject`](https://jsr.io/@observable/core/doc/~/Subject) created by a - * {@linkcode factory} function. Resets on [`return`](https://jsr.io/@observable/core/doc/~/Observer.return), + * [consumers](https://jsr.io/@observable/core#consumer) through a + * [`Subject`](https://jsr.io/@observable/core/doc/~/Subject) created the + * given {@linkcode factory} function. Resets on [`return`](https://jsr.io/@observable/core/doc/~/Observer.return), * [`throw`](https://jsr.io/@observable/core/doc/~/Observer.throw), or when on all - * [consumers](https://jsr.io/@observable/core#consumer) - * [unsubscribe](https://jsr.io/@observable/core/doc/~/Observer.signal). + * [consumers](https://jsr.io/@observable/core#consumer) [unsubscribe](https://jsr.io/@observable/core/doc/~/Observer.signal). * @example * Basic usage * ```ts @@ -56,8 +52,8 @@ import { defer } from "@observable/defer"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); - * const source = new Subject(); - * const shared = pipe(source, share(() => new ReplaySubject(1))); + * const subject = new Subject(); + * const shared = pipe(subject, share(() => new ReplaySubject(1))); * * shared.subscribe({ * signal: controller.signal, @@ -66,8 +62,8 @@ import { defer } from "@observable/defer"; * throw: (value) => console.log("1st throw", value), * }); * - * source.next(1); - * source.next(2); + * subject.next(1); + * subject.next(2); * * // A second consumer joins and receives the last buffered value (2) immediately. * shared.subscribe({ @@ -77,8 +73,8 @@ import { defer } from "@observable/defer"; * throw: (value) => console.log("2nd throw", value), * }); * - * source.next(3); - * source.return(); + * subject.next(3); + * subject.return(); * * // Console output: * // "1st" 1 diff --git a/switch-map/README.md b/switch-map/README.md index ce770a0..14ed2b3 100644 --- a/switch-map/README.md +++ b/switch-map/README.md @@ -1,12 +1,8 @@ # [@observable/switch-map](https://jsr.io/@observable/switch-map) -Projects each [source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable)'s -[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value to an -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) which is merged in the output -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable), switching to latest projected -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) and -[`unsubscribing`](https://jsr.io/@observable/core/doc/~/Observer.signal) the previous one. +Projects each value to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) and +[`unsubscribes`](https://jsr.io/@observable/core/doc/~/Observer.signal) from any previously +projected [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). ## Build diff --git a/switch-map/deno.json b/switch-map/deno.json index 1d9e50e..93cd36a 100644 --- a/switch-map/deno.json +++ b/switch-map/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/switch-map", - "version": "0.15.0", + "version": "0.16.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/switch-map/mod.ts b/switch-map/mod.ts index b9559f4..21bfea5 100644 --- a/switch-map/mod.ts +++ b/switch-map/mod.ts @@ -6,13 +6,9 @@ import { takeUntil } from "@observable/take-until"; import { mergeMap } from "@observable/merge-map"; /** - * {@linkcode project|Projects} each [source](https://jsr.io/@observable/core#source) - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable)'s - * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value to an - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) which is merged in the output - * [`Observable`](https://jsr.io/@observable/core/doc/~/Observable), switching to latest - * {@linkcode project|projected} [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) and - * [`unsubscribing`](https://jsr.io/@observable/core/doc/~/Observer.signal) the previous one. + * {@linkcode project|Projects} each {@linkcode In|value} to an [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) + * and [`unsubscribes`](https://jsr.io/@observable/core/doc/~/Observer.signal) from any previously + * {@linkcode project|projected} [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). * @example * ```ts * import { BehaviorSubject } from "@observable/behavior-subject"; diff --git a/take-until/README.md b/take-until/README.md index 5554a52..2957ed8 100644 --- a/take-until/README.md +++ b/take-until/README.md @@ -1,9 +1,7 @@ # [@observable/take-until](https://jsr.io/@observable/take-until) -Takes [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from the -[source](https://jsr.io/@observable/core#source) until -[notified](https://jsr.io/@observable/core#notifier) to -[`return`](https://jsr.io/@observable/core/doc/~/Observer.return). +Takes values until the given `notifier` +[`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a value. ## Build @@ -26,21 +24,21 @@ import { takeUntil } from "@observable/take-until"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); -const source = new Subject(); +const subject = new Subject(); const notifier = new Subject(); -pipe(source, takeUntil(notifier)).subscribe({ +pipe(subject, takeUntil(notifier)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), throw: (value) => console.log("throw", value), }); -source.next(1); // "next" 1 -source.next(2); // "next" 2 +subject.next(1); // "next" 1 +subject.next(2); // "next" 2 notifier.next(); // "return" -source.next(3); -source.return(); +subject.next(3); +subject.return(); ``` # AI Prompt diff --git a/take-until/deno.json b/take-until/deno.json index 40e6d77..8335ee9 100644 --- a/take-until/deno.json +++ b/take-until/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/take-until", - "version": "0.11.0", + "version": "0.12.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/take-until/mod.ts b/take-until/mod.ts index 9854894..5fb355b 100644 --- a/take-until/mod.ts +++ b/take-until/mod.ts @@ -2,9 +2,8 @@ import { isObservable, Observable } from "@observable/core"; import { from } from "@observable/from"; /** - * Takes [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from the - * [source](https://jsr.io/@observable/core#source) until [notified](https://jsr.io/@observable/core#notifier) - * to [`return`](https://jsr.io/@observable/core/doc/~/Observer.return). + * Takes {@linkcode Value|values} until the given {@linkcode notifier} + * [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a value. * @example * ```ts * import { Subject } from "@observable/core"; @@ -12,21 +11,21 @@ import { from } from "@observable/from"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); - * const source = new Subject(); + * const subject = new Subject(); * const notifier = new Subject(); * - * pipe(source, takeUntil(notifier)).subscribe({ + * pipe(subject, takeUntil(notifier)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), * throw: (value) => console.log("throw", value), * }); * - * source.next(1); // "next" 1 - * source.next(2); // "next" 2 + * subject.next(1); // "next" 1 + * subject.next(2); // "next" 2 * notifier.next(); // "return" - * source.next(3); - * source.return(); + * subject.next(3); + * subject.return(); * ``` */ export function takeUntil( diff --git a/take/README.md b/take/README.md index a1e4bee..c96d562 100644 --- a/take/README.md +++ b/take/README.md @@ -1,8 +1,6 @@ # [@observable/take](https://jsr.io/@observable/take) -Takes the first count of [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from -the [source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) and then +Takes the first `count` of values and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. ## Build diff --git a/take/deno.json b/take/deno.json index e6244ce..1422763 100644 --- a/take/deno.json +++ b/take/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/take", - "version": "0.13.0", + "version": "0.14.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/take/mod.ts b/take/mod.ts index 57eba4e..cda505a 100644 --- a/take/mod.ts +++ b/take/mod.ts @@ -3,9 +3,7 @@ import { from } from "@observable/from"; import { empty } from "@observable/empty"; /** - * Takes the first {@linkcode count} of [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed - * values from the [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) - * and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. + * Takes the first {@linkcode count} of {@linkcode Value|values} and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. * @example * Positive integer count * ```ts diff --git a/tap/README.md b/tap/README.md index 2c7a5f8..ea321d5 100644 --- a/tap/README.md +++ b/tap/README.md @@ -1,8 +1,6 @@ # [@observable/tap](https://jsr.io/@observable/tap) -Performs a side-effect for each [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed -value from the [source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable). +Registers the given `callback` to be invoked for each value. ## Build diff --git a/tap/deno.json b/tap/deno.json index 0b85dcd..e9ca425 100644 --- a/tap/deno.json +++ b/tap/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/tap", - "version": "0.14.0", + "version": "0.15.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/tap/mod.ts b/tap/mod.ts index ac2c9a8..d7c815b 100644 --- a/tap/mod.ts +++ b/tap/mod.ts @@ -3,8 +3,7 @@ import { pipe } from "@observable/pipe"; import { map } from "@observable/map"; /** - * Performs a {@linkcode callback|side-effect} for each [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed value - * from the [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable). + * Registers the given {@linkcode callback} to be invoked for each {@linkcode Value|value}. * @example * ```ts * import { tap } from "@observable/tap"; diff --git a/throttle/README.md b/throttle/README.md index aa66b95..9f033e9 100644 --- a/throttle/README.md +++ b/throttle/README.md @@ -1,9 +1,6 @@ # [@observable/throttle](https://jsr.io/@observable/throttle) -Throttles the [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from the -[source](https://jsr.io/@observable/core#source) -[`Observable`](https://jsr.io/@observable/core/doc/~/Observable) by the specified number of -milliseconds. +Throttles each value by the given number of `milliseconds`. ## Build @@ -28,21 +25,21 @@ import { Subject } from "@observable/core"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); -const source = new Subject(); +const subject = new Subject(); -pipe(source, throttle(100)).subscribe({ +pipe(subject, throttle(100)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), throw: (value) => console.log("throw", value), }); -source.next(1); // Emitted immediately -source.next(2); // Ignored (within throttle window) -source.next(3); // Ignored (within throttle window) +subject.next(1); // Emitted immediately +subject.next(2); // Ignored (within throttle window) +subject.next(3); // Ignored (within throttle window) // After 100ms, the next value will be emitted -source.next(4); // Emitted after throttle window +subject.next(4); // Emitted after throttle window // Console output: // "next" 1 @@ -58,6 +55,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3]), throttle(0)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -80,6 +78,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3]), throttle(-1)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -99,6 +98,7 @@ import { forOf } from "@observable/for-of"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); + pipe(forOf([1, 2, 3]), throttle(NaN)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), @@ -118,17 +118,18 @@ import { Subject } from "@observable/core"; import { pipe } from "@observable/pipe"; const controller = new AbortController(); -const source = new Subject(); -pipe(source, throttle(Infinity)).subscribe({ +const subject = new Subject(); + +pipe(subject, throttle(Infinity)).subscribe({ signal: controller.signal, next: (value) => console.log("next", value), return: () => console.log("return"), throw: (value) => console.log("throw", value), }); -source.next(1); -source.next(2); -source.return(); +subject.next(1); +subject.next(2); +subject.return(); // Console output (synchronously): // "next" 1 diff --git a/throttle/deno.json b/throttle/deno.json index 1fabafc..a22a121 100644 --- a/throttle/deno.json +++ b/throttle/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/throttle", - "version": "0.16.0", + "version": "0.17.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/throttle/mod.ts b/throttle/mod.ts index 8b4e800..31305c5 100644 --- a/throttle/mod.ts +++ b/throttle/mod.ts @@ -10,9 +10,7 @@ import { timeout } from "@observable/timeout"; import { drop } from "@observable/drop"; /** - * Throttles the [`next`](https://jsr.io/@observable/core/doc/~/Observer.next)ed values from the - * [source](https://jsr.io/@observable/core#source) [`Observable`](https://jsr.io/@observable/core/doc/~/Observable) - * by the specified number of {@linkcode milliseconds}. + * Throttles each {@linkcode Value|value} by the given {@linkcode milliseconds}. * @example * Positive integer milliseconds * ```ts @@ -21,21 +19,21 @@ import { drop } from "@observable/drop"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); - * const source = new Subject(); + * const subject = new Subject(); * - * pipe(source, throttle(100)).subscribe({ + * pipe(subject, throttle(100)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), * throw: (value) => console.log("throw", value), * }); * - * source.next(1); // Emitted immediately - * source.next(2); // Ignored (within throttle window) - * source.next(3); // Ignored (within throttle window) + * subject.next(1); // Emitted immediately + * subject.next(2); // Ignored (within throttle window) + * subject.next(3); // Ignored (within throttle window) * * // After 100ms, the next value will be emitted - * source.next(4); // Emitted after throttle window + * subject.next(4); // Emitted after throttle window * * // Console output: * // "next" 1 @@ -50,6 +48,7 @@ import { drop } from "@observable/drop"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3]), throttle(0)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -71,6 +70,7 @@ import { drop } from "@observable/drop"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3]), throttle(-1)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -89,6 +89,7 @@ import { drop } from "@observable/drop"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); + * * pipe(forOf([1, 2, 3]), throttle(NaN)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), @@ -107,17 +108,18 @@ import { drop } from "@observable/drop"; * import { pipe } from "@observable/pipe"; * * const controller = new AbortController(); - * const source = new Subject(); - * pipe(source, throttle(Infinity)).subscribe({ + * const subject = new Subject(); + * + * pipe(subject, throttle(Infinity)).subscribe({ * signal: controller.signal, * next: (value) => console.log("next", value), * return: () => console.log("return"), * throw: (value) => console.log("throw", value), * }); * - * source.next(1); - * source.next(2); - * source.return(); + * subject.next(1); + * subject.next(2); + * subject.return(); * * // Console output (synchronously): * // "next" 1 diff --git a/timeout/README.md b/timeout/README.md index 5a9c754..86db5e6 100644 --- a/timeout/README.md +++ b/timeout/README.md @@ -1,7 +1,7 @@ # [@observable/timeout](https://jsr.io/@observable/timeout) -[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a `void` value after a specified -number of milliseconds and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. +[`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a `void` value after the given number +of `milliseconds` and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. ## Build diff --git a/timeout/deno.json b/timeout/deno.json index 66774bd..3ad9c41 100644 --- a/timeout/deno.json +++ b/timeout/deno.json @@ -1,6 +1,6 @@ { "name": "@observable/timeout", - "version": "0.11.0", + "version": "0.12.0", "license": "MIT", "exports": "./mod.ts", "publish": { "exclude": ["*.test.ts"] } diff --git a/timeout/mod.ts b/timeout/mod.ts index 8461de7..9cf7a58 100644 --- a/timeout/mod.ts +++ b/timeout/mod.ts @@ -6,7 +6,7 @@ import { pipe } from "@observable/pipe"; import { take } from "@observable/take"; /** - * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a `void` value after a specified number of + * [`Next`](https://jsr.io/@observable/core/doc/~/Observer.next)s a `void` value after the given number of * {@linkcode milliseconds} and then [`return`](https://jsr.io/@observable/core/doc/~/Observer.return)s. * @example * Positive integer milliseconds