json-stream-stringify
Advanced tools
json-stream-stringify - npm Package Compare versions
Comparing version 1.6.1 to 2.0.0
| { | ||
| "name": "json-stream-stringify", | ||
| "version": "1.6.1", | ||
| "description": "JSON.Stringify as a readable stream", | ||
| "version": "2.0.0", | ||
| "license": "MIT", | ||
| "author": "Faleij <faleij@gmail.com> (https://github.com/faleij)", | ||
| "repository": { | ||
@@ -9,31 +11,39 @@ "type": "git", | ||
| }, | ||
| "main": "jsonStreamify.js", | ||
| "dependencies": {}, | ||
| "devDependencies": { | ||
| "coveralls": "2.11.9", | ||
| "istanbul": "0.4.3", | ||
| "expect.js": "0.3.1", | ||
| "mocha": "2.4.5" | ||
| "bugs": { | ||
| "url": "https://github.com/faleij/json-stream-stringify/issues" | ||
| }, | ||
| "main": "./umd.js", | ||
| "module": "./module.js", | ||
| "browser": "./umd.js", | ||
| "scripts": { | ||
| "test": "mocha", | ||
| "coverage": "istanbul cover node_modules/mocha/bin/_mocha -- test.js -R spec" | ||
| "lint": "eslint . && echo \"eslint: no lint errors\"", | ||
| "build": "rollup -c rollup.config.js && babel test-src --out-dir test", | ||
| "build:watch": "rollup -c rollup.config.js --watch", | ||
| "test": "mocha -R spec -b", | ||
| "coverage": "nyc npm test", | ||
| "coveralls": "nyc report --reporter=text-lcov | coveralls" | ||
| }, | ||
| "keywords": [ | ||
| "JSON", | ||
| "stringify", | ||
| "stream", | ||
| "string", | ||
| "streamify", | ||
| "read", | ||
| "readable", | ||
| "co", | ||
| "generator", | ||
| "iterable" | ||
| ], | ||
| "author": "Faleij", | ||
| "license": "MIT", | ||
| "engines": { | ||
| "node": ">=4.2.2" | ||
| "devDependencies": { | ||
| "@babel/cli": "^7.0.0-beta.51", | ||
| "@babel/core": "^7.0.0-beta.51", | ||
| "@babel/plugin-transform-runtime": "^7.0.0-beta.51", | ||
| "@babel/polyfill": "^7.0.0-beta.51", | ||
| "@babel/preset-env": "^7.0.0-beta.51", | ||
| "@babel/runtime": "^7.0.0-beta.51", | ||
| "babel-plugin-external-helpers": "^6.22.0", | ||
| "babel-register": "^6.26.0", | ||
| "coveralls": "3.0.1", | ||
| "eslint": "^4.19.1", | ||
| "eslint-config-airbnb": "^17.0.0", | ||
| "eslint-plugin-import": "^2.12.0", | ||
| "eslint-plugin-jsx-a11y": "^6.0.3", | ||
| "eslint-plugin-mocha": "^5.0.0", | ||
| "eslint-plugin-react": "^7.9.1", | ||
| "expect.js": "0.3.1", | ||
| "istanbul": "0.4.5", | ||
| "mocha": "3.5.3", | ||
| "nyc": "12.0.2", | ||
| "rollup": "0.60.4", | ||
| "rollup-plugin-babel": "^4.0.0-beta.5" | ||
| } | ||
| } |
133
README.md
| # JSON Stream Stringify | ||
| [![NPM version][npm-image]][npm-url] | ||
| [![NPM Downloads][downloads-image]][downloads-url] | ||
| [![Dependency Status][dependency-image]][dependency-url] | ||
| [![Build Status][travis-image]][travis-url] | ||
| [![Coverage Status][coveralls-image]][coveralls-url] | ||
| [![License][license-image]](LICENSE) | ||
| [![Gratipay][gratipay-image]][gratipay-url] | ||
| [![Donate][donate-image]][donate-url] | ||
| JSON Stringify as a Readable Stream with rescursive resolving of any readable streams and Promises. | ||
| ## Important and Breaking Changes in v2 | ||
| - Completely rewritten from scratch | ||
| - 100% Code Coverage! 🎉 | ||
| - Space argument finally implemented! 🎉 | ||
| - ⚠️ Cycling is off by default | ||
| - ⚠️ JsonStreamStringify is now a constructor; use ``new`` operator | ||
| - Removed dependency on global JSON.stringify, Async/Await and Generators | ||
| - JsonStreamStringify is now compiled with babel to target ES5 (polyfills needed) | ||
| - Rejected promises and input stream errors are now handled and emitted as errors | ||
| - Added cyclic structure detection to prevent infinite recursion | ||
| ## Main Features | ||
| - Promises are rescursively resolved and the result is piped through JSONStreamStreamify | ||
| - Streams (ObjectMode) are piped through a transform which pipes the data through JSONStreamStreamify (enabling recursive resolving) | ||
| - Streams (Non-ObjectMode) is stringified and piped | ||
| - Promises are rescursively resolved and the result is piped through JsonStreamStringify | ||
| - Streams (Object mode) are recursively read and output as arrays | ||
| - Streams (Non-Object mode) are output as a single string | ||
| - Output is streamed optimally with as small chunks as possible | ||
| - Decycling using Douglas Crockfords Cycle algorithm | ||
| - Great memory management with reference release post process (When a key and value has been processed the value is dereferenced) | ||
| - Stream pressure handling | ||
| - Cycling of cyclical structures and dags using [Douglas Crockfords cycle algorithm](https://github.com/douglascrockford/JSON-js)* | ||
| - Great memory management with reference release after processing and WeakMap/Set reference handling | ||
| - Optimal stream pressure handling | ||
| - Tested and runs on ES5** and ES2015 | ||
| - Bundled as UMD and Module | ||
| \* Off by default since v2 | ||
| \** With polyfills | ||
| ## Install | ||
@@ -25,28 +40,80 @@ | ||
| npm install --save json-stream-stringify | ||
| # Optional if you need polyfills | ||
| # Make sure to include these if you target NodeJS <=v6 or browsers | ||
| npm install --save @babel/polyfill @babel/runtime | ||
| ``` | ||
| ## Usage | ||
| Using Node v8 or later with ESM / Webpack / Browserify / Rollup | ||
| ```javascript | ||
| // No Polyfills | ||
| import JsonStreamStringify from 'JsonStreamStringify'; | ||
| ``` | ||
| ```javascript | ||
| // Polyfilled; loads only needed polyfills from @babel/polyfill @babel/runtime | ||
| import JsonStreamStringify from 'JsonStreamStringify/module.polyfill'; | ||
| ``` | ||
| Using Node >=8 / Other ES2015 environments | ||
| ```javascript | ||
| const JsonStreamStringify = require('JsonStreamStringify'); | ||
| ``` | ||
| Using Node <=6 / Other ES5 environments | ||
| ```javascript | ||
| var JsonStreamStringify = require('JsonStreamStringify/umd.polyfill'); | ||
| ``` | ||
| **Note:** This library is primarily written for LTS versions of NodeJS. Other environments are not tested. | ||
| **Note on non-NodeJS usage:** This module depends on node streams library. Any Streams3 compatible implementation should work - as long as it exports a Readable class, with instances that looks like readable streams. | ||
| **Note on Polyfills:** I have taken measures to minify global pollution of polyfills but this library **does not load polyfills by default** because the polyfills modify native object prototypes and it goes against the [W3C recommendations](https://www.w3.org/2001/tag/doc/polyfills/#advice-for-library-and-framework-authors). | ||
| ## API | ||
| ### JSONStreamStringify(value[, replacer[, spaces[, noDecycle]]]) | ||
| Convert value to JSON string. Returns a readable stream. | ||
| - ``value`` Any data to convert to JSON. | ||
| - ``replacer`` Optional ``Function(key, value)`` or ``Array``. | ||
| As a function the returned value replaces the value associated with the key. [Details](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter) | ||
| ### `new JsonStreamStringify(value[, replacer[, spaces[, cycle]]])` | ||
| Streaming conversion of ``value`` to JSON string. | ||
| **Parameters** | ||
| - ``value`` ``Any`` | ||
| Data to convert to JSON. | ||
| - ``replacer`` Optional ``Function(key, value)`` or ``Array`` | ||
| As a function the returned value replaces the value associated with the key. [Details](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter) | ||
| As an array all other keys are filtered. [Details](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Example_with_an_array) | ||
| - ``spaces`` Optional ``String`` or ``Number`` **Not yet implemented** | ||
| - ``noDecycle`` Optional ``Boolean`` Set to ``true`` to disable decycling. | ||
| - ``spaces`` Optional ``String`` or ``Number`` | ||
| A String or Number object that's used to insert white space into the output JSON string for readability purposes. If this is a Number, it indicates the number of space characters to use as white space. If this is a String, the string is used as white space. If this parameter is not recognized as a finite number or valid string, no white space is used. | ||
| - ``cycle`` Optional ``Boolean`` | ||
| ``true`` enables cycling of cyclical structures and dags. | ||
| To restore cyclical structures; use [Crockfords Retrocycle method](https://github.com/douglascrockford/JSON-js) on the parsed object (not included in this module). | ||
| **Returns** | ||
| - ``JsonStreamStringify`` object that exposes a [Streams3 interface](https://nodejs.org/api/stream.html#stream_class_stream_readable). | ||
| ### jsonStreamStringify#path | ||
| **Returns** | ||
| - ``Array[String, Number]`` | ||
| Current path being serialized as an array of Strings (keys of objects) and Numbers (index into arrays). | ||
| Can be transformed into an mpath with ``.join('.')``. | ||
| Useful in conjunction with ``.on('error', ...)``, for figuring out what path may have caused the error. | ||
| ## Example Usage | ||
| ```javascript | ||
| const JSONStreamStringify = require('json-stream-stringify'); | ||
| const JsonStreamStringify = require('json-stream-stringify'); | ||
| JSONStreamStringify({ | ||
| aPromise: Promise.resolve(Promise.resolve("text")), // Promise may resolve more promises and streams which will be consumed and resolved | ||
| aStream: ReadableObjectStream({a:1}, 'str'), // Stream may write more streams and promises which will be consumed and resolved | ||
| const jsonStream = new JsonStreamStringify({ | ||
| // Promises and Streams may resolve more promises and/or streams which will be consumed and processed into json output | ||
| aPromise: Promise.resolve(Promise.resolve("text")), | ||
| aStream: ReadableObjectStream({a:1}, 'str'), | ||
| arr: [1, 2, Promise.resolve(3), Promise.resolve([4, 5]), ReadableStream('a', 'b', 'c')], | ||
| date: new Date(2016, 0, 2) | ||
| }).pipe(process.stdout); | ||
| }); | ||
| jsonStream.once('error', () => console.log('Error at path', jsonStream.stack.join('.'))); | ||
| jsonStream.pipe(process.stdout); | ||
| ``` | ||
| Output (each line represents a write from JSONStreamStringify) | ||
| Output (each line represents a write from jsonStreamStringify) | ||
| ``` | ||
@@ -92,19 +159,5 @@ { | ||
| ```javascript | ||
| app.get('/api/users', (req, res, next) => JSONStreamStringify(Users.find().stream()).pipe(res)); | ||
| app.get('/api/users', (req, res, next) => new JsonStreamStringify(Users.find().stream()).pipe(res)); | ||
| ``` | ||
| ## TODO | ||
| - Space option | ||
| Feel free to contribute. | ||
| ## Technical Notes | ||
| Uses toJSON when available, and JSON.stringify to stringify everything but objects and arrays. | ||
| Streams with ObjectMode=true are output as arrays while ObjectMode=false output as a concatinated string (each chunk is piped with transforms). | ||
| Circular structures are handled using a WeakMap based implementation of [Douglas Crockfords Decycle method](https://github.com/douglascrockford/JSON-js/blob/master/cycle.js). To restore circular structures; use Crockfords Retrocycle method on the parsed object. | ||
| ## Requirements | ||
| NodeJS >4.2.2 | ||
| # License | ||
@@ -119,4 +172,2 @@ [MIT](LICENSE) | ||
| [downloads-url]: https://npmjs.org/package/json-stream-stringify | ||
| [dependency-image]: https://gemnasium.com/Faleij/json-stream-stringify.svg | ||
| [dependency-url]: https://gemnasium.com/Faleij/json-stream-stringify | ||
| [travis-image]: https://travis-ci.org/Faleij/json-stream-stringify.svg?branch=master | ||
@@ -127,3 +178,3 @@ [travis-url]: https://travis-ci.org/Faleij/json-stream-stringify | ||
| [license-image]: https://img.shields.io/badge/license-MIT-blue.svg | ||
| [gratipay-image]: https://img.shields.io/gratipay/faleij.svg | ||
| [gratipay-url]: https://gratipay.com/faleij/ | ||
| [donate-image]: https://img.shields.io/badge/Donate-PayPal-green.svg | ||
| [donate-url]: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=faleij%40gmail%2ecom&lc=GB&item_name=faleij&item_number=jsonStreamStringify¤cy_code=SEK&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage 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
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
No bug tracker
MaintenancePackage does not have a linked bug tracker in package.json.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by604.99%
168007
- Number of package files
- increased by22.22%
11
- Lines of code
- increased by339.86%
1887
- Number of low maintenance alerts
- decreased by-100%
0
- Number of lines in readme file
- increased by40.48%
177
Worsened metrics
- Dev dependency count
- increased by425%
21
- Number of medium supply chain risk alerts
- increased byInfinity%
1
No dependency changes