docs: update code snippets in docstrings (various pkgs)

thi-ng · Jun 21, 2024 · 73337cd · 73337cd
1 parent 058d63d
commit 73337cd
Showing 26 changed files with 170 additions and 128 deletions.
diff --git a/packages/rstream-log/src/format.ts b/packages/rstream-log/src/format.ts
@@ -45,20 +45,22 @@ export const formatString = (
  *
  *
  * @example
- * ```ts
- * import { Logger, formatString, maskSecrets, writeConsole } from "@thi.ng/rstream-log";
+ * ```ts tangle:../export/mask-secrets.ts
+ * import {
+ *   Logger, formatString, maskSecrets, writeConsole
+ * } from "@thi.ng/rstream-log";
  *
  * const logger = new Logger();
  *
- * logger.transform(
+ * logger.stream.transform(
  *   formatString(),
  *   maskSecrets([/(?<=[A-Z0-9_]\=)\w+/g])
  * ).subscribe(
  *   writeConsole()
  * );
  *
  * logger.info("logged in USER=toxi, using TOKEN=123456");
- * // [INFO] logger-0: logged in USER=****, using TOKEN=****
+ * // [INFO] logger-0: 2024-06-21T12:22:58.004Z  logged in USER=****, using TOKEN=****
  * ```
  *
  * @param patterns -

diff --git a/packages/rstream-query/src/convert.ts b/packages/rstream-query/src/convert.ts
@@ -47,10 +47,10 @@ const __mapSubject =
  *   described in the previous rule
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/as-triples.ts
  * import { asTriples } from "@thi.ng/rstream-query";
  *
- * src = {
+ * const src = {
  *   "@thi.ng/rstream-query": {
  *     type: "project",
  *     author: "toxi",
@@ -65,7 +65,7 @@ const __mapSubject =
  *   }
  * };
  *
- * [...asTriples(src)]
+ * console.log([...asTriples(src)]);
  * // [ [ '@thi.ng/rstream-query', 'type', 'project' ],
  * //   [ '@thi.ng/rstream-query', 'author', 'toxi' ],
  * //   [ '@thi.ng/rstream-query', 'tag', 'ES6' ],

diff --git a/packages/rstream/src/atom.ts b/packages/rstream/src/atom.ts
@@ -36,14 +36,16 @@ export interface FromAtomOpts<T> extends CommonOpts {
  * Also see {@link fromView}, {@link fromViewUnsafe}
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/from-atom.ts
  * import { defAtom, defCursor } from "@thi.ng/atom";
- * import { fromCursor } from "@thi.ng/rstream";
+ * import { fromAtom, trace } from "@thi.ng/rstream";
  *
- * db = defAtom({ a: 23, b: 88 });
- * cursor = defCursor(db, "a")
+ * type DB = { a: number; b?: number };
  *
- * rs.fromAtom(cursor).subscribe(rs.trace("cursor val:"))
+ * const db = defAtom<DB>({ a: 23, b: 88 });
+ * const cursor = defCursor(db, ["a"])
+ *
+ * fromAtom(cursor).subscribe(trace("cursor val:"))
  * // cursor val: 23
  *
  * cursor.reset(42);

diff --git a/packages/rstream/src/bisect.ts b/packages/rstream/src/bisect.ts
@@ -14,7 +14,7 @@ import { PubSub } from "./pubsub.js";
  * kept prior to calling `bisect()`.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/bisect.ts
  * import { bisect, fromIterable, trace } from "@thi.ng/rstream";
  *
  * fromIterable([1, 2, 3, 4]).subscribe(
@@ -33,19 +33,28 @@ import { PubSub } from "./pubsub.js";
  * ```
  *
  * @example
- * ```ts
- * import { bisect, subscription, trace } from "@thi.ng/rstream";
+ * ```ts tangle:../export/bisect-2.ts
+ * import { bisect, fromIterable, subscription, trace } from "@thi.ng/rstream";
  * import { map } from "@thi.ng/transducers";
  *
- * const odd = subscription();
- * const even = subscription();
+ * const odd = subscription<number, number>();
+ * const even = subscription<number, number>();
  * odd.subscribe(trace("odd"));
- * odd.subscribe(trace("odd x10"), { xform: map((x) => x * 10) });
+ * odd.subscribe(trace("odd x10"), { xform: map((x: number) => x * 10) });
  * even.subscribe(trace("even"));
  *
  * fromIterable([1, 2, 3, 4]).subscribe(
  *     bisect((x) => !!(x & 1), odd, even)
  * );
+ * // odd x10 10
+ * // odd 1
+ * // even 2
+ * // odd x10 30
+ * // odd 3
+ * // even 4
+ * // odd x10 done
+ * // odd done
+ * // even done
  * ```
  *
  * @param pred - predicate function

diff --git a/packages/rstream/src/debounce.ts b/packages/rstream/src/debounce.ts
@@ -8,12 +8,13 @@ import { metaStream, type MetaStreamOpts } from "./metastream.js";
  * milliseconds.
  *
  * @example
- * ```ts
- * import { debounce, fromIterable } from "@thi.ng/rstream";
+ * ```ts tangle:../export/debounce.ts
+ * import { debounce, fromIterable, trace } from "@thi.ng/rstream";
  *
  * const src = fromIterable([1, 2, 3], { delay: 10 })
- * src.subscribe(debounce(20)).subscribe({ next: console.log });
+ * src.subscribe(debounce(20)).subscribe(trace());
  * // 3
+ * // done
  * ```
  *
  * @param delay -

diff --git a/packages/rstream/src/event.ts b/packages/rstream/src/event.ts
@@ -49,8 +49,6 @@ export const fromEvent = (
  * fromEvent(document.body, "mousemove"); // Stream<Event>
  * ```
  *
- * Also see: {@link fromEvent}
- *
  * @param src -
  * @param name -
  * @param listenerOpts -

diff --git a/packages/rstream/src/merge.ts b/packages/rstream/src/merge.ts
@@ -27,7 +27,7 @@ export interface StreamMergeOpts<A, B> extends TransformableOpts<A, B> {
  * {@link StreamMergeOpts | options}.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/merge.ts
  * import { fromIterable, merge, trace } from "@thi.ng/rstream";
  *
  * merge({
@@ -47,6 +47,7 @@ export interface StreamMergeOpts<A, B> extends TransformableOpts<A, B> {
  * // 3
  * // 20
  * // 30
+ * // done
  * ```
  *
  * @example
@@ -56,13 +57,14 @@ export interface StreamMergeOpts<A, B> extends TransformableOpts<A, B> {
  * track their provenance:
  *
  * @example
- * ```ts
- * import { fromIterable, merge } from "@thi.ng/rstream";
+ * ```ts tangle:../export/merge-2.ts
+ * import { fromIterable, merge, trace } from "@thi.ng/rstream";
+ * import { labeled } from "@thi.ng/transducers";
  *
  * merge({
  *     src: [
- *         fromIterable([1, 2, 3]).transform(tx.labeled("a")),
- *         fromIterable([10, 20, 30]).transform(tx.labeled("b")),
+ *         fromIterable([1, 2, 3]).transform(labeled("a")),
+ *         fromIterable([10, 20, 30]).transform(labeled("b")),
  *     ]
  * }).subscribe(trace());
  * // ["a", 1]
@@ -71,6 +73,7 @@ export interface StreamMergeOpts<A, B> extends TransformableOpts<A, B> {
  * // ["b", 20]
  * // ["a", 3]
  * // ["b", 30]
+ * // done
  * ```
  *
  * @param opts -

diff --git a/packages/rstream/src/metastream.ts b/packages/rstream/src/metastream.ts
@@ -45,14 +45,14 @@ export interface MetaStreamOpts extends CommonOpts {
  * dynamic switching between them.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/metastream.ts
  * import { fromIterable, metaStream, trace } from "@thi.ng/rstream";
  * import { repeat } from "@thi.ng/transducers";
  *
  * // transform each received odd number into a stream
  * // producing 3 copies of that number in the metastream
  * // even numbers are ignored
- * a = metaStream(
+ * const a = metaStream<number, number>(
  *   (x) => (x & 1)
  *     ? fromIterable(repeat(x, 3), { delay: 100 })
  *     : null
@@ -65,41 +65,51 @@ export interface MetaStreamOpts extends CommonOpts {
  * // 23
  * // 23
  *
- * a.next(42) // ignored by factory fn
+ * setTimeout(() => a.next(42), 500); // value 42 ignored by metastream
  *
- * a.next(43)
+ * setTimeout(() => a.next(43), 1000);
  * // 43
  * // 43
  * // 43
  * ```
  *
  * @example
- * ```ts
- * import { fromIterable, metaStream, trace, CloseMode } from "@thi.ng/rstream";
- * import { repeat } from "@thi.ng/transducers";
+ * ```ts tangle:../export/metastream-2.ts
+ * import { CloseMode, fromIterable, metaStream, trace } from "@thi.ng/rstream";
+ * import { cycle, repeat } from "@thi.ng/transducers";
  *
- * // infinite inputs
- * a = fromIterable(
+ * // infinite inputs (important: closeOut mode = never!)
+ * const a = fromIterable(
  *   repeat("a"),
- *   { delay: 1000, closeOut: CloseMode.NEVER }
+ *   { delay: 100, closeOut: CloseMode.NEVER }
  * );
- * b = fromIterable(
+ * const b = fromIterable(
  *   repeat("b"),
- *   { delay: 1000, closeOut: CloseMode.NEVER }
+ *   { delay: 100, closeOut: CloseMode.NEVER }
  * );
  *
  * // stream selector / switch
- * m = metaStream((x) => x ? a : b);
+ * const m = metaStream<boolean, string>((x) => (x ? a : b));
  * m.subscribe(trace("meta from: "));
  *
- * m.next(true);
- * // meta from: a
- *
- * m.next(false);
- * // meta from: b
- *
- * m.next(true);
- * // meta from: a
+ * // create infinite stream of true/false and pipe into
+ * // the metastream and switch which source to use
+ * fromIterable(cycle([true, false]), { delay: 500 })
+ *   .subscribe({ next(x) { m.next(x); } });
+ *
+ * // a
+ * // a
+ * // a
+ * // a
+ * // a
+ * // b
+ * // b
+ * // b
+ * // b
+ * // b
+ * // a
+ * // a
+ * // ...
  * ```
  *
  * @param factory -

diff --git a/packages/rstream/src/nodejs.ts b/packages/rstream/src/nodejs.ts
@@ -35,9 +35,9 @@ export const fromNodeJS = <T>(
  * to rechunk input.
  *
  * @example
- * ```ts
- * import { spawn } from "node:child_process"
+ * ```ts tangle:../export/lines-from-nodejs.ts
  * import { linesFromNodeJS, trace } from "@thi.ng/rstream";
+ * import { spawn } from "node:child_process"
  *
  * const cmd = spawn("ls", ["-la"]);
  *

diff --git a/packages/rstream/src/object.ts b/packages/rstream/src/object.ts
@@ -97,28 +97,31 @@ export interface StreamObjOpts<T, K extends Keys<T>> extends CommonOpts {
  * `fromObject` and specify shared options for *all* created streams.
  *
  * @example
- * ```ts
- * import { fromObject } from "@thi.ng/rstream";
+ * ```ts tangle:../export/from-object.ts
+ * import { fromObject, trace } from "@thi.ng/rstream";
  *
  * type Foo = { a?: number; b: string; };
  *
- * const obj = fromObject(<Foo>{ a: 1, b: "foo" })
+ * const obj = fromObject(<Foo>{ a: 1, b: "foo" });
  *
- * obj.streams.a.subscribe(trace("a"))
+ * obj.streams.a.subscribe(trace("a"));
  * // a 1
- * obj.streams.b.subscribe(trace("b"))
+ *
+ * obj.streams.b.subscribe(trace("b"));
  * // b foo
  *
- * obj.next({ b: "bar" })
+ * obj.next({ b: "bar" });
  * // a undefined
  * // b bar
  * ```
  *
  * @example
- * ```ts
- * import { fromObject, trace } from "@thi.ng/rstream";
+ * ```ts tangle:../export/from-object-2.ts
+ * import { fromObject, subscription, trace } from "@thi.ng/rstream";
+ *
+ * type Foo = { a?: number; b: string; };
  *
- * const obj = fromObject(<Foo>{}, ["a", "b"], { initial: false });
+ * const obj = fromObject(<Foo>{}, { keys: ["a", "b"], initial: false });
  * obj.streams.a.subscribe(trace("a"));
  * obj.streams.b.subscribe(trace("b"));
  *

diff --git a/packages/rstream/src/post-worker.ts b/packages/rstream/src/post-worker.ts
@@ -21,15 +21,15 @@ import { defWorker } from "./defworker.js";
  * since the parent subscription is {@link ISubscriber.done}.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/post-worker.ts
  * import { postWorker, stream } from "@thi.ng/rstream";
  *
  * // worker source code
- * src = `self.onmessage = (e) => console.log("worker", e.data);`;
+ * const src = `self.onmessage = (e) => console.log("worker", e.data);`;
  *
- * a = stream();
+ * const a = stream<any>();
  * a.subscribe(
- *   postWorker(src, { type: "application/javascript" }))
+ *   postWorker(new Blob([src], { type: "application/javascript" }))
  * );
  *
  * a.next(42)

diff --git a/packages/rstream/src/promises.ts b/packages/rstream/src/promises.ts
@@ -14,8 +14,8 @@ import { fromPromise } from "./promise.js";
  * Also see {@link fromPromise}, {@link resolve}.
  *
  * @example
- * ```ts
- * import { fromPromises } from "@thi.ng/rstream";
+ * ```ts tangle:../export/from-promises.ts
+ * import { fromPromises, trace } from "@thi.ng/rstream";
  *
  * fromPromises([
  *     Promise.resolve(1),
@@ -28,20 +28,6 @@ import { fromPromise } from "./promise.js";
  * // done
  * ```
  *
- * @example
- * If individual error handling is required, an alternative is below
- * (however this approach provides no ordering guarantees):
- *
- * ```ts
- * import { fromIterable, resolve, trace } from "@thi.ng/rstream";
- *
- * fromIterable([
- *     Promise.resolve(1),
- *     new Promise(() => setTimeout(() => { throw new Error("eeek"); }, 10)),
- *     Promise.resolve(3)
- * ]).subscribe(resolve()).subscribe(trace())
- * ```
- *
  * @param promises -
  * @param opts -
  */

diff --git a/packages/rstream/src/resolve.ts b/packages/rstream/src/resolve.ts
@@ -22,14 +22,14 @@ export interface ResolverOpts extends IID<string> {
  * from receiving further values.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/resolve.ts
  * import { fromIterable, resolve, trace } from "@thi.ng/rstream";
  * import { delayed } from "@thi.ng/transducers";
  *
- * fromIterable([1, 2, 3], 100)
+ * fromIterable([1, 2, 3], 500)
  *   .transform(delayed(1000))
  *   .subscribe(resolve())
- *   .subscribe(trace("result"))
+ *   .subscribe(trace("result"));
  * // result 1
  * // result 2
  * // result 3