@colyseus/schema 3.0.76 → 4.0.0

package/src/Schema.ts

@@ -4,7 +4,7 @@ import { DEFAULT_VIEW_TAG, type DefinitionType } from "./annotations";
 import { AssignableProps, NonFunctionPropNames, ToJSON } from './types/HelperTypes';
 
 import { ChangeSet, ChangeSetName, ChangeTree, IRef, Ref } from './encoder/ChangeTree';
-import { $changes, $decoder, $deleteByIndex, $descriptors, $encoder, $filter, $getByIndex, $track } from './types/symbols';
+import { $changes, $decoder, $deleteByIndex, $descriptors, $encoder, $filter, $getByIndex, $refId, $track } from './types/symbols';
 import { StateView } from './encoder/StateView';
 
 import { encodeSchemaOperation } from './encoder/EncodeOperation';
@@ -22,6 +22,8 @@ export class Schema<C = any> implements IRef {
     static [$encoder] = encodeSchemaOperation;
     static [$decoder] = decodeSchemaOperation;
 
+    [$refId]?: number;
+
     /**
      * Assign the property descriptors required to track changes on this instance.
      * @param instance
@@ -95,13 +97,79 @@ export class Schema<C = any> implements IRef {
         }
     }
 
-    public assign<T extends Partial<this>>(
-        props: AssignableProps<T>,
-    ): this {
+    /**
+     * Assign properties to the instance.
+     * @param props Properties to assign to the instance
+     * @returns
+     */
+    public assign<T extends Partial<this>>(props: AssignableProps<T>,): this {
         Object.assign(this, props);
         return this;
     }
 
+    /**
+     * Restore the instance from JSON data.
+     * @param jsonData JSON data to restore the instance from
+     * @returns
+     */
+    public restore(jsonData: ToJSON<this>): this {
+        const metadata: Metadata = (this.constructor as typeof Schema)[Symbol.metadata];
+
+        for (const fieldIndex in metadata) {
+            const field = metadata[fieldIndex as any as number];
+            const fieldName = field.name as keyof this;
+            const fieldType = field.type;
+            const value = (jsonData as any)[fieldName];
+
+            if (value === undefined || value === null) {
+                continue;
+            }
+
+            if (typeof fieldType === "string") {
+                // Primitive type: assign directly
+                this[fieldName] = value;
+
+            } else if (Schema.is(fieldType)) {
+                // Schema type: create instance and restore
+                const instance = new (fieldType as typeof Schema)();
+                instance.restore(value);
+                this[fieldName] = instance as any;
+
+            } else if (typeof fieldType === "object") {
+                // Collection types: { map: ... }, { array: ... }, etc.
+                const collectionType = Object.keys(fieldType)[0] as string;
+                const childType = (fieldType as any)[collectionType];
+
+                if (collectionType === "map") {
+                    const mapSchema = this[fieldName] as any;
+                    for (const key in value) {
+                        if (Schema.is(childType)) {
+                            const childInstance = new (childType as typeof Schema)();
+                            childInstance.restore(value[key]);
+                            mapSchema.set(key, childInstance);
+                        } else {
+                            mapSchema.set(key, value[key]);
+                        }
+                    }
+
+                } else if (collectionType === "array") {
+                    const arraySchema = this[fieldName] as any;
+                    for (let i = 0; i < value.length; i++) {
+                        if (Schema.is(childType)) {
+                            const childInstance = new (childType as typeof Schema)();
+                            childInstance.restore(value[i]);
+                            arraySchema.push(childInstance);
+                        } else {
+                            arraySchema.push(value[i]);
+                        }
+                    }
+                }
+            }
+        }
+
+        return this;
+    }
+
     /**
      * (Server-side): Flag a property to be encoded for the next patch.
      * @param instance Schema instance
@@ -190,7 +258,7 @@ export class Schema<C = any> implements IRef {
         const contents = (showContents) ? ` - ${JSON.stringify(ref.toJSON())}` : "";
         const changeTree: ChangeTree = ref[$changes];
 
-        const refId = (decoder) ? decoder.root.refIds.get(ref) : changeTree.refId;
+        const refId = (ref as IRef)[$refId];
         const root = (decoder) ? decoder.root : changeTree.root;
 
          // log reference count if > 1
@@ -218,7 +286,7 @@ export class Schema<C = any> implements IRef {
         let current = ref[$changes].root[changeSet].next;
         while (current) {
             if (current.changeTree) {
-                encodeOrder.push(current.changeTree.refId);
+                encodeOrder.push(current.changeTree.ref[$refId]);
             }
             current = current.next;
         }
@@ -243,7 +311,7 @@ export class Schema<C = any> implements IRef {
         const changeSet = (isEncodeAll) ? changeTree.allChanges : changeTree.changes;
         const changeSetName = (isEncodeAll) ? "allChanges" : "changes";
 
-        let output = `${instance.constructor.name} (${changeTree.refId}) -> .${changeSetName}:\n`;
+        let output = `${instance.constructor.name} (${instance[$refId]}) -> .${changeSetName}:\n`;
 
         function dumpChangeSet(changeSet: ChangeSet) {
             changeSet.operations
@@ -262,7 +330,7 @@ export class Schema<C = any> implements IRef {
             changeTree.filteredChanges &&
             (changeTree.filteredChanges.operations).filter(op => op).length > 0
         ) {
-            output += `${instance.constructor.name} (${changeTree.refId}) -> .filteredChanges:\n`;
+            output += `${instance.constructor.name} (${instance[$refId]}) -> .filteredChanges:\n`;
             dumpChangeSet(changeTree.filteredChanges);
         }
 
@@ -272,7 +340,7 @@ export class Schema<C = any> implements IRef {
             changeTree.allFilteredChanges &&
             (changeTree.allFilteredChanges.operations).filter(op => op).length > 0
         ) {
-            output += `${instance.constructor.name} (${changeTree.refId}) -> .allFilteredChanges:\n`;
+            output += `${instance.constructor.name} (${instance[$refId]}) -> .allFilteredChanges:\n`;
             dumpChangeSet(changeTree.allFilteredChanges);
         }
 
@@ -313,14 +381,14 @@ export class Schema<C = any> implements IRef {
             }
 
             if (includeChangeTree) {
-                instanceRefIds.push(changeTree.refId);
+                instanceRefIds.push(changeTree.ref[$refId]);
                 totalOperations += Object.keys(changes).length;
                 changeTrees.set(changeTree, parentChangeTrees.reverse());
             }
         }
 
         output += "---\n"
-        output += `root refId: ${rootChangeTree.refId}\n`;
+        output += `root refId: ${rootChangeTree.ref[$refId]}\n`;
         output += `Total instances: ${instanceRefIds.length} (refIds: ${instanceRefIds.join(", ")})\n`;
         output += `Total changes: ${totalOperations}\n`;
         output += "---\n"
@@ -330,7 +398,7 @@ export class Schema<C = any> implements IRef {
         for (const [changeTree, parentChangeTrees] of changeTrees.entries()) {
             parentChangeTrees.forEach((parentChangeTree, level) => {
                 if (!visitedParents.has(parentChangeTree)) {
-                    output += `${getIndent(level)}${parentChangeTree.ref.constructor.name} (refId: ${parentChangeTree.refId})\n`;
+                    output += `${getIndent(level)}${parentChangeTree.ref.constructor.name} (refId: ${parentChangeTree.ref[$refId]})\n`;
                     visitedParents.add(parentChangeTree);
                 }
             });
@@ -340,7 +408,7 @@ export class Schema<C = any> implements IRef {
             const indent = getIndent(level);
 
             const parentIndex = (level > 0) ? `(${changeTree.parentIndex}) ` : "";
-            output += `${indent}${parentIndex}${changeTree.ref.constructor.name} (refId: ${changeTree.refId}) - changes: ${Object.keys(changes).length}\n`;
+            output += `${indent}${parentIndex}${changeTree.ref.constructor.name} (refId: ${changeTree.ref[$refId]}) - changes: ${Object.keys(changes).length}\n`;
 
             for (const index in changes) {
                 const operation = changes[index];

package/src/annotations.ts

@@ -33,11 +33,11 @@ export type PrimitiveType = RawPrimitiveType | typeof Schema | object;
 // TODO: infer "default" value type correctly.
 export type DefinitionType<T extends PrimitiveType = PrimitiveType> = T
     | T[]
-    | { type: T, default?: InferValueType<T>, view?: boolean | number }
-    | { array: T, default?: ArraySchema<InferValueType<T>>, view?: boolean | number }
-    | { map: T, default?: MapSchema<InferValueType<T>>, view?: boolean | number }
-    | { collection: T, default?: CollectionSchema<InferValueType<T>>, view?: boolean | number }
-    | { set: T, default?: SetSchema<InferValueType<T>>, view?: boolean | number };
+    | { type: T, default?: InferValueType<T>, view?: boolean | number, sync?: boolean }
+    | { array: T, default?: ArraySchema<InferValueType<T>>, view?: boolean | number, sync?: boolean }
+    | { map: T, default?: MapSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean }
+    | { collection: T, default?: CollectionSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean }
+    | { set: T, default?: SetSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean };
 
 export type Definition = { [field: string]: DefinitionType };
 
@@ -574,7 +574,10 @@ export function schema<
                     : value['view'];
             }
 
-            fields[fieldName] = getNormalizedType(value);
+            // allow to define a field as not synced
+            if (value['sync'] !== false) {
+                fields[fieldName] = getNormalizedType(value);
+            }
 
             // If no explicit default provided, handle automatic instantiation for collection types
             if (!Object.prototype.hasOwnProperty.call(value, 'default')) {
@@ -597,12 +600,7 @@ export function schema<
 
                 } else if (value['type'] !== undefined && Schema.is(value['type'])) {
                     // Direct Schema type: Type → new Type()
-                    if (!value['type'].prototype.initialize || value['type'].prototype.initialize.length === 0) {
-                        // only auto-initialize Schema instances if:
-                        // - they don't have an initialize method
-                        // - or initialize method doesn't accept any parameters
-                        defaultValues[fieldName] = new value['type']();
-                    }
+                    defaultValues[fieldName] = new value['type']();
                 }
             } else {
                 defaultValues[fieldName] = value['default'];
@@ -612,12 +610,7 @@ export function schema<
         } else if (typeof (value) === "function") {
             if (Schema.is(value)) {
                 // Direct Schema type: Type → new Type()
-                if (!value.prototype.initialize || value.prototype.initialize.length === 0) {
-                    // only auto-initialize Schema instances if:
-                    // - they don't have an initialize method
-                    // - or initialize method doesn't accept any parameters
-                    defaultValues[fieldName] = new value();
-                }
+                defaultValues[fieldName] = new value();
                 fields[fieldName] = getNormalizedType(value);
             } else {
                 methods[fieldName] = value;
@@ -645,33 +638,14 @@ export function schema<
         return defaults;
     };
 
-    const getParentProps = (props: any) => {
-        const fieldNames = Object.keys(fields);
-        const parentProps: any = {};
-        for (const key in props) {
-            if (!fieldNames.includes(key)) {
-                parentProps[key] = props[key];
-            }
-        }
-        return parentProps;
-    }
-
     /** @codegen-ignore */
     const klass = Metadata.setFields<any>(class extends (inherits as any) {
         constructor(...args: any[]) {
+            super(Object.assign({}, getDefaultValues(), args[0] || {}));
+
             // call initialize method
             if (methods.initialize && typeof methods.initialize === 'function') {
-                super(Object.assign({}, getDefaultValues(), getParentProps(args[0] || {})));
-                /**
-                 * only call initialize() in the current class, not the parent ones.
-                 * see "should not call initialize automatically when creating an instance of inherited Schema"
-                 */
-                if (new.target === klass) {
-                    methods.initialize.apply(this, args);
-                }
-
-            } else {
-                super(Object.assign({}, getDefaultValues(), args[0] || {}));
+                methods.initialize.apply(this, args);
             }
         }
     }, fields) as SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P>;

package/src/codegen/parser.ts

@@ -326,7 +326,7 @@ function inspectNode(node: ts.Node, context: Context, decoratorName: string) {
             break;
     }
 
-    ts.forEachChild(node, (n) => inspectNode(n, context, decoratorName));
+    ts.forEachChild(node, (n: ts.Node) => inspectNode(n, context, decoratorName));
 }
 
 let parsedFiles: { [filename: string]: boolean };

