rubico 2.6.6 → 2.7.0

package/set.js

@@ -96,6 +96,15 @@ const _set = function (obj, path, value) {
  * set(Promise.resolve({}), 'a', 1).then(console.log) // { a: 1 }
  * ```
  *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [all](/docs/all)
+ *  * [assign](/docs/assign)
+ *  * [get](/docs/get)
+ *  * [pick](/docs/pick)
+ *  * [omit](/docs/omit)
+ *  * [forEach](/docs/forEach)
+ *
  * @since 1.7.0
  */
 

package/some.js

@@ -40,7 +40,7 @@ const _some = function (collection, predicate) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Foldable = Array|Iterable|AsyncIterable|{ reduce: function }|Object
+ * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
  *
  * some(collection Foldable, predicate function) -> Promise|boolean
  *
@@ -48,7 +48,7 @@ const _some = function (collection, predicate) {
  * ```
  *
  * @description
- * Test a predicate concurrently across all items of a collection, returning true if any executions return truthy.
+ * Test a predicate concurrently across all items of a foldable, returning true if any executions return true.
  *
  * ```javascript [playground]
  * const isOdd = number => number % 2 == 1
@@ -58,7 +58,16 @@ const _some = function (collection, predicate) {
  * ) // true
  * ```
  *
- * The collection can be any iterable, async iterable, or object values iterable collection. Below is an example of `some` accepting an async generator as the collection.
+ * The following data types are considered to be foldables:
+ *  * `array`
+ *  * `set`
+ *  * `map`
+ *  * `generator`
+ *  * `async generator`
+ *  * `object with .reduce method`
+ *  * `object`
+ *
+ * `some` works for async generators.
  *
  * ```javascript [playground]
  * const toTodosUrl = id => 'https://jsonplaceholder.typicode.com/todos/' + id
@@ -98,6 +107,11 @@ const _some = function (collection, predicate) {
  * some(Promise.resolve([1, 2, 3, 4, 5]), n => n > 6).then(console.log) // false
  * ```
  *
+ * See also:
+ *  * [map](/docs/map)
+ *  * [every](/docs/every)
+ *  * [and](/docs/and)
+ *
  * @execution concurrent
  *
  * @muxing

package/switchCase.js

@@ -91,6 +91,12 @@ const curryArgs3 = require('./_internal/curryArgs3')
  * ]) // 1 + 2 + 3 == 6
  * ```
  *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [tap.if](/docs/tap.if)
+ *  * [tryCatch](/docs/tryCatch)
+ *  * [all](/docs/all)
+ *
  * @execution series
  */
 const switchCase = (...args) => {

package/tap.js

@@ -46,6 +46,13 @@ const _tap = function (args, f) {
  * ```javascript [playground]
  * tap(Promise.resolve(1), Promise.resolve(2), 3, console.log) // 1 2 3
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [compose](/docs/compose)
+ *  * [tap.if](/docs/tap.if)
+ *  * [switchCase](/docs/switchCase)
+ *  * [tryCatch](/docs/tryCatch)
  */
 const tap = function (...args) {
   const f = args.pop()
@@ -116,6 +123,13 @@ const _tapIf = function (predicate, f, args) {
  * tap.if(Promise.resolve(1), n => n < 5, console.log) // 1
  * tap.if(Promise.resolve(6), n => n < 5, console.log)
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [compose](/docs/compose)
+ *  * [tap](/docs/tap)
+ *  * [switchCase](/docs/switchCase)
+ *  * [tryCatch](/docs/tryCatch)
  */
 
 tap.if = function (...args) {

package/thunkify.js

@@ -22,6 +22,14 @@ const funcApply = require('./_internal/funcApply')
  *
  * console.log(thunkAdd12()) // 3
  * ```
+ *
+ * See also:
+ *  * [eq](/docs/eq)
+ *  * [always](/docs/always)
+ *  * [curry](/docs/curry)
+ *  * [__](/docs/__)
+ *  * [Transducer.map](/docs/Transducer.map)
+ *
  */
 const thunkify = (func, ...args) => function thunk() {
   if (areAnyValuesPromises(args)) {

package/transform.js

@@ -21,13 +21,11 @@ const _transform = function (collection, transducer, initialValue) {
  *
  * @synopsis
  * ```coffeescript [specscript]
- * type Foldable = Iterable|AsyncIterable|Object<value any>
+ * type Foldable = Array|Set|Map|Generator|AsyncGenerator|{ reduce: function }|Object
  *
  * type Reducer = (
  *   accumulator any,
  *   value any,
- *   indexOrKey number|string,
- *   f Foldable,
  * )=>(nextAccumulator Promise|any)
  *
  * type Transducer = Reducer=>Reducer
@@ -35,38 +33,94 @@ const _transform = function (collection, transducer, initialValue) {
  * type Semigroup =
  *   Array|String|Set|TypedArray|{ concat: function }|{ write: function }|Object
  *
- * type SemigroupResolver = (f Foldable)=>Promise|Semigroup
+ * type SemigroupResolver = (fold Foldable)=>Promise|Semigroup
  *
  * transform(
- *   f Foldable,
+ *   fold Foldable,
  *   transducer Transducer,
- *   initialValue? Semigroup|SemigroupResolver,
+ *   initial? Semigroup|SemigroupResolver,
  * ) -> result Promise|Semigroup
  *
  * transform(
  *   transducer Transducer,
- *   initialValue? Semigroup|SemigroupResolver,
- * )(f Foldable) -> result Promise|Semigroup
+ *   initial? Semigroup|SemigroupResolver,
+ * )(fold Foldable) -> result Promise|Semigroup
  * ```
  *
  * @description
- * Transforms a foldable into a semigroup. The type of transformation depends on the type of semigroup provided as the initial value. If the initial value is a function it is treated as a resolver of the semigroup.
+ * Transforms a foldable with [transducers](https://rubico.land/blog/transducers-crash-course-rubico-v2) into a semigroup.
  *
- * The following data types are considered foldables:
- *  * `iterable`
- *  * `async iterable`
- *  * `object`; only the values of the object are transformed
+ * The following data types are considered to be foldables:
+ *  * `array`
+ *  * `set`
+ *  * `map`
+ *  * `generator`
+ *  * `async generator`
+ *  * `object with .reduce method`
+ *  * `object`
  *
- * The following data types are considered semigroups:
- *  * `array`; concatenation defined by `result.concat(values)`
- *  * `string`; concatenation defined by `result + values`
- *  * `set`; concatenation defined by `result.add(...values)`
- *  * `binary`; concatenation defined by `result.set(prevResult); result.set(values, offset)`
- *  * `{ concat: function }`; concatenation defined by `result.concat(values)`
- *  * `{ write: function }`; concatenation defined by `result.write(item)`
- *  * `object`; concatenation defined by `({ ...result, ...values })`
+ * Transducers, due to their lazy nature, don't have knowledge of the foldable they are transforming. As such, the transducer signature for all foldables is the same:
  *
- * `transform` can transform any of the above collections into any of the other above collections.
+ * ```coffeescript [specscript]
+ * type Reducer = (
+ *   accumulator any,
+ *   value any,
+ * )=>(nextAccumulator Promise|any)
+ *
+ * type Transducer = Reducer=>Reducer
+ * ```
+ *
+ * The following data types are considered to be semigroups:
+ *  * `array`
+ *  * `string`
+ *  * `set`
+ *  * `binary`
+ *  * `{ concat: function }`
+ *  * `{ write: function }`
+ *  * `object`
+ *
+ * The concatenation operation changes depending on the provided semigroup:
+ *
+ * If the semigroup is an array, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = accumulator.concat(values)
+ * ```
+ *
+ * If the semigroup is a string, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = accumulator + values
+ * ```
+ *
+ * If the semigroup is a set, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = accumulator.add(...values)
+ * ```
+ *
+ * If the semigroup is binary, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = new accumulator.constructor(accumulator.length + values.length)
+ * nextAccumulator.set(accumulator)
+ * nextAccumulator.set(values, accumulator.length)
+ * ```
+ *
+ * If the semigroup is an object with a `.concat` method, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = accumulator
+ * accumulator.concat(values)
+ * ```
+ *
+ * If the semigroup is an object with a `.write` method, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = accumulator
+ * accumulator.write(values)
+ * ```
+ *
+ * If the semigroup is a plain object, concatenation is defined as:
+ * ```javascript
+ * nextAccumulator = ({ ...accumulator, ...values })
+ * ```
+ *
+ * `transform` transforms numbers from an array into another array.
  *
  * ```javascript [playground]
  * const square = number => number ** 2
@@ -80,22 +134,22 @@ const _transform = function (collection, transducer, initialValue) {
  *
  * // transform arrays into arrays
  * console.log(
- *   transform(squaredOdds, [])([1, 2, 3, 4, 5])
+ *   transform([1, 2, 3, 4, 5], squaredOdds, [])
  * ) // [1, 9, 25]
  *
  * // transform arrays into strings
  * console.log(
- *   transform(squaredOdds, '')([1, 2, 3, 4, 5])
+ *   transform([1, 2, 3, 4, 5], squaredOdds, '')
  * ) // '1925'
  *
  * // transform arrays into sets
  * console.log(
- *   transform(squaredOdds, new Set())([1, 2, 3, 4, 5])
+ *   transform([1, 2, 3, 4, 5], squaredOdds, new Set())
  * ) // Set (3) { 1, 9, 25 }
  *
  * // transform arrays into typed arrays
  * console.log(
- *   transform(squaredOdds, new Uint8Array())([1, 2, 3, 4, 5]),
+ *   transform([1, 2, 3, 4, 5], squaredOdds, new Uint8Array()),
  * ) // Uint8Array(3) [ 1, 9, 25 ]
  * ```
  *
@@ -111,7 +165,7 @@ const _transform = function (collection, transducer, initialValue) {
  *   },
  * }
  *
- * transform(Transducer.map(square), Stdout)([1, 2, 3, 4, 5])
+ * transform([1, 2, 3, 4, 5], Transducer.map(square), Stdout)
  * // 1
  * // 4
  * // 9
@@ -149,16 +203,38 @@ const _transform = function (collection, transducer, initialValue) {
  * )
  * ```
  *
+ * If the initial value is a function it is treated as a resolver of the semigroup. The resolver may be asynchronous.
+ *
+ * ```javascript [playground]
+ * const promise = transform(
+ *   [1, 2, 3, 4, 5],
+ *   Transducer.map(number => number ** 2),
+ *   async () => ['a'],
+ * )
+ *
+ * promise.then(console.log)
+ * ```
+ *
  * Any promises passed in argument position are resolved for their values before further execution. This only applies to the eager version of the API.
  *
  * ```javascript [playground]
- * transform(
+ * const promise = transform(
  *   Promise.resolve([1, 2, 3, 4, 5]),
  *   Transducer.map(n => n ** 2),
  *   [],
- * ).then(console.log) // [1, 4, 9, 16, 25]
+ * )
+ *
+ * promise.then(console.log) // [1, 4, 9, 16, 25]
  * ```
  *
+ * See also:
+ *  * [forEach](/docs/forEach)
+ *  * [map](/docs/map)
+ *  * [filter](/docs/filter)
+ *  * [reduce](/docs/reduce)
+ *  * [flatMap](/docs/flatMap)
+ *  * [some](/docs/some)
+ *
  * @execution series
  *
  * @transducing

package/tryCatch.js

@@ -75,6 +75,11 @@ const _tryCatch = function (tryer, catcher, args) {
  *   console.error(`${a} + ${b} + ${c}: ${error.message}`)
  * })
  * ```
+ *
+ * See also:
+ *  * [pipe](/docs/pipe)
+ *  * [switchCase](/docs/switchCase)
+ *  * [all](/docs/all)
  */
 
 const tryCatch = function (...args) {

package/x/append.js

@@ -35,6 +35,9 @@ const isArray = require('../_internal/isArray')
  * }
  * ```
  *
+ * See also:
+ *  * [callProp](/docs/callProp)
+ *
  * @since 1.7.3
  */
 

package/x/callProp.js

@@ -15,6 +15,11 @@
  * const priceRoundedDown = callProp('toFixed', 2)(5.992)
  * console.log('priceRoundedDown:', priceRoundedDown) // '5.99'
  * ```
+ *
+ * See also:
+ *  * [append](/docs/append)
+ *  * [defaultsDeep](/docs/defaultsDeep)
+ *
  */
 const callProp = (property, ...args) => function callingProp(object) {
   return object[property](...args)

package/x/defaultsDeep.d.ts

@@ -26,11 +26,11 @@ export = defaultsDeep;
  * })
  *
  * console.log(defaultUser({
- *   name: 'George',
+ *   name: 'John',
  *   images: [{ url: 'https://via.placeholder.com/150/0000FF/808080%20?Text=Digital.com' }],
  * }))
  * // {
- * //   name: 'George',
+ * //   name: 'John',
  * //   images: [
  * //    { url: 'https://via.placeholder.com/150/0000FF/808080%20?Text=Digital.com' },
  * //    { url: 'https://via.placeholder.com/150' },

package/x/defaultsDeep.js

@@ -91,11 +91,11 @@ const objectDefaultsDeepFromObject = function (object, defaultObject) {
  * })
  *
  * console.log(defaultUser({
- *   name: 'George',
+ *   name: 'John',
  *   images: [{ url: 'https://via.placeholder.com/150/0000FF/808080%20?Text=Digital.com' }],
  * }))
  * // {
- * //   name: 'George',
+ * //   name: 'John',
  * //   images: [
  * //    { url: 'https://via.placeholder.com/150/0000FF/808080%20?Text=Digital.com' },
  * //    { url: 'https://via.placeholder.com/150' },
@@ -103,6 +103,11 @@ const objectDefaultsDeepFromObject = function (object, defaultObject) {
  * //   ],
  * // }
  * ```
+ *
+ * See also:
+ *  * [callProp](/docs/callProp)
+ *  * [differenceWith](/docs/differenceWith)
+ *
  */
 const defaultsDeep = defaultCollection => function defaulting(value) {
   if (isArray(value) && isArray(defaultCollection)) {

package/x/differenceWith.js

@@ -96,6 +96,11 @@ const differenceWithArray = function (comparator, allValues, array) {
  *   differenceWith(isDeepEqual, [{ a: 1 }, { b: 2 }, { c: 3 }])([{ b: 2 }]),
  * ) // [{ a: 1 }, { c: 3 }]
  * ```
+ *
+ * See also:
+ *  * [defaultsDeep](/docs/defaultsDeep)
+ *  * [filterOut](/docs/filterOut)
+ *
  */
 const differenceWith = (
   comparator, allValues,

package/x/find.d.ts

@@ -23,12 +23,12 @@ export = find;
  * const users = [
  *   { name: 'John', age: 16 },
  *   { name: 'Jill', age: 32 },
- *   { name: 'George', age: 51 },
+ *   { name: 'John', age: 51 },
  * ]
  *
  * console.log(
  *   find(user => user.age > 50)(users),
- * ) // { name: 'George', age: 51 }
+ * ) // { name: 'John', age: 51 }
  * ```
  */
 declare function find(predicate: any): (value: any) => any;

package/x/find.js

@@ -30,12 +30,12 @@ const asyncIteratorFind = require('../_internal/asyncIteratorFind')
  * const users = [
  *   { name: 'John', age: 16 },
  *   { name: 'Jill', age: 32 },
- *   { name: 'George', age: 51 },
+ *   { name: 'John', age: 51 },
  * ]
  *
  * console.log(
  *   find(user => user.age > 50)(users),
- * ) // { name: 'George', age: 51 }
+ * ) // { name: 'John', age: 51 }
  * ```
  */
 const find = predicate => function finding(value) {

package/x/groupBy.d.ts

@@ -24,13 +24,13 @@ export = groupBy;
  *
  * console.log(
  *   groupBy('age')([
- *     { name: 'George', age: 22 },
+ *     { name: 'John', age: 22 },
  *     { name: 'Jane', age: 22 },
  *     { name: 'Henry', age: 23 },
  *   ]),
  * )
  * // Map {
- * //   22 => [{ name: 'George', age: 22 }, { name: 'Jane', age: 22 }],
+ * //   22 => [{ name: 'John', age: 22 }, { name: 'Jane', age: 22 }],
  * //   23 => [{ name: 'Henry', age: 23 }],
  * // }
  * ```

package/x/groupBy.js

@@ -59,13 +59,13 @@ const groupByResolver = resolver => function groupByResolverReducer(
  *
  * console.log(
  *   groupBy('age')([
- *     { name: 'George', age: 22 },
+ *     { name: 'John', age: 22 },
  *     { name: 'Jane', age: 22 },
  *     { name: 'Henry', age: 23 },
  *   ]),
  * )
  * // Map {
- * //   22 => [{ name: 'George', age: 22 }, { name: 'Jane', age: 22 }],
+ * //   22 => [{ name: 'John', age: 22 }, { name: 'Jane', age: 22 }],
  * //   23 => [{ name: 'Henry', age: 23 }],
  * // }
  * ```

package/x/pluck.d.ts

@@ -22,14 +22,14 @@ export = pluck;
  * import pluck from 'https://unpkg.com/rubico/dist/x/pluck.es.js'
  *
  * const users = [
- *   { name: 'George', age: 33 },
+ *   { name: 'John', age: 33 },
  *   { name: 'Jane', age: 51 },
  *   { name: 'Jim', age: 22 },
  * ]
  *
  * const usernames = pluck(users, 'name')
  *
- * console.log(usernames) // ['George', 'Jane', 'Jim']
+ * console.log(usernames) // ['John', 'Jane', 'Jim']
  * ```
  */
 declare function pluck(...args: any[]): any;

package/x/pluck.js

@@ -25,14 +25,14 @@ const get = require('../get')
  * import pluck from 'https://unpkg.com/rubico/dist/x/pluck.es.js'
  *
  * const users = [
- *   { name: 'George', age: 33 },
+ *   { name: 'John', age: 33 },
  *   { name: 'Jane', age: 51 },
  *   { name: 'Jim', age: 22 },
  * ]
  *
  * const usernames = pluck(users, 'name')
  *
- * console.log(usernames) // ['George', 'Jane', 'Jim']
+ * console.log(usernames) // ['John', 'Jane', 'Jim']
  * ```
  */
 const pluck = function (...args) {

package/x/unionWith.test.js

@@ -102,14 +102,14 @@ describe('unionWith', () => {
       assert.deepEqual(result, new Set([1, 2, 3]))
     })
     it('predicate item => item.name; values Set<[{...}, {...}, {...}]>; result Promise|<Set<[{...}, {...}]>>', async () => {
-      const people = new Set([{ name: 'George' }, { name: 'George' }, { name: 'Jim' }])
+      const people = new Set([{ name: 'John' }, { name: 'John' }, { name: 'Jim' }])
       const result = unionWith((personA, personB) => personA.name === personB.name)(people)
-      assert.deepEqual(result, new Set([{ name: 'George' }, { name: 'Jim' }]))
+      assert.deepEqual(result, new Set([{ name: 'John' }, { name: 'Jim' }]))
       {
         const p = unionWith(async (personA, personB) => personA.name === personB.name)(people)
         assert(p instanceof Promise)
         const result = await p
-        assert.deepEqual(result, new Set([{ name: 'George' }, { name: 'Jim' }]))
+        assert.deepEqual(result, new Set([{ name: 'John' }, { name: 'Jim' }]))
       }
     })
     it('predicate () => false; values Set<[[1], 2, [3]]>; result Set<[1, 2, 3]>', async () => {