mongodb-pipelinejs - npm Package Compare versions

Comparing version 0.0.2 to 0.0.3

package.json

 {
   "name": "mongodb-pipelinejs",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Use short and sweet JS syntax (instead of JSON) to compose and cleanly format MongoDB aggregations.",
@@ -13,30 +13,34 @@ "main": "index.js",
   "devDependencies": {
-    "@babel/cli": "^7.22.10",
-    "@babel/core": "^7.22.11",
-    "@babel/plugin-proposal-class-properties": "^7.18.6",
-    "@babel/plugin-proposal-decorators": "^7.22.10",
-    "@babel/plugin-proposal-object-rest-spread": "^7.20.7",
-    "@babel/preset-env": "^7.22.10",
-    "@babel/preset-typescript": "^7.22.11",
+    "@jsdoc/salty": "^0.2.7",
     "@types/jest": "^29.5.4",
     "@types/node": "^20.5.6",
-    "eslint": "^8.48.0",
+    "@typescript-eslint/eslint-plugin": "5.62.0",
+    "@typescript-eslint/parser": "^5.0.0",
+    "better-docs": "~2.7.3",
+    "eslint": "^8.0.0",
     "eslint-plugin-jsdoc": "^42.0.0",
     "jest": "^29.6.4",
-    "jsdoc-babel": "^0.5.0",
-    "jsdoc-to-markdown": "^8.0.0",
+    "jsdoc": "^3.2.2",
+    "prop-types": "^15.5.9",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    "react-frame-component": "^5.2.6",
+    "terser": "^5.26.0",
     "ts-jest": "^29.1.1",
     "ts-node": "^10.9.1",
-    "typescript": "^5.2.2"
+    "typescript": "~5.1.0"
   },
   "scripts": {
-    "build": "tsc --build",
-    "docs": "jsdoc2md --files ./index.ts -t .reference.hbs.md --configure ./jsdoc2md.json > REFERENCE.md",
+    "build": "tsc --build && terser index.js -o min.js",
+    "docs": "jsdoc -c jsdoc.json -d docs index.ts",
+    "lint": "eslint --fix --ext .ts .",
     "test": "jest",
-    "watch": "nodemon --exec yarn build"
+    "test:coverage": "jest --coverage",
+    "watch": "nodemon -w index.ts -x yarn docs"
   },
   "files": [
     "index.js",
-    "index.d.js"
+    "index.d.js",
+    "min.js"
   ]
 }

README.md

