| # @apache-fory/hps |
| |
| [](https://www.npmjs.com/package/@apache-fory/hps) |
| [](https://www.apache.org/licenses/LICENSE-2.0) |
| |
| 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. |
