@colyseus/schema 3.0.75 → 4.0.0

package/src/Reflection.ts

@@ -1,31 +1,15 @@
-import { type, PrimitiveType } from "./annotations";
+import { PrimitiveType, schema, SchemaType } from "./annotations";
 import { TypeContext } from "./types/TypeContext";
 import { Metadata } from "./Metadata";
-import { ArraySchema } from "./types/custom/ArraySchema";
 import { Iterator } from "./encoding/decode";
 import { Encoder } from "./encoder/Encoder";
 import { Decoder } from "./decoder/Decoder";
 import { Schema } from "./Schema";
 
 /**
- * Reflection
+ * Static methods available on Reflection
  */
-export class ReflectionField extends Schema {
-    @type("string") name: string;
-    @type("string") type: string;
-    @type("number") referencedType: number;
-}
-
-export class ReflectionType extends Schema {
-    @type("number") id: number;
-    @type("number") extendsId: number;
-    @type([ ReflectionField ]) fields = new ArraySchema<ReflectionField>();
-}
-
-export class Reflection extends Schema {
-    @type([ReflectionType]) types: ArraySchema<ReflectionType> = new ArraySchema<ReflectionType>();
-    @type("number") rootType: number;
-
+interface ReflectionStatic {
     /**
      * Encodes the TypeContext of an Encoder into a buffer.
      *
@@ -33,207 +17,234 @@ export class Reflection extends Schema {
      * @param it
      * @returns
      */
-    static encode(encoder: Encoder, it: Iterator = { offset: 0 }) {
-        const context = encoder.context;
+    encode: (encoder: Encoder, it?: Iterator) => Uint8Array;
 
-        const reflection = new Reflection();
-        const reflectionEncoder = new Encoder(reflection);
-
-        // rootType is usually the first schema passed to the Encoder
-        // (unless it inherits from another schema)
-        const rootType = context.schemas.get(encoder.state.constructor);
-        if (rootType > 0) { reflection.rootType = rootType; }
+    /**
+     * Decodes the TypeContext from a buffer into a Decoder instance.
+     *
+     * @param bytes Reflection.encode() output
+     * @param it
+     * @returns Decoder instance
+     */
+    decode: <T extends Schema = Schema>(bytes: Uint8Array, it?: Iterator) => Decoder<T>;
+}
 
-        const includedTypeIds = new Set<number>();
-        const pendingReflectionTypes: { [typeid: number]: ReflectionType[] } = {};
+/**
+ * Reflection
+ */
+export const ReflectionField = schema({
+    name: "string",
+    type: "string",
+    referencedType: "number",
+})
+export type ReflectionField = SchemaType<typeof ReflectionField>;
+
+export const ReflectionType = schema({
+    id: "number",
+    extendsId: "number",
+    fields: [ ReflectionField ],
+})
+export type ReflectionType = SchemaType<typeof ReflectionType>;
+
+export const Reflection = schema({
+    types: [ ReflectionType ],
+    rootType: "number",
+}) as ReturnType<typeof schema<{
+    types: [typeof ReflectionType];
+    rootType: "number";
+}>> & ReflectionStatic;
+
+export type Reflection = SchemaType<typeof Reflection>;
+
+Reflection.encode = function (encoder: Encoder, it: Iterator = { offset: 0 }) {
+    const context = encoder.context;
+
+    const reflection = new Reflection();
+    const reflectionEncoder = new Encoder(reflection);
+
+    // rootType is usually the first schema passed to the Encoder
+    // (unless it inherits from another schema)
+    const rootType = context.schemas.get(encoder.state.constructor);
+    if (rootType > 0) { reflection.rootType = rootType; }
+
+    const includedTypeIds = new Set<number>();
+    const pendingReflectionTypes: { [typeid: number]: ReflectionType[] } = {};
+
+    // add type to reflection in a way that respects inheritance
+    // (parent types should be added before their children)
+    const addType = (type: ReflectionType) => {
+        if (type.extendsId === undefined || includedTypeIds.has(type.extendsId)) {
+            includedTypeIds.add(type.id);
+
+            reflection.types.push(type);
+
+            const deps = pendingReflectionTypes[type.id];
+            if (deps !== undefined) {
+                delete pendingReflectionTypes[type.id];
+                deps.forEach((childType) => addType(childType));
+            }
+        } else {
+            if (pendingReflectionTypes[type.extendsId] === undefined) {
+                pendingReflectionTypes[type.extendsId] = [];
+            }
+            pendingReflectionTypes[type.extendsId].push(type);
+        }
+    };
 
-        // add type to reflection in a way that respects inheritance
-        // (parent types should be added before their children)
-        const addType = (type: ReflectionType) => {
-            if (type.extendsId === undefined || includedTypeIds.has(type.extendsId)) {
-                includedTypeIds.add(type.id);
+    context.schemas.forEach((typeid, klass) => {
+        const type = new ReflectionType();
+        type.id = Number(typeid);
 
-                reflection.types.push(type);
+        // support inheritance
+        const inheritFrom = Object.getPrototypeOf(klass);
+        if (inheritFrom !== Schema) {
+            type.extendsId = context.schemas.get(inheritFrom);
+        }
 
-                const deps = pendingReflectionTypes[type.id];
-                if (deps !== undefined) {
-                    delete pendingReflectionTypes[type.id];
-                    deps.forEach((childType) => addType(childType));
-                }
-            } else {
-                if (pendingReflectionTypes[type.extendsId] === undefined) {
-                    pendingReflectionTypes[type.extendsId] = [];
-                }
-                pendingReflectionTypes[type.extendsId].push(type);
-            }
-        };
+        const metadata = klass[Symbol.metadata];
 
-        context.schemas.forEach((typeid, klass) => {
-            const type = new ReflectionType();
-            type.id = Number(typeid);
+        //
+        // FIXME: this is a workaround for inherited types without additional fields
+        // if metadata is the same reference as the parent class - it means the class has no own metadata
+        //
+        if (metadata !== inheritFrom[Symbol.metadata]) {
+            for (const fieldIndex in metadata) {
+                const index = Number(fieldIndex);
+                const fieldName = metadata[index].name;
 
-            // support inheritance
-            const inheritFrom = Object.getPrototypeOf(klass);
-            if (inheritFrom !== Schema) {
-                type.extendsId = context.schemas.get(inheritFrom);
-            }
+                // skip fields from parent classes
+                if (!Object.prototype.hasOwnProperty.call(metadata, fieldName)) {
+                    continue;
+                }
 
-            const metadata = klass[Symbol.metadata];
+                const reflectionField = new ReflectionField();
+                reflectionField.name = fieldName;
 
-            //
-            // FIXME: this is a workaround for inherited types without additional fields
-            // if metadata is the same reference as the parent class - it means the class has no own metadata
-            //
-            if (metadata !== inheritFrom[Symbol.metadata]) {
-                for (const fieldIndex in metadata) {
-                    const index = Number(fieldIndex);
-                    const fieldName = metadata[index].name;
+                let fieldType: string;
 
-                    // skip fields from parent classes
-                    if (!Object.prototype.hasOwnProperty.call(metadata, fieldName)) {
-                        continue;
-                    }
+                const field = metadata[index];
 
-                    const reflectionField = new ReflectionField();
-                    reflectionField.name = fieldName;
+                if (typeof (field.type) === "string") {
+                    fieldType = field.type;
 
-                    let fieldType: string;
-
-                    const field = metadata[index];
+                } else {
+                    let childTypeSchema: typeof Schema;
 
-                    if (typeof (field.type) === "string") {
-                        fieldType = field.type;
+                    //
+                    // TODO: refactor below.
+                    //
+                    if (Schema.is(field.type)) {
+                        fieldType = "ref";
+                        childTypeSchema = field.type as typeof Schema;
 
                     } else {
-                        let childTypeSchema: typeof Schema;
+                        fieldType = Object.keys(field.type)[0];
 
-                        //
-                        // TODO: refactor below.
-                        //
-                        if (Schema.is(field.type)) {
-                            fieldType = "ref";
-                            childTypeSchema = field.type as typeof Schema;
+                        if (typeof (field.type[fieldType as keyof typeof field.type]) === "string") {
+                            fieldType += ":" + field.type[fieldType as keyof typeof field.type]; // array:string
 
                         } else {
-                            fieldType = Object.keys(field.type)[0];
-
-                            if (typeof (field.type[fieldType as keyof typeof field.type]) === "string") {
-                                fieldType += ":" + field.type[fieldType as keyof typeof field.type]; // array:string
-
-                            } else {
-                                childTypeSchema = field.type[fieldType as keyof typeof field.type];
-                            }
+                            childTypeSchema = field.type[fieldType as keyof typeof field.type];
                         }
-
-                        reflectionField.referencedType = (childTypeSchema)
-                            ? context.getTypeId(childTypeSchema)
-                            : -1;
                     }
 
-                    reflectionField.type = fieldType;
-                    type.fields.push(reflectionField);
+                    reflectionField.referencedType = (childTypeSchema)
+                        ? context.getTypeId(childTypeSchema)
+                        : -1;
                 }
-            }
-
-            addType(type);
-        });
 
-        // in case there are types that were not added due to inheritance
-        for (const typeid in pendingReflectionTypes) {
-            pendingReflectionTypes[typeid].forEach((type) =>
-                reflection.types.push(type))
+                reflectionField.type = fieldType;
+                type.fields.push(reflectionField);
+            }
         }
 
-        const buf = reflectionEncoder.encodeAll(it);
-        return buf.slice(0, it.offset)
-        // return Buffer.from(buf, 0, it.offset);
-    }
+        addType(type);
+    });
 
-    /**
-     * Decodes the TypeContext from a buffer into a Decoder instance.
-     *
-     * @param bytes Reflection.encode() output
-     * @param it
-     * @returns Decoder instance
-     */
-    static decode<T extends Schema = Schema>(bytes: Buffer, it?: Iterator): Decoder<T> {
-        const reflection = new Reflection();
+    // in case there are types that were not added due to inheritance
+    for (const typeid in pendingReflectionTypes) {
+        pendingReflectionTypes[typeid].forEach((type) =>
+            reflection.types.push(type))
+    }
 
-        const reflectionDecoder = new Decoder(reflection);
-        reflectionDecoder.decode(bytes, it);
+    const buf = reflectionEncoder.encodeAll(it);
+    return buf.slice(0, it.offset);
+};
 
-        const typeContext = new TypeContext();
+Reflection.decode = function <T extends Schema = Schema>(bytes: Uint8Array, it?: Iterator): Decoder<T> {
+    const reflection = new Reflection();
 
-        // 1st pass, initialize metadata + inheritance
-        reflection.types.forEach((reflectionType) => {
-            const parentClass: typeof Schema = typeContext.get(reflectionType.extendsId) ?? Schema;
-            const schema: typeof Schema = class _ extends parentClass {};
+    const reflectionDecoder = new Decoder(reflection);
+    reflectionDecoder.decode(bytes, it);
 
-            // register for inheritance support
-            TypeContext.register(schema);
+    const typeContext = new TypeContext();
 
-            // // for inheritance support
-            // Metadata.initialize(schema);
+    // 1st pass, initialize metadata + inheritance
+    reflection.types.forEach((reflectionType) => {
+        const parentClass: typeof Schema = typeContext.get(reflectionType.extendsId) ?? Schema;
+        const schema: typeof Schema = class _ extends parentClass { };
 
-            typeContext.add(schema, reflectionType.id);
-        }, {});
+        // register for inheritance support
+        TypeContext.register(schema);
 
-        // define fields
-        const addFields = (metadata: Metadata, reflectionType: ReflectionType, parentFieldIndex: number) => {
-            reflectionType.fields.forEach((field, i) => {
-                const fieldIndex = parentFieldIndex + i;
+        typeContext.add(schema, reflectionType.id);
+    }, {});
 
-                if (field.referencedType !== undefined) {
-                    let fieldType = field.type;
-                    let refType: PrimitiveType = typeContext.get(field.referencedType);
+    // define fields
+    const addFields = (metadata: Metadata, reflectionType: ReflectionType, parentFieldIndex: number) => {
+        reflectionType.fields.forEach((field, i) => {
+            const fieldIndex = parentFieldIndex + i;
 
-                    // map or array of primitive type (-1)
-                    if (!refType) {
-                        const typeInfo = field.type.split(":");
-                        fieldType = typeInfo[0];
-                        refType = typeInfo[1] as PrimitiveType; // string
-                    }
+            if (field.referencedType !== undefined) {
+                let fieldType = field.type;
+                let refType: PrimitiveType = typeContext.get(field.referencedType);
 
-                    if (fieldType === "ref") {
-                        Metadata.addField(metadata, fieldIndex, field.name, refType);
+                // map or array of primitive type (-1)
+                if (!refType) {
+                    const typeInfo = field.type.split(":");
+                    fieldType = typeInfo[0];
+                    refType = typeInfo[1] as PrimitiveType; // string
+                }
 
-                    } else {
-                        Metadata.addField(metadata, fieldIndex, field.name, { [fieldType]: refType });
-                    }
+                if (fieldType === "ref") {
+                    Metadata.addField(metadata, fieldIndex, field.name, refType);
 
                 } else {
-                    Metadata.addField(metadata, fieldIndex, field.name, field.type as PrimitiveType);
+                    Metadata.addField(metadata, fieldIndex, field.name, { [fieldType]: refType });
                 }
-            });
-        };
 
-        // 2nd pass, set fields
-        reflection.types.forEach((reflectionType) => {
-            const schema = typeContext.get(reflectionType.id);
+            } else {
+                Metadata.addField(metadata, fieldIndex, field.name, field.type as PrimitiveType);
+            }
+        });
+    };
 
-            // for inheritance support
-            const metadata = Metadata.initialize(schema);
+    // 2nd pass, set fields
+    reflection.types.forEach((reflectionType) => {
+        const schema = typeContext.get(reflectionType.id);
 
-            const inheritedTypes: ReflectionType[] = [];
+        // for inheritance support
+        const metadata = Metadata.initialize(schema);
 
-            let parentType: ReflectionType = reflectionType;
-            do {
-                inheritedTypes.push(parentType);
-                parentType = reflection.types.find((t) => t.id === parentType.extendsId);
-            } while (parentType);
+        const inheritedTypes: ReflectionType[] = [];
 
-            let parentFieldIndex = 0;
+        let parentType: ReflectionType = reflectionType;
+        do {
+            inheritedTypes.push(parentType);
+            parentType = reflection.types.find((t) => t.id === parentType.extendsId);
+        } while (parentType);
 
-            inheritedTypes.reverse().forEach((reflectionType) => {
-                // add fields from all inherited classes
-                // TODO: refactor this to avoid adding fields from parent classes
-                addFields(metadata, reflectionType, parentFieldIndex);
-                parentFieldIndex += reflectionType.fields.length;
-            });
+        let parentFieldIndex = 0;
+
+        inheritedTypes.reverse().forEach((reflectionType) => {
+            // add fields from all inherited classes
+            // TODO: refactor this to avoid adding fields from parent classes
+            addFields(metadata, reflectionType, parentFieldIndex);
+            parentFieldIndex += reflectionType.fields.length;
         });
+    });
 
-        const state: T = new (typeContext.get(reflection.rootType || 0) as unknown as any)();
+    const state: T = new (typeContext.get(reflection.rootType || 0) as unknown as any)();
 
-        return new Decoder<T>(state, typeContext);
-    }
-}
+    return new Decoder<T>(state, typeContext);
+}

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];