@@ -0,8 +1,96 @@
+[![view on npm](http://img.shields.io/npm/v/mongodb-pipelinejs.svg)](https://www.npmjs.org/package/mongodb-pipelinejs)
+[![npm module downloads](http://img.shields.io/npm/dt/mongodb-pipelinejs.svg)](https://www.npmjs.org/package/mongodb-pipelinejs)
+![test workflow](https://github.com/speedytwenty/mongodb-pipelinejs/actions/workflows/test.yml/badge.svg?event=push)
+[![Coverage Status](https://coveralls.io/repos/github/speedytwenty/mongodb-pipelinejs/badge.svg?branch=main)](https://coveralls.io/github/speedytwenty/mongodb-pipelinejs?branch=main)
+[![Maintainability](https://codeclimate.com/github/speedytwenty/mongodb-pipelinejs/badges/gpa.svg)](https://codeclimate.com/github/speedytwenty/mongodb-pipelinejs/maintainability)
+
 # MongoDB PipelineJS
 
-_Aggregation Syntax for Javascript_; Use Javascript syntax—instead of JSON—to
-compose MongoDB aggregations.
+_Abbreviated syntax for authoring MongoDB aggregation pipelines (and more)._
 
-[Browse Reference Documentation »](./REFERENCE.md)
+PipelineJS attempts to provide a concise _typed_ interface for writing MongoDB
+aggregations in [nodejs](https://nodejs.org) projects.
 
+[Other features](#built-in-extras) that may be commonly found useful are also
+available.
+
+Browse the [API Documentation](https://speedytwenty.github.io/mongodb-pipelinejs/)
+for implementation details.
+
+### Syntax Comparison
+
+**Without PipelineJS:**
+
+```js
+{ $map: {
+    input: { $filter: {
+      input: '$myArray',
+      as: 'item',
+      cond: $and('$$item.a', $or('$$item.b', '$$item.c')),
+    },
+    as: 'stockedItem',
+    in: { $multiply: ['$$stockedItem.quantity', '$$stockedItem.qtyDiscount'] },
+} }
+```
+
+What do you do with all those braces—without PipelineJS? Your linter might
+enforce one _opening_ brace per-line if your preference doesn't. Either way, the above
+example is a klunky mess.
+
+**With PipelineJS:** (Static Notation)
+
+```js
+$map(
+  $filter('$myArray', 'item', $gte('$$item.quantity', 1)),
+  'stockedItem',
+  $multiply('$$stockedItem.quantity', '$$stockedItem.price'),
+)
+```
+
+**With PipelineJS:** (Object Notation)
+
+```js
+$map($filter('$myArray').as('item').cond($gte('$$item.quanity', 1)))
+  .as('stockedItem')
+  .in($multiply('$$stockedItem.quantity', '$$stockedItem.price'))
+```
+
+**With PipelineJS:** (Mixed Notation)
+
+```js
+// Using object notation with $map for clean meaningful lines
+// Using static notation with $filter since it fits on a single line cleanly
+$map($filter('$myArray', 'item', $and('$$item.a', $or('$$item.b', '$$item.c')))).
+  .as('stockedItem')
+  .in($multiply('$$stockedItem.quantity', '$$stockedItem.price'))
+```
+
+**With PipelineJS:** (Upcoming release)
+
+```js
+// Use default variable name
+$map($filter('$myArray', '$$this.inStock')).in($multiply('$$this.quantity', '$$this.price'))
+```
+
+**PipelineJS is what you already expect!**
+PipelineJS nearly mimics the MongoDB aggregation syntax. There is nominal
+learning required to start writing cleaner aggregations today!
+
+
+MongoDB has numerous pipeline stages and operators. PipelineJS aims to support
+them all. As demonstrated above, PipelineJS provides the means to compose
+aggregations in an abbreviated fashion.
+
+### Built-in Extras
+
+PipelineJS includes some extras that provide additional functionality beyond
+MongoDB's supported operators.
+
+* **Safe-Operators**<br>
+  _Avoid runtime type errors using Safe Operators._ [details](#safe-operators)
+* **Utility Operators**<br>
+  _Some extra operator-like helpers that can be useful._ [details](#utility-operators)
+* **Standard Rounding**<br>
+  _Provides alternative numerical rounding commonly expected._ [details](#rounding)
+
 ## Installation
@@ -16,7 +104,15 @@
 
+_It is recommended to lock npm to the patch version (using "~") since breaking
+changes may be introduced in minor versions prior to a stable 1.0 release._
+
 ## Usage
 
-_Example needs refinement..._
+_Typescript support is included but needs refinement._
 
+The example below depicts an example aggregation using PipelineJS. What's not
+shown here is the default syntax that is replaced.
+
 ```js
+// Using the dollar-sign ($) closely resembles MongoDB's operator naming
+// convention and provides quick access to all operators.
 const $ = require('mongodb-pipelinejs');
@@ -32,6 +128,11 @@
   $.redact($.switch('$$PRUNE')
-    .case($.eq('$type', 'sale')),
+    .case($.eq('$type', 'sale'), '$$KEEP'),
+    .case($.eq('$type', 'transfer'), '$$PRUNE'),
   }),
   $.addFields({
-    payments: $.filter('$payments', 'payment', $.in('$$payment.status', ['complete', 'approved'])),
+    payments: $.filter(
+      '$payments',
+      'payment',
+      $.in('$$payment.status', ['complete', 'approved']),
+    ),
   }),
@@ -47,4 +148,143 @@ $.unwind('$payments'),
 ]).toArray();
+```
 
+### Use Minified Build
+
+```js
+const $ = require('mongodb-pipelinejs/min');
 ```
 
+OR
+
+```ts
+import * as $ from 'mongodb-pipelinejs/min';
+```
+
+### Explicit Inclusion Style
+
+```js
+// Include stages an operators only as needed
+const { $match, $group, $sort } = require('mongodb-pipelinejs');
+```
+
+## Purpose
+
+In a nutshell, PipelineJS can allow for writing aggregations with less
+syntatical characters—less array brackets (`[` & `]`) and fewer object
+braces (`{` & `}`).
+
+For some linting configurations, using PipelineJS can result
+in fewer nominal lines. Eg. Less lines that contain a single opening or closing
+delimeter.
+
+For those who use it, PipelineJS can offer the advantage of _code completion_
+and similar inflection utilities.
+
+### Safe Operators
+
+Some operators, commonly _mathematical_ operators, will cause the database
+server to complain if input to the operator doesn't resolve to the expected
+type.
+
+PipelineJS's "Safe Operators" are simply shorts that ensure the operator input
+resolves to the correct type—often times avoiding a fatal error.
+
+Some safe operators are presently included for these circumstances:
+
+  * [$addSafe](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24addSafe) 
+  * [$concatArraysSafe](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24concatArraysSafe)
+  * [$concatSafe](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24concatSafe)
+  * [$divideSafe](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24divideSafe)
+  * [$multiplySafe](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24multiplySafe)
+  * [$subtractSafe](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24subtractSafe)
+
+### Utility Operators
+
+These operators are exclusive to PipelineJS.
+
+  * [$arrayElemFirst](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24arrayElemFirst)
+  * [$arrayElemLast](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24arrayElemLast)
+  * [$ensureArray](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24ensureArray)
+  * [$ensureNumber](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24ensureNumber)
+  * [$ensureString](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24ensureString)
+  * [$if](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24if)
+  * [$increment](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24increment)
+  * [$decrement](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24decrement)
+  * [$roundStandard](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24roundStandard)
+
+### Rounding
+
+MongoDB's built-in `$round` operator behaves differently than some might expect.
+PipelineJS includes a more standard rounding operator:
+[$roundStandard](https://speedytwenty.github.io/mongodb-pipelinejs/global.html#%24roundStandard).
+
+With the sample documents:
+
+```js
+{_id : 1, "value" : 10.5},
+{_id : 2, "value" : 11.5},
+{_id : 3, "value" : 12.5},
+{_id : 4, "value" : 13.5}
+```
+
+MongoDB's default rounding with `$round : [ "$value", 0]` results in:
+
+```js
+{_id : 1, "value" : 10},
+{_id : 2, "value" : 12},
+{_id : 3, "value" : 12},
+{_id : 4, "value" : 14}
+```
+
+PipelineJS's rounding with `$roundStandard('$value', 0)` results in:
+
+```js
+{_id : 1, "value" : 11},
+{_id : 2, "value" : 12},
+{_id : 3, "value" : 13},
+{_id : 4, "value" : 14}
+```
+
+#### Mongo Round
+
+PipelineJS can be used in lieu of [mongo-round](https://www.npmjs.com/package/mongo-round)
+which is no longer maintained.
+
+Change:
+
+```js
+const round = require('mongo-round');
+```
+
+To:
+
+```js
+const { roundStandard: round } = require('mongodb-pipelinejs');`
+```
+
+## Documentation
+
+Aside from a few niceties, the documentation is an abbreviation of the official
+MongoDB documentation—with specific API/interface information and usage
+examples.
+
+**[Browse API Documentation &raquo;](https://speedytwenty.github.io/mongodb-pipelinejs/)**
+
+## Feedback (bugs, feature requests, etc)
+
+Found a missing or incorrect operator?.. have an idea for a super handy
+operator? Let us know by
+[posting an issue](https://github.com/speedytwenty/mongodb-pipelinejs/issues)
+
+## Contributing
+
+Pull requests are always welcome.
+
+## Next Steps
+
+- [PipelineJS Documentation](https://www.mongodb.com/docs/manual/)
+- [Star us on GitHub](https://github.com/speedytwenty/mongodb-pipelinejs)
+
+## License
+
+[Apache 2.0](LICENSE.md)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Empty package

Supply chain risk

Package does not contain any code. It may be removed, is name squatting, or the result of a faulty package publish.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

43047

increased by31.45%

Number of lines in readme file

288

increased by500%

Worsened metrics

Dev dependency count

18

increased by5.88%

Lines of code

0

decreased by-100%

Number of low quality alerts

3

increased by50%

Number of medium supply chain risk alerts

2

increased byInfinity%

No dependency changes