feat(website): revisions and playground for all tsdoc examples

Author: TomerAberbach

pnpm-lock.yaml

@@ -14,7 +14,9 @@ import type {
  * Returns a {@link Reducer} that collects values to an `Array`.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { cycle, pipe, reduce, take, toArray } from 'lfi'
+ *
  * console.log(
  *   pipe(
  *     cycle([`sloth`, `more sloth`]),
@@ -34,12 +36,14 @@ export const toArray: <Value>() => Reducer<Value, Value[]>
  * Returns a {@link Reducer} that collects values to a `Set`.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { cycle, pipe, reduce, take, toSet } from 'lfi'
+ *
  * console.log(
  *   pipe(
  *     cycle([`sloth`, `more sloth`]),
  *     take(4),
- *     reduce(toArray()),
+ *     reduce(toSet()),
  *   ),
  * )
  * //=> Set(2) { 'sloth', 'more sloth' }
@@ -54,7 +58,9 @@ export const toSet: <Value>() => Reducer<Value, Set<Value>>
  * Returns a {@link Reducer} that collects objects to a `WeakSet`.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { cycle, map, pipe, reduce, take, toWeakSet } from 'lfi'
+ *
  * console.log(
  *   pipe(
  *     cycle([`sloth`, `more sloth`]),
@@ -80,15 +86,21 @@ export const toWeakSet: <Value extends object>() => Reducer<
  * In the case of pairs with duplicate keys, the value of the last one wins.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { map, pipe, reduce, toObject } from 'lfi'
+ *
  * console.log(
  *   pipe(
  *     [`sloth`, `more sloth`, `even more sloth`],
  *     map(string => [string, string.length]),
  *     reduce(toObject()),
  *   ),
  * )
- * //=> { sloth: 5, 'more sloth': 10, 'even more sloth': 15 }
+ * //=> {
+ * //=>   sloth: 5,
+ * //=>   'more sloth': 10,
+ * //=>   'even more sloth': 15
+ * //=> }
  * ```
  *
  * @category Collections
@@ -106,15 +118,21 @@ export const toObject: <Key extends keyof never, Value>() => RawKeyedReducer<
  * In the case of pairs with duplicate keys, the value of the last one wins.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { map, pipe, reduce, toMap } from 'lfi'
+ *
  * console.log(
  *   pipe(
  *     [`sloth`, `more sloth`, `even more sloth`],
  *     map(string => [string, string.length]),
  *     reduce(toMap()),
  *   ),
  * )
- * //=> Map(3) { 'sloth' => 5, 'more sloth' => 10, 'even more sloth' => 15 }
+ * //=> Map(3) {
+ * //=>   'sloth' => 5,
+ * //=>   'more sloth' => 10,
+ * //=>   'even more sloth' => 15
+ * //=> }
  * ```
  *
  * @category Collections
@@ -132,7 +150,9 @@ export const toMap: <Key, Value>() => RawKeyedReducer<
  * In the case of pairs with duplicate keys, the value of the last one wins.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { map, pipe, reduce, toWeakMap } from 'lfi'
+ *
  * console.log(
  *   pipe(
  *     [`sloth`, `more sloth`, `even more sloth`],
@@ -157,7 +177,9 @@ export const toWeakMap: <Key extends object, Value>() => RawKeyedReducer<
  * and reduces values with the same key using `innerReducer`.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { map, pipe, reduce, toArray, toGrouped, toMap } from 'lfi'
+ *
  * console.log(
  *   pipe(
  *     [`sloth`, `some sloth`, `sleep`, `more sloth`, `even more sloth`],
@@ -252,15 +274,21 @@ export const toGrouped: {
  * an {@link OptionalReducer}. Otherwise, returns a {@link Reducer}.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { map, pipe, reduce, toCount, toJoin, toMultiple, toSet } from 'lfi'
+ *
  * console.log(
  *   pipe(
  *     [`sloth`, `some sloth`, `sleep`, `more sloth`, `even more sloth`],
  *     map(string => string.length),
  *     reduce(toMultiple([toSet(), toCount(), toJoin(`,`)])),
  *   ),
  * )
- * //=> [ Set(3) { 5, 10, 15 }, 5, '5,10,5,10,15' ]
+ * //=> [
+ * //=>   Set(3) { 5, 10, 15 },
+ * //=>   5,
+ * //=>   '5,10,5,10,15'
+ * //=> ]
  *
  * console.log(
  *   pipe(
@@ -275,7 +303,11 @@ export const toGrouped: {
  *     ),
  *   ),
  * )
- * //=> { set: Set(3) { 5, 10, 15 }, count: 5, string: '5,10,5,10,15' }
+ * //=> {
+ * //=>   set: Set(3) { 5, 10, 15 },
+ * //=>   count: 5,
+ * //=>   string: '5,10,5,10,15'
+ * //=> }
  * ```
  *
  * @category Collections
@@ -366,15 +398,20 @@ export const toMultiple: {
  * {@link joinConcur} for direct use on iterables.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { map, pipe, reduce, toGrouped, toJoin, toMap } from 'lfi'
+ *
  * console.log(
  *   pipe(
  *     [`sloth`, `more sloth`, `sleep`, `some sloth`],
  *     map(string => [string.length, string]),
  *     reduce(toGrouped(toJoin(`,`), toMap())),
  *   ),
  * )
- * //=> Map(2) { 5 => 'sloth,sleep', 10 => 'more sloth,some sloth' }
+ * //=> Map(2) {
+ * //=>   5 => 'sloth,sleep',
+ * //=>   10 => 'more sloth,some sloth'
+ * //=> }
  * ```
  *
  * @category Collections
@@ -383,21 +420,24 @@ export const toMultiple: {
 export const toJoin: (separator: string) => Reducer<unknown, unknown, string>
 
 /**
- * Returns the result of concatenating the values of `iterable` to a string
- * where values are separated by `separator`.
+ * Returns the string concatenation of the values of `iterable`, separated by
+ * `separator`.
  *
- * Like `Array.prototype.join`, but for iterables, but does not treat `null`,
- * `undefined`, or `[]` specially.
+ * Like `Array.prototype.join`, but for iterables, except it does not treat
+ * `null`, `undefined`, or `[]` specially.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { join, map, pipe } from 'lfi'
+ *
  * console.log(
  *   pipe(
  *     [`sloth`, `more sloth`, `even more sloth`],
+ *     map(string => string.toUpperCase()),
  *     join(`, `),
  *   ),
  * )
- * //=> sloth, more sloth, even more sloth
+ * //=> SLOTH, MORE SLOTH, EVEN MORE SLOTH
  * ```
  *
  * @category Collections
@@ -409,21 +449,24 @@ export const join: {
 }
 
 /**
- * Returns a promise that resolves to the result of concatenating the values of
- * `asyncIterable` to a string where values are separated by `separator`.
+ * Returns a promise that resolves to the string concatenation of the values of
+ * `asyncIterable`, separated by `separator`.
  *
- * Like `Array.prototype.join`, but for async iterables, but does not treat
- * `null`, `undefined`, or `[]` specially.
+ * Like `Array.prototype.join`, but for async iterables, except it does not
+ * treat `null`, `undefined`, or `[]` specially.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { asAsync, joinAsync, mapAsync, pipe } from 'lfi'
+ *
  * console.log(
  *   await pipe(
  *     asAsync([`sloth`, `more sloth`, `even more sloth`]),
+ *     mapAsync(string => string.toUpperCase()),
  *     joinAsync(`, `),
  *   ),
  * )
- * //=> sloth, more sloth, even more sloth
+ * //=> SLOTH, MORE SLOTH, EVEN MORE SLOTH
  * ```
  *
  * @category Collections
@@ -437,21 +480,27 @@ export const joinAsync: {
 }
 
 /**
- * Returns a promise that resolves to the result of concatenating the values of
- * `concurIterable` to a string where values are separated by `separator`.
+ * Returns a promise that resolves to the string concatenation of the values of
+ * `concurIterable`, separated by `separator`.
  *
- * Like `Array.prototype.join`, but for concur iterables, but does not treat
- * `null`, `undefined`, or `[]` specially.
+ * Like `Array.prototype.join`, but for concur iterables, except it does not
+ * treat `null`, `undefined`, or `[]` specially.
+ *
+ * WARNING: The iteration order of concur iterables is not deterministic, so the
+ * values will be concatenated in an arbitrary order.
  *
  * @example
- * ```js
+ * ```js playground
+ * import { asConcur, joinConcur, mapConcur, pipe } from 'lfi'
+ *
  * console.log(
  *   await pipe(
  *     asConcur([`sloth`, `more sloth`, `even more sloth`]),
+ *     mapConcur(string => string.toUpperCase()),
  *     joinConcur(`, `),
  *   ),
  * )
- * //=> sloth, more sloth, even more sloth
+ * //=> SLOTH, MORE SLOTH, EVEN MORE SLOTH
  * ```
  *
  * @category Collections

src/operations/collections.d.ts

@@ -1,6 +1,8 @@
 import { themes as prismThemes } from 'prism-react-renderer'
 import type { Config, Plugin } from '@docusaurus/types'
 import type * as Preset from '@docusaurus/preset-classic'
+import type { TypeDocOptions as TypedocOptions } from 'typedoc'
+import type { PluginOptions as TypedocMarkdownPluginOptions } from 'docusaurus-plugin-typedoc'
 
 const githubOrganizationName = `TomerAberbach`
 const githubProjectName = `lfi`
@@ -74,7 +76,24 @@ const config: Config = {
         return postcssOptions
       },
     }),
-    `docusaurus-plugin-typedoc`,
+    [
+      `docusaurus-plugin-typedoc`,
+      {
+        name: `API`,
+        entryPoints: [`../src/index.d.ts`],
+        tsconfig: `../tsconfig.json`,
+        readme: `none`,
+        excludeInternal: true,
+        intentionallyNotExported: [
+          `Integer`,
+          `MaybePromiseLike`,
+          `NonNegativeInteger`,
+          `PositiveInteger`,
+        ],
+        indexFormat: `htmlTable`,
+        watch: Boolean(process.env.TYPEDOC_WATCH),
+      } satisfies Partial<TypedocOptions | TypedocMarkdownPluginOptions>,
+    ],
   ],
 
   themeConfig: {

website/docusaurus.config.ts

@@ -3,9 +3,11 @@
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
-    "start": "docusaurus start",
-    "build:docs": "docusaurus generate-typedoc",
-    "build:website": "docusaurus build",
+    "start:typedoc": "cross-env TYPEDOC_WATCH=true docusaurus generate-typedoc",
+    "start:docusaurus": "docusaurus start",
+    "start": "run-p start:*",
+    "build:typedoc": "docusaurus generate-typedoc",
+    "build:docusaurus": "docusaurus build",
     "build": "cross-env NODE_ENV=production run-s build:*",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
@@ -54,6 +56,7 @@
     "react-dom": "^18.3.1",
     "react-spinners": "^0.14.1",
     "spin-delay": "^2.0.1",
+    "typedoc": "^0.27.1",
     "typedoc-plugin-markdown": "^4.3.0",
     "workerboxjs": "^6.4.0"
   },