fast-json-stringify 3.0.3 → 4.0.0

package/.github/workflows/benchmark.yml

@@ -8,6 +8,8 @@ jobs:
   benchmark:
     if: ${{ github.event.label.name == 'benchmark' }}
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     outputs:
       PR-BENCH-12: ${{ steps.benchmark-pr.outputs.BENCH_RESULT12 }}
       PR-BENCH-14: ${{ steps.benchmark-pr.outputs.BENCH_RESULT14 }}
@@ -19,12 +21,13 @@ jobs:
       matrix:
         node-version: [12, 14, 16]
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
-          ref: ${{github.event.pull_request.head.ref}}
+          persist-credentials: false
+          ref: ${{github.event.pull_request.head.sha}}
           repository: ${{github.event.pull_request.head.repo.full_name}}
 
-      - uses: actions/setup-node@v2
+      - uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
 
@@ -43,7 +46,7 @@ jobs:
           echo "::set-output name=BENCH_RESULT${{matrix.node-version}}::$content"
 
       # main benchmark
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           ref: 'master'
 
@@ -64,6 +67,8 @@ jobs:
   output-benchmark:
     needs: [benchmark]
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
       - name: Comment PR
         uses: thollander/actions-comment-pull-request@v1

package/.github/workflows/ci.yml

@@ -12,36 +12,6 @@ on:
 
 jobs:
   test:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        node-version: [14, 16, 17]
-        os: [macos-latest, ubuntu-latest, windows-latest]
-
-    steps:
-      - uses: actions/checkout@v2
-
-      - name: Use Node.js
-        uses: actions/setup-node@v2
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Install Dependencies
-        run: |
-          npm install --ignore-scripts
-
-      - name: Run Tests
-        run: |
-          npm test
-
-  automerge:
-    needs: test
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-      contents: write
-    steps:
-      - uses: fastify/github-action-merge-dependabot@v3
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          target: minor
+    uses: fastify/workflows/.github/workflows/plugins-ci.yml@v3
+    with:
+      auto-merge-exclude: 'chalk'

package/README.md

