docs: update code snippets in docstrings (various pkgs)

packages/oquery/src/api.ts

@@ -156,15 +156,19 @@ export interface QueryOpts {
 	 * successfully matched property values will be included for each result.
 	 *
 	 * @example
-	 * ```ts
+	 * ```ts tangle:../export/def-query.ts
 	 * import { defQuery } from "@thi.ng/oquery";
 	 *
 	 * const DB = { a: { id: 1, name: "alice" }, b: { name: "bob" } };
 	 *
-	 * defQuery({ partial: false })(DB, null, "id", 1)
+	 * console.log(
+	 *   defQuery({ partial: false })(DB, null, "id", 1)
+	 * );
 	 * // { a: { id: 1, name: "alice" } }
 	 *
-	 * defQuery({ partial: true })(DB, null, "id", 1)
+	 * console.log(
+	 *   defQuery({ partial: true })(DB, null, "id", 1)
+	 * );
 	 * // { a: { id: 1 } }
 	 * ```
 	 *
@@ -181,15 +185,20 @@ export interface QueryOpts {
 	 * ALWAYS matched in a componentwise manner.
 	 *
 	 * @example
-	 * ```ts
+	 * ```ts tangle:../export/def-query-2.ts
 	 * import { defQuery } from "@thi.ng/oquery";
 	 *
 	 * const DB = { a: { knows: ["b","c"] }, b: { knows: ["a","c"] }};
-	 * defQuery({ cwise: true })(DB, null, "knows", "b")
-	 * // { a: { knows: ["b","c"] } }
 	 *
-	 * defQuery({ cwise: false })(DB, null, "knows", (x) => x.includes("b"))
-	 * // { a: { knows: ["b","c"] } }
+	 * console.log(
+	 *   defQuery({ cwise: true })(DB, null, "knows", "b")
+	 * );
+	 * // { a: { knows: ["b", "c"] } }
+	 *
+	 * console.log(
+	 *   defQuery({ cwise: false })(DB, null, "knows", (x) => x.includes("b"))
+	 * );
+	 * // { a: { knows: ["b", "c"] } }
 	 * ```
 	 *
 	 * @defaultValue true

packages/oquery/src/match.ts

@@ -27,7 +27,37 @@ export interface MatchMultipleOpts<T> {
  * which contains any of these exclusions is automatically rejected, even if
  * other strings could be matched.
  *
- * See {@link matchMultiple} for more details & code example.
+ * See {@link matchMultiple} for more details.
+ *
+ * @example
+ * ```ts tangle:../export/match-strings.ts
+ * import { query, matchStrings } from "@thi.ng/oquery";
+ *
+ * const DB = [
+ *   { id: 1, tags: ["a", "b"] },
+ *   { id: 2, tags: ["c", "b"] },
+ *   { id: 3, tags: ["c", "a"] },
+ * ];
+ *
+ * // tag intersection
+ * console.log(
+ *   query(DB, [matchStrings("tags", ["a", "b"])])
+ * );
+ * // [ { id: 1, tags: ["a", "b"] } ]
+ *
+ * // tag union
+ * console.log(
+ *   query(DB, [matchStrings("tags", ["a", "b"])])
+ * );
+ * // here returns full DB...
+ * // since each item either has `a` and/or `b` tags
+ *
+ * // tag exclusion (require `a`, disallow `b`)
+ * console.log(
+ *   query(DB, [matchStrings("tags", ["a", "!b"])])
+ * );
+ * // [ { id: 3, tags: ["c", "a"] } ]
+ * ```
  *
  * @param key
  * @param matches
@@ -60,32 +90,8 @@ export const matchStrings = <T extends QueryObj = QueryObj>(
  * If the `union` option is true, only one of the provided values needs to
  * match. Exclusions _always_ take precedence.
  *
- * Note: See {@link matchStrings} for a syntax sugar of this function, aimed at
- * matching `string[]` options.
- *
- * @example
- * ```ts
- * import { query, matchStrings } from "@thi.ng/oquery";
- *
- * const DB = [
- *   { id: 1, tags: ["a", "b"] },
- *   { id: 2, tags: ["c", "b"] },
- *   { id: 3, tags: ["c", "a"] },
- * ];
- *
- * // tag intersection
- * query(DB, [matchStrings("tags", ["a", "b"])])
- * // [ { id: 1, tags: ["a", "b"] } ]
- *
- * // tag union
- * query(DB, [matchStrings("tags", ["a", "b"])])
- * // here returns full DB...
- * // since each item either has `a` and/or `b` tags
- *
- * // tag exclusion (require `a`, disallow `b`)
- * query(DB, [matchStrings("tags", ["a", "!b"])])
- * // [ { id: 3, tags: ["c", "a"] } ]
- * ```
+ * Note: See {@link matchStrings} for a syntax sugar & examples of this
+ * function, aimed at matching `string[]` options.
  *
  * @param key
  * @param matches
@@ -140,7 +146,7 @@ export const matchMultiple = <T extends QueryObj = QueryObj, V = any>(
  *   between operator and value are ignored.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/match-pattern.ts
  * import { query, matchPattern } from "@thi.ng/oquery";
  *
  * const DB = [
@@ -149,12 +155,19 @@ export const matchMultiple = <T extends QueryObj = QueryObj, V = any>(
  *   { id: "c", score: 15 },
  * ];
  *
- * query(DB, [matchPattern("id", /[a-z]{4,}/)]);
+ * console.log(
+ *   query(DB, [matchPattern("id", /[a-z]{4,}/)])
+ * );
  * // [{ id: "bbbb", score: 60 }]
- * query(DB, [matchPattern("id", ">= c")]);
+ *
+ * console.log(
+ *   query(DB, [matchPattern("id", ">= c")])
+ * );
  * // [{ id: "c", score: 15 }]
  *
- * query(DB, [matchPattern("score", "<50")]);
+ * console.log(
+ *   query(DB, [matchPattern("score", "<50")])
+ * );
  * // [{ id: "a", score: 32 }, { id: "c", score: 15 }]
  * ```
  *

packages/paths/src/delete-in.ts

@@ -25,11 +25,13 @@ import { updateIn } from "./update-in.js";
  * tuple.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/delete-in-unsafe.ts
  * import { deleteInUnsafe } from "@thi.ng/paths";
  *
  * // unchecked
- * deleteInUnsafe({ a: { b: { c: 23 } } }, "a.b.c");
+ * console.log(
+ *   deleteInUnsafe({ a: { b: { c: 23 } } }, "a.b.c")
+ * );
  * // { a: { b: { } } }
  * ```
  *
@@ -51,14 +53,18 @@ export const deleteInUnsafe = (state: any, path: Path): any =>
  * See {@link deleteInUnsafe} for unchecked version.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/delete-in.ts
  * import { deleteIn } from "@thi.ng/paths";
  *
  * // type checked
- * deleteIn({ a: { b: { c: 23 } } }, ["a","b","c"]);
+ * console.log(
+ *   deleteIn({ a: { b: { c: 23 } } }, ["a","b","c"])
+ * );
  *
  * // error (invalid path)
- * deleteIn({ a: { b: { c: 23 } } }, ["a","b","d"]);
+ * console.log(
+ *   deleteIn({ a: { b: { c: 23 } } }, ["a","b","d"])
+ * );
  * ```
  *
  * @param state -

packages/paths/src/get-in.ts

@@ -24,10 +24,12 @@ import { defGetter } from "./getter.js";
  * value to be retrieved (default: `any`).
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/get-in-unsafe.ts
  * import { getInUnsafe } from "@thi.ng/paths";
  *
- * getInUnsafe({ a: { b: { c: 23 } } }, "a.b.c");
+ * console.log(
+ *   getInUnsafe({ a: { b: { c: 23 } } }, "a.b.c")
+ * );
  * // 23
  * ```
  *
@@ -45,11 +47,13 @@ export const getInUnsafe = <T = any>(state: any, path: Path): Maybe<T> =>
  * Only the first 8 path levels are type checked.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/get-in.ts
  * import { getIn } from "@thi.ng/paths";
  *
  * // type checked path and inferred return type
- * getIn({ a: { b: { c: 23 } } }, ["a","b","c"]);
+ * console.log(
+ *   getIn({ a: { b: { c: 23 } } }, ["a","b","c"])
+ * );
  * // 23
  * ```
  *

packages/paths/src/getter.ts

@@ -27,14 +27,16 @@ import { toPath } from "./path.js";
  * Also see: {@link getIn}, {@link getInUnsafe}
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/def-getter-unsafe.ts
  * import { defGetterUnsafe } from "@thi.ng/paths";
  *
  * const g = defGetterUnsafe("a.b.c");
  *
- * g({ a: { b: { c: 23} } }) // 23
- * g({ x: 23 }) // undefined
- * g() // undefined
+ * console.log(g({ a: { b: { c: 23} } }));
+ * // 23
+ *
+ * console.log(g({ x: 23 }));
+ * // undefined
  * ```
  *
  * @param path -
@@ -62,22 +64,27 @@ export const defGetterUnsafe = <T = any>(path: Path): Fn<any, Maybe<T>> =>
  * Also see: {@link defGetterUnsafe}, {@link getIn}, {@link getInUnsafe}
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/def-getter.ts
  * import { defGetter } from "@thi.ng/paths";
  *
  * interface Foo {
  *   a: { b: { c: number; } }
  * }
  *
  * // fully type checked getter
- * g = defGetter<Foo, "a", "b", "c">(["a","b","c"]);
+ * const g = defGetter<Foo, "a", "b", "c">(["a","b","c"]);
  *
  * // error (wrong `d` key)
- * g = defGetter<Foo, "a", "b", "d">(["a","b","d"]);
+ * // g = defGetter<Foo, "a", "b", "d">(["a","b","d"]);
+ *
+ * console.log(g({ a: { b: { c: 23} } }));
+ * // 23
+ *
+ * // error
+ * console.log(g({ x: 23 }));
  *
- * g({ a: { b: { c: 23} } }); // 23
- * g({ x: 23 }); // error
- * g(); // error
+ * // error
+ * console.log(g());
  * ```
  *
  * @param path -

packages/paths/src/mut-in-many.ts

@@ -15,16 +15,18 @@ import { mutIn } from "./mut-in.js";
  * value and will also be used as return type.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/mut-in-many-unsafe.ts
  * import { mutInManyUnsafe } from "@thi.ng/paths";
  *
- * mutInManyUnsafe(
+ * const res = mutInManyUnsafe(
  *   { a: { b: 1 }, x: { y: { z: 2 } } },
  *   // pair #1
  *   "a.b", 10,
  *   // pair #2
  *   "x.y.z", 20
- * )
+ * );
+ *
+ * console.log(res);
  * // { a: { b: 10 }, x: { y: { z: 20 } } }
  * ```
  *

packages/paths/src/mut-in.ts

@@ -24,14 +24,18 @@ import { defMutator } from "./mutator.js";
  * Also see {@link defMutatorUnsafe}.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/mut-in-unsafe.ts
  * import { mutInUnsafe } from "@thi.ng/paths";
  *
- * mutInUnsafe({ a: { b: [10, 20] } }, "a.b.1", 23);
+ * console.log(
+ *   mutInUnsafe({ a: { b: [10, 20] } }, "a.b.1", 23)
+ * );
  * // { a: { b: [ 10, 23 ] } }
  *
  * // fails (see `defMutator()` docs)
- * mutInUnsafe({}, "a.b.c", 23);
+ * console.log(
+ *   mutInUnsafe({}, "a.b.c", 23)
+ * );
  * // undefined
  * ```
  *
@@ -52,10 +56,12 @@ export const mutInUnsafe = <T = any>(state: any, path: Path, val: T): any =>
  * Also see {@link defMutator}, {@link mutInUnsafe}
  *
  * @example
- * ```ts
- * import { muIn } from "@thi.ng/paths";
+ * ```ts tangle:../export/mut-in.ts
+ * import { mutIn } from "@thi.ng/paths";
  *
- * mutIn({ a: { b: [10, 20] } }, ["a", "b", 1], 23)
+ * console.log(
+ *   mutIn({ a: { b: [10, 20] } }, ["a", "b", 1], 23)
+ * );
  * // { a: { b: [ 10, 23 ] } }
  * ```
  *

packages/paths/src/path.ts

@@ -15,16 +15,16 @@ import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
  *
  * Also see {@link disallowProtoPath}.
  *
- * ```ts
+ * ```ts tangle:../export/to-path.ts
  * import { toPath } from "@thi.ng/paths";
  *
- * toPath("a.b.c");
+ * console.log(toPath("a.b.c"));
  * // ["a", "b", "c"]
  *
- * toPath(0)
+ * console.log(toPath(0));
  * // [0]
  *
- * toPath(["a", "b", "c"])
+ * console.log(toPath(["a", "b", "c"]));
  * // ["a", "b", "c"]
  * ```
  *

packages/paths/src/set-in-many.ts

@@ -16,16 +16,18 @@ import { setIn } from "./set-in.js";
  * overall state value and will also be used as return type.
  *
  * @example
- * ```ts
+ * ```ts tangle:../export/set-in-many-unsafe.ts
  * import { setInManyUnsafe } from "@thi.ng/paths";
  *
- * setInManyUnsafe(
+ * const res = setInManyUnsafe(
  *   {},
  *   // pair #1
  *   "a.b", 10,
  *   // pair #2
  *   "x.y.z", 20
  * );
+ *
+ * console.log(res);
  * // { a: { b: 10 }, x: { y: { z: 20 } } }
  * ```
  *