fast-json-stringify

fast-json-stringify  

fast-json-stringify is x1-4 times faster than JSON.stringify(). It is particularly suited if you are sending small JSON payloads, the advantages reduces on large payloads.

Benchmarks:

JSON.stringify array x 3,343 ops/sec ±1.28% (86 runs sampled)
fast-json-stringify array x 3,031 ops/sec ±1.38% (88 runs sampled)
fast-json-stringify-uglified array x 3,222 ops/sec ±1.12% (87 runs sampled)
JSON.stringify long string x 12,400 ops/sec ±1.25% (88 runs sampled)
fast-json-stringify long string x 12,151 ops/sec ±1.16% (84 runs sampled)
fast-json-stringify-uglified long string x 12,304 ops/sec ±1.00% (87 runs sampled)
JSON.stringify short string x 4,384,078 ops/sec ±1.53% (88 runs sampled)
fast-json-stringify short string x 11,062,569 ops/sec ±1.10% (85 runs sampled)
fast-json-stringify-uglified short string x 10,642,943 ops/sec ±3.01% (86 runs sampled)
JSON.stringify obj x 1,612,312 ops/sec ±1.40% (87 runs sampled)
fast-json-stringify obj x 3,149,885 ops/sec ±1.46% (85 runs sampled)
fast-json-stringify-uglified obj x 3,374,838 ops/sec ±1.35% (87 runs sampled)

Benchmarks taken on Node 6.11.0.

Table of contents:

• Example
• API
• fastJsonStringify
• Specific use cases
• Required
• Missing fields
• Pattern Properties
• Additional Properties
• Reuse - $ref
• Long integers
• Uglify
• Acknowledgements
• License

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: /"([^"]|\\")*"/
}))

API

fastJsonStringify(schema)

Build a stringify() function based on jsonschema.

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

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 has not 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: '[e-mail]'
}

console.log(stringify(obj)) // '{"mail":"[e-mail]"}'

Pattern properties

fast-json-stringify supports pattern properties as defined inside 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$': {
      type: 'string'
    }
  }
})

const obj = {
  nickname: 'nick',
  matchfoo: 42,
  otherfoo: 'str'
  matchnum: 3
}

console.log(stringify(obj)) // '{"matchfoo":"42","otherfoo":"str","matchnum":3,"nickname":"nick"}'

Additional properties

fast-json-stringify supports additional properties as defined inside JSON schema.
additionalProperties must be an object or a boolean, declared in this way: { type: 'type' }.
additionalProperties will work only for the properties that are not explicitly listed in the properties and patternProperties objects.

If additionalProperties is not present or is setted to false, every property that is not explicitly listed in the properties and patternProperties objects, will be ignored, as said in Missing fields.
If additionalProperties is setted to true, it will be used fast-safe-stringify to stringify the additional properties. If you want to achieve maximum performances we strongly encourage you to use a fixed schema where possible.
Example:

const stringify = fastJson({
  title: 'Example Schema',
  type: 'object',
  properties: {
    nickname: {
      type: 'string'
    }
  },
  patternProperties: {
    'num': {
      type: 'number'
    },
    '.*foo$': {
      type: 'string'
    }
  },
  additionalProperties: {
    type: 'string'
  }
})

const obj = {
  nickname: 'nick',
  matchfoo: 42,
  otherfoo: 'str'
  matchnum: 3,
  nomatchstr: 'valar morghulis',
  nomatchint: 313
}

console.log(stringify(obj)) // '{"matchfoo":"42","otherfoo":"str","matchnum":3,"nomatchstr":"valar morghulis",nomatchint:"313","nickname":"nick"}'

Reuse - $ref

If you want to reuse a definition of a value, you can use the property $ref.
The value of $ref must be a string in JSON Pointer format.
Example:

const schema = {
  title: 'Example Schema',
  definitions: {
    num: {
      type: 'object',
      properties: {
        int: {
          type: 'integer'
        }
      }
    },
    str: {
      type: 'string'
    }
  },
  type: 'object',
  properties: {
    nickname: {
      $ref: '#/definitions/str'
    }
  },
  patternProperties: {
    'num': {
      $ref: '#/definitions/num'
    }
  },
  additionalProperties: {
    $ref: '#/definitions/def'
  }
}

const stringify = fastJson(schema)

If you need to use an external definition, you can pass it as an option to fast-json-stringify.
Example:

const schema = {
  title: 'Example Schema',
  type: 'object',
  properties: {
    nickname: {
      $ref: 'strings#/definitions/str'
    }
  },
  patternProperties: {
    'num': {
      $ref: 'numbers#/definitions/num'
    }
  },
  additionalProperties: {
    $ref: 'strings#/definitions/def'
  }
}

const externalSchema = {
  numbers: {
    definitions: {
      num: {
        type: 'object',
        properties: {
          int: {
            type: 'integer'
          }
        }
      }
    }
  },
  strings: require('./string-def.json')
}

const stringify = fastJson(schema, { schema: externalSchema })

Long integers

Long integers (64-bit) are supported using the long module. Example:

const Long = require('long')

const stringify = fastJson({
  title: 'Example Schema',
  type: 'object',
  properties: {
    id: {
      type: 'integer'
    }
  }
})

const obj = {
  id: Long.fromString('18446744073709551615', true)
}

console.log(stringify(obj)) // '{"id":18446744073709551615}'

Uglify

If you want to squeeze a little bit more performance out of the serialisation, at the cost of readability in the generated code, you can pass uglify: true as an option. Note that you have to manually install uglify-es in order for it to work. Only version 3 is supported. Example:

const stringify = fastJson({
  title: 'Example Schema',
  type: 'object',
  properties: {
    id: {
      type: 'integer'
    }
  }
}, { uglify: true })

// stringify is now minified code
console.log(stringify({ some: 'object' })) // '{"some":"object"}'

Acknowledgements

This project was kindly sponsored by nearForm.

License

MIT