@colyseus/schema 3.0.0-alpha.8 → 3.0.0

package/src/Metadata.ts

@@ -1,134 +1,282 @@
-import { getPropertyDescriptor, type DefinitionType } from "./annotations";
+import { DefinitionType, getPropertyDescriptor } from "./annotations";
+import { Schema } from "./Schema";
 import { getType } from "./types/registry";
+import { $decoder, $descriptors, $encoder, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $track, $viewFieldIndexes } from "./types/symbols";
+import { TypeContext } from "./types/TypeContext";
 
 export type MetadataField = {
     type: DefinitionType,
+    name: string,
     index: number,
     tag?: number,
     unreliable?: boolean,
     deprecated?: boolean,
-    descriptor?: PropertyDescriptor,
 };
 
 export type Metadata =
-    { [-1]: number; } & // number of fields
-    { [-2]: number[]; } & // all field indexes with "view" tag
-    { [-3]: {[tag: number]: number[]}; } & // field indexes by "view" tag
-    { [field: number]: string; } & // index => field name
-    { [field: string]: MetadataField; } // field name => field metadata
+    { [$numFields]: number; } & // number of fields
+    { [$viewFieldIndexes]: number[]; } & // all field indexes with "view" tag
+    { [$fieldIndexesByViewTag]: {[tag: number]: number[]}; } & // field indexes by "view" tag
+    { [$refTypeFieldIndexes]: number[]; } & // all field indexes containing Ref types (Schema, ArraySchema, MapSchema, etc)
+    { [field: number]: MetadataField; } & // index => field name
+    { [field: string]: number; } & // field name => field metadata
+    { [$descriptors]: { [field: string]: PropertyDescriptor } }  // property descriptors
+
+export function getNormalizedType(type: DefinitionType): DefinitionType  {
+    return (Array.isArray(type))
+        ? { array: type[0] }
+        : (typeof(type['type']) !== "undefined")
+            ? type['type']
+            : type;
+}
 
 export const Metadata = {
 
-    addField(metadata: any, index: number, field: string, type: DefinitionType, descriptor?: PropertyDescriptor) {
+    addField(metadata: any, index: number, name: string, type: DefinitionType, descriptor?: PropertyDescriptor) {
         if (index > 64) {
-            throw new Error(`Can't define field '${field}'.\nSchema instances may only have up to 64 fields.`);
+            throw new Error(`Can't define field '${name}'.\nSchema instances may only have up to 64 fields.`);
         }
 
-        metadata[field] = Object.assign(
-            metadata[field] || {}, // avoid overwriting previous field metadata (@owned / @deprecated)
+        metadata[index] = Object.assign(
+            metadata[index] || {}, // avoid overwriting previous field metadata (@owned / @deprecated)
             {
-                type: (Array.isArray(type))
-                    ? { array: type[0] }
-                    : type,
+                type: getNormalizedType(type),
                 index,
-                descriptor,
+                name,
             }
         );
 
+        // create "descriptors" map
+        Object.defineProperty(metadata, $descriptors, {
+            value: metadata[$descriptors] || {},
+            enumerable: false,
+            configurable: true,
+        });
+
+        if (descriptor) {
+            // for encoder
+            metadata[$descriptors][name] = descriptor;
+            metadata[$descriptors][`_${name}`] = {
+                value: undefined,
+                writable: true,
+                enumerable: false,
+                configurable: true,
+            };
+        } else {
+            // for decoder
+            metadata[$descriptors][name] = {
+                value: undefined,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            };
+        }
+
         // map -1 as last field index
-        Object.defineProperty(metadata, -1, {
+        Object.defineProperty(metadata, $numFields, {
             value: index,
             enumerable: false,
             configurable: true
         });
 
-        // map index => field name (non enumerable)
-        Object.defineProperty(metadata, index, {
-            value: field,
+        // map field name => index (non enumerable)
+        Object.defineProperty(metadata, name, {
+            value: index,
             enumerable: false,
             configurable: true,
         });
+
+        // if child Ref/complex type, add to -4
+        if (typeof (metadata[index].type) !== "string") {
+            if (metadata[$refTypeFieldIndexes] === undefined) {
+                Object.defineProperty(metadata, $refTypeFieldIndexes, {
+                    value: [],
+                    enumerable: false,
+                    configurable: true,
+                });
+            }
+            metadata[$refTypeFieldIndexes].push(index);
+        }
     },
 
     setTag(metadata: Metadata, fieldName: string, tag: number) {
+        const index = metadata[fieldName];
+        const field = metadata[index];
+
         // add 'tag' to the field
-        const field = metadata[fieldName];
         field.tag = tag;
 
-        if (!metadata[-2]) {
+        if (!metadata[$viewFieldIndexes]) {
             // -2: all field indexes with "view" tag
-            Object.defineProperty(metadata, -2, {
+            Object.defineProperty(metadata, $viewFieldIndexes, {
                 value: [],
                 enumerable: false,
                 configurable: true
             });
 
             // -3: field indexes by "view" tag
-            Object.defineProperty(metadata, -3, {
+            Object.defineProperty(metadata, $fieldIndexesByViewTag, {
                 value: {},
                 enumerable: false,
                 configurable: true
             });
         }
 
-        metadata[-2].push(field.index);
+        metadata[$viewFieldIndexes].push(index);
 
-        if (!metadata[-3][tag]) {
-            metadata[-3][tag] = [];
+        if (!metadata[$fieldIndexesByViewTag][tag]) {
+            metadata[$fieldIndexesByViewTag][tag] = [];
         }
 
-        metadata[-3][tag].push(field.index);
+        metadata[$fieldIndexesByViewTag][tag].push(index);
     },
 
     setFields(target: any, fields: { [field: string]: DefinitionType }) {
-        const metadata = (target.prototype.constructor[Symbol.metadata] ??= {});
+        // for inheritance support
+        const constructor = target.prototype.constructor;
+        TypeContext.register(constructor);
+
+        const parentClass = Object.getPrototypeOf(constructor);
+        const parentMetadata = parentClass && parentClass[Symbol.metadata];
+        const metadata = Metadata.initialize(constructor);
 
-        // target[$track] = function (changeTree, index: number, operation: OPERATION = OPERATION.ADD) {
-        //     changeTree.change(index, operation, encodeSchemaOperation);
-        // };
+        // Use Schema's methods if not defined in the class
+        if (!constructor[$track]) { constructor[$track] = Schema[$track]; }
+        if (!constructor[$encoder]) { constructor[$encoder] = Schema[$encoder]; }
+        if (!constructor[$decoder]) { constructor[$decoder] = Schema[$decoder]; }
+        if (!constructor.prototype.toJSON) { constructor.prototype.toJSON = Schema.prototype.toJSON; }
 
-        // target[$encoder] = encodeSchemaOperation;
-        // target[$decoder] = decodeSchemaOperation;
+        //
+        // detect index for this field, considering inheritance
+        //
+        let fieldIndex = metadata[$numFields] // current structure already has fields defined
+            ?? (parentMetadata && parentMetadata[$numFields]) // parent structure has fields defined
+            ?? -1; // no fields defined
 
-        // if (!target.prototype.toJSON) { target.prototype.toJSON = Schema.prototype.toJSON; }
+        fieldIndex++;
 
-        let index = 0;
         for (const field in fields) {
             const type = fields[field];
+            const normalizedType = getNormalizedType(type);
 
             // FIXME: this code is duplicated from @type() annotation
             const complexTypeKlass = (Array.isArray(type))
                 ? getType("array")
                 : (typeof(Object.keys(type)[0]) === "string") && getType(Object.keys(type)[0]);
 
+            const childType = (complexTypeKlass)
+                ? Object.values(type)[0]
+                : normalizedType;
+
             Metadata.addField(
                 metadata,
-                index,
+                fieldIndex,
                 field,
                 type,
-                getPropertyDescriptor(`_${field}`, index, type, complexTypeKlass, metadata, field)
+                getPropertyDescriptor(`_${field}`, fieldIndex, childType, complexTypeKlass)
             );
 
-            index++;
+            fieldIndex++;
         }
+
+        return target;
     },
 
     isDeprecated(metadata: any, field: string) {
         return metadata[field].deprecated === true;
     },
 
+    init(klass: any) {
+        //
+        // Used only to initialize an empty Schema (Encoder#constructor)
+        // TODO: remove/refactor this...
+        //
+        const metadata = {};
+        klass[Symbol.metadata] = metadata;
+        Object.defineProperty(metadata, $numFields, {
+            value: 0,
+            enumerable: false,
+            configurable: true,
+        });
+    },
+
+    initialize(constructor: any) {
+        const parentClass = Object.getPrototypeOf(constructor);
+        const parentMetadata: Metadata = parentClass[Symbol.metadata];
+
+        let metadata: Metadata = constructor[Symbol.metadata] ?? Object.create(null);
+
+        // make sure inherited classes have their own metadata object.
+        if (parentClass !== Schema && metadata === parentMetadata) {
+            metadata = Object.create(null);
+
+            if (parentMetadata) {
+                //
+                // assign parent metadata to current
+                //
+                Object.setPrototypeOf(metadata, parentMetadata);
+
+                // $numFields
+                Object.defineProperty(metadata, $numFields, {
+                    value: parentMetadata[$numFields],
+                    enumerable: false,
+                    configurable: true,
+                    writable: true,
+                });
+
+                // $viewFieldIndexes / $fieldIndexesByViewTag
+                if (parentMetadata[$viewFieldIndexes] !== undefined) {
+                    Object.defineProperty(metadata, $viewFieldIndexes, {
+                        value: [...parentMetadata[$viewFieldIndexes]],
+                        enumerable: false,
+                        configurable: true,
+                        writable: true,
+                    });
+                    Object.defineProperty(metadata, $fieldIndexesByViewTag, {
+                        value: { ...parentMetadata[$fieldIndexesByViewTag] },
+                        enumerable: false,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
+
+                // $refTypeFieldIndexes
+                if (parentMetadata[$refTypeFieldIndexes] !== undefined) {
+                    Object.defineProperty(metadata, $refTypeFieldIndexes, {
+                        value: [...parentMetadata[$refTypeFieldIndexes]],
+                        enumerable: false,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
+
+                // $descriptors
+                Object.defineProperty(metadata, $descriptors, {
+                    value: { ...parentMetadata[$descriptors] },
+                    enumerable: false,
+                    configurable: true,
+                    writable: true,
+                });
+            }
+        }
+
+        constructor[Symbol.metadata] = metadata;
+
+        return metadata;
+    },
+
     isValidInstance(klass: any) {
         return (
             klass.constructor[Symbol.metadata] &&
-            Object.prototype.hasOwnProperty.call(klass.constructor[Symbol.metadata], -1) as boolean
+            Object.prototype.hasOwnProperty.call(klass.constructor[Symbol.metadata], $numFields) as boolean
         );
     },
 
     getFields(klass: any) {
-        const metadata = klass[Symbol.metadata];
+        const metadata: Metadata = klass[Symbol.metadata];
         const fields = {};
-        for (let i = 0; i <= metadata[-1]; i++) {
-            fields[metadata[i]] = metadata[metadata[i]].type;
+        for (let i = 0; i <= metadata[$numFields]; i++) {
+            fields[metadata[i].name] = metadata[i].type;
         }
         return fields;
     }

package/src/Reflection.ts

@@ -1,4 +1,5 @@
-import { type, PrimitiveType, DefinitionType, TypeContext } from "./annotations";
+import { type, PrimitiveType } from "./annotations";
+import { TypeContext } from "./types/TypeContext";
 import { Metadata } from "./Metadata";
 import { ArraySchema } from "./types/custom/ArraySchema";
 import { Iterator } from "./encoding/decode";
@@ -22,18 +23,32 @@ export class ReflectionType extends Schema {
 }
 
 export class Reflection extends Schema {
-    @type([ ReflectionType ]) types: ArraySchema<ReflectionType> = new ArraySchema<ReflectionType>();
-
-    static encode(instance: Schema, context?: TypeContext, it: Iterator = { offset: 0 }) {
-        if (!context) {
-            context = new TypeContext(instance.constructor as typeof Schema);
-        }
+    @type([ReflectionType]) types: ArraySchema<ReflectionType> = new ArraySchema<ReflectionType>();
+    @type("number") rootType: number;
+
+    /**
+     * Encodes the TypeContext of an Encoder into a buffer.
+     *
+     * @param encoder Encoder instance
+     * @param it
+     * @returns
+     */
+    static encode(encoder: Encoder, it: Iterator = { offset: 0 }) {
+        const context = encoder.context;
 
         const reflection = new Reflection();
-        const encoder = new Encoder(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 buildType = (currentType: ReflectionType, metadata: Metadata) => {
-            for (const fieldName in metadata) {
+            for (const fieldIndex in metadata) {
+                const index = Number(fieldIndex);
+                const fieldName = metadata[index].name;
+
                 // skip fields from parent classes
                 if (!Object.prototype.hasOwnProperty.call(metadata, fieldName)) {
                     continue;
@@ -44,7 +59,7 @@ export class Reflection extends Schema {
 
                 let fieldType: string;
 
-                const type = metadata[fieldName].type;
+                const type = metadata[index].type;
 
                 if (typeof (type) === "string") {
                     fieldType = type;
@@ -96,72 +111,95 @@ export class Reflection extends Schema {
             buildType(type, klass[Symbol.metadata]);
         }
 
-        const buf = encoder.encodeAll(it);
+        const buf = reflectionEncoder.encodeAll(it);
         return Buffer.from(buf, 0, it.offset);
     }
 
-    static decode<T extends Schema = Schema>(bytes: Buffer, it?: Iterator): T {
+    /**
+     * 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();
 
         const reflectionDecoder = new Decoder(reflection);
         reflectionDecoder.decode(bytes, it);
 
-        const context = new TypeContext();
-
-        const schemaTypes = reflection.types.reduce((types, reflectionType) => {
-            const parentKlass: typeof Schema = types[reflectionType.extendsId] || Schema;
-            const schema: typeof Schema = class _ extends parentKlass {};
+        const typeContext = new TypeContext();
 
-            // const _metadata = Object.create(_classSuper[Symbol.metadata] ?? null);
-            const _metadata = parentKlass && parentKlass[Symbol.metadata] || Object.create(null);
-            Object.defineProperty(schema, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata })
+        // 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 {};
 
             // register for inheritance support
             TypeContext.register(schema);
 
-            const typeid = reflectionType.id;
-            types[typeid] = schema
-            context.add(schema, typeid);
-            return types;
-        }, {});
+            // // for inheritance support
+            // Metadata.initialize(schema);
 
-        reflection.types.forEach((reflectionType) => {
-            const schemaType = schemaTypes[reflectionType.id];
-            const metadata = schemaType[Symbol.metadata];
-
-            const parentKlass = reflection.types[reflectionType.extendsId];
-            const parentFieldIndex = parentKlass && parentKlass.fields.length || 0;
+            typeContext.add(schema, reflectionType.id);
+        }, {});
 
+        // define fields
+        const addFields = (metadata: Metadata, reflectionType: ReflectionType, parentFieldIndex: number) => {
             reflectionType.fields.forEach((field, i) => {
                 const fieldIndex = parentFieldIndex + i;
 
                 if (field.referencedType !== undefined) {
                     let fieldType = field.type;
-                    let refType = schemaTypes[field.referencedType];
+                    let refType: PrimitiveType = typeContext.get(field.referencedType);
 
                     // map or array of primitive type (-1)
                     if (!refType) {
                         const typeInfo = field.type.split(":");
                         fieldType = typeInfo[0];
-                        refType = typeInfo[1];
+                        refType = typeInfo[1] as PrimitiveType; // string
                     }
 
                     if (fieldType === "ref") {
-                        // type(refType)(schemaType.prototype, field.name);
                         Metadata.addField(metadata, fieldIndex, field.name, refType);
 
                     } else {
-                        // type({ [fieldType]: refType } as DefinitionType)(schemaType.prototype, field.name);
-                        Metadata.addField(metadata, fieldIndex, field.name, { [fieldType]: refType } as DefinitionType);
+                        Metadata.addField(metadata, fieldIndex, field.name, { [fieldType]: refType });
                     }
 
                 } else {
-                    // type(field.type as PrimitiveType)(schemaType.prototype, field.name);
                     Metadata.addField(metadata, fieldIndex, field.name, field.type as PrimitiveType);
                 }
             });
+        };
+
+        // 2nd pass, set fields
+        reflection.types.forEach((reflectionType) => {
+            const schema = typeContext.get(reflectionType.id);
+
+            // for inheritance support
+            const metadata = Metadata.initialize(schema);
+
+            const inheritedTypes: ReflectionType[] = [];
+
+            let parentType: ReflectionType = reflectionType;
+            do {
+                inheritedTypes.push(parentType);
+                parentType = reflection.types.find((t) => t.id === parentType.extendsId);
+            } while (parentType);
+
+            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;
+            });
         });
 
-        return new (schemaTypes[0])();
+        const state: T = new (typeContext.get(reflection.rootType || 0) as unknown as any)();
+
+        return new Decoder<T>(state, typeContext);
     }
 }