@colyseus/schema 5.0.11 → 5.0.12

package/build/Metadata.d.ts

@@ -1,16 +1,24 @@
 import { DefinitionType } from "./annotations.js";
 import { TypeDefinition } from "./types/registry.js";
-import { $descriptors, $encoders, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $staticFieldIndexes, $streamFieldIndexes, $streamPriorities, $transientFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
+import { $descriptors, $encoders, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $fullStateOnlyFieldIndexes, $streamFieldIndexes, $streamPriorities, $patchOnlyFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
+/**
+ * Field indexes ride in the low 6 bits of the operation byte
+ * (`(index | operation) & 255`), which leaves room for 0..63. Index 63 is
+ * given up: `DELETE_AND_ADD | 63` is 255, the same byte the decoder claims
+ * as SWITCH_TO_STRUCTURE before any field decoder sees it. Every nullable
+ * field can produce that operation (delete-then-set in one tick merges to
+ * DELETE_AND_ADD), so the slot is unusable rather than partly usable.
+ */
+export declare const MAX_FIELDS = 63;
 export type MetadataField = {
     type: DefinitionType;
     name: string;
     index: number;
     tag?: number;
     unreliable?: boolean;
-    transient?: boolean;
+    patchOnly?: boolean;
     deprecated?: boolean;
-    owned?: boolean;
-    static?: boolean;
+    fullStateOnly?: boolean;
     stream?: boolean;
     optional?: boolean;
 };
@@ -32,11 +40,11 @@ export type Metadata = {
     [$unreliableFieldIndexes]: number[];
 } & // all field indexes tagged with @unreliable
 {
-    [$transientFieldIndexes]: number[];
-} & // all field indexes tagged with @transient (not persisted to snapshots)
+    [$patchOnlyFieldIndexes]: number[];
+} & // all field indexes tagged with @patchOnly (not persisted to snapshots)
 {
-    [$staticFieldIndexes]: number[];
-} & // all field indexes tagged with @static (not tracked after assignment)
+    [$fullStateOnlyFieldIndexes]: number[];
+} & // all field indexes tagged @fullStateOnly / .fullStateOnly() (not tracked after assignment)
 {
     [$streamFieldIndexes]: number[];
 } & // all field indexes holding a t.stream(...) collection
@@ -75,8 +83,8 @@ export declare const Metadata: {
     addField(metadata: any, index: number, name: string, type: DefinitionType, descriptor?: PropertyDescriptor): void;
     setTag(metadata: Metadata, fieldName: string, tag: number): void;
     setUnreliable(metadata: Metadata, fieldName: string): void;
-    setTransient(metadata: Metadata, fieldName: string): void;
-    setStatic(metadata: Metadata, fieldName: string): void;
+    setPatchOnly(metadata: Metadata, fieldName: string): void;
+    setFullStateOnly(metadata: Metadata, fieldName: string): void;
     setStream(metadata: Metadata, fieldName: string): void;
     /**
      * Attach a declaration-scope priority callback to a stream field.
@@ -104,7 +112,7 @@ export declare const Metadata: {
     getFields(klass: any): any;
     hasViewTagAtIndex(metadata: Metadata, index: number): boolean;
     hasUnreliableAtIndex(metadata: Metadata, index: number): boolean;
-    hasTransientAtIndex(metadata: Metadata, index: number): boolean;
-    hasStaticAtIndex(metadata: Metadata, index: number): boolean;
+    hasPatchOnlyAtIndex(metadata: Metadata, index: number): boolean;
+    hasFullStateOnlyAtIndex(metadata: Metadata, index: number): boolean;
     hasStreamAtIndex(metadata: Metadata, index: number): boolean;
 };

package/build/annotations.d.ts

@@ -15,37 +15,31 @@ export type DefinitionType<T extends PrimitiveType = PrimitiveType> = T | T[] |
     default?: InferValueType<T>;
     view?: boolean | number;
     sync?: boolean;
-    owned?: boolean;
 } | {
     array: T;
     default?: ArraySchema<InferValueType<T>>;
     view?: boolean | number;
     sync?: boolean;
-    owned?: boolean;
 } | {
     map: T;
     default?: MapSchema<InferValueType<T>>;
     view?: boolean | number;
     sync?: boolean;
-    owned?: boolean;
 } | {
     collection: T;
     default?: CollectionSchema<InferValueType<T>>;
     view?: boolean | number;
     sync?: boolean;
-    owned?: boolean;
 } | {
     set: T;
     default?: SetSchema<InferValueType<T>>;
     view?: boolean | number;
     sync?: boolean;
-    owned?: boolean;
 } | {
     stream: T;
     default?: StreamSchema<InferValueType<T>>;
     view?: boolean | number;
     sync?: boolean;
-    owned?: boolean;
     priority?: (view: any, element: InferValueType<T>) => number;
 };
 export type Definition = {
@@ -80,17 +74,36 @@ export declare function entity<T extends Function>(constructor: T): T;
  * ```
  */
 export declare function view<T>(tag?: number): (target: T, fieldName: string) => void;
-export declare function owned<T>(target: T, field: string): void;
+/**
+ * `@unreliable` — route a field onto the unreliable transport channel, so a
+ * dropped update costs one stale value instead of stalling the ordered stream
+ * behind a retransmit. Primitive fields only (see `Metadata.setUnreliable`).
+ *
+ * The field's FIRST value still travels the reliable channel, as part of the
+ * owning instance's ADD; only later mutations become unreliable. A decoder
+ * cannot apply a write to a ref it has not been told about, so a value emitted
+ * ahead of that ADD would be dropped — and lost for good if the field is never
+ * written again.
+ */
 export declare function unreliable<T>(target: T, field: string): void;
 /**
- * @transient — mark a field as not persisted to snapshots (encodeAll /
- * encodeAllView). Transient fields are still emitted on per-tick patches
+ * @patchOnly — mark a field as not persisted to snapshots (encodeAll /
+ * encodeAllView). PatchOnly fields are still emitted on per-tick patches
  * (reliable or unreliable), but late-joining clients won't see them until
  * the next mutation.
  *
  * Orthogonal to @unreliable: a field can be either, both, or neither.
  */
-export declare function transient<T>(target: T, field: string): void;
+export declare function patchOnly<T>(target: T, field: string): void;
+/**
+ * @fullStateOnly — mark a field as delivered in the full state sync only
+ * (encodeAll / encodeAllView), never on per-tick patches. Writes after a
+ * client has joined are not propagated to it — populate these fields
+ * before clients connect (e.g. during onCreate).
+ *
+ * The exact mirror of @patchOnly — the two are mutually exclusive.
+ */
+export declare function fullStateOnly<T>(target: T, field: string): void;
 export declare function type(type: DefinitionType, options?: TypeOptions): PropertyDecorator;
 export declare function getPropertyDescriptor(fieldName: string, fieldIndex: number, type: DefinitionType, complexTypeKlass: TypeDefinition | false): {
     get: (this: Schema) => any;