bfj 5.3.1 → 6.1.2

package/.eslintrc

@@ -83,7 +83,7 @@ rules:
   no-extra-bind: 2
   no-extra-boolean-cast: 2
   no-extra-label: 2
-  no-extra-parens: [ 2, "all" ]
+  no-extra-parens: [ 2, "all", { "nestedBinaryExpressions": false } ]
   no-extra-semi: 2
   no-fallthrough: 0
   no-floating-decimal: 2

package/.gitlab-ci.yml

@@ -0,0 +1,25 @@
+cache:
+  key: "$CI_JOB_NAME"
+  untracked: true
+  paths:
+    - node_modules/
+
+before_script:
+  - npm install
+
+.test_template: &npm_test
+  script:
+    - npm run lint
+    - npm test
+
+test:node6:
+  image: node:6
+  <<: *npm_test
+
+test:node8:
+  image: node:8
+  <<: *npm_test
+
+test:node10:
+  image: node:10
+  <<: *npm_test

package/AUTHORS

@@ -1,4 +1,4 @@
-Phil Booth <pmbooth@gmail.com> (https://github.com/philbooth)
+Phil Booth <pmbooth@gmail.com> (https://philbooth.me/)
 Rowan Manning (https://github.com/rowanmanning)
 Benedikt Rötsch (https://github.com/axe312ger)
 

package/CONTRIBUTING.md

@@ -30,8 +30,8 @@
   if the change is one that you think
   needs some discussion.
 
-[readme]: https://github.com/philbooth/bfj/blob/master/README.md
-[authors]: https://github.com/philbooth/bfj/blob/master/AUTHORS
-[newissue]: https://github.com/philbooth/bfj/issues/new
-[issues]: https://github.com/philbooth/bfj/issues
+[readme]: https://gitlab.com/philbooth/bfj/blob/master/README.md
+[authors]: https://gitlab.com/philbooth/bfj/blob/master/AUTHORS
+[newissue]: https://gitlab.com/philbooth/bfj/issues/new
+[issues]: https://gitlab.com/philbooth/bfj/issues
 

package/HISTORY.md

@@ -1,5 +1,55 @@
 # History
 
+## 6.1.2
+
+### Bug fixes
+
+* eventify: escape object keys (910ad08)
+
+### Other changes
+
+* package: update deps (aafb4ff)
+
+## 6.1.1
+
+### Bug fixes
+
+* eventify: don't serialise NaN or infinities (3c50fe4)
+
+### Other changes
+
+* deps: npm update (b3c86d0)
+* project: add package lock file (63df27d)
+* project: migrate to gitlab (26746a0)
+
+## 6.1.0
+
+### New features
+
+* match: pass a depth argument to selector predicates (af15939)
+
+### Other changes
+
+* tests: delete unused var (f10902a)
+* ci: reinstate tests in node 9 (7cd2594)
+* ci: temporarily disable tests in node 9 (e27ccd0)
+
+## 6.0.0
+
+### Breaking changes
+
+* eventify: distinguish between syntax and operational errors (e7bc23d)
+* walk: distinguish between syntax and operational errors (419ddae)
+
+### New features
+
+* streams: expose a highWaterMark option (626f755)
+* match: implement a streaming match api (e2e320d)
+
+### Other changes
+
+* docs: note the end of node-4 maintenance (0a32090)
+
 ## 5.3.1
 
 ### Bug fixes

package/README.md

@@ -1,8 +1,9 @@
 # BFJ
 
-[![Package status](https://img.shields.io/npm/v/bfj.svg?style=flat-square)](https://www.npmjs.com/package/bfj)
-[![Build status](https://img.shields.io/travis/philbooth/bfj.svg?style=flat-square)](https://travis-ci.org/philbooth/bfj)
-[![License](https://img.shields.io/github/license/philbooth/bfj.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Build status](https://gitlab.com/philbooth/bfj/badges/master/pipeline.svg)](https://gitlab.com/philbooth/bfj/pipelines)
+[![Package status](https://img.shields.io/npm/v/bfj.svg)](https://www.npmjs.com/package/bfj)
+[![Downloads](https://img.shields.io/npm/dm/bfj.svg)](https://www.npmjs.com/package/bfj)
+[![License](https://img.shields.io/npm/l/bfj.svg)](https://opensource.org/licenses/MIT)
 
 Big-Friendly JSON. Asynchronous streaming functions for large JSON data sets.
 
@@ -11,10 +12,11 @@ Big-Friendly JSON. Asynchronous streaming functions for large JSON data sets.
 * [What functions does it implement?](#what-functions-does-it-implement)
 * [How do I install it?](#how-do-i-install-it)
 * [How do I read a JSON file?](#how-do-i-read-a-json-file)
-* [How do I write a JSON file?](#how-do-i-write-a-json-file)
 * [How do I parse a stream of JSON?](#how-do-i-parse-a-stream-of-json)
-* [How do I create a JSON string?](#how-do-i-create-a-json-string)
+* [How do I selectively parse individual items from a JSON stream?](#how-do-i-selectively-parse-individual-items-from-a-json-stream)
+* [How do I write a JSON file?](#how-do-i-write-a-json-file)
 * [How do I create a stream of JSON?](#how-do-i-create-a-stream-of-json)
+* [How do I create a JSON string?](#how-do-i-create-a-json-string)
 * [What other methods are there?](#what-other-methods-are-there)
   * [bfj.walk (stream, options)](#bfjwalk-stream-options)
   * [bfj.eventify (data, options)](#bfjeventify-data-options)
@@ -69,10 +71,10 @@ BFJ is not for you.
 
 ## What functions does it implement?
 
-Eight functions
+Nine functions
 are exported.
 
-Four are
+Five are
 concerned with
 parsing, or
 turning JSON strings
@@ -86,6 +88,10 @@ into JavaScript data:
   are for asynchronously parsing
   streams of JSON.
 
+* [`match`](#how-do-i-selectively-parse-individual-items-from-a-json-stream)
+  selectively parses individual items
+  from a JSON stream.
+
 * [`walk`](#bfjwalk-stream-options)
   asynchronously walks
   a stream,
@@ -105,14 +111,14 @@ to JSON:
   asynchronously serialises data
   to a JSON file on disk.
 
-* [`stringify`](#how-do-i-create-a-json-string)
-  asynchronously serialises data
-  to a JSON string.
-
 * [`streamify`](#how-do-i-create-a-stream-of-json)
   asynchronously serialises data
   to a stream of JSON.
 
+* [`stringify`](#how-do-i-create-a-json-string)
+  asynchronously serialises data
+  to a JSON string.
+
 * [`eventify`](#bfjeventify-data-options)
   asynchronously traverses
   a data structure
@@ -136,7 +142,7 @@ Or if you just want
 the git repo:
 
 ```
-git clone git@github.com:philbooth/bfj.git
+git clone git@gitlab.com:philbooth/bfj.git
 ```
 
 ## How do I read a JSON file?
@@ -170,33 +176,6 @@ If syntax errors occur,
 the promise is rejected
 with the first error.
 
-## How do I write a JSON file?
-
-```js
-const bfj = require('bfj');
-
-bfj.write(path, data, options)
-  .then(() => {
-    // :)
-  })
-  .catch(error => {
-    // :(
-  });
-```
-
-`write` returns a [bluebird promise][promise]
-and asynchronously serialises a data structure
-to a JSON file on disk.
-The promise is resolved
-when the file has been written,
-or rejected with the error
-if writing failed.
-
-It takes three arguments;
-the path to the JSON file,
-the data structure to serialise
-and an [options](#options-for-serialisation-functions) object.
-
 ## How do I parse a stream of JSON?
 
 ```js
@@ -259,13 +238,60 @@ request({ url }).pipe(bfj.unpipe((error, data) => {
   the callback
   as the first argument.
 
-## How do I create a JSON string?
+## How do I selectively parse individual items from a JSON stream?
 
 ```js
 const bfj = require('bfj');
 
-bfj.stringify(data, options)
-  .then(json => {
+// Call match with your stream and a selector predicate/regex/string
+const dataStream = bfj.match(jsonStream, selector, options);
+
+// Get data out of the returned stream with event handlers
+dataStream.on('data', item => { /* ... */ });
+dataStream.on('end', () => { /* ... */);
+dataStream.on('error', () => { /* ... */);
+dataStream.on('dataError', () => { /* ... */);
+
+// ...or you can pipe it to another stream
+dataStream.pipe(someOtherStream);
+```
+
+`match` returns a readable, object-mode stream
+and asynchronously parses individual matching items
+from an input JSON stream.
+
+It takes three arguments:
+a [readable stream][readable]
+from which the JSON will be parsed;
+a selector argument for determining matches,
+which may be a string, a regular expression or a predicate function;
+and an [options](#options-for-parsing-functions) object.
+
+If the selector is a string,
+it will be compared to property keys
+to determine whether
+each item in the data is a match.
+If it is a regular expression,
+the comparison will be made
+by calling the [RegExp `test` method][regexp-test]
+with the property key.
+Predicate functions will be called with three arguments:
+`key`, `value` and `depth`.
+If the result of the predicate is a truthy value
+then the item will be deemed a match.
+
+If there are any syntax errors in the JSON,
+a `dataError` event will be emitted.
+If any other errors occur,
+an `error` event will be emitted.
+
+## How do I write a JSON file?
+
+```js
+const bfj = require('bfj');
+
+bfj.write(path, data, options)
+  .then(() => {
     // :)
   })
   .catch(error => {
@@ -273,14 +299,16 @@ bfj.stringify(data, options)
   });
 ```
 
-`stringify` returns a [bluebird promise][promise] and
-asynchronously serialises a data structure
-to a JSON string.
+`write` returns a [bluebird promise][promise]
+and asynchronously serialises a data structure
+to a JSON file on disk.
 The promise is resolved
-to the JSON string
-when serialisation is complete.
+when the file has been written,
+or rejected with the error
+if writing failed.
 
-It takes two arguments;
+It takes three arguments;
+the path to the JSON file,
 the data structure to serialise
 and an [options](#options-for-serialisation-functions) object.
 
@@ -294,6 +322,7 @@ const stream = bfj.streamify(data, options);
 // Get data out of the stream with event handlers
 stream.on('data', chunk => { /* ... */ });
 stream.on('end', () => { /* ... */);
+stream.on('error', () => { /* ... */);
 stream.on('dataError', () => { /* ... */);
 
 // ...or you can pipe it to another stream
@@ -310,6 +339,37 @@ It takes two arguments;
 the data structure to serialise
 and an [options](#options-for-serialisation-functions) object.
 
+If there a circular reference is encountered in the data
+and `options.circular` is not set to `'ignore'`,
+a `dataError` event will be emitted.
+If any other errors occur,
+an `error` event will be emitted.
+
+## How do I create a JSON string?
+
+```js
+const bfj = require('bfj');
+
+bfj.stringify(data, options)
+  .then(json => {
+    // :)
+  })
+  .catch(error => {
+    // :(
+  });
+```
+
+`stringify` returns a [bluebird promise][promise] and
+asynchronously serialises a data structure
+to a JSON string.
+The promise is resolved
+to the JSON string
+when serialisation is complete.
+
+It takes two arguments;
+the data structure to serialise
+and an [options](#options-for-serialisation-functions) object.
+
 ## What other methods are there?
 
 ### bfj.walk (stream, options)
@@ -328,6 +388,7 @@ emitter.on(bfj.events.literal, value => { /* ... */ });
 emitter.on(bfj.events.endArray, () => { /* ... */ });
 emitter.on(bfj.events.endObject, () => { /* ... */ });
 emitter.on(bfj.events.error, error => { /* ... */ });
+emitter.on(bfj.events.dataError, error => { /* ... */ });
 emitter.on(bfj.events.end, () => { /* ... */ });
 ```
 
@@ -423,16 +484,24 @@ of an object,
 
 * `bfj.events.error`
   indicates that
-  an error has occurred.
-  The error may be due to
-  invalid syntax on the incoming stream
-  or caught from one of the event handlers
+  an error was caught
+  from one of the event handlers
   in user code.
   The listener
   will be passed
   the `Error` instance
   as its argument.
 
+* `bfj.events.dataError`
+  indicates that
+  a syntax error was encountered
+  in the incoming JSON stream.
+  The listener
+  will be passed
+  an `Error` instance
+  decorated with `actual`, `expected`, `lineNumber` and `columnNumber` properties
+  as its argument.
+
 * `bfj.events.end`
   indicates that
   the end of the input
@@ -464,7 +533,8 @@ emitter.on(bfj.events.number, value => { /* ... */ });
 emitter.on(bfj.events.literal, value => { /* ... */ });
 emitter.on(bfj.events.endArray, () => { /* ... */ });
 emitter.on(bfj.events.endObject, () => { /* ... */ });
-emitter.on(bfj.events.error, () => { /* ... */ });
+emitter.on(bfj.events.error, error => { /* ... */ });
+emitter.on(bfj.events.dataError, error => { /* ... */ });
 emitter.on(bfj.events.end, () => { /* ... */ });
 ```
 
@@ -551,17 +621,23 @@ of an object,
 
 * `bfj.events.error`
   indicates that
-  an error has occurred.
-  The error may be due to
-  a circular reference
-  encountered in the data
-  or caught from one of the event handlers
+  an error was caught
+  from one of the event handlers
   in user code.
   The listener
   will be passed
   the `Error` instance
   as its argument.
 
+* `bfj.events.dataError`
+  indicates that
+  a circular reference was encountered in the data
+  and the `circular` option was not set to `'ignore'`.
+  The listener
+  will be passed
+  an `Error` instance
+  as its argument.
+
 * `bfj.events.end`
   indicates that
   the end of the data
@@ -610,6 +686,26 @@ of an object,
   discrete chunks of JSON.
   See [NDJSON](#can-it-handle-newline-delimited-json-ndjson) for more information.
 
+* `options.numbers`:
+  For `bfj.match` only,
+  set this to `true`
+  if you wish to match against numbers
+  with a string or regular expression
+  `selector` argument.
+
+* `options.bufferLength`:
+  For `bfj.match` only,
+  the length of the match buffer.
+  Smaller values use less memory
+  but may result in a slower parse time.
+  The default value is `1024`.
+
+* `options.highWaterMark`:
+  For `bfj.match` only,
+  set this if you would like to
+  pass a value for the `highWaterMark` option
+  to the readable stream constructor.
+
 ### Options for serialisation functions
 
 * `options.space`:
@@ -681,6 +777,11 @@ of an object,
   but may result in a slower serialisation time.
   The default value is `1024`.
 
+* `options.highWaterMark`:
+  Set this if you would like to
+  pass a value for the `highWaterMark` option
+  to the readable stream constructor.
+
 * `options.yieldRate`:
   The number of data items to process
   before yielding to the event loop.
@@ -734,7 +835,7 @@ resume();
 
 Yes.
 If you pass the `ndjson` [option](#options-for-parsing-functions)
-to `bfj.walk` or `bfj.parse`,
+to `bfj.walk`, `bfj.match` or `bfj.parse`,
 newline characters at the root level
 will act as delimiters between
 discrete JSON values:
@@ -742,6 +843,9 @@ discrete JSON values:
 * `bfj.walk` will emit a `bfj.events.endLine` event
   each time it encounters a newline character.
 
+* `bfj.match` will just ignore the newlines
+  while it continues looking for matching items.
+
 * `bfj.parse` will resolve with the first value
   and pause the underlying stream.
   If it's called again with the same stream,
@@ -821,14 +925,15 @@ As of [version `3.0.0`](HISTORY.md#300),
 only Node.js versions 6 or greater
 are supported
 because of the dependency
-on [Hoopy](https://github.com/philbooth/hoopy).
+on [Hoopy](https://gitlab.com/philbooth/hoopy).
 Previous versions supported
 node 4 and later.
 
-A separate `node-4` branch is also maintained,
-which maintains feature parity version-for-version
-with `master`.
-Releases from this branch
+A separate `node-4` branch was maintained
+until version `5.4.1`,
+which had feature parity version-for-version
+with releases from `master`.
+Releases from the `node-4` branch
 are available in npm
 under the package name [`bfj-node4`](https://www.npmjs.com/package/bfj-node4).
 
@@ -845,6 +950,7 @@ under the package name [`bfj-node4`](https://www.npmjs.com/package/bfj-node4).
 [readable]: https://nodejs.org/api/stream.html#stream_readable_streams
 [writable]: https://nodejs.org/api/stream.html#stream_writable_streams
 [pipe]: https://nodejs.org/api/stream.html#stream_readable_pipe_destination_options
+[regexp-test]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test
 [reviver]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Using_the_reviver_parameter
 [space]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_space_argument
 [history]: HISTORY.md
@@ -853,5 +959,5 @@ under the package name [`bfj-node4`](https://www.npmjs.com/package/bfj-node4).
 [mocha]: https://mochajs.org/
 [chai]: http://chaijs.com/
 [proxyquire]: https://github.com/thlorenz/proxyquire
-[spooks]: https://github.com/philbooth/spooks.js
+[spooks]: https://gitlab.com/philbooth/spooks.js
 [license]: COPYING

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "bfj",
-  "version": "5.3.1",
+  "version": "6.1.2",
   "description": "Big-friendly JSON. Asynchronous streaming functions for large JSON data sets.",
-  "homepage": "https://github.com/philbooth/bfj",
-  "bugs": "https://github.com/philbooth/bfj/issues",
+  "homepage": "https://gitlab.com/philbooth/bfj",
+  "bugs": "https://gitlab.com/philbooth/bfj/issues",
   "license": "MIT",
-  "author": "Phil Booth (https://github.com/philbooth)",
+  "author": "Phil Booth (https://gitlab.com/philbooth)",
   "main": "./src",
   "keywords": [
     "json",
@@ -23,25 +23,25 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/philbooth/bfj.git"
+    "url": "https://gitlab.com/philbooth/bfj.git"
   },
   "engines": {
     "node": ">= 6.0.0"
   },
   "dependencies": {
-    "bluebird": "^3.5.1",
-    "check-types": "^7.3.0",
-    "hoopy": "^0.1.2",
-    "tryer": "^1.0.0"
+    "bluebird": "^3.5.5",
+    "check-types": "^8.0.3",
+    "hoopy": "^0.1.4",
+    "tryer": "^1.0.1"
   },
   "devDependencies": {
-    "eslint": "4.19.x",
-    "mocha": "5.0.x",
-    "chai": "4.1.x",
-    "proxyquire": "1.8.x",
-    "spooks": "2.0.x",
-    "please-release-me": "2.0.x",
-    "request": "2.85.x"
+    "chai": "^4.2.0",
+    "eslint": "^6.0.1",
+    "mocha": "^6.1.4",
+    "please-release-me": "^2.1.2",
+    "proxyquire": "^2.1.0",
+    "request": "^2.88.0",
+    "spooks": "^2.0.0"
   },
   "scripts": {
     "lint": "eslint src",

package/src/datastream.js

@@ -0,0 +1,17 @@
+'use strict'
+
+const check = require('check-types')
+const BfjStream = require('./stream')
+const util = require('util')
+
+util.inherits(DataStream, BfjStream)
+
+module.exports = DataStream
+
+function DataStream (read, options) {
+  if (check.not.instanceStrict(this, DataStream)) {
+    return new DataStream(read, options)
+  }
+
+  return BfjStream.call(this, read, Object.assign({ objectMode: true }, options))
+}

package/src/eventify.js

@@ -110,7 +110,7 @@ function eventify (data, options = {}) {
     })
 
     function after (coerced) {
-      if (isInvalidType(coerced)) {
+      if (isInvalid(coerced)) {
         return
       }
 
@@ -205,8 +205,15 @@ function eventify (data, options = {}) {
     })
   }
 
-  function isInvalidType (datum) {
-    return !! invalidTypes[typeof datum]
+  function isInvalid (datum) {
+    const type = typeof datum
+    return !! invalidTypes[type] || (
+      type === 'number' && ! isValidNumber(datum)
+    )
+  }
+
+  function isValidNumber (datum) {
+    return datum > Number.NEGATIVE_INFINITY && datum < Number.POSITIVE_INFINITY
   }
 
   function literal (datum) {
@@ -232,7 +239,7 @@ function eventify (data, options = {}) {
   function array (datum) {
     // For an array, collection:object and collection:array are the same.
     return collection(datum, datum, 'array', item => {
-      if (isInvalidType(item)) {
+      if (isInvalid(item)) {
         return proceed(null)
       }
 
@@ -249,7 +256,7 @@ function eventify (data, options = {}) {
           ignoreThisItem = ignoreItems = true
 
           if (! ignoreCircularReferences) {
-            return emit(events.error, new Error('Circular reference.'))
+            return emit(events.dataError, new Error('Circular reference.'))
           }
         } else {
           references.set(obj, true)
@@ -286,11 +293,11 @@ function eventify (data, options = {}) {
     return collection(datum, Object.keys(datum), 'object', key => {
       const item = datum[key]
 
-      if (isInvalidType(item)) {
+      if (isInvalid(item)) {
         return Promise.resolve()
       }
 
-      return emit(events.property, key)
+      return emit(events.property, escapeString(key))
         .then(() => proceed(item))
     })
   }

package/src/events.js

@@ -15,3 +15,4 @@ module.exports = {
 module.exports.endArray = module.exports.endPrefix + module.exports.array
 module.exports.endObject = module.exports.endPrefix + module.exports.object
 module.exports.endLine = `${module.exports.endPrefix}line`
+module.exports.dataError = `${module.exports.error}-data`

package/src/index.js

@@ -2,6 +2,7 @@
 
 module.exports = {
   walk: require('./walk'),
+  match: require('./match'),
   parse: require('./parse'),
   unpipe: require('./unpipe'),
   read: require('./read'),