rubico 2.2.3 → 2.3.1

package/monad/Instance.js

@@ -1,14 +1,8 @@
-/* rubico v1.5.0
- * https://github.com/a-synchronous/rubico
- * (c) 2019-2020 Richard Tong
- * rubico may be freely distributed under the MIT license.
- */
-
-'use strict'
-
 const symbolIterator = Symbol.iterator
 
-/*
+const symbolAsyncIterator = Symbol.asyncIterator
+
+/**
  * @name Instance
  *
  * @synopsis
@@ -17,47 +11,192 @@ const symbolIterator = Symbol.iterator
  * @catchphrase
  * Type checking
  */
-const Instance = function(value) {
-  this.value = value
-}
+class Instance {
+  constructor(value) {
+    this.value = value
+  }
+
+  /**
+   * @name Instance.prototype.chain
+   *
+   * @synopsis
+   * <A any, B any>new Instance(x A).chain(f A=>Instance<B>) -> Instance<B>
+   *
+   * @description
+   * For associativity
+   *
+   * @example
+   * const inst = new Instance(3)
+   * console.log(
+   *   inst.chain(number => new Instance(number ** 2))
+   * ) // Instance { 9 }
+   */
+  chain(func) {
+    return func(this.value)
+  }
+
+  /**
+   * @name Instance.prototype.map
+   *
+   * @synopsis
+   * <A any, B any>new Instance(value A).map(func A=>B) -> Instance<B>
+  map(func) {
+    return new Instance(func(this.value))
+  } */
+
+
+  /**
+   * @name Instance.prototype.is
+   *
+   * @synopsis
+   * new Instance(x any).is(ctor function) -> boolean
+   */
+  is(ctor) {
+    const x = this.value
+    return x != null && x.constructor == ctor
+  }
+
+
+  /**
+   * @name Instance.prototype.isString
+   *
+   * @synopsis
+   * new Instance(x any).isString() -> boolean
+   */
+  isString() {
+    const x = this.value
+    return typeof x == 'string' || (x != null && x.constructor == String)
+  }
+
+  /**
+   * @name Instance.prototype.isNumber
+   *
+   * @synopsis
+   * new Instance(x any).isNumber() -> boolean
+   */
+  isNumber() {
+    const x = this.value
+    return typeof x == 'number' || (x != null && x.constructor == Number)
+  }
+
+  /**
+   * @name Instance.prototype.isArray
+   *
+   * @synopsis
+   * new Instance(x any).isArray() -> boolean
+   */
+  isArray() {
+    return Array.isArray(this.value)
+  }
+
+  /**
+   * @name Instance.prototype.isObject
+   *
+   * @synopsis
+   * new Instance(x any).isObject() -> boolean
+   */
+  isObject() {
+    const x = this.value
+    return x != null && x.constructor == Object
+  }
+
+  /**
+   * @name Instance.prototype.isSet
+   *
+   * @synopsis
+   * new Instance(x any).isSet() -> boolean
+   */
+  isSet() {
+    const x = this.value
+    return x != null && x.constructor == Set
+  }
+
+  /**
+   * @name Instance.prototype.isMap
+   *
+   * @synopsis
+   * new Instance(x any).isMap() -> boolean
+   */
+  isMap() {
+    const x = this.value
+    return x != null && x.constructor == Map
+  }
+
+  /**
+   * @name Instance.prototype.isIterable
+   *
+   * @synopsis
+   * new Instance(value any).isIterable() -> boolean
+   */
+  isIterable() {
+    const value = this.value
+    return value != null && typeof value[symbolIterator] == 'function'
+  }
+
+  /**
+   * @name Instance.prototype.isAsyncIterable
+   *
+   * @synopsis
+   * new Instance(value any).isAsyncIterable() -> boolean
+   */
+  isAsyncIterable() {
+    const value = this.value
+    return value != null && typeof value[symbolAsyncIterator] == 'function'
+  }
+
+  /**
+   * @name Instance.prototype.isFunction
+   *
+   * @synopsis
+   * new Instance(x any).isFunction() -> boolean
+   */
+  isFunction() {
+    return typeof this.value == 'function'
+  }
+
+  /**
+   * @name Instance.prototype.isReadable
+   *
+   * @synopsis
+   * new Instance(x any).isReadable() -> boolean
+   */
+  isReadable() {
+    const x = this.value
+    return x != null && typeof x.read == 'function'
+  }
+
+  /**
+   * @name Instance.prototype.isWritable
+   *
+   * @synopsis
+   * new Instance(x any).isWritable() -> boolean
+   */
+  isWritable() {
+    const x = this.value
+    return x != null && typeof x.write == 'function'
+  }
+
+  /**
+   * @name Instance.prototype.isPromise
+   *
+   * @synopsis
+   * new Instance(x any).isPromise() -> boolean
+   */
+  isPromise() {
+    const x = this.value
+    return x != null && typeof x.then == 'function'
+  }
+
+  /**
+   * @name Instance.prototype.isTypedArray
+   *
+   * @synopsis
+   * new Instance(x any).isTypedArray() -> boolean
+   */
+  isTypedArray() {
+    return ArrayBuffer.isView(this.value)
+  }
 
-/**
- * @name Instance.prototype.map
- *
- * @synopsis
- * <A any, B any>new Instance(value A).map(func A=>B) -> Instance<B>
-Instance.prototype.map = function(func) {
-  return new Instance(func(this.value))
-} */
-
-/**
- * @name Instance.prototype.join
- *
- * @synopsis
- * <T any>new Instance(Instance<T>).join() -> Instance<T>
- *
- * <T any>new Instance(value T).join() -> value T
-Instance.prototype.join = function() {
-  return this.value
-} */
-
-/**
- * @name Instance.prototype.chain
- *
- * @synopsis
- * <A any, B any>new Instance(x A).chain(f A=>Instance<B>) -> Instance<B>
- *
- * @catchphrase
- * For associativity
- *
- * @example
- * const inst = new Instance(3)
- * console.log(
- *   inst.chain(number => new Instance(number ** 2))
- * ) // Instance { 9 }
- */
-Instance.prototype.chain = function(f) {
-  return f(this.value)
 }
 
 /*
@@ -81,17 +220,6 @@ Instance.isInstance = x => x != null
  */
 Instance.is = (x, constructor) => x != null && x.constructor == constructor
 
-/*
- * @name Instance.prototype.is
- *
- * @synopsis
- * new Instance(x any).is(constructor function) -> boolean
- */
-Instance.prototype.is = function(constructor) {
-  const x = this.value
-  return x != null && x.constructor == constructor
-}
-
 /*
  * @name Instance.isString
  *
@@ -101,17 +229,6 @@ Instance.prototype.is = function(constructor) {
 Instance.isString = x => (
   typeof x == 'string' || (x != null && x.constructor == String))
 
-/*
- * @name Instance.prototype.isString
- *
- * @synopsis
- * new Instance(x any).isString() -> boolean
- */
-Instance.prototype.isString = function() {
-  const x = this.value
-  return typeof x == 'string' || (x != null && x.constructor == String)
-}
-
 /*
  * @name Instance.isNumber
  *
@@ -121,17 +238,6 @@ Instance.prototype.isString = function() {
 Instance.isNumber = x => (
   typeof x == 'number' || (x != null && x.constructor == Number))
 
-/*
- * @name Instance.prototype.isNumber
- *
- * @synopsis
- * new Instance(x any).isNumber() -> boolean
- */
-Instance.prototype.isNumber = function() {
-  const x = this.value
-  return typeof x == 'number' || (x != null && x.constructor == Number)
-}
-
 /*
  * @name Instance.isArray
  *
@@ -140,16 +246,6 @@ Instance.prototype.isNumber = function() {
  */
 Instance.isArray = Array.isArray
 
-/*
- * @name Instance.prototype.isArray
- *
- * @synopsis
- * new Instance(x any).isArray() -> boolean
- */
-Instance.prototype.isArray = function() {
-  return Array.isArray(this.value)
-}
-
 /*
  * @name Instance.isObject
  *
@@ -158,17 +254,6 @@ Instance.prototype.isArray = function() {
  */
 Instance.isObject = x => x != null && x.constructor == Object
 
-/*
- * @name Instance.prototype.isObject
- *
- * @synopsis
- * new Instance(x any).isObject() -> boolean
- */
-Instance.prototype.isObject = function() {
-  const x = this.value
-  return x != null && x.constructor == Object
-}
-
 /*
  * @name Instance.isSet
  *
@@ -177,17 +262,6 @@ Instance.prototype.isObject = function() {
  */
 Instance.isSet = x => x != null && x.constructor == Set
 
-/*
- * @name Instance.prototype.isSet
- *
- * @synopsis
- * new Instance(x any).isSet() -> boolean
- */
-Instance.prototype.isSet = function() {
-  const x = this.value
-  return x != null && x.constructor == Set
-}
-
 /*
  * @name Instance.isMap
  *
@@ -196,17 +270,6 @@ Instance.prototype.isSet = function() {
  */
 Instance.isMap = x => x != null && x.constructor == Map
 
-/*
- * @name Instance.prototype.isMap
- *
- * @synopsis
- * new Instance(x any).isMap() -> boolean
- */
-Instance.prototype.isMap = function() {
-  const x = this.value
-  return x != null && x.constructor == Map
-}
-
 /*
  * @name Instance.isIterable
  *
@@ -217,19 +280,6 @@ Instance.isIterable = function isIterable(value) {
   return value != null && typeof value[symbolIterator] == 'function'
 }
 
-/*
- * @name Instance.prototype.isIterable
- *
- * @synopsis
- * new Instance(value any).isIterable() -> boolean
- */
-Instance.prototype.isIterable = function isIterable() {
-  const value = this.value
-  return value != null && typeof value[symbolIterator] == 'function'
-}
-
-const symbolAsyncIterator = Symbol.asyncIterator
-
 /*
  * @name Instance.isAsyncIterable
  *
@@ -240,17 +290,6 @@ Instance.isAsyncIterable = function isAsyncIterable(value) {
   return value != null && typeof value[symbolAsyncIterator] == 'function'
 }
 
-/*
- * @name Instance.prototype.isAsyncIterable
- *
- * @synopsis
- * new Instance(value any).isAsyncIterable() -> boolean
- */
-Instance.prototype.isAsyncIterable = function() {
-  const value = this.value
-  return value != null && typeof value[symbolAsyncIterator] == 'function'
-}
-
 /*
  * @name Instance.isFunction
  *
@@ -259,16 +298,6 @@ Instance.prototype.isAsyncIterable = function() {
  */
 Instance.isFunction = x => typeof x == 'function'
 
-/*
- * @name Instance.prototype.isFunction
- *
- * @synopsis
- * new Instance(x any).isFunction() -> boolean
- */
-Instance.prototype.isFunction = function() {
-  return typeof this.value == 'function'
-}
-
 /*
  * @name Instance.isReadable
  *
@@ -277,17 +306,6 @@ Instance.prototype.isFunction = function() {
  */
 Instance.isReadable = x => x != null && typeof x.read == 'function'
 
-/*
- * @name Instance.prototype.isReadable
- *
- * @synopsis
- * new Instance(x any).isReadable() -> boolean
- */
-Instance.prototype.isReadable = function() {
-  const x = this.value
-  return x != null && typeof x.read == 'function'
-}
-
 /*
  * @name Instance.isWritable
  *
@@ -296,17 +314,6 @@ Instance.prototype.isReadable = function() {
  */
 Instance.isWritable = x => x != null && typeof x.write == 'function'
 
-/*
- * @name Instance.prototype.isWritable
- *
- * @synopsis
- * new Instance(x any).isWritable() -> boolean
- */
-Instance.prototype.isWritable = function() {
-  const x = this.value
-  return x != null && typeof x.write == 'function'
-}
-
 /*
  * @name Instance.isPromise
  *
@@ -315,17 +322,6 @@ Instance.prototype.isWritable = function() {
  */
 Instance.isPromise = x => x != null && typeof x.then == 'function'
 
-/*
- * @name Instance.prototype.isPromise
- *
- * @synopsis
- * new Instance(x any).isPromise() -> boolean
- */
-Instance.prototype.isPromise = function() {
-  const x = this.value
-  return x != null && typeof x.then == 'function'
-}
-
 /*
  * @name Instance.isTypedArray
  *
@@ -334,18 +330,4 @@ Instance.prototype.isPromise = function() {
  */
 Instance.isTypedArray = ArrayBuffer.isView
 
-// Instance.isTypedArrayCandidate0 = x => x != null && typedArrayConstructorNames.has(x.constructor.name)
-
-// Instance.isTypedArrayCandidate1 = ArrayBuffer.isView
-
-/*
- * @name Instance.prototype.isTypedArray
- *
- * @synopsis
- * new Instance(x any).isTypedArray() -> boolean
- */
-Instance.prototype.isTypedArray = function() {
-  return ArrayBuffer.isView(this.value)
-}
-
 module.exports = Instance

package/not.d.ts

@@ -0,0 +1,34 @@
+export = not;
+/**
+ * @name not
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * not(value boolean) -> negated boolean
+ *
+ * not(...args, predicate function) -> negated boolean
+ *
+ * not(predicate function)(...args) -> negated boolean
+ * ```
+ *
+ * @description
+ * Negate a value like the [logical NOT (`!`)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_NOT) operator.
+ *
+ * ```javascript [playground]
+ * const myObj = { a: 1 }
+ *
+ * console.log(not('a' in myObj)) // false
+ * console.log(not('b' in myObj)) // true
+ * ```
+ *
+ * If provided a predicate function, `not` returns a logically inverted predicate that returns true everywhere the original predicate would have returned false.
+ *
+ * ```javascript [playground]
+ * const isOdd = number => number % 2 == 1
+ *
+ * console.log(
+ *   not(isOdd)(3),
+ * ) // false
+ * ```
+ */
+declare function not(...args: any[]): any;

package/omit.d.ts

@@ -0,0 +1,50 @@
+export = omit;
+/**
+ * @name omit
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * omit(paths Array<string>)(source Object) -> omitted Object
+ *
+ * omit(source Object, paths Array<string>) -> omitted Object
+ * ```
+ *
+ * @description
+ * Create a new object by excluding provided paths on a source object.
+ *
+ * ```javascript [playground]
+ * console.log(
+ *   omit({ _id: '1', name: 'George' }, ['_id']),
+ * ) // { name: 'George' }
+ * ```
+ *
+ * `omit` supports three types of path patterns for nested property access
+ *
+ *  * dot delimited - `'a.b.c'`
+ *  * bracket notation - `'a[0].value'`
+ *  * an array of keys or indices - `['a', 0, 'value']`
+ *
+ * ```javascript [playground]
+ * console.log(
+ *   omit(['a.b.d'])({
+ *     a: {
+ *       b: {
+ *         c: 'hello',
+ *         d: 'goodbye',
+ *       },
+ *     },
+ *   }),
+ * ) // { a: { b: { c: 'hello' } } }
+ * ```
+ *
+ * Compose `omit` inside a `pipe` with its tacit API
+ *
+ * ```javascript [playground]
+ * pipe({ a: 1, b: 2, c: 3 }, [
+ *   map(number => number ** 2),
+ *   omit(['a', 'b']),
+ *   console.log, // { c: 9 }
+ * ])
+ * ```
+ */
+declare function omit(arg0: any, arg1: any): any;

package/or.d.ts

@@ -0,0 +1,43 @@
+export = or;
+/**
+ * @name or
+ *
+ * @synopsis
+ * ```coffeescript [specscript]
+ * or(values Array<boolean>) -> result boolean
+ *
+ * or(...args, predicatesOrValues Array<function|boolean>) -> Promise|boolean
+ *
+ * or(predicatesOrValues Array<function|boolean>)(...args) -> Promise|boolean
+ * ```
+ *
+ * @description
+ * Tests an array of boolean values, returning true if any boolean values are truthy.
+ *
+ * ```javascript [playground]
+ * const oneIsLessThanZero = 1 < 0
+ * const oneIsGreaterThanTwo = 1 > 2
+ * const threeIsNotEqualToThree = 3 !== 3
+ *
+ * console.log(
+ *   or([oneIsLessThanZero, oneIsGreaterThanTwo, threeIsNotEqualToThree]),
+ * ) // false
+ * ```
+ *
+ * If any values in the array are synchronous or asynchronous predicate functions, `or` takes another argument to test concurrently against the predicate functions, returning true if any array values or resolved values from the predicates are truthy.
+ *
+ * ```javascript [playground]
+ * const isOdd = number => number % 2 == 1
+ *
+ * const isEven = number => number % 2 == 0
+ *
+ * console.log(
+ *   or([isOdd, isEven])(0),
+ * ) // true
+ * ```
+ *
+ * @execution series
+ *
+ * @note ...args slows down here by an order of magnitude
+ */
+declare function or(...args: any[]): any;