From bda0b51af93d07f53059bbcdf6835c9a3855a16d Mon Sep 17 00:00:00 2001 From: achingbrain Date: Fri, 18 Sep 2026 11:02:17 +0300 Subject: [PATCH 1/2] fix: document message naming conventions Add a note to the readme about naming messages. Fixes #64 --- packages/protons-runtime/src/codec.ts | 36 ++++++++++++++++++--------- packages/protons-runtime/src/index.ts | 12 +++++++++ packages/protons/README.md | 10 ++++++++ packages/protons/src/index.ts | 10 ++++++++ 4 files changed, 56 insertions(+), 12 deletions(-) diff --git a/packages/protons-runtime/src/codec.ts b/packages/protons-runtime/src/codec.ts index 6757322..ebff2dc 100644 --- a/packages/protons-runtime/src/codec.ts +++ b/packages/protons-runtime/src/codec.ts @@ -19,34 +19,46 @@ export interface EncodeFunction { (value: T, writer: Writer, opts?: EncodeOptions): void } -// protobuf types that contain multiple values -type CollectionTypes = any[] | Map +/** + * Protobuf types that contain multiple values + */ +export type CollectionTypes = any[] | Map -// protobuf types that are not collections or messages -type PrimitiveTypes = boolean | number | string | bigint | Uint8Array +/** + * Protobuf types that are not collections or messages + */ +export type PrimitiveTypes = boolean | number | string | bigint | Uint8Array -// recursive array/map field length limits -type CollectionLimits = { +/** + * Recursive array/map field length limits + */ +export type CollectionLimits = { [K in keyof T]: T[K] extends CollectionTypes ? number : T[K] extends PrimitiveTypes ? never : Limits } -// recursive array member array/map field length limits -type ArrayElementLimits = { +/** + * Recursive array member array/map field length limits + */ +export type ArrayElementLimits = { [K in keyof T as `${string & K}$`]: T[K] extends Array ? (ElementType extends PrimitiveTypes ? never : Limits) : (T[K] extends PrimitiveTypes ? never : Limits) } -// recursive map value array/map field length limits -type MapValueLimits = { +/** + * Recursive map value array/map field length limits + */ +export type MapValueLimits = { [K in keyof T as `${string & K}$value`]: T[K] extends Map ? (MapValueType extends PrimitiveTypes ? never : Limits) : (T[K] extends PrimitiveTypes ? never : Limits) } -// union of collection and array elements -type Limits = Partial & ArrayElementLimits & MapValueLimits> +/** + * Union of collection and array elements + */ +export type Limits = Partial & ArrayElementLimits & MapValueLimits> export interface DecodeOptions { /** diff --git a/packages/protons-runtime/src/index.ts b/packages/protons-runtime/src/index.ts index bd955eb..c8bf0bd 100644 --- a/packages/protons-runtime/src/index.ts +++ b/packages/protons-runtime/src/index.ts @@ -32,6 +32,18 @@ export { streamMessage } from './stream.ts' +export type { + StreamFunction, + DecodeFunction, + EncodeFunction, + CollectionTypes, + PrimitiveTypes, + CollectionLimits, + ArrayElementLimits, + MapValueLimits, + Limits +} from './codec.ts' + export { enumeration } from './codecs/enum.ts' export { message } from './codecs/message.ts' export { createReader as reader } from './utils/reader.ts' diff --git a/packages/protons/README.md b/packages/protons/README.md index 5226c1e..e50474d 100644 --- a/packages/protons/README.md +++ b/packages/protons/README.md @@ -80,6 +80,16 @@ It does have one or two differences: 5. `map` fields can have keys of any type - protobufs.js [only supports strings](https://github.com/protobufjs/protobuf.js/issues/1203#issuecomment-488637338) 6. `map` fields are deserialized as ES6 `Map`s - protobuf.js uses `Object`s +\## .proto Message naming conventions + +Protobuf messages in `.proto` files are transformed into TypeScript classes, +so they must not conflict with built-in JavaScript types (`Number`, `Error`, +etc). + +Message names are not encoded onto the wire, only field types and ids so you +can name things in your `.proto` file however you like, as long as the above +rule is respected. + ## Extra features ### Limiting the size of repeated/map elements diff --git a/packages/protons/src/index.ts b/packages/protons/src/index.ts index 51af42f..83f2969 100644 --- a/packages/protons/src/index.ts +++ b/packages/protons/src/index.ts @@ -57,6 +57,16 @@ * 5. `map` fields can have keys of any type - protobufs.js [only supports strings](https://github.com/protobufjs/protobuf.js/issues/1203#issuecomment-488637338) * 6. `map` fields are deserialized as ES6 `Map`s - protobuf.js uses `Object`s * + * ## .proto Message naming conventions + * + * Protobuf messages in `.proto` files are transformed into TypeScript classes, + * so they must not conflict with built-in JavaScript types (`Number`, `Error`, + * etc). + * + * Message names are not encoded onto the wire, only field types and ids so you + * can name things in your `.proto` file however you like, as long as the above + * rule is respected. + * * ## Extra features * * ### Limiting the size of repeated/map elements From 99e8ec854d61d3c21f40efa4596d71d8ad66c2fd Mon Sep 17 00:00:00 2001 From: achingbrain Date: Fri, 18 Sep 2026 11:05:28 +0300 Subject: [PATCH 2/2] chore: linting --- packages/protons/README.md | 2 +- packages/protons/src/index.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/protons/README.md b/packages/protons/README.md index e50474d..5644225 100644 --- a/packages/protons/README.md +++ b/packages/protons/README.md @@ -80,7 +80,7 @@ It does have one or two differences: 5. `map` fields can have keys of any type - protobufs.js [only supports strings](https://github.com/protobufjs/protobuf.js/issues/1203#issuecomment-488637338) 6. `map` fields are deserialized as ES6 `Map`s - protobuf.js uses `Object`s -\## .proto Message naming conventions +## .proto Message naming conventions Protobuf messages in `.proto` files are transformed into TypeScript classes, so they must not conflict with built-in JavaScript types (`Number`, `Error`, diff --git a/packages/protons/src/index.ts b/packages/protons/src/index.ts index 83f2969..c715ad1 100644 --- a/packages/protons/src/index.ts +++ b/packages/protons/src/index.ts @@ -57,7 +57,7 @@ * 5. `map` fields can have keys of any type - protobufs.js [only supports strings](https://github.com/protobufjs/protobuf.js/issues/1203#issuecomment-488637338) * 6. `map` fields are deserialized as ES6 `Map`s - protobuf.js uses `Object`s * - * ## .proto Message naming conventions + * ## .proto Message naming conventions * * Protobuf messages in `.proto` files are transformed into TypeScript classes, * so they must not conflict with built-in JavaScript types (`Number`, `Error`,