@colyseus/schema 5.0.0 → 5.0.2

package/build/index.d.ts

@@ -22,7 +22,7 @@ export { Metadata } from "./Metadata.js";
 export { type, deprecated, owned, unreliable, transient, view, schema, entity, type DefinitionType, type PrimitiveType, type Definition, type FieldsAndMethods, type SchemaWithExtendsConstructor, type SchemaWithExtends, type SchemaType, } from "./annotations.js";
 export { t, FieldBuilder, isBuilder, type BuilderDefinition, type ChildType } from "./types/builder.js";
 export { TypeContext } from "./types/TypeContext.js";
-export type { InferValueType, InferSchemaInstanceType, AssignableProps } from "./types/HelperTypes.js";
+export type { InferValueType, InferSchemaInstanceType, AssignableProps, BuilderInitProps } from "./types/HelperTypes.js";
 export { getDecoderStateCallbacks, type CallbackProxy, type SchemaCallback, type CollectionCallback, type SchemaCallbackProxy } from "./decoder/strategy/getDecoderStateCallbacks.js";
 export { Callbacks, StateCallbackStrategy } from "./decoder/strategy/Callbacks.js";
 export { getRawChangesCallback } from "./decoder/strategy/RawChanges.js";

package/build/index.js

@@ -32,7 +32,31 @@
 
     Symbol.metadata ??= Symbol.for("Symbol.metadata");
 
-    const $refId = Symbol("$refId");
+    const _g = (function () {
+        if (typeof globalThis !== "undefined")
+            return globalThis;
+        if (typeof global !== "undefined")
+            return global;
+        if (typeof self !== "undefined")
+            return self;
+        if (typeof window !== "undefined")
+            return window;
+        return {};
+    })();
+    if (typeof Symbol === "function" && typeof Symbol.for !== "function") {
+        const REGISTRY_KEY = "colyseus.symbolRegistry";
+        const registry = _g[REGISTRY_KEY] || (_g[REGISTRY_KEY] = Object.create(null));
+        Symbol.for = function (key) {
+            return registry[key] || (registry[key] = Symbol(key));
+        };
+        Symbol.keyFor = function (sym) {
+            for (const k in registry)
+                if (registry[k] === sym)
+                    return k;
+            return undefined;
+        };
+    }
+    const $refId = Symbol.for("$refId");
     const $track = "~track";
     const $encoder = "~encoder";
     const $decoder = "~decoder";
@@ -44,12 +68,12 @@
      *
      * Real JS Symbol — see the `$values` comment for rationale.
      */
-    const $changes = Symbol("$changes");
+    const $changes = Symbol.for("$changes");
     /**
      * Used to keep track of the type of the child elements of a collection
      * (MapSchema, ArraySchema, etc.). Real Symbol — same rationale as $values.
      */
-    const $childType = Symbol("$childType");
+    const $childType = Symbol.for("$childType");
     /**
      * Self-reference an instance sets on `this` so its own methods can recover
      * the underlying object even when `this` is a Proxy wrapper. Used by
@@ -57,7 +81,7 @@
      * once at the top of hot methods and then access fields directly without
      * paying the Proxy.get cost on every read.
      */
-    const $proxyTarget = Symbol("$proxyTarget");
+    const $proxyTarget = Symbol.for("$proxyTarget");
     /**
      * Optional "discard" method for custom types (ArraySchema)
      * (Discards changes for next serialization)
@@ -76,7 +100,7 @@
      * which means we can drop Object.defineProperty(...{ enumerable: false })
      * and avoid the slow-path / dictionary-mode hazards that come with it.
      */
-    const $values = Symbol("$values");
+    const $values = Symbol.for("$values");
     /**
      * Brand for FieldBuilder instances so schema() can detect them.
      */
