@irtio/schema 4.7.0 → 4.8.0

package/dist/index.d.ts

@@ -2,8 +2,11 @@
  * Type builders and runtime type descriptors.
  *
  * The type menu is exactly: bool u8 u16 u32 i32 f32 f64 str(max) enumOf(...) ref(entity)
- * list(T, max) struct({...}) plus `.opt` and `.default(v)` chainable on any of them.
- * Nothing else — the menu is deliberately closed.
+ * bytes(n) list(T, max) struct({...}) plus `.opt` and `.default(v)` chainable on any of them.
+ * Nothing else — the menu is deliberately closed. `bytes(n)` is the one deliberate addition: a
+ * fixed-length `Uint8Array` whose deltas carry only the byte ranges that changed, for tile chunks
+ * and other dense buffers that `list(u8, n)` (whole-replace, 8 bytes per element in memory) serves
+ * badly.
  */
 type ScalarKind = 'bool' | 'u8' | 'u16' | 'u32' | 'i32' | 'f32' | 'f64';
 /** Common flags on every descriptor. */
@@ -25,6 +28,9 @@ type TypeDesc = (DescBase & {
 }) | (DescBase & {
     readonly kind: 'ref';
     readonly entity: string;
+}) | (DescBase & {
+    readonly kind: 'bytes';
+    readonly n: number;
 }) | (DescBase & {
     readonly kind: 'list';
     readonly item: TypeDesc;
@@ -65,6 +71,15 @@ declare function str(max: number): Type<string>;
 declare function enumOf<const V extends readonly [string, ...string[]]>(...values: V): Type<V[number]>;
 /** Reference to an entity instance by id; encoded as the id string. */
 declare function ref<E extends string>(entity: E): Type<string>;
+/** The largest `n` a `bytes(n)` field may declare. */
+declare const BYTES_MAX = 65535;
+/**
+ * Fixed-length byte buffer: the value is a `Uint8Array` of exactly `n` bytes (zero-filled by
+ * default). Unlike a list, a change inside it is sent as the byte ranges that changed.
+ */
+declare function bytes(n: number): Type<Uint8Array>;
+/** Does `d` contain a `bytes(n)` field, directly or anywhere inside a struct or list? */
+declare function containsBytes(d: TypeDesc): boolean;
 /** Bounded list, whole-replace on the wire. */
 declare function list<T, D extends boolean>(item: Type<T, D>, max: number): Type<T[]>;
 /** Nested object; fields are tracked and encoded individually. */
@@ -111,6 +126,16 @@ declare function cloneValue<T>(v: T): T;
  * Returns a fresh value (never aliases `v` for lists/structs).
  */
 declare function normalizeValue(d: TypeDesc, v: unknown, path?: string): unknown;
+/**
+ * A fresh, plain `Uint8Array` copy. Not `v.slice()` alone: a Node `Buffer` is a `Uint8Array` whose
+ * `slice` is a *view*, which would alias the caller's memory into state. A tracked `bytes` proxy is
+ * not a view at all (`ArrayBuffer.isView` is false) and copies through its own bound `slice`.
+ */
+declare function copyBytes(v: Uint8Array): Uint8Array;
+/** Standard base64 (with padding). Dependency-free, so it runs in every host the schema does. */
+declare function bytesToBase64(b: Uint8Array): string;
+/** Decodes standard base64 (padding required). Throws on anything else. */
+declare function base64ToBytes(s: string): Uint8Array;
 
 /**
  * The `physics` entity option (D22): which of an entity's fields the simulation owns, and which
@@ -212,7 +237,7 @@ declare function applyChannel2d(channel: PhysicsBodyChannel, value: number, targ
 }): void;
 
 /**
- * M6 lane K (D77): the declarative ownership policies a collection may declare.
+ * The declarative ownership policies a collection may declare.
  *
  * A relay room with state has no room file, so the three things a rung-1 room file exists for —
  * add one record per player, remove it when they go, and decide contested handovers — have to be
@@ -786,10 +811,10 @@ declare function createState<S extends AnySchema>(schema: S, init?: Partial<Reco
  * Kept to simple mapped types so a 30-entity schema type-checks fast (see test/large.test-d.ts).
  */
 
-type DeepReadonly<T> = T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
+type DeepReadonly<T> = T extends Uint8Array ? Readonly<Uint8Array> : T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
     readonly [K in keyof T]: DeepReadonly<T[K]>;
 } : T;
-type DeepWritable<T> = T extends readonly (infer U)[] ? DeepWritable<U>[] : T extends object ? {
+type DeepWritable<T> = T extends Uint8Array ? Uint8Array : T extends readonly (infer U)[] ? DeepWritable<U>[] : T extends object ? {
     -readonly [K in keyof T]: DeepWritable<T[K]>;
 } : T;
 /** The writable view of an instance the client owns (the client SDK hands these out). */
@@ -956,14 +981,35 @@ type BroadcastProxy<R extends RpcMap> = {
  * - Field indices are the declaration indices on the collection/struct descriptor.
  * - A struct field is dirty when its bit is in `fields`. If `nested` has an entry for it, only the
  *   nested-dirty fields are sent; no nested entry ⇒ the whole struct value is re-sent.
+ * - A `bytes(n)` field is dirty when its bit is in `fields`. If `ranges` has an entry for it, only
+ *   those byte ranges changed (sorted, merged, non-overlapping, half-open); no entry ⇒ the whole
+ *   buffer is re-sent. So a field is *whole* iff its bit is set and it has neither a `nested` nor a
+ *   `ranges` entry.
  * - `owner: true` ⇒ the owner system field changed (entities only).
  * - `added` records are sent whole (every field + owner); `removed` ids are sent as removes.
  *   An id is never in more than one of `added` / `removed` / `updated`.
  * - Singletons use `SINGLETON_ID` (`''`) in `updated` and never add/remove.
  */
+/** A half-open byte range `[start, end)` inside a `bytes(n)` field. */
+interface ByteRange {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * The most ranges one `bytes(n)` field carries per tick. More than this and the field is sent
+ * whole — past a handful of scattered edits the per-span framing stops paying for itself, and the
+ * cap bounds what a decoder has to accept.
+ */
+declare const MAX_BYTE_RANGES = 16;
 interface FieldMask {
     readonly fields: Set<number>;
     readonly nested: Map<number, FieldMask>;
+    /**
+     * Byte ranges for a dirty `bytes(n)` field at `idx`: sorted, merged, non-overlapping. Absent (or
+     * no entry for `idx`) ⇒ the field is whole. Created lazily, so masks without bytes fields never
+     * carry it.
+     */
+    ranges?: Map<number, ByteRange[]>;
 }
 interface RecordDirty {
     readonly mask: FieldMask;
@@ -985,6 +1031,32 @@ declare function collectionDirty(dirty: DirtySet, collection: string): Collectio
  */
 declare function markField(dirty: DirtySet, collection: string, id: string, path: readonly number[]): void;
 declare function markPath(mask: FieldMask, path: readonly number[]): void;
+/**
+ * Marks bytes `[start, end)` of the `bytes(n)` field at `path` dirty on a record. A field already
+ * dirty whole stays whole; otherwise the range is merged into the field's ranges, which collapse
+ * to whole once they stop being cheaper than the field itself (see {@link settleRanges}).
+ */
+declare function markBytes(dirty: DirtySet, collection: string, id: string, path: readonly number[], start: number, end: number, n: number): void;
+declare function markBytesPath(mask: FieldMask, path: readonly number[], start: number, end: number, n: number): void;
+/**
+ * Encoded size of a byte-range patch body: the span count, then per span its offset, its length
+ * and its bytes. The codec's PATCH-or-WHOLE choice compares exactly this against `n`.
+ */
+declare function rangesPatchBytes(ranges: readonly ByteRange[]): number;
+/**
+ * Applies the caps: `ranges` if they are still worth sending as a patch, `undefined` (whole) when
+ * there are more than {@link MAX_BYTE_RANGES} of them or the patch would be at least as big as the
+ * field. `n` may be omitted where it is unknown (`mergeMask`); only the count cap applies then.
+ */
+declare function settleRanges(ranges: ByteRange[], n?: number): ByteRange[] | undefined;
+/** The union of two range lists, sorted, with overlapping and adjacent ranges merged. */
+declare function unionRanges(a: readonly ByteRange[], b: readonly ByteRange[]): ByteRange[];
+/**
+ * The ranges where `a` and `b` (same length) differ, merging runs separated by fewer than
+ * `gap` equal bytes (a short gap costs less resent than a new span's framing). May return more
+ * than {@link MAX_BYTE_RANGES}; pass the result through {@link settleRanges}.
+ */
+declare function diffByteRanges(a: Uint8Array, b: Uint8Array, gap?: number): ByteRange[];
 declare function markOwner(dirty: DirtySet, collection: string, id: string): void;
 declare function markAdd(dirty: DirtySet, collection: string, id: string): void;
 declare function markRemove(dirty: DirtySet, collection: string, id: string): void;
@@ -1097,6 +1169,13 @@ declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
  *   the owner bit is set, then the dirty fields in index order. A dirty struct field is written
  *   as its presence byte (when `.opt`) followed by a nested mask of `ceil(n / 8)` bytes — all
  *   bits set when the whole struct is dirty — and its dirty fields under the same rule.
+ * - `bytes(n)`: snapshot form is the presence byte (when `.opt`) and exactly `n` raw bytes — the
+ *   length is implied by the schema. Delta form (a dirty bytes field in an update) is the presence
+ *   byte (when `.opt`; 0 = cleared, nothing follows), then a tag byte: 0 = WHOLE (`n` raw bytes)
+ *   or 1 = PATCH (varint span count 1..16, then per span varint offset, varint length ≥ 1 and that
+ *   many raw bytes; spans strictly ascending and non-overlapping). PATCH is written exactly when
+ *   the mask carries ranges for the field and the patch is smaller than the whole value, which is
+ *   a function of (mask, n) alone — so `estimateSize` stays exact.
  *
  * Encoding validates: oversize strings/lists, out-of-range or non-integer ints, wrong types,
  * missing required values and unknown enum members all throw with the field path.
@@ -1106,6 +1185,11 @@ declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
  * surfaces as a refused frame rather than as a value in state. The single exception is
  * `decodeSnapshot`, which coerces a non-finite float to the field default and warns, because
  * those bytes can be a room's own save and refusing them loses the room; see the comment there.
+ *
+ * A delta's shape is bounded before its ops are read (#147): no more collections than the schema
+ * has, no more ops than bytes left, every id and owner within `ID_MAX_BYTES`, and, when the caller
+ * passes `maxOps` (the runtime does for a client WRITE), no more ops than that in total. A crafted
+ * frame is refused at its header instead of costing a second of decode first.
  */
 
 /**
@@ -1126,6 +1210,17 @@ interface ValueSink {
 }
 /** Writes one value in snapshot form (presence byte first when the descriptor is `.opt`). */
 declare function writeValue(w: ValueSink, desc: TypeDesc, v: unknown, path?: string): void;
+/**
+ * A decoded byte-range patch for a `bytes(n)` field: what a delta carries in `patch[field]` when
+ * the field was sent as PATCH (and `mask.ranges` has its entry). `applyDelta` writes each span
+ * into the existing buffer in place.
+ */
+interface BytesPatch {
+    readonly spans: readonly {
+        readonly offset: number;
+        readonly bytes: Uint8Array;
+    }[];
+}
 /**
  * How a decode answers a non-finite `f32`/`f64` it reads off the wire.
  *
@@ -1211,14 +1306,18 @@ interface Delta {
 declare function encodeDelta(schema: AnySchema, state: PlainState, dirty: DirtySet, header: Header): Uint8Array;
 /** Exact byte length of `encodeDelta` for the same arguments, without building the payload. */
 declare function estimateSize(schema: AnySchema, state: PlainState, dirty: DirtySet): number;
-declare function decodeDelta(schema: AnySchema, bytes: Uint8Array): Delta;
+interface DecodeDeltaOptions {
+    /** Refuse the delta if its ops across all collections exceed this. Unbounded when omitted. */
+    readonly maxOps?: number;
+}
+declare function decodeDelta(schema: AnySchema, bytes: Uint8Array, options?: DecodeDeltaOptions): Delta;
 /**
  * `decodeDelta` against a caller-owned reader, which is left positioned at the first byte after
  * the delta body. Trailing bytes are the caller's: the `CORRECT` frame appends `clientTick`
  * (u32) after the delta body (week 8, D19) — a decoder that does not know about the suffix
  * ignores it, which is what makes the extension additive.
  */
-declare function decodeDeltaFrom(schema: AnySchema, r: ByteReader): Delta;
+declare function decodeDeltaFrom(schema: AnySchema, r: ByteReader, options?: DecodeDeltaOptions): Delta;
 /**
  * Applies a decoded delta in place. Only the `Collection` interface and plain property
  * assignment are used, so this also works against a tracked proxy state.
@@ -1290,6 +1389,14 @@ declare function walkSnapshot(schema: AnySchema, bytes: Uint8Array | ByteReader,
  * Paths are declaration indices, outermost first (`[fieldIndex, nestedIndex, ...]`), exactly the
  * shape `markField` wants. Lists are whole-replace on the wire, so anything that changes inside a
  * list marks the list field itself.
+ *
+ * A `bytes(n)` field reads back as a proxy over the stored `Uint8Array`. Every write path through
+ * it — `data[i] = v`, `set`, `fill`, `copyWithin`, `sort`, `reverse` — is validated (no silent
+ * wrap-around mod 256) and marks only the byte range it actually changed (`markBytes`), so a one
+ * tile edit sends a few bytes rather than the chunk. Every other member is forwarded to the target
+ * itself, because TypedArray methods and accessors throw when `this` is a Proxy. Two holes are
+ * documented rather than closed: `subarray()` and `.buffer` hand back untracked views of the same
+ * memory, and `ArrayBuffer.isView(proxy)` is false.
  */
 
 interface Tracked<S> {
@@ -1320,6 +1427,11 @@ declare function frozenProxy<T>(value: T, ownershipHint: string): DeepReadonly<T
 
 interface SchemaChange {
     readonly kind: 'additive' | 'breaking';
+    /**
+     * Which part of the schema changed. `path` alone cannot say: a collection path is the bare
+     * collection name, and `rpc` / `message` are legal collection names (issue #226).
+     */
+    readonly scope: SchemaChangeScope;
     /** Stable machine tag, e.g. `field.removed`, `enum.appended`. */
     readonly code: string;
     /** Dotted path to the changed thing, e.g. `players.color`, `rpc.dealCards.params.count`. */
@@ -1327,11 +1439,13 @@ interface SchemaChange {
     /** One-line human message, printed verbatim by the CLI. */
     readonly message: string;
 }
+type SchemaChangeScope = 'collection' | 'rpc' | 'message' | 'roles';
 /** Compares two compiled schemas and returns every classified change, sorted by path then code. */
 declare function diffSchemas(oldSchema: AnySchema, newSchema: AnySchema): SchemaChange[];
 /**
- * True when every breaking change in `changes` lives under the RPC table (`rpc` / `rpc.*`) or the
- * message table (`message.*`), and there is at least one. Such a change breaks connected clients
+ * True when every breaking change in `changes` has scope `rpc` or `message` (the RPC table or the
+ * message table), and there is at least one. Scope, not the path string: a collection named `rpc`
+ * or `message` has paths that look like the tables' (issue #226). Such a change breaks connected clients
  * (the version fence reconnects them) but touches nothing a snapshot stores, so a deploy needs
  * `--allow-breaking` and no migration: a chain step without one decodes and re-encodes losslessly.
  *
@@ -1344,4 +1458,4 @@ declare function diffSchemas(oldSchema: AnySchema, newSchema: AnySchema): Schema
  */
 declare function breakingIsWireOnly(changes: readonly SchemaChange[]): boolean;
 
-export { type AddOptions, type AnyDef, type AnyMessageMap, type AnyRpc, type AnySchema, type AnyType, type Body2dState, type BodyFieldsOf, type BroadcastProxy, ByteReader, ByteWriter, CANONICAL_VERSION, type ClientCallProxy, type ClientImplementations, type ClientRpcs, type ClientState, type Collection, type CollectionDesc, type CollectionDirty, type DecodeSnapshotOptions, type DecodedSnapshot, type DeepReadonly, type DeepWritable, type DefMap, type Delta, type DeltaCollection, type DeltaOp, type DirtySet, EntityCollection, type EntityDef, type EntityOptions, type EntityPhysics, type FieldDesc, type FieldMask, type Fields, type FromCanonicalOptions, type GridDesc, type GridOptions, type Header, ID_MAX_BYTES, type Implementations, type Infer, type InferFields, type InitFields, type InitOf, type InstanceOf, type Kind, MAX_MESSAGES, MAX_USER_RPCS, type MessageChannels, type MessageDesc, type MessageMap, type MessageNames, type MessageValue, type MessagesOf, type OwnableKeys, type Owned, type OwnershipDesc, type OwnershipLeave, type OwnershipLeaveAction, type OwnershipOptions, type OwnershipPosition, type OwnershipTransfer, PERSIST_BLOB_BYTES, PHYSICS_BODY_CHANNELS, type PhysicsBodyChannel, type PhysicsBodyMap, type PhysicsDesc, type PhysicsKeys, type PlainState, RESERVED_COLLECTION_NAMES, RESERVED_RPC_NAMES, RESERVED_RPC_PREFIX, type ReadOptions, type ReadonlyBodyFields, type ReadonlyCollection, type RecordDirty, type RoleOf, type RpcDef, type RpcDesc, type RpcDirection, type RpcMap, type RpcParams, type RpcReturns, type RpcSpec, SERVER_OWNER, SINGLETON_ID, type Schema, type SchemaChange, type SchemaDefs, type SchemaIssue, type SchemaMessages, type SchemaOptions, type SchemaRoles, type SchemaRpc, type ServerCallProxy, type ServerMessageChannels, type ServerOwnedKeys, type ServerRpcs, type SingletonDef, type SnapshotOptions, type State, type Tracked, type Type, type TypeDesc, type ValueSink, type Visibility, type VisibleKeys, type WalkEvents, angleFrom2d, applyChannel2d, applyDelta, bool, breakingIsWireOnly, bytesEqual, canonicalOwnership, canonicalPhysics, canonicalType, channelOf2d, client, cloneValue, collectionDirty, compileOwnership, compilePhysics, computeDirty, createDirtySet, createFieldMask, createState, decodeDelta, decodeDeltaFrom, decodeFields, decodeSnapshot, defaultRecord, defaultValue, defineSchema, describeType, diffSchemas, encodeDelta, encodeFields, encodeSnapshot, entity, enumOf, estimateSize, f32, f64, filterDirty, frozenProxy, i32, isDirtyEmpty, isWhole, list, markAdd, markField, markOwner, markPath, markRemove, maxEncodedBytes, mergeDirty, mergeMask, normalizeRecord, normalizeValue, ownershipFromCanonical, parseHold, physicsFromCanonical, readValue, reconcileCollection, ref, schemaFromCanonical, server, sha256, sha256Hex, singleton, stableStringify, str, struct, toHex, track, u16, u32, u8, utf8Length, validateForDeploy, validateValue, walkDelta, walkSnapshot, writeValue };
+export { type AddOptions, type AnyDef, type AnyMessageMap, type AnyRpc, type AnySchema, type AnyType, BYTES_MAX, type Body2dState, type BodyFieldsOf, type BroadcastProxy, type ByteRange, ByteReader, ByteWriter, type BytesPatch, CANONICAL_VERSION, type ClientCallProxy, type ClientImplementations, type ClientRpcs, type ClientState, type Collection, type CollectionDesc, type CollectionDirty, type DecodeDeltaOptions, type DecodeSnapshotOptions, type DecodedSnapshot, type DeepReadonly, type DeepWritable, type DefMap, type Delta, type DeltaCollection, type DeltaOp, type DirtySet, EntityCollection, type EntityDef, type EntityOptions, type EntityPhysics, type FieldDesc, type FieldMask, type Fields, type FromCanonicalOptions, type GridDesc, type GridOptions, type Header, ID_MAX_BYTES, type Implementations, type Infer, type InferFields, type InitFields, type InitOf, type InstanceOf, type Kind, MAX_BYTE_RANGES, MAX_MESSAGES, MAX_USER_RPCS, type MessageChannels, type MessageDesc, type MessageMap, type MessageNames, type MessageValue, type MessagesOf, type OwnableKeys, type Owned, type OwnershipDesc, type OwnershipLeave, type OwnershipLeaveAction, type OwnershipOptions, type OwnershipPosition, type OwnershipTransfer, PERSIST_BLOB_BYTES, PHYSICS_BODY_CHANNELS, type PhysicsBodyChannel, type PhysicsBodyMap, type PhysicsDesc, type PhysicsKeys, type PlainState, RESERVED_COLLECTION_NAMES, RESERVED_RPC_NAMES, RESERVED_RPC_PREFIX, type ReadOptions, type ReadonlyBodyFields, type ReadonlyCollection, type RecordDirty, type RoleOf, type RpcDef, type RpcDesc, type RpcDirection, type RpcMap, type RpcParams, type RpcReturns, type RpcSpec, SERVER_OWNER, SINGLETON_ID, type Schema, type SchemaChange, type SchemaChangeScope, type SchemaDefs, type SchemaIssue, type SchemaMessages, type SchemaOptions, type SchemaRoles, type SchemaRpc, type ServerCallProxy, type ServerMessageChannels, type ServerOwnedKeys, type ServerRpcs, type SingletonDef, type SnapshotOptions, type State, type Tracked, type Type, type TypeDesc, type ValueSink, type Visibility, type VisibleKeys, type WalkEvents, angleFrom2d, applyChannel2d, applyDelta, base64ToBytes, bool, breakingIsWireOnly, bytes, bytesEqual, bytesToBase64, canonicalOwnership, canonicalPhysics, canonicalType, channelOf2d, client, cloneValue, collectionDirty, compileOwnership, compilePhysics, computeDirty, containsBytes, copyBytes, createDirtySet, createFieldMask, createState, decodeDelta, decodeDeltaFrom, decodeFields, decodeSnapshot, defaultRecord, defaultValue, defineSchema, describeType, diffByteRanges, diffSchemas, encodeDelta, encodeFields, encodeSnapshot, entity, enumOf, estimateSize, f32, f64, filterDirty, frozenProxy, i32, isDirtyEmpty, isWhole, list, markAdd, markBytes, markBytesPath, markField, markOwner, markPath, markRemove, maxEncodedBytes, mergeDirty, mergeMask, normalizeRecord, normalizeValue, ownershipFromCanonical, parseHold, physicsFromCanonical, rangesPatchBytes, readValue, reconcileCollection, ref, schemaFromCanonical, server, settleRanges, sha256, sha256Hex, singleton, stableStringify, str, struct, toHex, track, u16, u32, u8, unionRanges, utf8Length, validateForDeploy, validateValue, walkDelta, walkSnapshot, writeValue };