This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory.git
The following commit(s) were added to refs/heads/main by this push:
new 4a3c71c72 docs: update readme (#3575)
4a3c71c72 is described below
commit 4a3c71c72dc82a84a13ef022126e7c8bce386018
Author: Shawn Yang <[email protected]>
AuthorDate: Thu Apr 16 13:14:02 2026 +0800
docs: update readme (#3575)
## Why?
## What does this PR do?
## Related issues
## AI Contribution Checklist
- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] If `yes`, I included a completed [AI Contribution
Checklist](https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
in this PR description and the required `AI Usage Disclosure`.
- [ ] If `yes`, my PR description includes the required `ai_review`
summary and screenshot evidence of the final clean AI review results
from both fresh reviewers on the current PR diff or current HEAD after
the latest code changes.
## Does this PR introduce any user-facing change?
- [ ] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?
## Benchmark
---
dart/README.md | 186 ++++++++++++++-----------------------
dart/packages/fory/README.md | 106 +++++++++++++++------
javascript/README.md | 146 ++++++++++++++++++++++-------
javascript/packages/core/README.md | 149 ++++++++++++++++++++++++++++-
javascript/packages/hps/README.md | 70 +++++++++++++-
5 files changed, 474 insertions(+), 183 deletions(-)
diff --git a/dart/README.md b/dart/README.md
index ee2cc6d66..e7496e463 100644
--- a/dart/README.md
+++ b/dart/README.md
@@ -1,145 +1,97 @@
# Apache Fory™ Dart
-## Overview
+Apache Fory™ Dart is the Dart xlang runtime for Apache Fory™. It reads and
+writes Fory's cross-language wire format and works in both Dart and Flutter
+applications. Because Flutter prohibits `dart:mirrors`, the runtime uses static
+code generation for type handling.
-This PR adds Dart language support to Apache Fory™, implementing a
comprehensive serialization solution for Dart and Flutter applications. Apache
Fory™ Dart consists of approximately 15,000 lines of code and provides an
efficient serialization mechanism that works within Flutter's reflection
limitations.
+The publishable package lives at `packages/fory/`. See its
+[README](packages/fory/README.md) for the full user-facing documentation
+including getting started, API reference, and code examples.
-## Implementation Approach
-
-Dart supports reflection, but Flutter explicitly prohibits it. To address this
constraint, Apache Fory™ Dart uses a combination of:
-
-1. Core serialization/deserialization logic
-2. Static code generation for type handling
-
-This approach ensures compatibility with Flutter while maintaining the
performance and flexibility expected from Apache Fory™.
-
-## Features
-
-- XLANG mode support for cross-language serialization
-- Reference tracking for handling object graphs
-- Support for primitive types, collections, and custom classes
-- Serializer registration system
-- Code generation for class and enum serialization
-- Support for nested collections with automatic generic type conversion
-- Custom serializer registration
-- Support for using ByteWriter/ByteReader as serialization sources
-
-## Usage Examples
+## Project Structure
-### Basic Class Serialization
+| Directory | Description |
+| -------------------------------- | --------------------------------------- |
+| `packages/fory/lib/` | Core runtime and public API |
+| `packages/fory/lib/src/codegen/` | Build-runner code generator |
+| `packages/fory/example/` | Annotated example with generated output |
+| `packages/fory/test/` | Unit and integration tests |
+| `test/` | Cross-language integration tests |
+
+## Type Mapping
+
+| Fory xlang type | Dart type |
+| --------------- | ------------------------ |
+| bool | `bool` |
+| int8 | `fory.Int8` (wrapper) |
+| int16 | `fory.Int16` (wrapper) |
+| int32 | `fory.Int32` (wrapper) |
+| int64 | `int` |
+| float16 | `fory.Float16` (wrapper) |
+| float32 | `fory.Float32` (wrapper) |
+| float64 | `double` |
+| string | `String` |
+| binary | `Uint8List` |
+| local_date | `LocalDate` |
+| timestamp | `Timestamp` |
+| list | `List` |
+| set | `Set` |
+| map | `Map` |
+| enum | `enum` |
+| named_struct | `class` |
+| bool_array | `List<bool>` |
+| int8_array | `Int8List` |
+| int16_array | `Int16List` |
+| int32_array | `Int32List` |
+| int64_array | `Int64List` |
+| float32_array | `Float32List` |
+| float64_array | `Float64List` |
+
+## Quick Start
+
+Annotate your model and run the code generator:
```dart
import 'package:fory/fory.dart';
-part 'example.g.dart';
+part 'person.fory.dart';
-@foryClass
-class SomeClass with _$SomeClassFory {
- late int id;
- late String name;
- late Map<String, double> map;
+@ForyStruct()
+class Person {
+ Person();
- SomeClass(this.id, this.name, this.map);
-
- SomeClass.noArgs();
+ String name = '';
+ Int32 age = Int32(0);
}
```
-After annotating your class with `@foryClass`, run:
-
```bash
-dart run build_runner build
+dart run build_runner build --delete-conflicting-outputs
```
-This generates the necessary code in `example.g.dart` and creates the
`_$SomeClassFory` mixin.
-
-### Serializing and Deserializing
+Serialize and deserialize:
```dart
-Fory fory = Fory(ref: true);
-fory.register($SomeClass, typename: "example.SomeClass");
-SomeClass obj = SomeClass(1, 'SomeClass', {'a': 1.0});
-
-// Serialize
-Uint8List bytes = fory.serialize(obj);
+final fory = Fory();
+PersonFory.register(fory, Person, namespace: 'example', typeName: 'Person');
-// Deserialize
-obj = fory.deserialize(bytes) as SomeClass;
+final bytes = fory.serialize(Person()..name = 'Ada'..age = Int32(36));
+final roundTrip = fory.deserialize<Person>(bytes);
```
-### Enum Serialization
-
-```dart
-import 'package:fory/fory.dart';
+## Development
-part 'example.g.dart';
+Run tests from the workspace root:
-@foryEnum
-enum EnumFoo {
- A,
- B
-}
+```bash
+cd packages/fory
+dart test
```
-Registration is similar to classes:
+Run the code generator on the example:
-```dart
-fory.register($EnumFoo, typename: "example.EnumFoo");
+```bash
+cd packages/fory
+dart run build_runner build --delete-conflicting-outputs
```
-
-## Type Support
-
-Apache Fory™ Dart currently supports the following type mappings in XLANG mode:
-
-| Fory Type | Dart Type |
-| ------------- | ------------------------------------------ |
-| bool | bool |
-| int8 | fory.Int8 |
-| int16 | fory.Int16 |
-| int32 | fory.Int32 |
-| var_int32 | fory.Int32 |
-| int64 | int |
-| var_int64 | int |
-| sli_int64 | int |
-| float32 | fory.Float32 |
-| float64 | double |
-| string | String |
-| enum | Enum |
-| named_enum | Enum |
-| named_struct | class |
-| list | List |
-| set | Set (LinkedHashSet, HashSet, SplayTreeSet) |
-| map | Map (LinkedHashMap, HashMap, SplayTreeMap) |
-| timestamp | fory.TimeStamp |
-| local_date | fory.LocalDate |
-| binary | Uint8List |
-| bool_array | BoolList |
-| int8_array | Int8List |
-| int16_array | Int16List |
-| int32_array | Int32List |
-| int64_array | Int64List |
-| float32_array | Float32List |
-| float64_array | Float64List |
-
-## Project Structure
-
-The implementation is organized into three main components:
-
-1. **Codegen**: Located at `dart/packages/fory/lib/src/codegen`
- Handles static code generation for serialization/deserialization.
-
-2. **ForyCore**: Located at `dart/packages/fory/lib/src`
- Contains the core serialization and deserialization logic.
-
-3. **ForyTest**: Located at `dart/fory-test`
- Comprehensive test suite for Apache Fory™ Dart functionality.
-
-## Testing Approach
-
-The test suite is inspired by Apache Fory™ Java's testing approach and
includes:
-
-- **Data Type Tests**: Validates custom data types implemented for Dart
-- **Code Generation Tests**: Ensures correctness of the generated static code
-- **Buffer Tests**: Validates correct memory handling for primitive types
-- **Cross-Language Tests**: Tests functionality against other Apache Fory™
implementations
-- **Performance Tests**: Simple benchmarks for serialization/deserialization
performance
diff --git a/dart/packages/fory/README.md b/dart/packages/fory/README.md
index 417820b4a..302685b49 100644
--- a/dart/packages/fory/README.md
+++ b/dart/packages/fory/README.md
@@ -1,8 +1,9 @@
-# Apache Fory Dart
+# Apache Fory™ Dart
-Apache Fory Dart is the Dart xlang runtime for Apache Fory. It reads and writes
-Fory's cross-language wire format and is designed around generated serializers
-for annotated Dart models, with customized serializers available for advanced
use
+Apache Fory™ Dart is the Dart xlang runtime for
+[Apache Fory™](https://github.com/apache/fory). It reads and writes Fory's
+cross-language wire format and is designed around generated serializers for
+annotated Dart models, with customized serializers available for advanced use
cases.
## Features
@@ -21,7 +22,7 @@ Add `fory` to your package dependencies.
```yaml
dependencies:
- fory: ^0.17.0-dev
+ fory: ^0.17.0
dev_dependencies:
build_runner: ^2.4.13
@@ -89,7 +90,9 @@ dart run build_runner build --delete-conflicting-outputs
## Type Registration
-Generated types register through the generated library namespace.
+Generated types register through the generated library namespace. The namespace
+class is named `<FileName>Fory` based on the source file that contains the
+annotated types.
```dart
PersonFory.register(fory, Person, id: 100);
@@ -115,8 +118,6 @@ Keep the same registration identity on all runtimes that
exchange the type.
## Configuration
-Configure the runtime through `Config`.
-
```dart
final fory = Fory(
compatible: true,
@@ -126,14 +127,13 @@ final fory = Fory(
);
```
-Key options:
-
-- `compatible`: enables compatible struct encoding and decoding
-- `checkStructVersion`: enables struct-version validation in
- schema-consistent mode
-- `maxDepth`: limits nesting depth for one operation
-- `maxCollectionSize`: limits collection and map payload sizes
-- `maxBinarySize`: limits binary payload size
+| Option | Default | Description
|
+| -------------------- | ---------- |
------------------------------------------------------- |
+| `compatible` | `false` | Enables compatible struct encoding for
schema evolution |
+| `checkStructVersion` | `true` | Validates struct version in
schema-consistent mode |
+| `maxDepth` | `256` | Maximum nesting depth per operation
|
+| `maxCollectionSize` | `1 << 20` | Maximum collection and map payload size
|
+| `maxBinarySize` | `64 << 20` | Maximum binary payload size
|
## Reference Tracking
@@ -158,6 +158,18 @@ class NodeList {
}
```
+## Field Annotations
+
+`@ForyField()` controls per-field serialization behavior:
+
+| Option | Description |
+| ---------- | ------------------------------------------------ |
+| `skip` | Skip the field during serialization |
+| `id` | Stable field ID for compatible-mode evolution |
+| `nullable` | Override nullability inference |
+| `ref` | Enable reference tracking for this field |
+| `dynamic` | Control whether runtime type metadata is written |
+
## Customized Serializers
Use `Serializer<T>` when a type cannot use generated struct support or when you
@@ -205,21 +217,57 @@ void main() {
}
```
+## Type Mapping
+
+Dart has no native fixed-width 8/16/32-bit integer or single-precision float
+types. Fory Dart provides thin wrapper types (`Int8`, `Int16`, `Int32`,
`UInt8`,
+`UInt16`, `UInt32`, `Float16`, `Float32`) imported from
`package:fory/fory.dart`
+to represent these xlang wire types.
+
+| Fory xlang type | Dart type |
+| --------------- | ------------------------ |
+| bool | `bool` |
+| int8 | `fory.Int8` (wrapper) |
+| int16 | `fory.Int16` (wrapper) |
+| int32 | `fory.Int32` (wrapper) |
+| int64 | `int` |
+| float16 | `fory.Float16` (wrapper) |
+| float32 | `fory.Float32` (wrapper) |
+| float64 | `double` |
+| string | `String` |
+| binary | `Uint8List` |
+| local_date | `LocalDate` |
+| timestamp | `Timestamp` |
+| list | `List` |
+| set | `Set` |
+| map | `Map` |
+| enum | `enum` |
+| named_struct | `class` |
+| bool_array | `List<bool>` |
+| int8_array | `Int8List` |
+| int16_array | `Int16List` |
+| int32_array | `Int32List` |
+| int64_array | `Int64List` |
+| float32_array | `Float32List` |
+| float64_array | `Float64List` |
+
## Public API
The main exported API includes:
-- `Fory`
-- `Config`
-- `Buffer`
-- `WriteContext`
-- `ReadContext`
-- `Serializer`
-- `UnionSerializer`
-- `ForyStruct`
-- `ForyField`
-- Numeric and temporal wrappers such as `Int8`, `Int16`, `Int32`, `UInt8`,
- `UInt16`, `UInt32`, `Float16`, `Float32`, `LocalDate`, and `Timestamp`
+- `Fory` — main serialization facade
+- `Config` — runtime configuration
+- `ForyStruct`, `ForyField` — struct annotations
+- `ForyUnion` — union type annotation
+- `Serializer`, `UnionSerializer`, `EnumSerializer` — serializer base classes
+- `Buffer`, `WriteContext`, `ReadContext` — low-level I/O
+- `TypeSpec`, `ListType`, `MapType`, `ValueType` — nested container type
+ annotations
+- `Int32Type`, `Int64Type`, `Uint32Type`, `Uint64Type` — numeric encoding
+ overrides
+- Numeric wrappers: `Int8`, `Int16`, `Int32`, `UInt8`, `UInt16`, `UInt32`,
+ `Float16`, `Float32`
+- Temporal wrappers: `LocalDate`, `Timestamp`
## Cross-Language Notes
@@ -230,5 +278,5 @@ The main exported API includes:
- Use wrappers or numeric field annotations when the exact xlang wire type
matters.
-For the xlang wire format and type mapping details, see the Apache Fory
-specification in the main repository.
+For the xlang wire format and type mapping details, see the
+[Apache Fory
specification](https://github.com/apache/fory/tree/main/docs/specification).
diff --git a/javascript/README.md b/javascript/README.md
index 34f3cf660..4799dda9d 100644
--- a/javascript/README.md
+++ b/javascript/README.md
@@ -1,40 +1,124 @@
# Apache Fory™ JavaScript
-Javascript implementation for the Fory protocol.
-
-## Usage
-
-```Javascript
-import Fory, { Type } from '@apache-fory/core';
-
-/**
- * @apache-fory/hps use v8's fast-calls-api that can be called directly by
jit, ensure that the version of Node is 20 or above.
- * Optional performance feature. If installation fails or your environment
does not support it, you can continue using `@apache-fory/core` without it.
- * If you are unable to install the module, replace it with `const hps = null;`
- **/
-import hps from '@apache-fory/hps';
-
-// Now we describe data structures using JSON, but in the future, we will use
more ways.
-const typeInfo = Type.struct('example.foo', {
- foo: Type.string(),
-});
-const fory = new Fory({ hps });
-const { serialize, deserialize } = fory.register(typeInfo);
-const input = serialize({ foo: 'hello fory' });
-const result = deserialize(input);
-console.log(result);
-```
+[](https://www.npmjs.com/package/@apache-fory/core)
+[](https://www.apache.org/licenses/LICENSE-2.0)
+
+JavaScript / TypeScript implementation of the [Apache
Fory™](https://fory.apache.org) cross-language serialization protocol.
Serialize JavaScript objects to bytes and deserialize them back — including
across services written in Java, Python, Go, Rust, C++, and other
Fory-supported languages.
+
+## Key Features
+
+- **Cross-language** — serialize in JavaScript, deserialize in Java, Python,
Go, Rust, C++, and more without writing glue code
+- **Fast** — serializer code is generated and cached at registration time;
optimized for V8 JIT
+- **Reference-aware** — shared references and circular object graphs are
supported
+- **Schema-driven** — field types, nullability, and polymorphism are declared
once with `Type.*` builders
+- **Schema evolution** — optional forward/backward compatibility for
independent service deployments
+- **Modern types** — `bigint`, typed arrays, `Map`, `Set`, `Date`, `float16`,
`bfloat16` supported
## Packages
-### core
+| Package |
Description |
+| ---------------------------------------------------------------------- |
----------------------------------------------------- |
+| [`@apache-fory/core`](https://www.npmjs.com/package/@apache-fory/core) |
Main Fory runtime for JavaScript/TypeScript |
+| [`@apache-fory/hps`](https://www.npmjs.com/package/@apache-fory/hps) |
Optional Node.js high-performance suite (Node.js 20+) |
+
+## Installation
+
+```bash
+npm install @apache-fory/core
+```
+
+For optional Node.js string-detection acceleration:
+
+```bash
+npm install @apache-fory/hps
+```
+
+`@apache-fory/hps` uses V8's fast-call API to detect string encoding
efficiently. It requires Node.js 20+ and is **completely optional** — if
installation fails or your environment does not support it, `@apache-fory/core`
works perfectly on its own.
+
+## Quick Start
+
+```ts
+import Fory, { Type } from "@apache-fory/core";
+
+// Optional: import hps for Node.js string performance boost
+// import hps from "@apache-fory/hps";
+
+const userType = Type.struct(
+ { typeName: "example.user" },
+ {
+ id: Type.int64(),
+ name: Type.string(),
+ age: Type.int32(),
+ },
+);
+
+const fory = new Fory();
+// With hps: const fory = new Fory({ hps });
+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 |
+
+## Cross-Language Serialization
+
+Fory JavaScript serializes to the same binary format as the Java, Python, Go,
Rust, C++, and Swift runtimes. A message written in JavaScript can be read in
any other supported language without any conversion layer.
+
+```ts
+// JavaScript side
+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
+```
+
+Register the same `example.message` type on the other side using the peer
runtime's API.
+
+## Schema Evolution
+
+Enable compatible mode for independent service deployments:
+
+```ts
+const fory = new Fory({ compatible: true });
+```
+
+Readers can skip unknown fields and tolerate missing ones, supporting rolling
upgrades and schema changes across services.
+
+## Documentation
-`@apache-fory/core` is the main Fory protocol implementation for JavaScript.
It generates JavaScript code at runtime to make sure that all the code could be
optimized by v8 JIT efficiently.
+Full documentation is available at [fory.apache.org](https://fory.apache.org):
-### hps
+- [JavaScript Serialization
Guide](https://fory.apache.org/docs/guide/javascript)
+- [Cross-Language
Serialization](https://fory.apache.org/docs/guide/javascript/cross_language)
+- [Supported
Types](https://fory.apache.org/docs/guide/javascript/supported_types)
+- [Schema
Evolution](https://fory.apache.org/docs/guide/javascript/schema_evolution)
+- [Xlang Serialization
Spec](https://fory.apache.org/docs/specification/xlang_serialization_spec)
-Node.js high-performance suite, ensuring that your Node.js version is 20 or
later.
+## License
-`hps` is use for detect the string type in v8. Fory support latin1 and utf8
string both, we should get the certain type of string before write it
-in buffer. It is slow to detect the string is latin1 or utf8, but hps can
detect it by a hack way, which is called FASTCALL in v8.
-so it remains an optional performance optimization path.
+Apache License 2.0 — see
[LICENSE](https://github.com/apache/fory/blob/main/LICENSE) for details.
diff --git a/javascript/packages/core/README.md
b/javascript/packages/core/README.md
index d2475fd96..ee944866f 100644
--- a/javascript/packages/core/README.md
+++ b/javascript/packages/core/README.md
@@ -1,3 +1,150 @@
# @apache-fory/core
-Main Apache Fory JavaScript runtime package.
+[](https://www.npmjs.com/package/@apache-fory/core)
+[](https://www.apache.org/licenses/LICENSE-2.0)
+
+Main JavaScript / TypeScript runtime for [Apache
Fory™](https://fory.apache.org) — 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
+
+```bash
+npm install @apache-fory/core
+```
+
+For optional Node.js string-detection acceleration (Node.js 20+ only):
+
+```bash
+npm install @apache-fory/hps
+```
+
+## Quick Start
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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:
+
+```ts
+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`.
+
+```ts
+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](https://fory.apache.org/docs/guide/javascript)
+- [Cross-Language
Serialization](https://fory.apache.org/docs/guide/javascript/cross_language)
+- [Supported
Types](https://fory.apache.org/docs/guide/javascript/supported_types)
+- [Schema
Evolution](https://fory.apache.org/docs/guide/javascript/schema_evolution)
+- [Xlang Serialization
Spec](https://fory.apache.org/docs/specification/xlang_serialization_spec)
+
+## License
+
+Apache License 2.0 — see
[LICENSE](https://github.com/apache/fory/blob/main/LICENSE) for details.
diff --git a/javascript/packages/hps/README.md
b/javascript/packages/hps/README.md
index d05f42f73..77efd31a0 100644
--- a/javascript/packages/hps/README.md
+++ b/javascript/packages/hps/README.md
@@ -1,7 +1,67 @@
-# Apache Fory™ JavaScript
+# @apache-fory/hps
-Node.js high-performance suite, ensuring that your Node.js version is 20 or
later.
+[](https://www.npmjs.com/package/@apache-fory/hps)
+[](https://www.apache.org/licenses/LICENSE-2.0)
-`hps` is use for detect the string type in v8. Fory support latin1 and utf8
string both, we should get the certain type of string before write it
-in buffer. It is slow to detect the string is latin1 or utf8, but hps can
detect it by a hack way, which is called FASTCALL in v8.
-so it is not stable now.
+Optional Node.js high-performance suite for [Apache
Fory™](https://fory.apache.org) — a blazingly-fast multi-language serialization
framework.
+
+## What It Does
+
+`@apache-fory/hps` accelerates string encoding detection in V8 using the
fast-call API. Fory supports both Latin-1 and UTF-8 strings, and detecting a
string's encoding in pure JavaScript is slow. This native addon uses V8's
`FASTCALL` mechanism to perform the detection dramatically faster.
+
+## Requirements
+
+- **Node.js 20+**
+- A C++ build toolchain (for native addon compilation via `node-gyp`)
+
+## Installation
+
+```bash
+npm install @apache-fory/hps
+```
+
+If installation fails (e.g., missing build tools or unsupported platform), you
can safely skip this package. `@apache-fory/core` works correctly without it —
you just miss the string-detection optimization.
+
+## Usage
+
+Pass the `hps` module to the Fory constructor:
+
+```ts
+import Fory, { Type } from "@apache-fory/core";
+import hps from "@apache-fory/hps";
+
+const fory = new Fory({ hps });
+const { serialize, deserialize } = fory.register(
+ Type.struct("example.foo", {
+ foo: Type.string(),
+ }),
+);
+
+const bytes = serialize({ foo: "hello fory" });
+const result = deserialize(bytes);
+console.log(result);
+// { foo: 'hello fory' }
+```
+
+If `hps` is unavailable, omit it or pass `null`:
+
+```ts
+const fory = new Fory(); // works without hps
+```
+
+## When to Use
+
+- You are running on **Node.js 20+**
+- Your workload serializes a significant amount of string data
+- You want the best possible serialization throughput
+
+If you are running in a browser or on a Node.js version below 20, skip this
package entirely.
+
+## Documentation
+
+- [JavaScript Serialization
Guide](https://fory.apache.org/docs/guide/javascript)
+- [Apache Fory GitHub](https://github.com/apache/fory)
+
+## License
+
+Apache License 2.0 — see
[LICENSE](https://github.com/apache/fory/blob/main/LICENSE) for details.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
