@colyseus/schema 5.0.0 → 5.0.2

package/build/Metadata.d.ts

@@ -12,6 +12,7 @@ export type MetadataField = {
     owned?: boolean;
     static?: boolean;
     stream?: boolean;
+    optional?: boolean;
 };
 export type Metadata = {
     [$numFields]: number;

package/build/Reflection.d.ts

@@ -30,36 +30,36 @@ interface ReflectionStatic {
  * Reflection
  */
 export declare const ReflectionField: import("./annotations.js").SchemaWithExtendsConstructor<{
-    name: FieldBuilder<string>;
-    type: FieldBuilder<string>;
-    referencedType: FieldBuilder<number>;
-}, import("./index.js").AssignableProps<import("./index.js").InferSchemaInstanceType<{
-    name: FieldBuilder<string>;
-    type: FieldBuilder<string>;
-    referencedType: FieldBuilder<number>;
-}>>, typeof Schema>;
+    name: FieldBuilder<string, false, false>;
+    type: FieldBuilder<string, false, false>;
+    referencedType: FieldBuilder<number, false, false>;
+}, import("./index.js").BuilderInitProps<{
+    name: FieldBuilder<string, false, false>;
+    type: FieldBuilder<string, false, false>;
+    referencedType: FieldBuilder<number, false, false>;
+}>, typeof Schema>;
 export type ReflectionField = SchemaType<typeof ReflectionField>;
 export declare const ReflectionType: import("./annotations.js").SchemaWithExtendsConstructor<{
-    id: FieldBuilder<number>;
-    extendsId: FieldBuilder<number>;
-    fields: FieldBuilder<ArraySchema<{
-        name: string;
-        type: string;
-        referencedType: number;
-    } & Schema<any> & Schema<unknown>>>;
-}, import("./index.js").AssignableProps<import("./index.js").InferSchemaInstanceType<{
-    id: FieldBuilder<number>;
-    extendsId: FieldBuilder<number>;
-    fields: FieldBuilder<ArraySchema<{
-        name: string;
-        type: string;
-        referencedType: number;
-    } & Schema<any> & Schema<unknown>>>;
-}>>, typeof Schema>;
+    id: FieldBuilder<number, false, false>;
+    extendsId: FieldBuilder<number, false, false>;
+    fields: FieldBuilder<ArraySchema<{} & {
+        name?: string;
+        type?: string;
+        referencedType?: number;
+    } & Schema<any> & Schema<unknown>>, true, false>;
+}, import("./index.js").BuilderInitProps<{
+    id: FieldBuilder<number, false, false>;
+    extendsId: FieldBuilder<number, false, false>;
+    fields: FieldBuilder<ArraySchema<{} & {
+        name?: string;
+        type?: string;
+        referencedType?: number;
+    } & Schema<any> & Schema<unknown>>, true, false>;
+}>, typeof Schema>;
 export type ReflectionType = SchemaType<typeof ReflectionType>;
 export declare const Reflection: ReturnType<typeof schema<{
-    types: FieldBuilder<ArraySchema<ReflectionType>>;
-    rootType: FieldBuilder<number>;
+    types: FieldBuilder<ArraySchema<ReflectionType>, true, false>;
+    rootType: FieldBuilder<number, false, false>;
 }>> & ReflectionStatic;
 export type Reflection = SchemaType<typeof Reflection>;
 export {};

package/build/annotations.d.ts

@@ -3,7 +3,7 @@ import { Schema } from './Schema.js';
 import { ArraySchema } from './types/custom/ArraySchema.js';
 import { MapSchema } from './types/custom/MapSchema.js';
 import { TypeDefinition } from "./types/registry.js";
-import type { InferValueType, InferSchemaInstanceType, AssignableProps } from "./types/HelperTypes.js";
+import type { InferValueType, InferSchemaInstanceType, BuilderInitProps } from "./types/HelperTypes.js";
 import { CollectionSchema } from "./types/custom/CollectionSchema.js";
 import { SetSchema } from "./types/custom/SetSchema.js";
 import { StreamSchema } from "./types/custom/StreamSchema.js";
