Skip to main content
Version: 1.2.0

Configuration

Fory JavaScript is an xlang-only implementation. new Fory() writes xlang payloads and uses compatible schema evolution by default. There is no native-mode switch in the JavaScript API.

Basic Configuration​

import Fory from "@apache-fory/core";

const fory = new Fory();

Create one Fory instance per application area and reuse it. Registration generates and caches serializer code for each schema.

Constructor Options​

import Fory from "@apache-fory/core";
import hps from "@apache-fory/hps";

const fory = new Fory({
  ref: true,
  compatible: true,
  maxDepth: 100,
  hps,
});
OptionDefaultDescription
reffalseEnable reference tracking for shared or circular object graphs
compatibletrueAllow field additions/removals without breaking existing messages
maxDepth50Maximum nesting depth. Must be >= 2. Increase for deeply nested structures
useSliceStringfalseOptional string-reading optimization for Node.js. Leave at default unless benchmarked
hpsunsetOptional fast string helper from @apache-fory/hps (Node.js 20+)
hooks.afterCodeGeneratedunsetCallback to inspect the generated serializer code, useful for debugging

Reference Tracking​

Global reference tracking must be enabled before field-level reference metadata can take effect:

const fory = new Fory({ ref: true });

Then mark reference-tracked fields in the schema, for example with Type.struct("example.node").setTrackingRef(true). See References and Schema Metadata.

Compatible Schema Evolution​

Compatible mode is the default. To use faster serialization and smaller size:

const fory = new Fory({ compatible: false });

Use compatible mode for rolling upgrades, independently deployed services, and cross-language payloads. Use compatible: false only when every reader and writer always uses the same struct schema and you want faster serialization and smaller size. For individual structs, evolving: false applies the same opt-out to that struct. For cross-language payloads, set compatible: false only after verifying that every language uses the same schema, or when native types are generated from Fory schema IDL. See Schema Evolution.

Optional HPS String Path​

@apache-fory/hps provides an optional Node.js string fast path:

import hps from "@apache-fory/hps";

const fory = new Fory({ hps });

Leave this unset unless you run on Node.js 20+ and have benchmarked your workload.

Security​

Security-related configuration:

  • Register only the expected schemas before deserializing untrusted payloads.
  • Set maxDepth for the maximum nesting depth your service accepts.
  • Prefer explicit Type.struct(...) schemas over Type.any() for untrusted input.
  • Pass hps only from the official package version you deploy with Fory.