@colyseus/schema 2.0.32 → 3.0.0-alpha.1

package/src/annotations.ts

@@ -1,8 +1,11 @@
-import { ChangeTree } from './changes/ChangeTree';
+import "./symbol.shim";
 import { Schema } from './Schema';
-import { ArraySchema, getArrayProxy } from './types/ArraySchema';
-import { MapSchema, getMapProxy } from './types/MapSchema';
-import { getType } from './types/typeRegistry';
+import { ArraySchema } from './types/custom/ArraySchema';
+import { MapSchema } from './types/custom/MapSchema';
+import { Metadata } from "./Metadata";
+import { $changes, $childType, $track } from "./types/symbols";
+import { TypeDefinition, getType } from "./types/registry";
+import { OPERATION } from "./encoding/spec";
 
 /**
  * Data types
@@ -21,7 +24,8 @@ export type PrimitiveType =
     "uint64" |
     "float32" |
     "float64" |
-    typeof Schema;
+    typeof Schema |
+    object;
 
 export type DefinitionType = PrimitiveType
     | PrimitiveType[]
@@ -31,149 +35,128 @@ export type DefinitionType = PrimitiveType
     | { set: PrimitiveType };
 
 export type Definition = { [field: string]: DefinitionType };
-export type FilterCallback<
-    T extends Schema = any,
-    V = any,
-    R extends Schema = any
-> = (
-    ((this: T, client: ClientWithSessionId, value: V) => boolean) |
-    ((this: T, client: ClientWithSessionId, value: V, root: R) => boolean)
-);
-
-export type FilterChildrenCallback<
-    T extends Schema = any,
-    K = any,
-    V = any,
-    R extends Schema = any
-> = (
-    ((this: T, client: ClientWithSessionId, key: K, value: V) => boolean) |
-    ((this: T, client: ClientWithSessionId, key: K, value: V, root: R) => boolean)
-)
-
-export class SchemaDefinition {
-    schema: Definition;
 
-    //
-    // TODO: use a "field" structure combining all these properties per-field.
-    //
-
-    indexes: { [field: string]: number } = {};
-    fieldsByIndex: { [index: number]: string } = {};
-
-    filters: { [field: string]: FilterCallback };
-    indexesWithFilters: number[];
-    childFilters: { [field: string]: FilterChildrenCallback }; // childFilters are used on Map, Array, Set items.
+export interface TypeOptions {
+    manual?: boolean,
+}
 
-    deprecated: { [field: string]: boolean } = {};
-    descriptors: PropertyDescriptorMap & ThisType<any> = {};
+export const DEFAULT_VIEW_TAG = -1;
 
-    static create(parent?: SchemaDefinition) {
-        const definition = new SchemaDefinition();
+export class TypeContext {
+    types: {[id: number]: typeof Schema} = {};
+    schemas = new Map<typeof Schema, number>();
 
-        // support inheritance
-        definition.schema = Object.assign({}, parent && parent.schema || {});
-        definition.indexes = Object.assign({}, parent && parent.indexes || {});
-        definition.fieldsByIndex = Object.assign({}, parent && parent.fieldsByIndex || {});
-        definition.descriptors = Object.assign({}, parent && parent.descriptors || {});
-        definition.deprecated = Object.assign({}, parent && parent.deprecated || {});
+    hasFilters: boolean = false;
+
+    /**
+     * For inheritance support
+     * Keeps track of which classes extends which. (parent -> children)
+     */
+    static inheritedTypes = new Map<typeof Schema, Set<typeof Schema>>();
+
+    static register(target: typeof Schema) {
+        const parent = Object.getPrototypeOf(target);
+        if (parent !== Schema) {
+            let inherits = TypeContext.inheritedTypes.get(parent);
+            if (!inherits) {
+                inherits = new Set<typeof Schema>();
+                TypeContext.inheritedTypes.set(parent, inherits);
+            }
+            inherits.add(target);
+        }
+    }
 
-        return definition;
+    constructor(rootClass?: typeof Schema) {
+        if (rootClass) {
+            this.discoverTypes(rootClass);
+        }
     }
 
