extant - npm Package Compare versions

Comparing version 1.0.21 to 2.0.0-alpha.0

extant.js

@@ -1,2 +0,7 @@
-module.exports = function () {
+// # Extant
+
+// Return the first non-null-like argument. Much like SQL COALESCE.
+
+//
+exports.coalesce = function () {
     for (var i = 0, I = arguments.length; i < I; i++) {
@@ -3,0 +8,0 @@ if (arguments[i] != null) {

package.json

 {
     "name":                 "extant",
-    "version":              "1.0.21",
+    "version":              "2.0.0-alpha.0",
     "description":
@@ -5,0 +5,0 @@

README.md

@@ -17,5 +17,137 @@ [![Actions Status](https://github.com/bigeasy/extant/workflows/Node%20CI/badge.svg)](https://github.com/bigeasy/extant/actions)
 
-
 ```
 npm install extant
 ```
+
+## Overview
+
+Extant is an implementation of SQL's COALESCE that I've used for some time to
+deal with the fact that JavaScript truthiness will treat `''` and `0` as true so
+the `||` operator can't always be used to create given or default one-liner.
+
+```javascript
+const { coalesce } = require('extant')
+
+function foo (count) {
+    count = coalesce(count, 1)
+    for (let i = 0; i < count; i++) {
+        console.log('hello')
+    }
+}
+
+foo()
+```
+
+We use the name "extant" on NPM because we want the first extant argument.
+
+## Follow Along
+
+This `README.md` is also a unit test using the
+[Proof](https://github.com/bigeasy/proof) unit test framework. We'll use the
+Proof `okay` function to assert out statements in the readme. A Proof unit test
+generally looks like this.
+
+```javascript
+require('proof')(4, async okay => {
+    okay('always okay')
+    okay(true, 'okay if true')
+    okay(1, 1, 'okay if equal')
+    okay({ value: 1 }, { value: 1 }, 'okay if deep strict equal')
+})
+```
+
+You can run this unit test yourself to see the output from the various
+code sections of the readme.
+
+```text
+git clone [e-mail]:bigeasy/duplicitous.git
+cd duplicitous
+npm install --no-package-lock --no-save
+node test/readme.t.js
+```
+
+## Usage
+
+The `'extant'` module exports a single `coalesce` function.
+
+```javascript
+const { coalesce } = require('extant')
+```
+
+Note that Extant is SQL's `COALESCE`. It returns the first non-null-like value,
+that is the first value that is not `== null`, which would be `null` or
+`undefined`. If there is no such argument it returns `null`.
+
+```javascript
+const maybe = null
+let maybeNot
+okay(coalesce(maybe, maybeNot, 1), 1, 'return first non-null value')
+okay(coalesce(maybe, maybeNot), null, 'return null')
+okay(coalesce(), null, 'no arguments is also null')
+```
+
+I've used this module for a long time to initialize function arguments.
+
+```javascript
+function increment (value, increment) {
+    return value + coalesce(increment, 1)
+}
+
+okay(increment(1, 2), 3, 'specify parameter')
+okay(increment(1), 2, 'use default parameter')
+```
+
+Although these days I'd probably just use the JavaScript default parameters
+syntax.
+
+```javascript
+function increment (value, increment = 1) {
+    return value + increment
+}
+
+okay(increment(1, 2), 3, 'specify default parameter')
+okay(increment(1), 2, 'use default default parameter')
+```
+
+And when Node.js 14 goes end-of-life I'll switch to `??`, but for now its still
+useful when initializing from named parameters when you want to preserve the
+original options array. You can always do this for simple cases.
+
+```javascript
+function increment (value, { increment = 1 } = {}) {
+    return value + increment
+}
+
+okay(increment(1, { increment: 2 }), 3, 'specify destructed named parameters')
+okay(increment(1), 2, 'use default destructed named parameters')
+```
+
+But, if you wanted keep the options object around for some reason `coalesce`
+still comes in handy.
+
+```javascript
+function increment (value, options = {}) {
+    return value + coalesce(options.increment, 1)
+}
+
+okay(increment(1, { increment: 2 }), 3, 'specify named arguments')
+okay(increment(1), 2, 'use default named arguments')
+```
+
+Really would take an example where your constructing an object that has a lot of
+options, or nested options. At that point the destructuring gets too verbose and
+`coalesce` is more appropriate.
+
+Another place where it is useful is variadic functions where destructed and
+default parameters are not an option.
+
+```javascript
+function adjuster (value, ...vargs) {
+    const increment = typeof vargs[0] == 'boolean' ? vargs.shift() : true
+    const by = coalesce(vargs.shift(), 1)
+    return value + (by * (increment ? 1 : -1))
+}
+
+okay(adjuster(1, true, 2), 3, 'increment variadic')
+okay(adjuster(1, false), 0, 'decrement variadic')
+```

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Fixed alerts

Trivial Package

Supply chain risk

Packages less than 10 lines of code are easily copied into your own project and may not warrant the additional supply chain risk of an external dependency.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

7028

increased by123.39%

Lines of code

11

increased by37.5%

Number of lines in readme file

153

increased by628.57%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Number of low quality alerts

1

increased byInfinity%

No dependency changes