package/src/decoder/DecodeOperation.ts

@@ -4,7 +4,7 @@ import { Schema } from "../Schema";
 import type { Ref } from "../encoder/ChangeTree";
 import type { Decoder } from "./Decoder";
 import { Iterator, decode } from "../encoding/decode";
-import { $childType, $deleteByIndex, $getByIndex } from "../types/symbols";
+import { $childType, $deleteByIndex, $getByIndex, $refId } from "../types/symbols";
 
 import type { MapSchema } from "../types/custom/MapSchema";
 import type { ArraySchema } from "../types/custom/ArraySchema";
@@ -27,7 +27,7 @@ export const DEFINITION_MISMATCH = -1;
 
 export type DecodeOperation<T extends Schema = any> = (
     decoder: Decoder<T>,
-    bytes: Buffer,
+    bytes: Uint8Array,
     it: Iterator,
     ref: Ref,
     allChanges: DataChange[],
@@ -39,7 +39,7 @@ export function decodeValue<T extends Ref>(
     ref: T,
     index: number,
     type: any,
-    bytes: Buffer,
+    bytes: Uint8Array,
     it: Iterator,
     allChanges: DataChange[],
 ) {
@@ -51,7 +51,7 @@ export function decodeValue<T extends Ref>(
     if ((operation & OPERATION.DELETE) === OPERATION.DELETE)
     {
         // Flag `refId` for garbage collection.
-        const previousRefId = $root.refIds.get(previousValue);
+        const previousRefId = previousValue?.[$refId];
         if (previousRefId !== undefined) { $root.removeRef(previousRefId); }
 
         //
@@ -107,7 +107,7 @@ export function decodeValue<T extends Ref>(
         value[$childType] = Object.values(type)[0]; // cache childType for ArraySchema and MapSchema
 
         if (previousValue) {
-            let previousRefId = $root.refIds.get(previousValue);
+            let previousRefId = previousValue[$refId];
 
             if (previousRefId !== undefined && refId !== previousRefId) {
                 //
@@ -120,7 +120,7 @@ export function decodeValue<T extends Ref>(
 
                     // if value is a schema, remove its reference
                     if (typeof(value) === "object") {
-                        previousRefId = $root.refIds.get(value);
+                        previousRefId = value[$refId];
                         $root.removeRef(previousRefId);
                     }
 
@@ -148,7 +148,7 @@ export function decodeValue<T extends Ref>(
 
 export const decodeSchemaOperation: DecodeOperation = function <T extends Schema>(
     decoder: Decoder<any>,
-    bytes: Buffer,
+    bytes: Uint8Array,
     it: Iterator,
     ref: T,
     allChanges: DataChange[],
@@ -197,7 +197,7 @@ export const decodeSchemaOperation: DecodeOperation = function <T extends Schema
 
 export const decodeKeyValueOperation: DecodeOperation = function (
     decoder: Decoder<any>,
-    bytes: Buffer,
+    bytes: Uint8Array,
     it: Iterator,
     ref: Ref,
     allChanges: DataChange[]
@@ -280,7 +280,7 @@ export const decodeKeyValueOperation: DecodeOperation = function (
 
 export const decodeArray: DecodeOperation = function (
     decoder: Decoder<any>,
-    bytes: Buffer,
+    bytes: Uint8Array,
     it: Iterator,
     ref: ArraySchema,
     allChanges: DataChange[]

package/src/decoder/Decoder.ts

@@ -1,5 +1,5 @@
 import { TypeContext } from "../types/TypeContext";
-import { $changes, $childType, $decoder, $onDecodeEnd } from "../types/symbols";
+import { $changes, $childType, $decoder, $onDecodeEnd, $refId } from "../types/symbols";
 import { Schema } from "../Schema";
 
 import { decode } from "../encoding/decode";
@@ -38,7 +38,7 @@ export class Decoder<T extends Schema = any> {
     }
 
     decode(
-        bytes: Buffer,
+        bytes: Uint8Array,
         it: Iterator = { offset: 0 },
         ref: Ref = this.state,
     ) {
@@ -102,7 +102,7 @@ export class Decoder<T extends Schema = any> {
         return allChanges;
     }
 
-    skipCurrentStructure(bytes: Buffer, it: Iterator, totalBytes: number) {
+    skipCurrentStructure(bytes: Uint8Array, it: Iterator, totalBytes: number) {
         //
         // keep skipping next bytes until reaches a known structure
         // by local decoder.
@@ -119,7 +119,7 @@ export class Decoder<T extends Schema = any> {
         }
     }
 
-    getInstanceType(bytes: Buffer, it: Iterator, defaultType: typeof Schema): typeof Schema {
+    getInstanceType(bytes: Uint8Array, it: Iterator, defaultType: typeof Schema): typeof Schema {
         let type: typeof Schema;
 
         if (bytes[it.offset] === TYPE_ID) {
@@ -137,7 +137,7 @@ export class Decoder<T extends Schema = any> {
 
     removeChildRefs(ref: Collection, allChanges: DataChange[]) {
         const needRemoveRef = typeof ((ref as any)[$childType]) !== "string";
-        const refId = this.root.refIds.get(ref as Ref);
+        const refId = (ref as Ref)[$refId];
 
         ref.forEach((value: any, key: any) => {
             allChanges.push({
@@ -150,7 +150,7 @@ export class Decoder<T extends Schema = any> {
             });
 
             if (needRemoveRef) {
-                this.root.removeRef(this.root.refIds.get(value));
+                this.root.removeRef(value[$refId]);
             }
         });
     }

package/src/decoder/ReferenceTracker.ts

@@ -1,5 +1,5 @@
 import { Metadata } from "../Metadata";
-import { $childType } from "../types/symbols";
+import { $childType, $refId } from "../types/symbols";
 import { Ref } from "../encoder/ChangeTree";
 import { spliceOne } from "../types/utils";
 import { OPERATION } from "../encoding/spec";
@@ -26,7 +26,6 @@ export class ReferenceTracker {
     // For direct access of structures during decoding time.
     //
     public refs = new Map<number, Ref>();
-    public refIds = new WeakMap<Ref, number>();
 
     public refCount: { [refId: number]: number; } = {};
     public deletedRefs = new Set<number>();
@@ -41,7 +40,7 @@ export class ReferenceTracker {
     // for decoding
     addRef(refId: number, ref: Ref, incrementCount: boolean = true) {
         this.refs.set(refId, ref);
-        this.refIds.set(ref, refId);
+        ref[$refId] = refId;
 
         if (incrementCount) {
             this.refCount[refId] = (this.refCount[refId] || 0) + 1;
@@ -104,9 +103,12 @@ export class ReferenceTracker {
                 const metadata: Metadata = (ref.constructor as typeof Schema)[Symbol.metadata];
                 for (const index in metadata) {
                     const field = metadata[index as any as number].name;
-                    const childRefId = typeof(ref[field as keyof Ref]) === "object" && this.refIds.get((ref as any)[field]);
-                    if (childRefId && !this.deletedRefs.has(childRefId)) {
-                        this.removeRef(childRefId);
+                    const child = ref[field as keyof Ref];
+                    if (typeof(child) === "object" && child) {
+                        const childRefId = (child as any)[$refId];
+                        if (childRefId !== undefined && !this.deletedRefs.has(childRefId)) {
+                            this.removeRef(childRefId);
+                        }
                     }
                 }
 
@@ -114,8 +116,8 @@ export class ReferenceTracker {
                 if (typeof ((ref as any)[$childType]) === "function") {
                     Array.from((ref as MapSchema).values())
                         .forEach((child) => {
-                            const childRefId = this.refIds.get(child);
-                            if (!this.deletedRefs.has(childRefId)) {
+                            const childRefId = child[$refId];
+                            if (childRefId !== undefined && !this.deletedRefs.has(childRefId)) {
                                 this.removeRef(childRefId);
                             }
                         });