-    addField(field: string, type: DefinitionType) {
-        const index = this.getNextFieldIndex();
-        this.fieldsByIndex[index] = field;
-        this.indexes[field] = index;
-        this.schema[field] = (Array.isArray(type))
-            ? { array: type[0] }
-            : type;
+    has(schema: typeof Schema) {
+        return this.schemas.has(schema);
     }
 
-    hasField(field: string) {
-        return this.indexes[field] !== undefined;
+    get(typeid: number) {
+        return this.types[typeid];
     }
 
-    addFilter(field: string, cb: FilterCallback) {
-        if (!this.filters) {
-            this.filters = {};
-            this.indexesWithFilters = [];
+    add(schema: typeof Schema, typeid: number = this.schemas.size) {
+        // skip if already registered
+        if (this.schemas.has(schema)) {
+            return false;
         }
-        this.filters[this.indexes[field]] = cb;
-        this.indexesWithFilters.push(this.indexes[field]);
+
+        this.types[typeid] = schema;
+        this.schemas.set(schema, typeid);
         return true;
     }
 
-    addChildrenFilter(field: string, cb: FilterChildrenCallback) {
-        const index = this.indexes[field];
-        const type = this.schema[field];
-
-        if (getType(Object.keys(type)[0])) {
-            if (!this.childFilters) { this.childFilters = {}; }
-
-            this.childFilters[index] = cb;
-            return true;
-
-        } else {
-            console.warn(`@filterChildren: field '${field}' can't have children. Ignoring filter.`);
-        }
+    getTypeId(klass: typeof Schema) {
+        return this.schemas.get(klass);
     }
 
-    getChildrenFilter(field: string) {
-        return this.childFilters && this.childFilters[this.indexes[field]];
-    }
+    private discoverTypes(klass: typeof Schema) {
+        if (!this.add(klass)) {
+            return;
+        }
 
-    getNextFieldIndex() {
-        return Object.keys(this.schema || {}).length;
-    }
-}
+        // add classes inherited from this base class
+        TypeContext.inheritedTypes.get(klass)?.forEach((child) => {
+            this.discoverTypes(child);
+        });
 
-export function hasFilter(klass: typeof Schema) {
-    return klass._context && klass._context.useFilters;
-}
+        // skip if no fields are defined for this class.
+        if (klass[Symbol.metadata] === undefined) {
+            klass[Symbol.metadata] = {};
+        }
 
-// Colyseus integration
-export type ClientWithSessionId = { sessionId: string } & any;
+        // const metadata = Metadata.getFor(klass);
+        const metadata = klass[Symbol.metadata];
 
-export interface TypeOptions {
-    manual?: boolean,
-    context?: Context,
-}
+        // if any schema/field has filters, mark "context" as having filters.
+        if (metadata[-2]) {
+            this.hasFilters = true;
+        }
 
-export class Context {
-    types: {[id: number]: typeof Schema} = {};
-    schemas = new Map<typeof Schema, number>();
-    useFilters = false;
+        for (const field in metadata) {
+            const fieldType = metadata[field].type;
 
-    has(schema: typeof Schema) {
-        return this.schemas.has(schema);
-    }
+            if (typeof(fieldType) === "string") {
+                continue;
+            }
 
-    get(typeid: number) {
-        return this.types[typeid];
-    }
+            if (Array.isArray(fieldType)) {
+                const type = fieldType[0];
+                if (type === "string") {
+                    continue;
+                }
+                this.discoverTypes(type as typeof Schema);
 
-    add(schema: typeof Schema, typeid: number = this.schemas.size) {
-        // FIXME: move this to somewhere else?
-        // support inheritance
-        schema._definition = SchemaDefinition.create(schema._definition);
+            } else if (typeof(fieldType) === "function") {
+                this.discoverTypes(fieldType);
 
-        schema._typeid = typeid;
-        this.types[typeid] = schema;
-        this.schemas.set(schema, typeid);
-    }
+            } else {
+                const type = Object.values(fieldType)[0];
 
+                // skip primitive types
+                if (typeof(type) === "string") {
+                    continue;
+                }
 
-    static create(options: TypeOptions = {}) {
-        return function (definition: DefinitionType) {
-            if (!options.context) {
-                options.context = new Context();
+                this.discoverTypes(type as typeof Schema);
             }
-            return type(definition, options);
         }
     }
 }
 
-export const globalContext = new Context();
+export function entity(constructor, context: ClassDecoratorContext) {
+    if (!constructor._definition) {
+        // for inheritance support
+        TypeContext.register(constructor);
+    }
+
+    return constructor;
+}
 
 /**
  * [See documentation](https://docs.colyseus.io/state/schema/)
@@ -191,38 +174,235 @@ export const globalContext = new Context();
  * \@type("string", { manual: true })
  * ```
  */
+// export function type(type: DefinitionType, options?: TypeOptions) {
+//     return function ({ get, set }, context: ClassAccessorDecoratorContext): ClassAccessorDecoratorResult<Schema, any> {
+//         if (context.kind !== "accessor") {
+//             throw new Error("@type() is only supported for class accessor properties");
+//         }
+
+//         const field = context.name.toString();
+
+//         //
+//         // detect index for this field, considering inheritance
+//         //
+//         const parent = Object.getPrototypeOf(context.metadata);
+//         let fieldIndex: number = context.metadata[-1] // current structure already has fields defined
+//             ?? (parent && parent[-1]) // parent structure has fields defined
+//             ?? -1; // no fields defined
+//         fieldIndex++;
+
+//         if (
+//             !parent && // the parent already initializes the `$changes` property
+//             !Metadata.hasFields(context.metadata)
+//         ) {
+//             context.addInitializer(function (this: Ref) {
+//                 Object.defineProperty(this, $changes, {
+//                     value: new ChangeTree(this),
+//                     enumerable: false,
+//                     writable: true
+//                 });
+//             });
+//         }
+
+//         Metadata.addField(context.metadata, fieldIndex, field, type);
+
+//         const isArray = ArraySchema.is(type);
+//         const isMap = !isArray && MapSchema.is(type);
+
+//         // if (options && options.manual) {
+//         //     // do not declare getter/setter descriptor
+//         //     definition.descriptors[field] = {
+//         //         enumerable: true,
+//         //         configurable: true,
+//         //         writable: true,
+//         //     };
+//         //     return;
+//         // }
+
+//         return {
+//             init(value) {
+//                 // TODO: may need to convert ArraySchema/MapSchema here
+
+//                 // do not flag change if value is undefined.
+//                 if (value !== undefined) {
+//                     this[$changes].change(fieldIndex);
+
+//                     // automaticallty transform Array into ArraySchema
+//                     if (isArray) {
+//                         if (!(value instanceof ArraySchema)) {
+//                             value = new ArraySchema(...value);
+//                         }
+//                         value[$childType] = Object.values(type)[0];
+//                     }
+
+//                     // automaticallty transform Map into MapSchema
+//                     if (isMap) {
+//                         if (!(value instanceof MapSchema)) {
+//                             value = new MapSchema(value);
+//                         }
+//                         value[$childType] = Object.values(type)[0];
+//                     }
+
+//                     // try to turn provided structure into a Proxy
+//                     if (value['$proxy'] === undefined) {
+//                         if (isMap) {
+//                             value = getMapProxy(value);
+//                         }
+//                     }
+
+//                 }
+
+//                 return value;
+//             },
+
+//             get() {
+//                 return get.call(this);
+//             },
+
+//             set(value: any) {
+//                 /**
+//                  * Create Proxy for array or map items
+//                  */
+
+//                 // skip if value is the same as cached.
+//                 if (value === get.call(this)) {
+//                     return;
+//                 }
+
+//                 if (
+//                     value !== undefined &&
+//                     value !== null
+//                 ) {
+//                     // automaticallty transform Array into ArraySchema
+//                     if (isArray) {
+//                         if (!(value instanceof ArraySchema)) {
+//                             value = new ArraySchema(...value);
+//                         }
+//                         value[$childType] = Object.values(type)[0];
+//                     }
+
+//                     // automaticallty transform Map into MapSchema
+//                     if (isMap) {
+//                         if (!(value instanceof MapSchema)) {
+//                             value = new MapSchema(value);
+//                         }
+//                         value[$childType] = Object.values(type)[0];
+//                     }
+
+//                     // try to turn provided structure into a Proxy
+//                     if (value['$proxy'] === undefined) {
+//                         if (isMap) {
+//                             value = getMapProxy(value);
+//                         }
+//                     }
+
+//                     // flag the change for encoding.
+//                     this[$changes].change(fieldIndex);
+
+//                     //
+//                     // call setParent() recursively for this and its child
+//                     // structures.
+//                     //
+//                     if (value[$changes]) {
+//                         value[$changes].setParent(
+//                             this,
+//                             this[$changes].root,
+//                             Metadata.getIndex(context.metadata, field),
+//                         );
+//                     }
+
+//                 } else if (get.call(this)) {
+//                     //
+//                     // Setting a field to `null` or `undefined` will delete it.
+//                     //
+//                     this[$changes].delete(field);
+//                 }
+
+//                 set.call(this, value);
+//             },
+//         };
+//     }
+// }
+
+export function view<T> (tag: number = DEFAULT_VIEW_TAG) {
+    return function(target: T, fieldName: string) {
+        const constructor = target.constructor as typeof Schema;
+
+        const parentClass = Object.getPrototypeOf(constructor);
+        const parentMetadata = parentClass[Symbol.metadata];
+        const metadata: Metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
+
+        if (!metadata[fieldName]) {
+            //
+            // detect index for this field, considering inheritance
+            //
+            metadata[fieldName] = {
+                type: undefined,
+                index: (metadata[-1] // current structure already has fields defined
+                    ?? (parentMetadata && parentMetadata[-1]) // parent structure has fields defined
+                    ?? -1) + 1 // no fields defined
+            }
+        }
+
+        Metadata.setTag(metadata, fieldName, tag);
+    }
+}
+
+export function unreliable<T> (target: T, field: string) {
+    //
+    // FIXME: the following block of code is repeated across `@type()`, `@deprecated()` and `@unreliable()` decorators.
+    //
+    const constructor = target.constructor as typeof Schema;
+
+    const parentClass = Object.getPrototypeOf(constructor);
+    const parentMetadata = parentClass[Symbol.metadata];
+    const metadata: Metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
+
+    if (!metadata[field]) {
+        //
+        // detect index for this field, considering inheritance
+        //
+        metadata[field] = {
+            type: undefined,
+            index: (metadata[-1] // current structure already has fields defined
+                ?? (parentMetadata && parentMetadata[-1]) // parent structure has fields defined
+                ?? -1) + 1 // no fields defined
+        }
+    }
+
+    // add owned flag to the field
+    metadata[field].unreliable = true;
+}
+
 export function type (
     type: DefinitionType,
-    options: TypeOptions = {}
+    options?: TypeOptions
 ): PropertyDecorator {
     return function (target: typeof Schema, field: string) {
-        const context = options.context || globalContext;
         const constructor = target.constructor as typeof Schema;
-        constructor._context = context;
 
         if (!type) {
             throw new Error(`${constructor.name}: @type() reference provided for "${field}" is undefined. Make sure you don't have any circular dependencies.`);
         }
 
-        /*
-         * static schema
-         */
-        if (!context.has(constructor)) {
-            context.add(constructor);
-        }
+        // for inheritance support
+        TypeContext.register(constructor);
+
+        const parentClass = Object.getPrototypeOf(constructor);
+        const parentMetadata = parentClass[Symbol.metadata];
+        const metadata: Metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
 
-        const definition = constructor._definition;
-        definition.addField(field, type);
+        let fieldIndex: number;
 
         /**
          * skip if descriptor already exists for this field (`@deprecated()`)
          */
-        if (definition.descriptors[field]) {
-            if (definition.deprecated[field]) {
+        if (metadata[field]) {
+            if (metadata[field].deprecated) {
                 // do not create accessors for deprecated properties.
                 return;
 
-            } else {
+            } else if (metadata[field].descriptor !== undefined) {
                 // trying to define same property multiple times across inheritance.
                 // https://github.com/colyseus/colyseus-unity3d/issues/131#issuecomment-814308572
                 try {
@@ -232,167 +412,174 @@ export function type (
                     const definitionAtLine = e.stack.split("\n")[4].trim();
                     throw new Error(`${e.message} ${definitionAtLine}`);
                 }
-            }
-        }
-
-        const isArray = ArraySchema.is(type);
-        const isMap = !isArray && MapSchema.is(type);
 
-        // TODO: refactor me.
-        // Allow abstract intermediary classes with no fields to be serialized
-        // (See "should support an inheritance with a Schema type without fields" test)
-        if (typeof (type) !== "string" && !Schema.is(type)) {
-            const childType = Object.values(type)[0];
-            if (typeof (childType) !== "string" && !context.has(childType)) {
-                context.add(childType);
+            } else {
+                fieldIndex = metadata[field].index;
             }
+
+        } else {
+            //
+            // detect index for this field, considering inheritance
+            //
+            fieldIndex = metadata[-1] // current structure already has fields defined
+                ?? (parentMetadata && parentMetadata[-1]) // parent structure has fields defined
+                ?? -1; // no fields defined
+            fieldIndex++;
         }
 
-        if (options.manual) {
-            // do not declare getter/setter descriptor
-            definition.descriptors[field] = {
+        if (options && options.manual) {
+            Metadata.addField(metadata, fieldIndex, field, type, {
+                // do not declare getter/setter descriptor
                 enumerable: true,
                 configurable: true,
                 writable: true,
-            };
-            return;
-        }
+            });
 
-        const fieldCached = `_${field}`;
-        definition.descriptors[fieldCached] = {
-            enumerable: false,
-            configurable: false,
-            writable: true,
-        };
-
-        definition.descriptors[field] = {
-            get: function () {
-                return this[fieldCached];
-            },
-
-            set: function (this: Schema, value: any) {
-                /**
-                 * Create Proxy for array or map items
-                 */
-
-                // skip if value is the same as cached.
-                if (value === this[fieldCached]) {
-                    return;
-                }
+        } else {
+            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]
+                : type;
+
+            Metadata.addField(
+                metadata,
+                fieldIndex,
+                field,
+                type,
+                getPropertyDescriptor(`_${field}`, fieldIndex, childType, complexTypeKlass, metadata, field)
+            );
+        }
+    }
+}
 
-                if (
-                    value !== undefined &&
-                    value !== null
-                ) {
+export function getPropertyDescriptor(
+    fieldCached: string,
+    fieldIndex: number,
+    type: DefinitionType,
+    complexTypeKlass: TypeDefinition,
+    metadata: Metadata,
+    field: string,
+) {
+    return {
+        get: function () { return this[fieldCached]; },
+        set: function (this: Schema, value: any) {
+            const previousValue = this[fieldCached] || undefined;
+
+            // skip if value is the same as cached.
+            if (value === previousValue) { return; }
+
+            if (
+                value !== undefined &&
+                value !== null
+            ) {
+                if (complexTypeKlass) {
                     // automaticallty transform Array into ArraySchema
-                    if (isArray && !(value instanceof ArraySchema)) {
+                    if (complexTypeKlass.constructor === ArraySchema && !(value instanceof ArraySchema)) {
                         value = new ArraySchema(...value);
                     }
 
                     // automaticallty transform Map into MapSchema
-                    if (isMap && !(value instanceof MapSchema)) {
+                    if (complexTypeKlass.constructor === MapSchema && !(value instanceof MapSchema)) {
                         value = new MapSchema(value);
                     }
 
-                    // try to turn provided structure into a Proxy
-                    if (value['$proxy'] === undefined) {
-                        if (isMap) {
-                            value = getMapProxy(value);
-
-                        } else if (isArray) {
-                            value = getArrayProxy(value);
-                        }
-                    }
-
-                    // flag the change for encoding.
-                    this.$changes.change(field);
-
-                    //
-                    // call setParent() recursively for this and its child
-                    // structures.
-                    //
-                    if (value['$changes']) {
-                        (value['$changes'] as ChangeTree).setParent(
-                            this,
-                            this.$changes.root,
-                            this._definition.indexes[field],
-                        );
-                    }
-
-                } else if (this[fieldCached]) {
-                    //
-                    // Setting a field to `null` or `undefined` will delete it.
-                    //
-                    this.$changes.delete(field);
+                    value[$childType] = type;
                 }
 
-                this[fieldCached] = value;
-            },
-
-            enumerable: true,
-            configurable: true
-        };
-    }
-}
+                //
+                // Replacing existing "ref", remove it from root.
+                // TODO: if there are other references to this instance, we should not remove it from root.
+                //
+                if (previousValue !== undefined && previousValue[$changes]) {
+                    this[$changes].root?.remove(previousValue[$changes]);
+                }
 
-/**
- * `@filter()` decorator for defining data filters per client
- */
+                // flag the change for encoding.
+                this.constructor[$track](this[$changes], fieldIndex, OPERATION.ADD);
+
+                //
+                // call setParent() recursively for this and its child
+                // structures.
+                //
+                if (value[$changes]) {
+                    value[$changes].setParent(
+                        this,
+                        this[$changes].root,
+                        metadata[field].index,
+                    );
+                }
 
-export function filter<T extends Schema, V, R extends Schema>(cb: FilterCallback<T, V, R>): PropertyDecorator {
-    return function (target: any, field: string) {
-        const constructor = target.constructor as typeof Schema;
-        const definition = constructor._definition;
+            } else if (previousValue !== undefined) {
+                //
+                // Setting a field to `null` or `undefined` will delete it.
+                //
+                this[$changes].delete(fieldIndex);
+            }
 
-        if (definition.addFilter(field, cb)) {
-            constructor._context.useFilters = true;
-        }
-    }
-}
+            this[fieldCached] = value;
+        },
 
-export function filterChildren<T extends Schema, K, V, R extends Schema>(cb: FilterChildrenCallback<T, K, V, R>): PropertyDecorator {
-    return function (target: any, field: string) {
-        const constructor = target.constructor as typeof Schema;
-        const definition = constructor._definition;
-        if (definition.addChildrenFilter(field, cb)) {
-            constructor._context.useFilters = true;
-        }
-    }
+        enumerable: true,
+        configurable: true
+    };
 }
 
-
 /**
  * `@deprecated()` flag a field as deprecated.
  * The previous `@type()` annotation should remain along with this one.
  */
 
 export function deprecated(throws: boolean = true): PropertyDecorator {
-    return function (target: typeof Schema, field: string) {
-        const constructor = target.constructor as typeof Schema;
-        const definition = constructor._definition;
+    return function (klass: typeof Schema, field: string) {
+        //
+        // FIXME: the following block of code is repeated across `@type()`, `@deprecated()` and `@unreliable()` decorators.
+        //
+        const constructor = klass.constructor as typeof Schema;
+
+        const parentClass = Object.getPrototypeOf(constructor);
+        const parentMetadata = parentClass[Symbol.metadata];
+        const metadata: Metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
+
+        if (!metadata[field]) {
+            //
+            // detect index for this field, considering inheritance
+            //
+            metadata[field] = {
+                type: undefined,
+                index: (metadata[-1] // current structure already has fields defined
+                    ?? (parentMetadata && parentMetadata[-1]) // parent structure has fields defined
+                    ?? -1) + 1 // no fields defined
+            }
+        }
 
-        definition.deprecated[field] = true;
+        metadata[field].deprecated = true;
 
         if (throws) {
-            definition.descriptors[field] = {
+            metadata[field].descriptor = {
                 get: function () { throw new Error(`${field} is deprecated.`); },
                 set: function (this: Schema, value: any) { /* throw new Error(`${field} is deprecated.`); */ },
                 enumerable: false,
                 configurable: true
             };
         }
+
+        // flag metadata[field] as non-enumerable
+        Object.defineProperty(metadata, field, {
+            value: metadata[field],
+            enumerable: false,
+            configurable: true
+        });
     }
 }
 
 export function defineTypes(
     target: typeof Schema,
     fields: { [property: string]: DefinitionType },
-    options: TypeOptions = {}
+    options?: TypeOptions
 ) {
-    if (!options.context) {
-        options.context = target._context || options.context || globalContext;
-    }
-
     for (let field in fields) {
         type(fields[field], options)(target.prototype, field);
     }