README
fast-json-stringify
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, which triggers a V8 optimization that improves performance when eventually converting the string to a Buffer
.
How it works
fast-json-stringify requires a JSON Schema Draft 7 input to generate a fast stringify
function.
Benchmarks
- Machine:
EX41S-SSD, Intel Core i7, 4Ghz, 64GB RAM, 4C/8T, SSD
. - Node.js
v16.9.1
FJS creation x 8,443 ops/sec ±1.01% (90 runs sampled)
CJS creation x 183,219 ops/sec ±0.13% (96 runs sampled)
AJV Serialize creation x 83,541,848 ops/sec ±0.24% (98 runs sampled)
JSON.stringify array x 5,363 ops/sec ±0.11% (100 runs sampled)
fast-json-stringify array x 6,747 ops/sec ±0.13% (98 runs sampled)
compile-json-stringify array x 7,121 ops/sec ±0.42% (98 runs sampled)
AJV Serialize array x 7,533 ops/sec ±0.13% (98 runs sampled)
JSON.stringify long string x 16,461 ops/sec ±0.12% (98 runs sampled)
fast-json-stringify long string x 16,443 ops/sec ±0.37% (99 runs sampled)
compile-json-stringify long string x 16,458 ops/sec ±0.09% (98 runs sampled)
AJV Serialize long string x 21,433 ops/sec ±0.08% (95 runs sampled)
JSON.stringify short string x 12,035,664 ops/sec ±0.62% (96 runs sampled)
fast-json-stringify short string x 38,281,060 ops/sec ±0.24% (98 runs sampled)
compile-json-stringify short string x 32,388,037 ops/sec ±0.27% (97 runs sampled)
AJV Serialize short string x 32,288,612 ops/sec ±0.32% (95 runs sampled)
JSON.stringify obj x 3,068,185 ops/sec ±0.16% (98 runs sampled)
fast-json-stringify obj x 10,082,694 ops/sec ±0.10% (97 runs sampled)
compile-json-stringify obj x 17,037,963 ops/sec ±1.17% (97 runs sampled)
AJV Serialize obj x 9,660,041 ops/sec ±0.11% (97 runs sampled)
JSON stringify date x 1,084,008 ops/sec ±0.16% (98 runs sampled)
fast-json-stringify date format x 1,781,044 ops/sec ±0.48% (99 runs sampled)
compile-json-stringify date format x 1,086,187 ops/sec ±0.16% (99 runs sampled)
Table of contents:
Example
Options
API
fastJsonStringify
Specific use cases
Required
Missing fields
Pattern Properties
Additional Properties
AnyOf
andOneOf
Reuse - $ref
Long integers
Integers
Nullable
Security Notice
Acknowledgements
License
Try it out on RunKit: https://runkit.com/npm/fast-json-stringify
Example
const fastJson = require('fast-json-stringify')
const stringify = fastJson({
title: 'Example Schema',
type: 'object',
properties: {
firstName: {
type: 'string'
},
lastName: {
type: 'string'
},
age: {
description: 'Age in years',
type: 'integer'
},
reg: {
type: 'string'
}
}
})
console.log(stringify({
firstName: 'Matteo',
lastName: 'Collina',
age: 32,
reg: /"([^"]|\\")*"/
}))
Options
Optionally, you may provide to fast-json-stringify
an option object as second parameter:
const fastJson = require('fast-json-stringify')
const stringify = fastJson(mySchema, {
schema: { ... },
ajv: { ... },
rounding: 'ceil'
})
schema
: external schemas references by $ref property. More detailsajv
: ajv v8 instance's settings for those properties that requireajv
. More detailsrounding
: setup how theinteger
types will be rounded when not integers. More details
API
fastJsonStringify(schema)
Build a stringify()
function based on jsonschema draft 7 spec.
Supported types:
'string'
'integer'
'number'
'array'
'object'
'boolean'
'null'
And nested ones, too.
Specific use cases
Instance | Serialized as |
---|---|
Date |
string via toISOString() |
RegExp |
string |
BigInt |
integer via toString |
JSON Schema built-in formats for dates are supported and will be serialized as:
Format | Serialized format example |
---|---|
date-time |
2020-04-03T09:11:08.615Z |
date |
2020-04-03 |
time |
09:11:08 |
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:
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"'
Required
You can set specific fields of an object as required in your schema by adding the field name inside the required
array in your schema.
Example:
const schema = {
title: 'Example Schema with required field',
type: 'object',
properties: {
nickname: {
type: 'string'
},
mail: {
type: 'string'
}
},
required: ['mail']
}
If the object to stringify is missing the required field(s), fast-json-stringify
will throw an error.
Missing fields
If a field is present in the schema (and is not required) but it is not present in the object to stringify, fast-json-stringify
will not write it in the final string.
Example:
const stringify = fastJson({
title: 'Example Schema',
type: 'object',
properties: {
nickname: {
type: 'string'
},
mail: {
type: 'string'
}
}
})
const obj = {
mail: 'mail@example.com'
}
console.log(stringify(obj)) // '{"mail":"mail@example.com"}'
Defaults
fast-json-stringify
supports default
jsonschema key in order to serialize a value
if it is undefined
or not present.
Example:
const stringify = fastJson({
title: 'Example Schema',
type: 'object',
properties: {
nickname: {
type: 'string',
default: 'the default string'
}
}
})
console.log(stringify({})) // '{"nickname":"the default string"}'
console.log(stringify({nickname: 'my-nickname'})) // '{"nickname":"my-nickname"}'
Pattern properties
fast-json-stringify
supports pattern properties as defined by JSON schema.
patternProperties must be an object, where the key is a valid regex and the value is an object, declared in this way: { type: 'type' }
.
patternProperties will work only for the properties that are not explicitly listed in the properties object.
Example:
const stringify = fastJson({
title: 'Example Schema',
type: 'object',
properties: {
nickname: {
type: 'string'
}
},
patternProperties: {
'num': {
type: 'number'
},
'.*foo