fix: document message naming conventions

packages/protons-runtime/src/codec.ts

@@ -19,34 +19,46 @@ export interface EncodeFunction<T> {
   (value: T, writer: Writer, opts?: EncodeOptions): void
 }
 
-// protobuf types that contain multiple values
-type CollectionTypes = any[] | Map<any, any>
+/**
+ * Protobuf types that contain multiple values
+ */
+export type CollectionTypes = any[] | Map<any, any>
 
-// 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 <T> = {
+/**
+ * Recursive array/map field length limits
+ */
+export type CollectionLimits <T> = {
   [K in keyof T]: T[K] extends CollectionTypes ? number :
     T[K] extends PrimitiveTypes ? never : Limits<T[K]>
 }
 
-// recursive array member array/map field length limits
-type ArrayElementLimits <T> = {
+/**
+ * Recursive array member array/map field length limits
+ */
+export type ArrayElementLimits <T> = {
   [K in keyof T as `${string & K}$`]: T[K] extends Array<infer ElementType> ?
       (ElementType extends PrimitiveTypes ? never : Limits<ElementType>) :
       (T[K] extends PrimitiveTypes ? never : Limits<T[K]>)
 }
 
-// recursive map value array/map field length limits
-type MapValueLimits <T> = {
+/**
+ * Recursive map value array/map field length limits
+ */
+export type MapValueLimits <T> = {
   [K in keyof T as `${string & K}$value`]: T[K] extends Map<any, infer MapValueType> ?
       (MapValueType extends PrimitiveTypes ? never : Limits<MapValueType>) :
       (T[K] extends PrimitiveTypes ? never : Limits<T[K]>)
 }
 
-// union of collection and array elements
-type Limits<T> = Partial<CollectionLimits<T> & ArrayElementLimits<T> & MapValueLimits<T>>
+/**
+ * Union of collection and array elements
+ */
+export type Limits<T> = Partial<CollectionLimits<T> & ArrayElementLimits<T> & MapValueLimits<T>>
 
 export interface DecodeOptions<T> {
   /**

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'

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

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