@apache-fory/core

Main JavaScript / TypeScript runtime for Apache Fory™ — a blazingly-fast multi-language serialization framework powered by JIT compilation and zero-copy techniques.

Serialize JavaScript objects to bytes and deserialize them back, including across services written in Java, Python, Go, Rust, C++, and other Fory-supported languages.

Features

• Cross-language — serialize in JavaScript, deserialize in Java, Python, Go, Rust, C++, and more
• Fast — serializer code is generated and cached at registration time; optimized for V8 JIT
• Reference-aware — shared and circular object graphs work correctly
• Schema-driven — declare field types, nullability, and polymorphism once with Type.* builders
• Schema evolution — optional forward/backward compatibility for rolling upgrades
• Modern types — bigint, typed arrays, Map, Set, Date, float16, bfloat16 supported

Installation

npm install @apache-fory/core

For optional Node.js string-detection acceleration (Node.js 20+ only):

npm install @apache-fory/hps

Quick Start

import Fory, { Type } from "@apache-fory/core";

const userType = Type.struct(
  { typeName: "example.user" },
  {
    id: Type.int64(),
    name: Type.string(),
    age: Type.int32(),
  },
);

const fory = new Fory();
const { serialize, deserialize } = fory.register(userType);

const bytes = serialize({ id: 1n, name: "Alice", age: 30 });
const user = deserialize(bytes);
console.log(user);
// { id: 1n, name: 'Alice', age: 30 }

Supported Types

| JavaScript Value | Fory Schema | Notes | | ---------------- | ----------------------------------------------------------------- | ----------------------------------------- | | boolean | Type.bool() | | | number | Type.int8() / int16() / int32() / float32() / float64() | Pick the width matching the peer language | | bigint | Type.int64() / uint64() | Use for 64-bit integers | | string | Type.string() | | | Uint8Array | Type.binary() | Binary blob | | Date | Type.timestamp() / Type.date() | | | Array | Type.array(Type.T()) | | | Map | Type.map(Type.K(), Type.V()) | | | Set | Type.set(Type.T()) | | | Typed arrays | Type.int32Array() / float64Array() / ... | Maps to native typed arrays |

Define Schemas

Structs

import { Type } from "@apache-fory/core";

const accountType = Type.struct(
  { typeName: "example.account" },
  {
    id: Type.int64(),
    owner: Type.string(),
    active: Type.bool(),
    nickname: Type.string().setNullable(true),
  },
);

Nested Structs

const addressType = Type.struct("example.address", {
  city: Type.string(),
  zip: Type.string(),
});

const personType = Type.struct("example.person", {
  name: Type.string(),
  address: addressType,
});

Arrays, Maps, and Sets

const inventoryType = Type.struct("example.inventory", {
  tags: Type.array(Type.string()),
  counts: Type.map(Type.string(), Type.int32()),
  labels: Type.set(Type.string()),
});

Schema Evolution

Enable compatible mode for independent service deployments:

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

Readers skip unknown fields and tolerate missing ones, supporting rolling upgrades.

Cross-Language Serialization

Fory JavaScript serializes to the same binary format as Java, Python, Go, Rust, C++, and Swift. A Type.int32() field in JavaScript matches Java int, Go int32, C# int.

const messageType = Type.struct(
  { typeName: "example.message" },
  {
    id: Type.int64(),
    content: Type.string(),
  },
);

const fory = new Fory();
const { serialize } = fory.register(messageType);
const bytes = serialize({ id: 1n, content: "hello from JavaScript" });
// Send bytes to a Java/Python/Go/Rust service

Documentation

• JavaScript Serialization Guide
• Cross-Language Serialization
• Supported Types
• Schema Evolution
• Xlang Serialization Spec

License

Apache License 2.0 — see LICENSE for details.