@@ -5390,9 +5414,23 @@
     /**
      * Chainable field builder. Instances are produced by `t.*()` factories.
      *
-     * The generic parameter T is the runtime/JS type of the field (e.g. `number`,
-     * `string`, `ArraySchema<Item>`). schema() reads the internal configuration
-     * via `toDefinition()` and wires up metadata through the existing pipeline.
+     * Generics:
+     *  - `T` is the runtime/JS type of the field (e.g. `number`, `string`,
+     *    `ArraySchema<Item>`). `.optional()` widens it to `T | undefined`
+     *    so the inferred instance/toJSON shapes reflect absence.
+     *  - `HasDefault` is a compile-time flag that the field carries a
+     *    construction-time default — either an explicit `.default(v)` or an
+     *    auto-default from a collection factory (`t.array`, `t.map`, …) or a
+     *    Schema ref whose `initialize` takes zero args.
+     *  - `IsOptional` is a compile-time brand for `.optional()`. Both
+     *    `HasDefault` and `IsOptional` make the field omittable in
+     *    `BuilderInitProps<T>`. A separate brand (rather than reading
+     *    `undefined extends V`) sidesteps a TypeScript quirk where
+     *    class-generic-inferred `V` resolves `undefined extends V` as `true`
+     *    even for non-undefined types.
+     *
+     * schema() reads the internal configuration via `toDefinition()` and wires
+     * up metadata through the existing pipeline.
      */
     class FieldBuilder {
         [$builder] = true;
@@ -5409,6 +5447,7 @@
         _deprecatedThrows = true;
         _static = false;
         _stream = false;
+        _optional = false;
         _streamPriority = undefined;
         constructor(type) {
             this._type = type;
@@ -5503,6 +5542,16 @@
             this._deprecatedThrows = throws;
             return this;
         }
+        /**
+         * Mark this field as optional — inferred instance type becomes
+         * `T | undefined` and the property becomes omittable in initialization
+         * props. Skips the auto-instantiation of collection / Schema-ref
+         * defaults, so the field starts as `undefined` at runtime.
+         */
+        optional() {
+            this._optional = true;
+            return this;
+        }
         toDefinition() {
             return {
                 type: this._type,
@@ -5516,6 +5565,7 @@
                 deprecatedThrows: this._deprecatedThrows,
                 static: this._static,
                 stream: this._stream,
+                optional: this._optional,
                 streamPriority: this._streamPriority,
             };
         }
@@ -5544,9 +5594,7 @@
         b._stream = true;
         return b;
     });
