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-site.git
commit 913f1ee598f9e484e08796782c8a3216fea355b1 Author: chaokunyang <[email protected]> AuthorDate: Sat Jun 13 09:48:05 2026 +0000 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/' --- docs/compiler/compiler-guide.md | 42 +++++++++++++++++++-------- docs/compiler/flatbuffers-idl.md | 13 +++++---- docs/compiler/generated-code.md | 63 ++++++++++++++++++++++++++++++++++++++++ docs/compiler/index.md | 29 ++++++++++++------ docs/compiler/protobuf-idl.md | 41 ++++++++++++++------------ docs/compiler/schema-idl.md | 6 ++-- 6 files changed, 147 insertions(+), 47 deletions(-) diff --git a/docs/compiler/compiler-guide.md b/docs/compiler/compiler-guide.md index 638c3ad268..a89880bb20 100644 --- a/docs/compiler/compiler-guide.md +++ b/docs/compiler/compiler-guide.md @@ -73,6 +73,7 @@ Compile options: | `--emit-fdl` | Emit translated FDL (for non-FDL inputs) | `false` | | `--emit-fdl-path` | Write translated FDL to this path (file or directory) | (stdout) | | `--grpc` | Generate gRPC service companions for supported outputs | `false` | +| `--grpc-web` | Generate JavaScript gRPC-Web client companions | `false` | Schema-level file options are supported for language-specific generation choices. For `go_nested_type_style` and `swift_namespace_style`, the CLI flag overrides @@ -141,28 +142,40 @@ foryc schema.fdl --output ./src/generated foryc user.fdl order.fdl product.fdl --output ./generated ``` -**Compile a simple schema containing service definitions (Java + Python + Rust + C# + Scala + Kotlin models):** +**Compile a simple schema containing service definitions (Java + Python + Go + Rust + C# + Scala + Kotlin + JavaScript models):** ```bash -foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin +foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript ``` -**Generate Java, Python, Rust, C#, Scala, and Kotlin gRPC service companions:** +**Generate Java, Python, Go, Rust, C#, Scala, Kotlin, and Node.js JavaScript gRPC service companions:** ```bash -foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --grpc +foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc ``` The generated gRPC service code uses Fory to serialize request and response -payloads. Java output imports grpc-java APIs, Python output imports `grpc`, and -Rust output imports `tonic` and `bytes`. Scala output imports grpc-java APIs. -Kotlin output imports grpc-java and grpc-kotlin APIs and uses coroutine stubs. -C# output imports `Grpc.Core.Api` types and can be hosted with normal .NET gRPC -packages such as `Grpc.AspNetCore` or called through `Grpc.Net.Client`. +payloads. Java output imports grpc-java APIs, Python output imports `grpc`, Go +output imports grpc-go, Rust output imports `tonic` and `bytes`, Scala output +imports grpc-java APIs, and Kotlin output imports grpc-java and grpc-kotlin APIs +and uses coroutine stubs. C# output imports `Grpc.Core.Api` types and can be +hosted with normal .NET gRPC packages such as `Grpc.AspNetCore` or called +through `Grpc.Net.Client`. JavaScript output imports `@grpc/grpc-js`. Applications that compile or run those generated service files must provide their own gRPC dependencies. Fory packages do not add a hard gRPC dependency for this feature. +**Generate JavaScript gRPC-Web browser clients:** + +```bash +foryc compiler/examples/service.fdl --javascript_out=./generated/javascript --grpc-web +``` + +Use `--grpc` and `--grpc-web` together when the same JavaScript output should +include both Node.js and browser companions. The browser companion imports +`grpc-web`; the application must provide the package and a gRPC-Web compatible +server or proxy. + **Use import search paths:** ```bash @@ -275,7 +288,7 @@ Compiling src/main.fdl... | Rust | `rust` | `.rs` | Structs with derive macros | | C++ | `cpp` | `.h` | Structs with FORY macros | | C# | `csharp` | `.cs` | Classes with Fory attributes | -| JavaScript/TypeScript | `javascript` | `.ts` | Interfaces with registration function | +| JavaScript/TypeScript | `javascript` | `.ts` | Interfaces with schema module helpers | | Swift | `swift` | `.swift` | Fory Swift model macros | | Dart | `dart` | `.dart` | `@ForyStruct` classes with annotations | | Scala | `scala` | `.scala` | Scala 3 models with macro derivation | @@ -354,14 +367,19 @@ generated/ ``` generated/ └── javascript/ - └── example.ts + ├── example.ts + ├── example_grpc.ts # with --grpc + └── example_grpc_web.ts # with --grpc-web ``` - Single `.ts` file per schema - `export interface` declarations for messages - `export enum` declarations for enums - Discriminated unions with case enums -- Registration helper function included +- Schema helpers `registerXxxTypes(fory)` plus default `serializeX` and + `deserializeX` helpers included +- `--grpc` emits a Node.js companion using `@grpc/grpc-js` +- `--grpc-web` emits a browser client companion using `grpc-web` ### C\# diff --git a/docs/compiler/flatbuffers-idl.md b/docs/compiler/flatbuffers-idl.md index 9a0d3e9a27..abf6652189 100644 --- a/docs/compiler/flatbuffers-idl.md +++ b/docs/compiler/flatbuffers-idl.md @@ -126,7 +126,8 @@ message Container { FlatBuffers `rpc_service` definitions are translated to Fory services. With `--grpc`, the compiler emits gRPC service companions for supported outputs such -as Java, Python, Go, Rust, C#, Scala, and Kotlin. These companions use Fory +as Java, Python, Go, Rust, C#, Scala, Kotlin, and JavaScript. JavaScript browser +clients are generated with `--grpc-web`. These companions use Fory serialization for request and response payloads. ```fbs @@ -137,13 +138,15 @@ rpc_service SearchService { ``` ```bash -foryc api.fbs --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --grpc +foryc api.fbs --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc ``` Generated service code imports grpc APIs, so applications must provide grpc-java, grpc-kotlin, Scala grpc-java APIs, `grpcio`, grpc-go, Rust `tonic` and `bytes`, -or C# `Grpc.Core.Api` plus server/client dependencies when they compile or run -those files. Fory packages do not add gRPC as a hard dependency. +`@grpc/grpc-js`, or C# `Grpc.Core.Api` plus server/client dependencies when they +compile or run those files. Fory packages do not add gRPC as a hard dependency. +Use `--grpc-web` with JavaScript output to generate browser clients that import +`grpc-web`. ### Defaults and Metadata @@ -192,7 +195,7 @@ FlatBuffers `ByteBuffer`-style APIs. - Java, Scala, and Kotlin: JVM model types with Fory metadata and registration helpers - Python: dataclasses plus registration helpers - C++, Go, and Rust: native structs and Fory metadata -- JavaScript/TypeScript: TypeScript interfaces and registration helpers +- JavaScript/TypeScript: TypeScript interfaces and schema helpers - C#, Swift, and Dart: annotated or macro-based model types with registration helpers The serialization format is Fory binary protocol, not FlatBuffers wire format. diff --git a/docs/compiler/generated-code.md b/docs/compiler/generated-code.md index a9035f9aff..9180887bb8 100644 --- a/docs/compiler/generated-code.md +++ b/docs/compiler/generated-code.md @@ -1015,6 +1015,11 @@ JavaScript/TypeScript output is one `.ts` file per schema, for example: - `<javascript_out>/addressbook.ts` +When the schema contains services, JavaScript can also emit service companions: + +- `<javascript_out>/addressbook_grpc.ts` with `--grpc` +- `<javascript_out>/addressbook_grpc_web.ts` with `--grpc-web` + ### Type Generation Messages generate `export interface` declarations with camelCase field names: @@ -1051,6 +1056,64 @@ export type Animal = | { case: AnimalCase.CAT; value: Cat }; ``` +### Schema Helpers + +Each generated model file exports a registration helper for custom `Fory` +instances and root serialization helpers. The public API looks like: + +```typescript +import type Fory, { Serializer } from "@apache-fory/core"; + +export function registerAddressbookTypes(fory: Fory): { + person: { + serialize: (value: Person | null) => Uint8Array; + deserialize: (bytes: Uint8Array) => Person; + serializer: Serializer; + }; +}; +export const serializePerson: (value: Person | null) => Uint8Array; +export const deserializePerson: (bytes: Uint8Array) => Person; +``` + +Imported schema modules are registered automatically by `registerXxxTypes(fory)`. +Use `serializeX` and `deserializeX` for the generated default serialization +path. Call `registerXxxTypes(fory)` when the application manages its own `Fory` +instance. Generated gRPC companions import the generated helpers automatically. + +### gRPC Service Companions + +When a schema contains services and the compiler is run with `--grpc`, +JavaScript generation emits a Node.js companion named `<module>_grpc.ts`. +The file contains service descriptors, handler interfaces, a client class, and a +server registration helper for `@grpc/grpc-js`. + +```typescript +export interface GreeterHandlers extends grpc.UntypedServiceImplementation { + sayHello: grpc.handleUnaryCall<HelloRequest, HelloReply>; +} + +export function addGreeterService( + server: grpc.Server, + handlers: GreeterHandlers, +): void { ... } + +export class GreeterClient extends grpc.Client { ... } +``` + +When the compiler is run with `--grpc-web`, JavaScript generation emits a +browser companion named `<module>_grpc_web.ts`. It contains callback clients for +`grpc-web`; services with unary RPCs also get promise clients: + +```typescript +export class GreeterWebClient { ... } + +export class GreeterWebPromiseClient { ... } +``` + +Node.js service companions import `@grpc/grpc-js`; browser companions import +`grpc-web`. Add those packages to the application that compiles or runs the +generated files. + ## Swift ### Output Layout diff --git a/docs/compiler/index.md b/docs/compiler/index.md index 99136fafb9..be81f5bfc2 100644 --- a/docs/compiler/index.md +++ b/docs/compiler/index.md @@ -23,9 +23,9 @@ Fory IDL is a schema definition language for Apache Fory that enables type-safe cross-language serialization. Define your data structures once and generate native data structure code for Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin. Fory IDL can also -describe RPC services; for Java, Python, Go, Rust, C#, Scala, and Kotlin, the -compiler can generate gRPC service companions that use Fory serialization for -request and response payloads. +describe RPC services; for Java, Python, Go, Rust, C#, Scala, Kotlin, and +JavaScript, the compiler can generate gRPC service companions that use Fory +serialization for request and response payloads. ## Example Schema @@ -88,17 +88,19 @@ service AnimalService { } ``` -Generate Java, Python, Rust, C#, Scala, and Kotlin models plus gRPC service companions with: +Generate Java, Python, Go, Rust, C#, Scala, Kotlin, and JavaScript models plus +gRPC service companions with: ```bash -foryc animals.fdl --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --grpc +foryc animals.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc ``` The generated service code uses normal gRPC APIs, but request and response objects are serialized with Fory. Applications provide their own grpc-java, -grpc-kotlin, `grpcio`, grpc-go, Rust `tonic` and `bytes`, or C# -`Grpc.Core.Api` and hosting/client dependencies; Fory packages do not add gRPC -as a hard dependency. +grpc-kotlin, Scala grpc-java APIs, `grpcio`, grpc-go, Rust `tonic` and `bytes`, +or C# `Grpc.Core.Api` and hosting/client dependencies; Fory packages do not add +gRPC as a hard dependency. JavaScript Node.js companions use `@grpc/grpc-js`; +browser clients are generated separately with `--grpc-web` and use `grpc-web`. ## Why Fory IDL? @@ -130,7 +132,7 @@ Generated code uses native language constructs: - Rust: Structs with `#[derive(ForyStruct)]` - C++: Structs with `FORY_STRUCT` macros - C#: `[ForyStruct]` classes, `[ForyEnum]` enums, `[ForyUnion]` unions, and registration helpers -- JavaScript/TypeScript: Interfaces with registration function +- JavaScript/TypeScript: Interfaces with schema module helpers - Swift: Fory model macros with field/case metadata and registration helpers - Dart: `@ForyStruct` classes with `@ForyField` annotations and registration helpers - Scala: Scala 3 `case class`, normal class, enum, and ADT enum models with macro-derived serializers @@ -196,6 +198,15 @@ person = Person(name="Alice", age=30) data = bytes(person) # or `person.to_bytes()` ``` +**JavaScript/TypeScript:** + +```ts +import { deserializePerson, serializePerson } from "./generated/example"; + +const data = serializePerson({ name: "Alice", age: 30, email: null }); +const person = deserializePerson(data); +``` + ## Documentation | Document | Description | diff --git a/docs/compiler/protobuf-idl.md b/docs/compiler/protobuf-idl.md index 40ad72b85c..2c23602429 100644 --- a/docs/compiler/protobuf-idl.md +++ b/docs/compiler/protobuf-idl.md @@ -41,20 +41,20 @@ how protobuf concepts map to Fory, and how to use protobuf-only Fory extension o ## Protobuf vs Fory at a Glance -| Aspect | Protocol Buffers | Fory | -| ------------------ | ----------------------------- | --------------------------------------------------- | -| Primary purpose | RPC/message contracts | High-performance object serialization | -| Encoding model | Tag-length-value | Fory binary protocol | -| Reference tracking | Not built-in | First-class (`ref`) | -| Circular refs | Not supported | Supported | -| Unknown fields | Preserved | Not preserved | -| Generated types | Protobuf-specific model types | Native language constructs | -| gRPC ecosystem | Native | Java/Python/Go/Rust/C#/Scala/Kotlin service codegen | - -Fory can generate Java, Python, Go, Rust, C#, Scala, and Kotlin gRPC service -companions with `--grpc`. Those services use normal gRPC transports but -serialize request and response payloads with Fory rather than protobuf. For -broad gRPC ecosystem +| Aspect | Protocol Buffers | Fory | +| ------------------ | ----------------------------- | -------------------------------------------------------------- | +| Primary purpose | RPC/message contracts | High-performance object serialization | +| Encoding model | Tag-length-value | Fory binary protocol | +| Reference tracking | Not built-in | First-class (`ref`) | +| Circular refs | Not supported | Supported | +| Unknown fields | Preserved | Not preserved | +| Generated types | Protobuf-specific model types | Native language constructs | +| gRPC ecosystem | Native | Java/Python/Go/Rust/C#/Scala/Kotlin/JavaScript service codegen | + +Fory can generate Java, Python, Go, Rust, C#, Scala, Kotlin, and JavaScript gRPC +service companions with `--grpc`. JavaScript browser clients are generated with +`--grpc-web`. Those services use normal gRPC transports but serialize request +and response payloads with Fory rather than protobuf. For broad gRPC ecosystem tooling, schema reflection, and protobuf-native interceptors, protobuf remains the mature/default choice. @@ -315,18 +315,21 @@ languages. For supported service outputs, add `--grpc` to emit gRPC companion code: ```bash -foryc api.proto --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --grpc +foryc api.proto --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc ``` Generated Java service files compile against grpc-java, generated Python service modules import `grpc`, generated Rust service files import `tonic` and `bytes`, +generated Go service files import grpc-go, generated JavaScript Node.js service +files import `@grpc/grpc-js`, generated C# service files import `Grpc.Core.Api` types, generated Scala service files compile against grpc-java, and generated Kotlin service files compile against grpc-java and grpc-kotlin. Add those dependencies in your application -build; Fory packages do not add gRPC as a hard dependency. Protobuf `oneof` -fields are translated to Fory union fields inside request and response messages. -Direct union RPC request or response types are not part of normal protobuf RPC -syntax. +build; Fory packages do not add gRPC as a hard dependency. Use `--grpc-web` +with JavaScript output to generate browser clients that import `grpc-web`. +Protobuf `oneof` fields are translated to Fory union fields inside request and +response messages. Direct union RPC request or response types are not part of +normal protobuf RPC syntax. ### Step 5: Run Compatibility Checks diff --git a/docs/compiler/schema-idl.md b/docs/compiler/schema-idl.md index 168c07ddcd..28da5fa7d8 100644 --- a/docs/compiler/schema-idl.md +++ b/docs/compiler/schema-idl.md @@ -908,7 +908,8 @@ union_field := ['repeated'] field_type IDENTIFIER '=' INTEGER [field_options] '; Services define RPC method contracts in Fory IDL. They are optional: schemas with services still generate the normal data model types, and gRPC service code is generated only when the compiler is run with `--grpc` for supported language -outputs such as Java, Python, Go, Rust, C#, Scala, and Kotlin. +outputs such as Java, Python, Go, Rust, C#, Scala, Kotlin, and JavaScript. +JavaScript browser gRPC-Web clients are generated with `--grpc-web`. ```protobuf message GetPetRequest [id=200] { @@ -951,7 +952,8 @@ service PetDirectory { - The generated gRPC companions use Fory serialization for each RPC payload. Applications that compile or run those companions provide their own gRPC dependency, such as grpc-java, grpc-kotlin, `grpcio`, grpc-go, Rust `tonic` - and `bytes`, or C# `Grpc.Core.Api` plus a server or client package. + and `bytes`, Scala grpc-java APIs, `@grpc/grpc-js`, `grpc-web`, or C# + `Grpc.Core.Api` plus a server or client package. **Grammar:** --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
