rubico 2.6.6 → 2.7.1

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

@@ -22,6 +22,8 @@ const _tap = function (args, f) {
  *
  * @synopsis
  * ```coffeescript [specscript]
+ * args Array<any>
+ *
  * tap(...args, f function) -> Promise|args[0]
  * tap(f function)(...args) -> Promise|args[0]
  * ```
@@ -46,6 +48,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()
@@ -94,6 +103,8 @@ const _tapIf = function (predicate, f, args) {
  *
  * @synopsis
  * ```coffeescript [specscript]
+ * args Array<any>
+ *
  * tap.if(...args, predicate function, f function) -> Promise|args[0]
  * tap.if(predicate function, f function)(...args) -> Promise|args[0]
  * ```
@@ -116,6 +127,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

@@ -9,11 +9,13 @@ const funcApply = require('./_internal/funcApply')
  *
  * @synopsis
  * ```coffeescript [specscript]
- * thunkify(func function, ...args) -> thunk ()=>func(...args)
+ * argsWithPromises Array<Promise|any>
+ *
+ * thunkify(func function, ...argsWithPromises) -> thunk function
  * ```
  *
  * @description
- * Create a thunk function from another function and any number of arguments. The thunk function takes no arguments, and when called, executes the other function with the provided arguments. The other function is said to be "thunkified".
+ * Create a thunk function from an original function and any number of arguments. A thunk function takes no arguments, and when called, executes the original function with the previously provided arguments. The original function is said to be "thunkified".
  *
  * ```javascript [playground]
  * const add = (a, b) => a + b
@@ -22,12 +24,35 @@ const funcApply = require('./_internal/funcApply')
  *
  * console.log(thunkAdd12()) // 3
  * ```
+ *
+ * If any promises are passed as arguments, they are resolved before being applied to the original function, and `thunkify` returns a promise of the thunk function.
+ *
+ * ```javascript [playground]
+ * const add = (a, b) => a + b
+ *
+ * const promise = thunkify(add, Promise.resolve(1), 2)
+ * const thunkAdd12 = await promise
+ *
+ * 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() {
+const thunkify = function (func, ...args) {
   if (areAnyValuesPromises(args)) {
-    return promiseAll(args).then(curry2(funcApply, func, __))
+    return promiseAll(args).then(resolvedArgs => function thunk() {
+      return func(...resolvedArgs)
+    })
+  }
+  return function thunk() {
+    return func(...args)
   }
-  return func(...args)
 }
 
 module.exports = thunkify

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 () => {