-    function refFactory(ctor) {
-        return new FieldBuilder(ctor);
-    }
+    const refFactory = ((ctor) => new FieldBuilder(ctor));
     const t = Object.freeze({
         // Primitives
         string: primitive("string"),
@@ -6003,6 +6051,7 @@
         const staticFields = [];
         const streamFields = [];
         const streamPriorityFields = {};
+        const optionalFields = [];
         for (const fieldName in fieldsAndMethods) {
             const value = fieldsAndMethods[fieldName];
             if (isBuilder(value)) {
@@ -6032,11 +6081,15 @@
                 if (def.streamPriority !== undefined) {
                     streamPriorityFields[fieldName] = def.streamPriority;
                 }
+                if (def.optional) {
+                    optionalFields.push(fieldName);
+                }
                 if (def.hasDefault) {
                     defaultValues[fieldName] = def.default;
                 }
-                else {
+                else if (!def.optional) {
                     // Auto-instantiate collection/Schema defaults when none is provided.
+                    // `.optional()` opts out — field starts as undefined.
                     const rawType = def.type;
                     if (rawType && typeof rawType === "object") {
                         if (rawType.array !== undefined) {
@@ -6146,6 +6199,12 @@
                 Metadata.setStreamPriority(metadata, fieldName, streamPriorityFields[fieldName]);
             }
         }
+        if (optionalFields.length > 0) {
+            const metadata = klass[Symbol.metadata];
+            for (const fieldName of optionalFields) {
+                metadata[metadata[fieldName]].optional = true;
+            }
+        }
         if (name) {
             Object.defineProperty(klass, "name", { value: name });
         }

package/build/index.mjs

@@ -26,7 +26,31 @@ var OPERATION;
 
 Symbol.metadata ??= Symbol.for("Symbol.metadata");
 
-const $refId = Symbol("$refId");
+const _g = (function () {
+    if (typeof globalThis !== "undefined")
+        return globalThis;
+    if (typeof global !== "undefined")
+        return global;
+    if (typeof self !== "undefined")
+        return self;
+    if (typeof window !== "undefined")
+        return window;
+    return {};
+})();
+if (typeof Symbol === "function" && typeof Symbol.for !== "function") {
+    const REGISTRY_KEY = "colyseus.symbolRegistry";
+    const registry = _g[REGISTRY_KEY] || (_g[REGISTRY_KEY] = Object.create(null));
+    Symbol.for = function (key) {
+        return registry[key] || (registry[key] = Symbol(key));
+    };
+    Symbol.keyFor = function (sym) {
+        for (const k in registry)
+            if (registry[k] === sym)
+                return k;
+        return undefined;
+    };
+}
+const $refId = Symbol.for("$refId");
 const $track = "~track";
 const $encoder = "~encoder";
 const $decoder = "~decoder";
@@ -38,12 +62,12 @@ const $deleteByIndex = "~deleteByIndex";
  *
  * Real JS Symbol — see the `$values` comment for rationale.
  */
-const $changes = Symbol("$changes");
+const $changes = Symbol.for("$changes");
 /**
  * Used to keep track of the type of the child elements of a collection
  * (MapSchema, ArraySchema, etc.). Real Symbol — same rationale as $values.
  */
-const $childType = Symbol("$childType");
+const $childType = Symbol.for("$childType");
 /**
  * Self-reference an instance sets on `this` so its own methods can recover
  * the underlying object even when `this` is a Proxy wrapper. Used by
@@ -51,7 +75,7 @@ const $childType = Symbol("$childType");
  * once at the top of hot methods and then access fields directly without
  * paying the Proxy.get cost on every read.
  */
-const $proxyTarget = Symbol("$proxyTarget");
+const $proxyTarget = Symbol.for("$proxyTarget");
 /**
  * Optional "discard" method for custom types (ArraySchema)
  * (Discards changes for next serialization)
@@ -70,7 +94,7 @@ const $onDecodeEnd = "~onDecodeEnd";
  * which means we can drop Object.defineProperty(...{ enumerable: false })
  * and avoid the slow-path / dictionary-mode hazards that come with it.
  */
-const $values = Symbol("$values");
+const $values = Symbol.for("$values");
 /**
  * Brand for FieldBuilder instances so schema() can detect them.
  */
@@ -5384,9 +5408,23 @@ registerType("stream", { constructor: StreamSchema });
 /**
  * Chainable field builder. Instances are produced by `t.*()` factories.
  *
- * The generic parameter T is the runtime/JS type of the field (e.g. `number`,
- * `string`, `ArraySchema<Item>`). schema() reads the internal configuration
- * via `toDefinition()` and wires up metadata through the existing pipeline.
+ * Generics:
+ *  - `T` is the runtime/JS type of the field (e.g. `number`, `string`,
+ *    `ArraySchema<Item>`). `.optional()` widens it to `T | undefined`
+ *    so the inferred instance/toJSON shapes reflect absence.
+ *  - `HasDefault` is a compile-time flag that the field carries a
+ *    construction-time default — either an explicit `.default(v)` or an
+ *    auto-default from a collection factory (`t.array`, `t.map`, …) or a
+ *    Schema ref whose `initialize` takes zero args.
+ *  - `IsOptional` is a compile-time brand for `.optional()`. Both
+ *    `HasDefault` and `IsOptional` make the field omittable in
+ *    `BuilderInitProps<T>`. A separate brand (rather than reading
+ *    `undefined extends V`) sidesteps a TypeScript quirk where
+ *    class-generic-inferred `V` resolves `undefined extends V` as `true`
+ *    even for non-undefined types.
+ *
+ * schema() reads the internal configuration via `toDefinition()` and wires
+ * up metadata through the existing pipeline.
  */
 class FieldBuilder {
     [$builder] = true;
@@ -5403,6 +5441,7 @@ class FieldBuilder {
     _deprecatedThrows = true;
     _static = false;
     _stream = false;
+    _optional = false;
     _streamPriority = undefined;
     constructor(type) {
         this._type = type;
@@ -5497,6 +5536,16 @@ class FieldBuilder {
         this._deprecatedThrows = throws;
         return this;
     }
+    /**
+     * Mark this field as optional — inferred instance type becomes
+     * `T | undefined` and the property becomes omittable in initialization
+     * props. Skips the auto-instantiation of collection / Schema-ref
+     * defaults, so the field starts as `undefined` at runtime.
+     */
+    optional() {
+        this._optional = true;
+        return this;
+    }
     toDefinition() {
         return {
             type: this._type,
@@ -5510,6 +5559,7 @@ class FieldBuilder {
             deprecatedThrows: this._deprecatedThrows,
             static: this._static,
             stream: this._stream,
+            optional: this._optional,
             streamPriority: this._streamPriority,
         };
     }
@@ -5538,9 +5588,7 @@ const streamFactory = ((child) => {
     b._stream = true;
     return b;
 });
-function refFactory(ctor) {
-    return new FieldBuilder(ctor);
-}
+const refFactory = ((ctor) => new FieldBuilder(ctor));
 const t = Object.freeze({
     // Primitives
     string: primitive("string"),
@@ -5997,6 +6045,7 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
     const staticFields = [];
     const streamFields = [];
     const streamPriorityFields = {};
+    const optionalFields = [];
     for (const fieldName in fieldsAndMethods) {
         const value = fieldsAndMethods[fieldName];
         if (isBuilder(value)) {
@@ -6026,11 +6075,15 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
             if (def.streamPriority !== undefined) {
                 streamPriorityFields[fieldName] = def.streamPriority;
             }
+            if (def.optional) {
+                optionalFields.push(fieldName);
+            }
             if (def.hasDefault) {
                 defaultValues[fieldName] = def.default;
             }
-            else {
+            else if (!def.optional) {
                 // Auto-instantiate collection/Schema defaults when none is provided.
+                // `.optional()` opts out — field starts as undefined.
                 const rawType = def.type;
                 if (rawType && typeof rawType === "object") {
                     if (rawType.array !== undefined) {
@@ -6140,6 +6193,12 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
             Metadata.setStreamPriority(metadata, fieldName, streamPriorityFields[fieldName]);
         }
     }
+    if (optionalFields.length > 0) {
+        const metadata = klass[Symbol.metadata];
+        for (const fieldName of optionalFields) {
+            metadata[metadata[fieldName]].optional = true;
+        }
+    }
     if (name) {
         Object.defineProperty(klass, "name", { value: name });
     }