@@ -98,19 +98,21 @@ export declare function getPropertyDescriptor(fieldName: string, fieldIndex: num
 export declare function deprecated(throws?: boolean): PropertyDecorator;
 type ExtractInitProps<T> = T extends {
     initialize: (...args: infer P) => void;
-} ? P extends readonly [] ? never : P extends readonly [infer First] ? First extends object ? First : P : P : AssignableProps<InferSchemaInstanceType<T>>;
+} ? P extends readonly [] ? never : P extends readonly [infer First] ? First extends object ? First : P : P : BuilderInitProps<T>;
+type HasRequiredKeys<X> = {} extends X ? false : true;
 type IsInitPropsRequired<T> = T extends {
-    initialize: (props: any) => void;
-} ? true : T extends {
+    initialize: (...args: infer P) => void;
+} ? P extends readonly [] ? false : true : HasRequiredKeys<BuilderInitProps<T>>;
+type HasExplicitInit<T> = T extends {
     initialize: (...args: infer P) => void;
 } ? P extends readonly [] ? false : true : false;
 /**
  * A `schema()` field definition accepts a FieldBuilder, a Schema subclass
  * (shorthand for `t.ref(Class)`), or a method (attached to the prototype).
  */
-export type FieldsAndMethods = Record<string, FieldBuilder<any> | (new (...args: any[]) => Schema) | Function>;
+export type FieldsAndMethods = Record<string, FieldBuilder<any, boolean, boolean> | (new (...args: any[]) => Schema) | Function>;
 export interface SchemaWithExtends<T, P extends typeof Schema> {
-    extend: <T2 extends FieldsAndMethods = FieldsAndMethods>(fields: T2 & ThisType<InferSchemaInstanceType<T & T2>>, name?: string) => SchemaWithExtendsConstructor<T & T2, ExtractInitProps<T2>, P>;
+    extend: <T2 extends FieldsAndMethods = FieldsAndMethods>(fields: T2 & ThisType<InferSchemaInstanceType<T & T2>>, name?: string) => SchemaWithExtendsConstructor<T & T2, ExtractInitProps<T & T2>, P>;
 }
 /**
  * Get the type of the schema defined via `schema('Name', {...})` method.
@@ -127,7 +129,9 @@ export type SchemaType<T extends {
 }> = T['~type'];
 export interface SchemaWithExtendsConstructor<T, InitProps, P extends typeof Schema> extends SchemaWithExtends<T, P> {
     '~type': InferSchemaInstanceType<T>;
-    new (...args: [InitProps] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : IsInitPropsRequired<T> extends true ? [InitProps] : [InitProps?]): InferSchemaInstanceType<T> & InstanceType<P>;
+    new (...args: [
+        InitProps
+    ] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : HasExplicitInit<T> extends true ? [InitProps] : IsInitPropsRequired<T> extends true ? ([] | [InitProps]) : [InitProps?]): InferSchemaInstanceType<T> & InstanceType<P>;
     prototype: InferSchemaInstanceType<T> & InstanceType<P> & {
         initialize(...args: [InitProps] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : [InitProps]): void;
     };

package/build/index.cjs

@@ -28,7 +28,31 @@ exports.OPERATION = void 0;
 
 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";
@@ -40,12 +64,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
@@ -53,7 +77,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)
@@ -72,7 +96,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.
  */
@@ -5386,9 +5410,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;
@@ -5405,6 +5443,7 @@ class FieldBuilder {
     _deprecatedThrows = true;
     _static = false;
     _stream = false;
+    _optional = false;
     _streamPriority = undefined;
     constructor(type) {
         this._type = type;
@@ -5499,6 +5538,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,
@@ -5512,6 +5561,7 @@ class FieldBuilder {
             deprecatedThrows: this._deprecatedThrows,
             static: this._static,
             stream: this._stream,
+            optional: this._optional,
             streamPriority: this._streamPriority,
         };
     }
@@ -5540,9 +5590,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"),
@@ -5999,6 +6047,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)) {
@@ -6028,11 +6077,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) {
@@ -6142,6 +6195,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 });
     }