fast-json-stringify 7.2.0 → 7.3.0

package/.github/workflows/release.yml

@@ -19,6 +19,6 @@ jobs:
     permissions:
       id-token: write # required for npm provenance via OIDC
       contents: write # required to push the release commit and the tag
-    uses: fastify/workflows/.github/workflows/reusable-release.yml@b1a11bce713bc857e52b2231fec3c89071ad3135
+    uses: fastify/workflows/.github/workflows/reusable-release.yml@731d0cca9a6a5b9586dad6b0326d49001ab9216f
     with:
       semver: ${{ inputs.semver }}

package/README.md

@@ -135,9 +135,8 @@ are rejected before compilation.
 - `inlineValidators`: when using standalone mode, embed Ajv-generated validator functions in the output instead of compiling schemas at runtime. [More details](#standalone)
 - `largeArrayMechanism`: set the mechanism that should be used to handle large
 (by default `20000` or more items) arrays. [More details](#largearrays)
-- `compileValidators`: when `true`, the `ajv` validators used by `anyOf`, `oneOf` and
-`if/then/else` are compiled during `build()` instead of lazily, on the first serialization
-that reaches them. This makes `build()` slower but removes a potentially large one-off cost
+- `objectMechanism`: set the mechanism used to serialize objects. `'native'` projects the input into schema-shaped scratch objects and delegates to the native `JSON.stringify`, which is much faster on Node.js 25+. [More details](#objectmechanism)
+- `compileValidators`: when `true`, the `ajv` validators used by `anyOf`, `oneOf` and `if/then/else` are compiled during `build()` instead of lazily, on the first serialization that reaches them. This makes `build()` slower but removes a potentially large one-off cost
 from the first `stringify()` call. Defaults to `false`.
 
 
@@ -673,6 +672,52 @@ In [standalone mode](#standalone) the cutoffs are baked into the generated
 code, so the generated module inherits the cutoffs of the Node.js version that
 ran `build()`, not of the one that runs the module.
 
+<a name="objectmechanism"></a>
+#### Object mechanism
+
+By default every object is serialized by generated code that appends the JSON
+text property by property. Since V8 13.8 (Node.js 25+) the native
+`JSON.stringify` has a side-effect-free fast path that no JavaScript string
+building can match, but that fast path bails out as soon as the input carries a
+`Date`, a `toJSON`, a class prototype or any property that is not plain data.
+
+With `objectMechanism: 'native'`, `fast-json-stringify` instead *projects* the
+input into preallocated scratch objects whose keys are exactly the schema
+properties, in schema order, and hands the scratch to the native
+`JSON.stringify`. The scratch is plain by construction, so the fast path is
+always taken, whatever the input looks like, while the schema is still applied:
+undeclared properties are dropped, `required` is enforced, `default` applied,
+types coerced and `format: date-time` / `date` / `time` rendered as before.
+The output is byte-identical to the default mechanism.
+
+```js
+const stringify = fastJson(schema, { objectMechanism: 'native' })
+```
+
+The projection covers schemas made only of:
+
+- `object` with `properties` (no `additionalProperties`, `patternProperties`,
+  `nullable`, `dependencies`, combinators or `$ref`), with at least one property;
+- `string` (optionally with `format: date-time`, `date` or `time`), `number`,
+  `integer`, `boolean`, without `nullable`, `const`, `enum`, combinators or `$ref`;
+- the two-element forms `['string', 'null']`, `['number', 'null']` and
+  `['boolean', 'null']` (in either order), with the same strict type dispatch
+  as the default mechanism;
+- `array` whose `items` is one such schema (no tuples), nested to any depth;
+  every array element gets its own scratch objects.
+
+Any other schema silently uses the default mechanism, so the option is always
+safe to enable. The projection only pays off where V8 has the fast path, so on
+Node.js 24 and older the option is a no-op and the default mechanism is used.
+On Node.js 25+ the projection serializes plain objects within 5-15% of a bare
+`JSON.stringify` (the default mechanism is 35-50% behind it there), and objects
+coming from an ORM (extra columns, `Date` instances, class prototypes) several
+times faster than both the default mechanism and `JSON.stringify` itself.
+
+The scratch objects are reused across calls; `JSON.stringify` is synchronous,
+so this is safe, and no reference to the last input is retained beyond the
+primitive values written into the scratch.
+
 <a name="unsafe"></a>
 #### Unsafe string
 By default, the library escapes all strings. With the 'unsafe' format, the string isn't escaped. This has a potentially dangerous security issue. You can use it only if you are sure that your data doesn't need escaping. The advantage is a significant performance improvement.

package/benchmark/bench-cmp-lib.js

@@ -114,6 +114,7 @@ const CJSStringifyString = CJS({ type: 'string' })
 
 const FJS = require('..')
 const stringify = FJS(schema)
+const stringifyNative = FJS(schema, { objectMechanism: 'native' })
 const stringifyArrayDefault = FJS(arraySchema)
 const stringifyArrayJSONStringify = FJS(arraySchema, {
   largeArrayMechanism: 'json-stringify'
@@ -282,6 +283,10 @@ suite.add('fast-json-stringify: obj', function () {
   Buffer.byteLength(stringify(obj))
 })
 
+suite.add('fast-json-stringify [native]: obj', function () {
+  Buffer.byteLength(stringifyNative(obj))
+})
+
 suite.add('json-accelerator: obj', function () {
   Buffer.byteLength(accelStringify(obj))
 })
@@ -312,8 +317,10 @@ suite.add('compile-json-stringify: date', function () {
 
 for (const { name, schema: responseSchema, input } of apiResponses) {
   const stringifyResponse = FJS(responseSchema)
+  const stringifyResponseNative = FJS(responseSchema, { objectMechanism: 'native' })
   // Check outside the timed loop that the schema preserves the complete response.
   assert.deepStrictEqual(JSON.parse(stringifyResponse(input)), JSON.parse(JSON.stringify(input)))
+  assert.equal(stringifyResponseNative(input), stringifyResponse(input))
 
   suite.add(`JSON.stringify: ${name}`, function () {
     Buffer.byteLength(JSON.stringify(input))
@@ -321,6 +328,9 @@ for (const { name, schema: responseSchema, input } of apiResponses) {
   suite.add(`fast-json-stringify: ${name}`, function () {
     Buffer.byteLength(stringifyResponse(input))
   })
+  suite.add(`fast-json-stringify [native]: ${name}`, function () {
+    Buffer.byteLength(stringifyResponseNative(input))
+  })
 }
 
 if (process.argv.includes('--fjs-vs-json')) {

package/benchmark/bench.js

@@ -300,6 +300,80 @@ const benchmarks = [
     },
     input: { firstName: 'Max', lastName: 'Power', age: 22 }
   },
+  {
+    name: 'nested object with array and required',
+    schema: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: { type: 'integer' },
+        name: { type: 'string' },
+        email: { type: 'string' },
+        active: { type: 'boolean' },
+        score: { type: 'number' },
+        tags: { type: 'array', items: { type: 'string' } },
+        address: {
+          type: 'object',
+          properties: {
+            street: { type: 'string' },
+            city: { type: 'string' },
+            zip: { type: 'string' }
+          }
+        }
+      }
+    },
+    input: { id: 1, name: 'John Doe', email: 'john@example.com', active: true, score: 42.195, tags: ['a', 'b', 'c'], address: { street: '1 Example Street', city: 'London', zip: 'SW1A 1AA' } }
+  },
+  {
+    name: 'nested object with array and required (objectMechanism: native)',
+    schema: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: { type: 'integer' },
+        name: { type: 'string' },
+        email: { type: 'string' },
+        active: { type: 'boolean' },
+        score: { type: 'number' },
+        tags: { type: 'array', items: { type: 'string' } },
+        address: {
+          type: 'object',
+          properties: {
+            street: { type: 'string' },
+            city: { type: 'string' },
+            zip: { type: 'string' }
+          }
+        }
+      }
+    },
+    options: { objectMechanism: 'native' },
+    input: { id: 1, name: 'John Doe', email: 'john@example.com', active: true, score: 42.195, tags: ['a', 'b', 'c'], address: { street: '1 Example Street', city: 'London', zip: 'SW1A 1AA' } }
+  },
+  {
+    name: 'nested object with extra props and Date (objectMechanism: native)',
+    schema: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: { type: 'integer' },
+        name: { type: 'string' },
+        email: { type: 'string' },
+        active: { type: 'boolean' },
+        score: { type: 'number' },
+        tags: { type: 'array', items: { type: 'string' } },
+        address: {
+          type: 'object',
+          properties: {
+            street: { type: 'string' },
+            city: { type: 'string' },
+            zip: { type: 'string' }
+          }
+        }
+      }
+    },
+    options: { objectMechanism: 'native' },
+    input: { id: 1, name: 'John Doe', email: 'john@example.com', active: true, score: 42.195, tags: ['a', 'b', 'c'], address: { street: '1 Example Street', city: 'London', zip: 'SW1A 1AA' }, passwordHash: 'x', createdAt: new Date(0) }
+  },
   {
     name: 'oneOf external refs compile and first stringify',
     compile: true,

package/index.js

@@ -7,6 +7,7 @@ const { MergeError } = require('@fastify/merge-json-schemas')
 
 const Serializer = require('./lib/serializer')
 const Validator = require('./lib/validator')
+const { buildProjection } = require('./lib/projection')
 const Location = require('./lib/location')
 const validate = require('./lib/schema-validator')
 const mergeSchemas = require('./lib/merge-schemas')
@@ -41,6 +42,9 @@ const NAMED_FRAGMENT_REF = /^#[a-z_][-\w._]*$/i
 // TODO: drop the Node 20 tier (and this version check) once Node 20 is no
 // longer supported.
 const nodeMajor = Number.parseInt(process.versions.node, 10)
+// V8 13.8 (Node 25+) introduced the side-effect-free JSON.stringify fast path
+// that objectMechanism: 'native' relies on.
+const PROJECTION_SUPPORTED = nodeMajor >= 25
 const PRIMITIVE_FAST_PATH_MIN_LENGTH = [{ integer: 3e5, number: 3e5, string: 128 }, { integer: 512, number: 128, string: 8 }][+(nodeMajor >= 22)]
 const STRING_ARRAY_FAST_PATH_MIN_LENGTH = PRIMITIVE_FAST_PATH_MIN_LENGTH.string
 const INTEGER_ARRAY_FAST_PATH = { condition: 'Number.isInteger(v)', minLength: PRIMITIVE_FAST_PATH_MIN_LENGTH.integer }
@@ -97,6 +101,11 @@ const validLargeArrayMechanisms = new Set([
   'json-stringify'
 ])
 
+const validObjectMechanisms = new Set([
+  'default',
+  'native'
+])
+
 // Keywords that do not change the output, so a $ref carrying only these
 // can still be dereferenced directly instead of merged with its target.
 const IGNORED_REF_SIBLING_KEYWORDS = new Set([
@@ -442,6 +451,7 @@ function build (schema, options) {
     buildingSet: new Set(),
     largeArraySize: 2e4,
     largeArrayMechanism: 'default',
+    objectMechanism: 'default',
     uid: 0
   }
 
@@ -479,6 +489,14 @@ function build (schema, options) {
     }
   }
 
+  if (options.objectMechanism) {
+    if (validObjectMechanisms.has(options.objectMechanism)) {
+      context.objectMechanism = options.objectMechanism
+    } else {
+      throw new Error(`Unsupported object mechanism ${options.objectMechanism}`)
+    }
+  }
+
   if (options.largeArraySize) {
     const largeArraySizeType = typeof options.largeArraySize
     let parsedNumber
@@ -500,7 +518,24 @@ function build (schema, options) {
   if (hasRef) {
     detectRecursiveSchemas(context, location)
   }
-  const code = buildValue(context, location, 'input')
+
+  // objectMechanism: 'native' projects the input into shape-stable scratch
+  // objects and delegates to the native JSON.stringify. Only whole schemas
+  // made of objects, arrays and primitives qualify; anything else falls back
+  // to the string codegen below, so output never changes for unsupported shapes.
+  // The projection only pays off where V8 has the side-effect-free
+  // JSON.stringify fast path (V8 13.8+, Node 25+): on older runtimes the
+  // string codegen is up to 2x faster, so the option is a no-op there.
+  let code = null
+  let projection = null
+  // `forceProjection` is an internal, undocumented escape hatch used by the
+  // test suite to exercise the projection on runtimes where it is gated off.
+  if (context.objectMechanism === 'native' && (options.forceProjection === true || PROJECTION_SUPPORTED)) {
+    projection = buildProjection(schema)
+  }
+  if (projection === null) {
+    code = buildValue(context, location, 'input')
+  }
 
   let contextFunctionCode = `
     ${serializerFns}
@@ -522,7 +557,9 @@ function build (schema, options) {
   // and the overhead of the intermediate variable 'json'. We can avoid the
   // wrapping and the unnecessary memory allocation by aliasing 'anonymous0' to
   // 'main'
-  if (code === 'json += anonymous0(input)') {
+  if (projection !== null) {
+    contextFunctionCode += projection
+  } else if (code === 'json += anonymous0(input)') {
     contextFunctionCode += `
     ${context.functions.join('\n')}
     const main = anonymous0
@@ -1161,7 +1198,7 @@ function buildArray (context, location, input) {
         const tmpRes = buildValue(context, itemLocation, value)
         functionCode += `
         if (${i} < arrayLength) {
-          if (${buildArrayTypeCondition(item.type, value)}) {
+          if (${buildTupleItemCondition(item, value)}) {
             if (${i}) {
               json += JSON_STR_COMMA
             }
@@ -1255,7 +1292,7 @@ function buildArray (context, location, input) {
       const tmpRes = buildValue(context, itemLocation, value)
       inlinedCode += `
         if (${i} < arrayLength_${objVar}) {
-          if (${buildArrayTypeCondition(item.type, value)}) {
+          if (${buildTupleItemCondition(item, value)}) {
             !addComma_${localUid} && (addComma_${localUid} = true) || (json += JSON_STR_COMMA)
             ${tmpRes}
           } else {
@@ -1342,6 +1379,13 @@ function buildArrayTypeCondition (type, accessor) {
   return condition
 }
 
+// A nullable tuple item accepts null on top of its declared type(s);
+// buildValue() then serializes it as `null`.
+function buildTupleItemCondition (item, accessor) {
+  const condition = buildArrayTypeCondition(item.type, accessor)
+  return item.nullable === true ? `${accessor} === null || ${condition}` : condition
+}
+
 function generateFuncName (context) {
   return 'anonymous' + context.functionsCounter++
 }

package/lib/projection.js

@@ -0,0 +1,325 @@
+'use strict'
+
+// Projection strategy (objectMechanism: 'native').
+//
+// Instead of building the JSON string in generated JS, project the input into
+// preallocated "scratch" objects whose keys are exactly the schema properties,
+// in schema order, and hand the scratch to the native JSON.stringify. The
+// scratch is clean by construction (no extra properties, no Date, no toJSON,
+// standard prototypes), so V8's side-effect-free fast path (V8 13.8+) is
+// always taken, even when the user's input would have bailed out of it.
+//
+// Projectable schemas (every node must be one of these):
+//   - object with `properties` only: no additionalProperties, patternProperties,
+//     nullable, combinators, $ref, dependencies; at least one property;
+//   - string / number / integer / boolean without nullable, const, enum,
+//     combinators, $ref; string may have format date-time / date / time;
+//   - the two-element forms ['string'|'number'|'boolean', 'null'] (any order),
+//     with the strict no-coercion dispatch of the multi-type codegen;
+//     ['integer', 'null'] is left to the codegen (its null handling depends
+//     on the type order);
+//   - array whose `items` is a single projectable schema (not a tuple); array
+//     elements get their own scratch tree from a per-element slot pool.
+// Anything else makes buildProjection return null and the caller falls back to
+// the string codegen, so the option never changes output for unsupported
+// schemas.
+//
+// Semantics match the string codegen byte for byte: input.toJSON() honoured,
+// `required` missing throws, `undefined` omitted, `default` applied, null
+// string -> "", null number -> 0, null object -> {}, Date in a string -> ISO,
+// numbers via the asNumber/asInteger rules, booleans via truthiness.
+
+const PRIMITIVES = new Set(['string', 'number', 'integer', 'boolean'])
+const STRING_FORMATS = new Set([undefined, 'date-time', 'date', 'time'])
+
+// ['string'|'number'|'boolean', 'null'] in either order -> the non-null type;
+// anything else -> null. Also requires the format rules of the base type.
+function nullableMultiType (schema) {
+  const t = schema.type
+  if (!Array.isArray(t) || t.length !== 2 || !t.includes('null')) return null
+  const base = t[0] === 'null' ? t[1] : t[0]
+  if (base !== 'string' && base !== 'number' && base !== 'boolean') return null
+  if (base === 'string' ? !STRING_FORMATS.has(schema.format) : schema.format !== undefined) return null
+  return base
+}
+
+function hasDispatchKeyword (s) {
+  return s.nullable === true || s.const !== undefined || s.enum !== undefined ||
+    s.allOf !== undefined || s.anyOf !== undefined || s.oneOf !== undefined ||
+    s.if !== undefined || s.$ref !== undefined
+}
+
+function isProjectable (schema, depth = 0) {
+  if (typeof schema !== 'object' || schema === null || depth > 32) return false
+  if (hasDispatchKeyword(schema)) return false
+  if (Array.isArray(schema.type)) return nullableMultiType(schema) !== null
+
+  if (schema.type === 'object') {
+    if (schema.additionalProperties !== undefined || schema.patternProperties !== undefined ||
+        schema.dependencies !== undefined ||
+        typeof schema.properties !== 'object' || schema.properties === null) {
+      return false
+    }
+    const keys = Object.keys(schema.properties)
+    if (keys.length === 0) return false
+    for (const key of keys) {
+      if (!isProjectable(schema.properties[key], depth + 1)) return false
+    }
+    return true
+  }
+
+  if (schema.type === 'array') {
+    if (schema.items === undefined || Array.isArray(schema.items) || schema.additionalItems !== undefined) return false
+    return isProjectable(schema.items, depth + 1)
+  }
+
+  if (!PRIMITIVES.has(schema.type)) return false
+  if (schema.type === 'string') return STRING_FORMATS.has(schema.format)
+  return schema.format === undefined
+}
+
+function primitiveExpr (schema, src, pointerIdx) {
+  const base = nullableMultiType(schema)
+  if (base !== null) {
+    // Same acceptance rules as the multi-type codegen (buildMultiTypeSerializer):
+    // null passes through; a matching primitive goes through the single-type
+    // conversion; anything else is a TypeError. No coercion across types.
+    const err = `typeMismatch(${pointerIdx})`
+    const single = primitiveExpr({ ...schema, type: base }, src, pointerIdx)
+    if (base === 'string') {
+      return `(${src} === null ? null : (typeof ${src} === 'string' || ${src} instanceof Date || ${src} instanceof RegExp || (typeof ${src} === 'object' && typeof ${src}.toString === 'function' && ${src}.toString !== Object.prototype.toString)) ? ${single} : ${err})`
+    }
+    if (base === 'number') {
+      return `(${src} === null ? null : typeof ${src} === 'number' ? ${single} : ${err})`
+    }
+    return `(${src} === null ? null : typeof ${src} === 'boolean' ? ${src} : ${err})`
+  }
+  switch (schema.type) {
+    case 'string':
+      if (schema.format === 'date-time') return `asDateTimeValue(${src})`
+      if (schema.format === 'date') return `asDateValue(${src})`
+      if (schema.format === 'time') return `asTimeValue(${src})`
+      return `asStringValue(${src})`
+    case 'number': return `asNumberValue(${src})`
+    case 'integer': return `asIntegerValue(${src})`
+    case 'boolean': return `(${src} ? true : false)`
+  }
+}
+
+// Same order as the string codegen: required properties first (stable sort).
+function orderedKeys (schema) {
+  const required = schema.required || []
+  return Object.keys(schema.properties).sort((a, b) => {
+    const ra = required.includes(a); const rb = required.includes(b)
+    return ra === rb ? 0 : ra ? -1 : 1
+  })
+}
+
+class Emitter {
+  constructor () {
+    this.decls = []
+    this.uid = 0
+    // JSON pointers for error messages. The generated code only ever refers
+    // to them by index into this table (emitted as a JSON literal), so no
+    // schema-derived text is interpolated into the code itself.
+    this.pointers = []
+    this.keys = []
+  }
+
+  id (prefix) { return `${prefix}_${this.uid++}` }
+
+  pointerIndex (pointer) {
+    let i = this.pointers.indexOf(pointer)
+    if (i === -1) { i = this.pointers.length; this.pointers.push(pointer) }
+    return i
+  }
+
+  keyIndex (key) {
+    let i = this.keys.indexOf(key)
+    if (i === -1) { i = this.keys.length; this.keys.push(key) }
+    return i
+  }
+
+  scratchLiteral (schema) {
+    return '{ ' + orderedKeys(schema).map((k) => `${JSON.stringify(k)}: undefined`).join(', ') + ' }'
+  }
+
+  // Scratch storage for a schema node. Nodes reachable without crossing an
+  // array are module-level constants (one per serializer). Nodes inside array
+  // items live in a per-slot holder object created by a generated factory, so
+  // that each array element has its own scratch tree.
+  //
+  // `holder` is null at the top level (declare constants) or the expression of
+  // the current slot holder; `slotFields` collects the holder's fields.
+  allocScratch (schema, holder, slotFields) {
+    if (holder === null) {
+      const name = this.id('scratch')
+      this.decls.push(`const ${name} = ${this.scratchLiteral(schema)}`)
+      return name
+    }
+    const field = this.id('s')
+    slotFields.push([field, this.scratchLiteral(schema)])
+    return `${holder}.${field}`
+  }
+
+  allocArray (holder, slotFields) {
+    if (holder === null) {
+      const name = this.id('arr')
+      this.decls.push(`const ${name} = []`)
+      return name
+    }
+    const field = this.id('a')
+    slotFields.push([field, '[]'])
+    return `${holder}.${field}`
+  }
+
+  fillObject (schema, src, dst, out, indent, pointer, holder, slotFields) {
+    const props = schema.properties
+    const requiredList = schema.required || []
+    const required = new Set(requiredList)
+    const keys = orderedKeys(schema)
+    const o = this.id('o')
+    out.push(`${indent}const ${o} = (${src} !== null && typeof ${src} === 'object' && typeof ${src}.toJSON === 'function') ? ${src}.toJSON() : ${src}`)
+    out.push(`${indent}if (${o} === null) {`)
+    for (const k of keys) out.push(`${indent}  ${dst}[${JSON.stringify(k)}] = undefined`)
+    out.push(`${indent}} else {`)
+    for (const k of requiredList) {
+      if (props[k] === undefined) {
+        out.push(`${indent}  if (${o}[${JSON.stringify(k)}] === undefined) requiredMissing(${this.keyIndex(k)})`)
+      }
+    }
+    for (const k of keys) {
+      const p = props[k]
+      const ks = JSON.stringify(k)
+      const v = this.id('v')
+      out.push(`${indent}  const ${v} = ${o}[${ks}]`)
+      out.push(`${indent}  if (${v} === undefined) {`)
+      if (required.has(k)) {
+        out.push(`${indent}    requiredMissing(${this.keyIndex(k)})`)
+      } else if (p.default !== undefined) {
+        out.push(`${indent}    ${dst}[${ks}] = ${JSON.stringify(p.default)}`)
+      } else {
+        out.push(`${indent}    ${dst}[${ks}] = undefined`)
+      }
+      out.push(`${indent}  } else {`)
+      out.push(`${indent}    ${dst}[${ks}] = ${this.valueExpr(p, v, out, indent + '    ', `${pointer}/properties/${k}`, holder, slotFields)}`)
+      out.push(`${indent}  }`)
+    }
+    out.push(`${indent}}`)
+  }
+
+  // Returns an expression for the projected value of `src`; may push
+  // preparatory statements to `out` (filling a nested scratch) first.
+  valueExpr (schema, src, out, indent, pointer, holder, slotFields) {
+    if (schema.type === 'object') {
+      const scratch = this.allocScratch(schema, holder, slotFields)
+      this.fillObject(schema, src, scratch, out, indent, pointer, holder, slotFields)
+      return scratch
+    }
+    if (schema.type === 'array') {
+      const pool = this.allocArray(holder, slotFields)
+      this.fillArray(schema, src, pool, out, indent, pointer, holder, slotFields)
+      return pool
+    }
+    return primitiveExpr(schema, src, this.pointerIndex(pointer))
+  }
+
+  fillArray (schema, src, pool, out, indent, pointer, holder, slotFields) {
+    const items = schema.items
+    const n = this.id('n')
+    const i = this.id('i')
+    out.push(`${indent}if (${src} === null) {`)
+    out.push(`${indent}  ${pool}.length = 0`)
+    out.push(`${indent}} else {`)
+    out.push(`${indent}  if (!Array.isArray(${src})) typeMismatch(${this.pointerIndex(pointer)})`)
+    out.push(`${indent}  const ${n} = ${src}.length`)
+    out.push(`${indent}  ${pool}.length = ${n}`)
+    if (items.type === 'object' || items.type === 'array') {
+      // Pool of per-element slot holders; each holder owns the scratch tree of
+      // one element (nested objects and arrays included). Grows to the longest
+      // array seen, never shrinks. When this array is itself inside an array
+      // element, its slot pool lives in the enclosing holder, so sibling
+      // elements never share scratch objects.
+      const slots = this.allocArray(holder, slotFields)
+      const factory = this.id('makeSlot')
+      const el = this.id('el')
+      const innerHolder = this.id('slot')
+      const innerFields = []
+      const inner = []
+      const expr = this.valueExpr(items, el, inner, indent + '    ', `${pointer}/items`, innerHolder, innerFields)
+      this.decls.push(`function ${factory} () { return { ${innerFields.map(([f, lit]) => `${f}: ${lit}`).join(', ')} } }`)
+      out.push(`${indent}  for (let ${i} = ${slots}.length; ${i} < ${n}; ${i}++) ${slots}[${i}] = ${factory}()`)
+      out.push(`${indent}  for (let ${i} = 0; ${i} < ${n}; ${i}++) {`)
+      out.push(`${indent}    const ${el} = ${src}[${i}]`)
+      out.push(`${indent}    const ${innerHolder} = ${slots}[${i}]`)
+      out.push(...inner)
+      out.push(`${indent}    ${pool}[${i}] = ${expr}`)
+      out.push(`${indent}  }`)
+    } else {
+      out.push(`${indent}  for (let ${i} = 0; ${i} < ${n}; ${i}++) {`)
+      out.push(`${indent}    ${pool}[${i}] = ${primitiveExpr(items, `${src}[${i}]`, this.pointerIndex(`${pointer}/items`))}`)
+      out.push(`${indent}  }`)
+    }
+    out.push(`${indent}}`)
+  }
+}
+
+// Returns the full body of the context function (declarations + main) or null
+// when the schema is not projectable.
+function buildProjection (schema) {
+  if (!isProjectable(schema)) return null
+  if (schema.type !== 'object' && schema.type !== 'array') return null // primitive roots gain nothing
+  const em = new Emitter()
+  const body = []
+  const rootExpr = em.valueExpr(schema, 'input', body, '      ', '#', null, null)
+  // root object: a null input serializes as {} (same as the codegen)
+  body.push(`      return JSON.stringify(${rootExpr})`)
+  return `
+    ${projectionHelpers}
+    const POINTERS = ${JSON.stringify(em.pointers)}
+    const KEYS = ${JSON.stringify(em.keys)}
+    function typeMismatch (i) {
+      throw new TypeError("The value of '" + POINTERS[i] + "' does not match schema definition.")
+    }
+    function requiredMissing (i) {
+      throw new Error('"' + KEYS[i] + '" is required!')
+    }
+    ${em.decls.join('\n    ')}
+    function main (input) {
+${body.join('\n')}
+    }
+    return main
+  `
+}
+
+// Runtime helpers mirroring lib/serializer.js, returning values (not JSON text)
+// to be placed into the scratch.
+const projectionHelpers = `
+  const asStringValue = (v) => {
+    if (typeof v === 'string') return v
+    if (v === null) return ''
+    if (v instanceof Date) return v.toISOString()
+    if (v instanceof RegExp) return v.source
+    return v.toString()
+  }
+  const asDateTimeValue = (v) => {
+    if (v === null) return ''
+    if (v instanceof Date) return v.toISOString()
+    if (typeof v === 'string') return v
+    return v.toString()
+  }
+  const asDateValue = (v) => { const s = serializer.asDate(v); return s.slice(1, -1) }
+  const asTimeValue = (v) => { const s = serializer.asTime(v); return s.slice(1, -1) }
+  const asNumberValue = (v) => {
+    const num = typeof v === 'number' ? v : Number(v)
+    if (num !== num) throw new Error('The value "' + v + '" cannot be converted to a number.')
+    return (num === Infinity || num === -Infinity) ? null : num
+  }
+  const asIntegerValue = (v) => {
+    if (Number.isInteger(v)) return v
+    if (typeof v === 'bigint') return Number(v)
+    return Number(serializer.asInteger(v))
+  }
+`
+
+module.exports = { buildProjection, isProjectable }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fast-json-stringify",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "Stringify your JSON at max speed",
   "main": "index.js",
   "type": "commonjs",

package/test/array.test.js

@@ -411,6 +411,35 @@ test('array items is a schema and additionalItems is false', (t) => {
   t.assert.equal(validate({ foo: ['foo', 'bar'] }), true)
 })
 
+test('array items is a list of schema with nullable items', (t) => {
+  t.plan(6)
+
+  const items = [
+    { type: 'integer', nullable: true },
+    { type: 'number', nullable: true },
+    { type: 'boolean', nullable: true },
+    { type: 'object', nullable: true, properties: { a: { type: 'string' } } },
+    { type: 'array', nullable: true, items: { type: 'string' } },
+    { type: 'string', nullable: true }
+  ]
+  const input = [null, null, null, null, null, null]
+  const expected = '[null,null,null,null,null,null]'
+
+  const inlined = build({ type: 'array', items })
+  t.assert.equal(inlined(input), expected)
+  t.assert.equal(inlined([1, 1.5, true, { a: 'x' }, ['y'], 'z']), '[1,1.5,true,{"a":"x"},["y"],"z"]')
+
+  const withId = build({ $id: 'nullable-tuple', type: 'array', items })
+  t.assert.equal(withId(input), expected)
+  t.assert.equal(withId([1, 1.5, true, { a: 'x' }, ['y'], 'z']), '[1,1.5,true,{"a":"x"},["y"],"z"]')
+
+  const notNullable = build({ type: 'array', items: [{ type: 'integer' }] })
+  t.assert.throws(() => notNullable([null]), /Item at 0 does not match schema definition/)
+
+  const ajv = new Ajv({ allErrors: true, strict: false })
+  t.assert.equal(ajv.validate({ type: 'array', items }, JSON.parse(inlined(input))), true)
+})
+
 test('array items is a list of schema and additionalItems is a schema', (t) => {
   t.plan(1)
 

package/test/object-mechanism-gate.test.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const { test } = require('node:test')
+
+// objectMechanism: 'native' is a no-op on runtimes without the V8 JSON.stringify
+// fast path (Node < 25).
+const build = require('..')
+
+const schema = { type: 'object', properties: { a: { type: 'string' }, n: { type: 'number' } } }
+const nodeMajor = Number.parseInt(process.versions.node, 10)
+
+test('native mechanism is enabled only on Node 25+', t => {
+  t.plan(2)
+  const code = build(schema, { objectMechanism: 'native', mode: 'debug' }).code
+  t.assert.equal(code.includes('asStringValue'), nodeMajor >= 25)
+  // whatever the runtime, output is the same as the default mechanism
+  t.assert.equal(build(schema, { objectMechanism: 'native' })({ a: 'x', n: 1, extra: true }), build(schema)({ a: 'x', n: 1, extra: true }))
+})

package/test/object-mechanism-native.test.js

@@ -0,0 +1,301 @@
+'use strict'
+
+// The projection is only enabled on Node 25+ (V8 13.8+). Force it here so the
+// semantics are tested on every runtime in CI; the gate itself is tested in
+// object-mechanism-gate.test.js.
+const { test } = require('node:test')
+const fjs = require('..')
+const build = (schema, options) => fjs(schema, options && options.objectMechanism === 'native' ? { ...options, forceProjection: true } : options)
+
+// objectMechanism: 'native' must be byte-identical to the default codegen on
+// every projectable schema (same output, or same error), and must fall back to
+// the default codegen on every schema it does not cover.
+
+const userSchema = {
+  type: 'object',
+  required: ['id'],
+  properties: {
+    id: { type: 'integer' },
+    name: { type: 'string' },
+    email: { type: 'string', default: 'none@example.com' },
+    active: { type: 'boolean' },
+    score: { type: 'number' },
+    createdAt: { type: 'string', format: 'date-time' },
+    birthday: { type: 'string', format: 'date' },
+    at: { type: 'string', format: 'time' },
+    tags: { type: 'array', items: { type: 'string' } },
+    scores: { type: 'array', items: { type: 'number' } },
+    address: {
+      type: 'object',
+      required: ['city'],
+      properties: { street: { type: 'string' }, city: { type: 'string' }, zip: { type: 'string' } }
+    },
+    friends: {
+      type: 'array',
+      items: { type: 'object', properties: { id: { type: 'integer' }, name: { type: 'string' } } }
+    }
+  }
+}
+
+class User { constructor (o) { Object.assign(this, o) } }
+
+const base = {
+  id: 1,
+  name: 'Mario "Il" Rossi\n\u0000',
+  email: 'm@x.it',
+  active: true,
+  score: 42.5,
+  createdAt: new Date(0),
+  birthday: new Date(86400000),
+  at: new Date(3600000),
+  tags: ['a', 'b"c', 'd'],
+  scores: [1, 2.5, -3],
+  address: { street: 'Via Roma 1', city: 'Milano', zip: '20100' },
+  friends: [{ id: 2, name: 'Luigi' }, { id: 3, name: 'Peach' }]
+}
+
+const inputs = {
+  base,
+  'extra properties are dropped': { ...base, secret: 'x', internal: { a: 1 } },
+  'class instance': new User(base),
+  'undefined optional is omitted': { ...base, name: undefined, address: undefined, friends: undefined },
+  'missing optional, default applied': { id: 1 },
+  nulls: { id: 1, name: null, email: null, active: null, score: null, createdAt: null, birthday: null, at: null, tags: null, scores: null, address: null, friends: null },
+  'null inside arrays': { id: 1, tags: ['a', null, 'c'], scores: [1, null, 3], friends: [null, { id: 1 }] },
+  coercions: { id: 1.7, name: 123, active: 'yes', score: '3.5', tags: [1, 2], scores: ['4', '5'] },
+  'Date in a plain string': { id: 1, name: new Date(0), tags: [new Date(0)] },
+  'RegExp in a plain string': { id: 1, name: /a"b/, tags: [/c/g] },
+  'date-time given as string': { id: 1, createdAt: '2020-01-01T00:00:00.000Z' },
+  'toJSON on root': { id: 1, toJSON () { return { id: 7, name: 'json' } } },
+  'toJSON on nested object': { id: 1, address: { toJSON () { return { city: 'Roma' } } } },
+  'toJSON on array item': { id: 1, friends: [{ toJSON () { return { id: 9 } } }] },
+  'required missing on root throws': { name: 'no id' },
+  'required missing on nested throws': { id: 1, address: { street: 'x' } },
+  'NaN throws': { id: 1, score: NaN },
+  'Infinity becomes null': { id: 1, score: Infinity },
+  'bigint integer': { id: 10n },
+  'object items with missing fields': { id: 1, friends: [{ id: 1 }, { name: 'x' }, {}] },
+  'empty arrays': { id: 1, tags: [], scores: [], friends: [] },
+  'input key order differs from schema': { friends: [], address: { zip: '1', city: 'c', street: 's' }, score: 1, id: 1 },
+  'null root': null,
+  'non-array where array expected throws': { id: 1, tags: 'abc' }
+}
+
+const run = (fn, v) => {
+  try { return { ok: fn(v) } } catch (e) { return { err: `${e.constructor.name}: ${e.message}` } }
+}
+
+test('native mechanism is byte-identical to the default codegen', t => {
+  const def = build(userSchema)
+  const nat = build(userSchema, { objectMechanism: 'native' })
+  t.plan(Object.keys(inputs).length)
+  for (const [name, input] of Object.entries(inputs)) {
+    t.assert.deepStrictEqual(run(nat, input), run(def, input), name)
+  }
+})
+
+test('native mechanism: array root of objects', t => {
+  const schema = { type: 'array', items: { type: 'object', required: ['id'], properties: { id: { type: 'integer' }, name: { type: 'string' } } } }
+  const def = build(schema)
+  const nat = build(schema, { objectMechanism: 'native' })
+  const data = [
+    [],
+    [{ id: 1, name: 'a' }, { id: 2 }, { id: 3, name: null, extra: true }],
+    Array.from({ length: 50 }, (_, i) => ({ id: i, name: 'n' + i })),
+    [{ name: 'missing id' }],
+    null,
+    'not an array'
+  ]
+  t.plan(data.length + 1)
+  for (const d of data) t.assert.deepStrictEqual(run(nat, d), run(def, d))
+  // pool grows and shrinks with the input length without leaking previous items
+  t.assert.equal(nat([{ id: 1 }]), '[{"id":1}]')
+})
+
+test('native mechanism: array root of primitives', t => {
+  t.plan(3)
+  for (const items of [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }]) {
+    const schema = { type: 'array', items }
+    const d = ['a', 1, null, true, 2.5, 'b']
+    t.assert.deepStrictEqual(run(build(schema, { objectMechanism: 'native' }), d), run(build(schema), d))
+  }
+})
+
+test('native mechanism generates projection code only for projectable schemas', t => {
+  const projectable = [
+    userSchema,
+    { type: 'object', properties: { a: { type: 'string' } } },
+    { type: 'array', items: { type: 'object', properties: { a: { type: 'string' } } } },
+    { type: 'object', properties: { a: { type: 'array', items: { type: 'array', items: { type: 'string' } } } } },
+    { type: 'object', properties: { a: { type: 'array', items: { type: 'object', properties: { b: { type: 'object', properties: { c: { type: 'string' } } } } } } } },
+    { type: 'object', properties: { a: { type: ['string', 'null'] } } }
+  ]
+  const notProjectable = [
+    { type: 'string' },
+    { type: 'object', properties: {} },
+    { type: 'object', properties: { a: { type: 'string' } }, additionalProperties: true },
+    { type: 'object', properties: { a: { type: 'string' } }, patternProperties: { '^x': { type: 'string' } } },
+    { type: 'object', nullable: true, properties: { a: { type: 'string' } } },
+    { type: 'object', properties: { a: { type: 'string', nullable: true } } },
+    { type: 'object', properties: { a: { type: ['string', 'number'] } } },
+    { type: 'object', properties: { a: { type: ['integer', 'null'] } } },
+    { type: 'object', properties: { a: { const: 'x' } } },
+    { type: 'object', properties: { a: { type: 'string', enum: ['x'] } } },
+    { type: 'object', properties: { a: { anyOf: [{ type: 'string' }] } } },
+    { type: 'object', properties: { a: { type: 'string', format: 'email' } } },
+    { type: 'object', properties: { a: { $ref: '#/definitions/s' } }, definitions: { s: { type: 'string' } } },
+    { type: 'object', properties: { a: { type: 'array', items: [{ type: 'string' }] } } },
+    { type: 'object', properties: { a: { type: 'array' } } },
+    { type: 'object', properties: { a: { type: 'null' } } }
+  ]
+  t.plan(projectable.length + notProjectable.length)
+  for (const s of projectable) {
+    t.assert.ok(build(s, { objectMechanism: 'native', mode: 'debug' }).code.includes('asStringValue'), JSON.stringify(s))
+  }
+  for (const s of notProjectable) {
+    t.assert.ok(!build(s, { objectMechanism: 'native', mode: 'debug' }).code.includes('asStringValue'), JSON.stringify(s))
+  }
+})
+
+test('native mechanism: unsupported schemas keep the default output', t => {
+  const schema = {
+    type: 'object',
+    properties: { a: { type: 'string' }, b: { type: 'string', nullable: true } },
+    additionalProperties: { type: 'number' }
+  }
+  const data = { a: 'x', b: null, c: 1, d: 2 }
+  t.plan(1)
+  t.assert.equal(build(schema, { objectMechanism: 'native' })(data), build(schema)(data))
+})
+
+test('objectMechanism option validation', t => {
+  t.plan(3)
+  t.assert.doesNotThrow(() => build({ type: 'object', properties: { a: { type: 'string' } } }, { objectMechanism: 'default' }))
+  t.assert.doesNotThrow(() => build({ type: 'object', properties: { a: { type: 'string' } } }, { objectMechanism: 'native' }))
+  t.assert.throws(() => build({ type: 'object', properties: { a: { type: 'string' } } }, { objectMechanism: 'turbo' }), /Unsupported object mechanism turbo/)
+})
+
+test('native mechanism: scratch does not leak state between calls', t => {
+  const schema = { type: 'object', properties: { a: { type: 'string' }, b: { type: 'string' }, nested: { type: 'object', properties: { c: { type: 'string' } } } } }
+  const nat = build(schema, { objectMechanism: 'native' })
+  t.plan(3)
+  t.assert.equal(nat({ a: '1', b: '2', nested: { c: '3' } }), '{"a":"1","b":"2","nested":{"c":"3"}}')
+  t.assert.equal(nat({ a: '1' }), '{"a":"1"}')
+  t.assert.equal(nat({ nested: {} }), '{"nested":{}}')
+})
+
+test('native mechanism works in standalone mode', t => {
+  const schema = { type: 'object', properties: { a: { type: 'string' }, n: { type: 'number' } } }
+  const code = build(schema, { objectMechanism: 'native', mode: 'standalone' })
+  const fs = require('node:fs'); const path = require('node:path')
+  // written under test/fixtures like the other standalone tests, so that the
+  // generated require('fast-json-stringify/...') resolves against this package
+  const file = path.resolve('test/fixtures', 'standalone-native.js')
+  fs.writeFileSync(file, code)
+  t.after(() => fs.rmSync(file, { force: true }))
+  const stringify = require(file)
+  t.plan(2)
+  t.assert.ok(code.includes('asStringValue'), 'projection code is emitted')
+  t.assert.equal(stringify({ a: 'x', n: 1.5, extra: true }), '{"a":"x","n":1.5}')
+})
+
+test('native mechanism: required keys not declared in properties still throw', t => {
+  const schema = { type: 'object', required: ['id', 'token'], properties: { id: { type: 'integer' } } }
+  const def = build(schema)
+  const nat = build(schema, { objectMechanism: 'native' })
+  t.plan(2)
+  t.assert.deepStrictEqual(run(nat, { id: 1 }), run(def, { id: 1 }))
+  t.assert.deepStrictEqual(run(nat, { id: 1, token: 'x' }), run(def, { id: 1, token: 'x' }))
+})
+
+test('native mechanism: deeply nested schema beyond the projection depth falls back', t => {
+  let schema = { type: 'string' }
+  for (let i = 0; i < 40; i++) schema = { type: 'object', properties: { p: schema } }
+  t.plan(1)
+  t.assert.ok(!build(schema, { objectMechanism: 'native', mode: 'debug' }).code.includes('asStringValue'))
+})
+
+test('native mechanism: [primitive, null] multi-type properties keep the strict dispatch', t => {
+  const schema = {
+    type: 'object',
+    properties: {
+      s: { type: ['string', 'null'] },
+      sr: { type: ['null', 'string'] },
+      sd: { type: ['string', 'null'], format: 'date-time' },
+      sdef: { type: ['string', 'null'], default: 'd' },
+      n: { type: ['number', 'null'] },
+      b: { type: ['boolean', 'null'] },
+      arr: { type: 'array', items: { type: ['string', 'null'] } }
+    }
+  }
+  const def = build(schema)
+  const nat = build(schema, { objectMechanism: 'native' })
+  const cases = [
+    { s: 'x', sr: 'y', sd: new Date(0), sdef: 'z', n: 1.5, b: true, arr: ['a', null] },
+    { s: null, sr: null, sd: null, sdef: null, n: null, b: null, arr: [null] },
+    {},
+    { s: new Date(0) },
+    { s: /re/ },
+    { s: { toString () { return 'custom' } } },
+    { s: {} },
+    { s: 5 },
+    { s: true },
+    { sd: '2020-01-01' },
+    { sd: 5 },
+    { n: Infinity },
+    { n: NaN },
+    { n: '3' },
+    { n: 10n },
+    { b: 'y' },
+    { b: 0 },
+    { arr: ['a', 5] },
+    { arr: [new Date(0)] }
+  ]
+  t.plan(cases.length + 2)
+  t.assert.ok(build(schema, { objectMechanism: 'native', mode: 'debug' }).code.includes('asStringValue'), 'schema is projected')
+  for (const c of cases) t.assert.deepStrictEqual(run(nat, c), run(def, c), JSON.stringify(c, (k, v) => typeof v === 'bigint' ? 'bigint' : v))
+  // ['integer', 'null'] and non-null multi-types are not projected
+  const notProjected = [{ type: ['integer', 'null'] }, { type: ['string', 'number'] }, { type: ['string', 'null', 'number'] }, { type: ['string', 'null'], format: 'email' }]
+  t.assert.ok(notProjected.every((p) => !build({ type: 'object', properties: { a: p } }, { objectMechanism: 'native', mode: 'debug' }).code.includes('asStringValue')))
+})
+
+test('native mechanism projects the realistic api-response fixtures byte for byte', t => {
+  const fixtures = require('../benchmark/fixtures/api-responses')
+  t.plan(fixtures.length * 2)
+  for (const { name, schema, input } of fixtures) {
+    const def = build(schema)
+    const nat = build(schema, { objectMechanism: 'native' })
+    t.assert.ok(build(schema, { objectMechanism: 'native', mode: 'debug' }).code.includes('asStringValue'), `${name} is projected`)
+    t.assert.equal(nat(input), def(input), name)
+  }
+})
+
+test('native mechanism: array elements never share scratch objects (no aliasing)', t => {
+  // items[].product.images[] : an array of objects inside an array of objects.
+  // Every element must get its own scratch tree, otherwise the last element
+  // written wins for all of them.
+  const schema = {
+    type: 'array',
+    items: {
+      type: 'object',
+      properties: {
+        id: { type: 'integer' },
+        images: { type: 'array', items: { type: 'object', properties: { url: { type: 'string' }, tags: { type: 'array', items: { type: 'string' } } } } },
+        meta: { type: 'object', properties: { k: { type: 'string' } } }
+      }
+    }
+  }
+  const def = build(schema)
+  const nat = build(schema, { objectMechanism: 'native' })
+  const a = [
+    { id: 1, images: [{ url: 'a', tags: ['x'] }, { url: 'b', tags: [] }], meta: { k: '1' } },
+    { id: 2, images: [{ url: 'c', tags: ['y', 'z'] }], meta: { k: '2' } },
+    { id: 3, images: [], meta: null }
+  ]
+  const b = [{ id: 9, images: [{ url: 'q', tags: ['k'] }] }]
+  t.plan(4)
+  t.assert.equal(nat(a), def(a))
+  t.assert.equal(nat(b), def(b))
+  t.assert.equal(nat(a), def(a), 'shrinking then growing again keeps elements independent')
+  t.assert.ok(nat(a).includes('"url":"a"') && nat(a).includes('"url":"c"'))
+})

package/types/index.d.ts

@@ -193,6 +193,15 @@ declare namespace build {
      * @default 'default'
      */
     largeArrayMechanism?: 'default' | 'json-stringify'
+    /**
+     * Specify how objects should be stringified. `'native'` projects the
+     * input into schema-shaped scratch objects and delegates to the native
+     * `JSON.stringify`. Effective on Node.js 25+ only (no-op on older
+     * runtimes); schemas it cannot project silently use the default mechanism.
+     *
+     * @default 'default'
+     */
+    objectMechanism?: 'default' | 'native'
     /**
      * Eagerly compile the Ajv validators used by `anyOf`, `oneOf` and
      * `if/then/else` at build time instead of on the first serialization

package/types/index.tst.ts

@@ -255,6 +255,10 @@ expect(stringify7).type.not.toBeCallableWith('a string')
 // largeArrayMechanism
 build({}, { largeArrayMechanism: 'json-stringify' })
 build({}, { largeArrayMechanism: 'default' })
+
+// objectMechanism
+build({}, { objectMechanism: 'native' })
+build({}, { objectMechanism: 'default' })
 expect(build).type.not.toBeCallableWith({} as Schema, { largeArrayMechanism: 'invalid' })
 
 build({}, { largeArraySize: 2000 })