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