@@ -2,13 +2,12 @@
 
 ![CI](https://github.com/fastify/fast-json-stringify/workflows/CI/badge.svg)
 [![NPM version](https://img.shields.io/npm/v/fast-json-stringify.svg?style=flat)](https://www.npmjs.com/package/fast-json-stringify)
-[![Known Vulnerabilities](https://snyk.io/test/github/fastify/fast-json-stringify/badge.svg)](https://snyk.io/test/github/fastify/fast-json-stringify)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
 [![NPM downloads](https://img.shields.io/npm/dm/fast-json-stringify.svg?style=flat)](https://www.npmjs.com/package/fast-json-stringify)
 
 
-__fast-json-stringify__ is significantly faster than `JSON.stringify()` for small payloads.  
-Its performance advantage shrinks as your payload grows.  
+__fast-json-stringify__ is significantly faster than `JSON.stringify()` for small payloads.
+Its performance advantage shrinks as your payload grows.
 It pairs well with [__flatstr__](https://www.npmjs.com/package/flatstr), which triggers a V8 optimization that improves performance when eventually converting the string to a `Buffer`.
 
 
@@ -56,11 +55,12 @@ compile-json-stringify date format x 1,086,187 ops/sec ±0.16% (99 runs sampled)
  - <a href="#missingFields">`Missing fields`</a>
  - <a href="#patternProperties">`Pattern Properties`</a>
  - <a href="#additionalProperties">`Additional Properties`</a>
- - <a href="#anyof">`AnyOf` and `OneOf`</a>
+ - <a href="#AnyOf-and-OneOf">`AnyOf` and `OneOf`</a>
  - <a href="#ref">`Reuse - $ref`</a>
  - <a href="#long">`Long integers`</a>
  - <a href="#integer">`Integers`</a>
  - <a href="#nullable">`Nullable`</a>
+ - <a href="#largearrays">`Large Arrays`</a>
 - <a href="#security">`Security Notice`</a>
 - <a href="#acknowledgements">`Acknowledgements`</a>
 - <a href="#license">`License`</a>
@@ -117,6 +117,8 @@ const stringify = fastJson(mySchema, {
 - `schema`: external schemas references by $ref property. [More details](#ref)
 - `ajv`: [ajv v8 instance's settings](https://ajv.js.org/options.html) for those properties that require `ajv`. [More details](#anyof)
 - `rounding`: setup how the `integer` types will be rounded when not integers. [More details](#integer)
+- `largeArrayMechanism`: set the mechanism that should be used to handle large
+(by default `20000` or more items) arrays. [More details](#largearrays)
 
 
 <a name="api"></a>
@@ -157,18 +159,17 @@ And nested ones, too.
 
 **Note**: In the case of string formatted Date and not Date Object, there will be no manipulation on it. It should be properly formatted.
 
-Example with a MomentJS object:
+Example with a Date object:
 
 ```javascript
-const moment = require('moment')
-
 const stringify = fastJson({
   title: 'Example Schema with string date-time field',
   type: 'string',
   format: 'date-time'
 })
 
-console.log(stringify(moment())) // '"YYYY-MM-DDTHH:mm:ss.sssZ"'
+const date = new Date()
+console.log(stringify(date)) // '"YYYY-MM-DDTHH:mm:ss.sssZ"'
 ```
 
 
@@ -268,7 +269,7 @@ const stringify = fastJson({
 const obj = {
   nickname: 'nick',
   matchfoo: 42,
-  otherfoo: 'str'
+  otherfoo: 'str',
   matchnum: 3
 }
 
@@ -284,7 +285,7 @@ console.log(stringify(obj)) // '{"matchfoo":"42","otherfoo":"str","matchnum":3,"
 If *additionalProperties* is not present or is set to `false`, every property that is not explicitly listed in the *properties* and *patternProperties* objects,will be ignored, as described in <a href="#missingFields">Missing fields</a>.
 Missing fields are ignored to avoid having to rewrite objects before serializing. However, other schema rules would throw in similar situations.
 If *additionalProperties* is set to `true`, it will be used by `JSON.stringify` to stringify the additional properties. If you want to achieve maximum performance, we strongly encourage you to use a fixed schema where possible.
-The additional properties will always be serialzied at the end of the object.
+The additional properties will always be serialized at the end of the object.
 Example:
 ```javascript
 const stringify = fastJson({
@@ -311,7 +312,7 @@ const stringify = fastJson({
 const obj = {
   nickname: 'nick',
   matchfoo: 42,
-  otherfoo: 'str'
+  otherfoo: 'str',
   matchnum: 3,
   nomatchstr: 'valar morghulis',
   nomatchint: 313
@@ -582,6 +583,59 @@ Otherwise, instead of raising an error, null values will be coerced as follows:
 - `string` -> `""`
 - `boolean` -> `false`
 
+<a name="largearrays"></a>
+#### Large Arrays
+
+Large arrays are, for the scope of this document, defined as arrays containing,
+by default, `20000` elements or more. That value can be adjusted via the option
+parameter `largeArraySize`.
+
+At some point the overhead caused by the default mechanism used by
+`fast-json-stringify` to handle arrays starts increasing exponentially, leading
+to slow overall executions.
+
+##### Settings
+
+In order to improve that the user can set the `largeArrayMechanism` and
+`largeArraySize` options.
+
+`largeArrayMechanism`'s default value is `default`. Valid values for it are:
+
+- `default` - This option is a compromise between performance and feature set by
+still providing the expected functionality out of this lib but giving up some
+possible performance gain. With this option set, **large arrays** would be
+stringified by joining their stringified elements using `Array.join` instead of
+string concatenation for better performance
+- `json-stringify` - This option will remove support for schema validation
+within **large arrays** completely. By doing so the overhead previously
+mentioned is nulled, greatly improving execution time. Mind there's no change
+in behavior for arrays not considered _large_
+
+`largeArraySize`'s default value is `20000`. Valid values for it are
+integer-like values, such as:
+
+- `20000`
+- `2e4`
+- `'20000'`
+- `'2e4'` - _note this will be converted to `2`, not `20000`_
+- `1.5` - _note this will be converted to `1`_
+
+##### Benchmarks
+
+For reference, here goes some benchmarks for comparison over the three
+mechanisms. Benchmarks conducted on an old machine.
+
+- Machine: `ST1000LM024 HN-M 1TB HDD, Intel Core i7-3610QM @ 2.3GHz, 12GB RAM, 4C/8T`.
+- Node.js `v16.13.1`
+
+```
+JSON.stringify large array x 157 ops/sec ±0.73% (86 runs sampled)
+fast-json-stringify large array default x 48.72 ops/sec ±4.92% (48 runs sampled)
+fast-json-stringify large array json-stringify x 157 ops/sec ±0.76% (86 runs sampled)
+compile-json-stringify large array x 175 ops/sec ±4.47% (79 runs sampled)
+AJV Serialize large array x 58.76 ops/sec ±4.59% (60 runs sampled)
+```
+
 <a name="security"></a>
 ## Security notice
 

package/benchmark/bench-cmp-branch.js

@@ -0,0 +1,114 @@
+'use strict'
+
+const { spawn } = require('child_process')
+
+const chalk = require('chalk')
+const inquirer = require('inquirer')
+const simpleGit = require('simple-git')
+
+const git = simpleGit(process.cwd())
+
+const COMMAND = 'npm run bench'
+const DEFAULT_BRANCH = 'master'
+const PERCENT_THRESHOLD = 5
+
+async function selectBranchName (message, branches) {
+  const result = await inquirer.prompt([{
+    type: 'list',
+    name: 'branch',
+    choices: branches,
+    loop: false,
+    pageSize: 20,
+    message
+  }])
+  return result.branch
+}
+
+async function executeCommandOnBranch (command, branch) {
+  console.log(chalk.grey(`Checking out "${branch}"`))
+  await git.checkout(branch)
+
+  console.log(chalk.grey(`Execute "${command}"`))
+  const childProcess = spawn(command, { stdio: 'pipe', shell: true })
+
+  let result = ''
+  childProcess.stdout.on('data', (data) => {
+    process.stdout.write(data.toString())
+    result += data.toString()
+  })
+
+  await new Promise(resolve => childProcess.on('close', resolve))
+
+  console.log()
+
+  return parseBenchmarksStdout(result)
+}
+
+function parseBenchmarksStdout (text) {
+  const results = []
+
+  const lines = text.split('\n')
+  for (const line of lines) {
+    const match = /^(.+?)(\.*) x (.+) ops\/sec .*$/.exec(line)
+    if (match !== null) {
+      results.push({
+        name: match[1],
+        alignedName: match[1] + match[2],
+        result: parseInt(match[3].split(',').join(''))
+      })
+    }
+  }
+
+  return results
+}
+
+function compareResults (featureBranch, mainBranch) {
+  for (const { name, alignedName, result: mainBranchResult } of mainBranch) {
+    const featureBranchBenchmark = featureBranch.find(result => result.name === name)
+    if (featureBranchBenchmark) {
+      const featureBranchResult = featureBranchBenchmark.result
+      const percent = (featureBranchResult - mainBranchResult) * 100 / mainBranchResult
+      const roundedPercent = Math.round(percent * 100) / 100
+
+      const percentString = roundedPercent > 0 ? `+${roundedPercent}%` : `${roundedPercent}%`
+      const message = alignedName + percentString.padStart(7, '.')
+
+      if (roundedPercent > PERCENT_THRESHOLD) {
+        console.log(chalk.green(message))
+      } else if (roundedPercent < -PERCENT_THRESHOLD) {
+        console.log(chalk.red(message))
+      } else {
+        console.log(message)
+      }
+    }
+  }
+}
+
+(async function () {
+  const branches = await git.branch()
+  const currentBranch = branches.branches[branches.current]
+
+  let featureBranch = null
+  let mainBranch = null
+
+  if (process.argv[2] === '--ci') {
+    featureBranch = currentBranch.name
+    mainBranch = DEFAULT_BRANCH
+  } else {
+    featureBranch = await selectBranchName('Select the branch you want to compare (feature branch):', branches.all)
+    mainBranch = await selectBranchName('Select the branch you want to compare with (main branch):', branches.all)
+  }
+
+  try {
+    const featureBranchResult = await executeCommandOnBranch(COMMAND, featureBranch)
+    const mainBranchResult = await executeCommandOnBranch(COMMAND, mainBranch)
+    compareResults(featureBranchResult, mainBranchResult)
+  } catch (error) {
+    console.error('Switch to origin branch due to an error', error.message)
+  }
+
+  await git.checkout(currentBranch.commit)
+  await git.checkout(currentBranch.name)
+
+  console.log(chalk.gray(`Back to ${currentBranch.name} ${currentBranch.commit}`))
+})()

package/{bench.js → benchmark/bench-cmp-lib.js}

@@ -3,6 +3,10 @@
 const benchmark = require('benchmark')
 const suite = new benchmark.Suite()
 
+const STR_LEN = 1e4
+const LARGE_ARRAY_SIZE = 2e4
+const MULTI_ARRAY_LENGTH = 1e3
+
 const schema = {
   title: 'Example Schema',
   type: 'object',
@@ -89,7 +93,8 @@ const obj = {
 
 const date = new Date()
 
-const multiArray = []
+const multiArray = new Array(MULTI_ARRAY_LENGTH)
+const largeArray = new Array(LARGE_ARRAY_SIZE)
 
 const CJS = require('compile-json-stringify')
 const CJSStringify = CJS(schemaCJS)
@@ -97,9 +102,12 @@ const CJSStringifyArray = CJS(arraySchemaCJS)
 const CJSStringifyDate = CJS(dateFormatSchemaCJS)
 const CJSStringifyString = CJS({ type: 'string' })
 
-const FJS = require('.')
+const FJS = require('..')
 const stringify = FJS(schema)
-const stringifyArray = FJS(arraySchema)
+const stringifyArrayDefault = FJS(arraySchema)
+const stringifyArrayJSONStringify = FJS(arraySchema, {
+  largeArrayMechanism: 'json-stringify'
+})
 const stringifyDate = FJS(dateFormatSchema)
 const stringifyString = FJS({ type: 'string' })
 let str = ''
@@ -110,18 +118,48 @@ const ajvSerialize = ajv.compileSerializer(schemaAJVJTD)
 const ajvSerializeArray = ajv.compileSerializer(arraySchemaAJVJTD)
 const ajvSerializeString = ajv.compileSerializer({ type: 'string' })
 
+const getRandomString = (length) => {
+  if (!Number.isInteger(length)) {
+    throw new Error('Expected integer length')
+  }
+
+  const validCharacters = 'abcdefghijklmnopqrstuvwxyz'
+  const nValidCharacters = 26
+
+  let result = ''
+  for (let i = 0; i < length; ++i) {
+    result += validCharacters[Math.floor(Math.random() * nValidCharacters)]
+  }
+
+  return result[0].toUpperCase() + result.slice(1)
+}
+
 // eslint-disable-next-line
-for (var i = 0; i < 10000; i++) {
+for (let i = 0; i < STR_LEN; i++) {
+  largeArray[i] = {
+    firstName: getRandomString(8),
+    lastName: getRandomString(6),
+    age: Math.ceil(Math.random() * 99)
+  }
+
   str += i
   if (i % 100 === 0) {
     str += '"'
   }
 }
 
+for (let i = STR_LEN; i < LARGE_ARRAY_SIZE; ++i) {
+  largeArray[i] = {
+    firstName: getRandomString(10),
+    lastName: getRandomString(4),
+    age: Math.ceil(Math.random() * 99)
+  }
+}
+
 Number(str)
 
-for (i = 0; i < 1000; i++) {
-  multiArray.push(obj)
+for (let i = 0; i < MULTI_ARRAY_LENGTH; i++) {
+  multiArray[i] = obj
 }
 
 suite.add('FJS creation', function () {
@@ -138,8 +176,12 @@ suite.add('JSON.stringify array', function () {
   JSON.stringify(multiArray)
 })
 
-suite.add('fast-json-stringify array', function () {
-  stringifyArray(multiArray)
+suite.add('fast-json-stringify array default', function () {
+  stringifyArrayDefault(multiArray)
+})
+
+suite.add('fast-json-stringify array json-stringify', function () {
+  stringifyArrayJSONStringify(multiArray)
 })
 
 suite.add('compile-json-stringify array', function () {
@@ -150,6 +192,26 @@ suite.add('AJV Serialize array', function () {
   ajvSerializeArray(multiArray)
 })
 
+suite.add('JSON.stringify large array', function () {
+  JSON.stringify(largeArray)
+})
+
+suite.add('fast-json-stringify large array default', function () {
+  stringifyArrayDefault(largeArray)
+})
+
+suite.add('fast-json-stringify large array json-stringify', function () {
+  stringifyArrayJSONStringify(largeArray)
+})
+
+suite.add('compile-json-stringify large array', function () {
+  CJSStringifyArray(largeArray)
+})
+
+suite.add('AJV Serialize large array', function () {
+  ajvSerializeArray(largeArray)
+})
+
 suite.add('JSON.stringify long string', function () {
   JSON.stringify(str)
 })

package/benchmark/bench-thread.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const { workerData: benchmark, parentPort } = require('worker_threads')
+
+const Benchmark = require('benchmark')
+Benchmark.options.minSamples = 500
+
+const suite = Benchmark.Suite()
+
+const FJS = require('..')
+const stringify = FJS(benchmark.schema)
+
+suite
+  .add(benchmark.name, () => {
+    stringify(benchmark.input)
+  })
+  .on('cycle', (event) => {
+    parentPort.postMessage(String(event.target))
+  })
+  .on('complete', () => {})
+  .run()