@colyseus/schema 2.0.4 → 2.0.6

package/src/annotations.ts

@@ -0,0 +1,400 @@
+import { ChangeTree } from './changes/ChangeTree';
+import { Schema } from './Schema';
+import { ArraySchema, getArrayProxy } from './types/ArraySchema';
+import { MapSchema, getMapProxy } from './types/MapSchema';
+import { getType } from './types/typeRegistry';
+
+/**
+ * Data types
+ */
+export type PrimitiveType =
+    "string" |
+    "number" |
+    "boolean" |
+    "int8" |
+    "uint8" |
+    "int16" |
+    "uint16" |
+    "int32" |
+    "uint32" |
+    "int64" |
+    "uint64" |
+    "float32" |
+    "float64" |
+    typeof Schema;
+
+export type DefinitionType = PrimitiveType
+    | PrimitiveType[]
+    | { array: PrimitiveType }
+    | { map: PrimitiveType }
+    | { collection: 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.
+
+    deprecated: { [field: string]: boolean } = {};
+    descriptors: PropertyDescriptorMap & ThisType<any> = {};
+
+    static create(parent?: SchemaDefinition) {
+        const definition = new SchemaDefinition();
+
+        // 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 || {});
+
+        return definition;
+    }
+
+    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;
+    }
+
+    hasField(field: string) {
+        return this.indexes[field] !== undefined;
+    }
+
+    addFilter(field: string, cb: FilterCallback) {
+        if (!this.filters) {
+            this.filters = {};
+            this.indexesWithFilters = [];
+        }
+        this.filters[this.indexes[field]] = cb;
+        this.indexesWithFilters.push(this.indexes[field]);
+        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.`);
+        }
+    }
+
+    getChildrenFilter(field: string) {
+        return this.childFilters && this.childFilters[this.indexes[field]];
+    }
+
+    getNextFieldIndex() {
+        return Object.keys(this.schema || {}).length;
+    }
+}
+
+export function hasFilter(klass: typeof Schema) {
+    return klass._context && klass._context.useFilters;
+}
+
+// Colyseus integration
+export type ClientWithSessionId = { sessionId: string } & any;
+
+export interface TypeOptions {
+    manual?: boolean,
+    context?: Context,
+}
+
+export class Context {
+    types: {[id: number]: typeof Schema} = {};
+    schemas = new Map<typeof Schema, number>();
+    useFilters = false;
+
+    has(schema: typeof Schema) {
+        return this.schemas.has(schema);
+    }
+
+    get(typeid: number) {
+        return this.types[typeid];
+    }
+
+    add(schema: typeof Schema, typeid: number = this.schemas.size) {
+        // FIXME: move this to somewhere else?
+        // support inheritance
+        schema._definition = SchemaDefinition.create(schema._definition);
+
+        schema._typeid = typeid;
+        this.types[typeid] = schema;
+        this.schemas.set(schema, typeid);
+    }
+
+
+    static create(options: TypeOptions = {}) {
+        return function (definition: DefinitionType) {
+            if (!options.context) {
+                options.context = new Context();
+            }
+            return type(definition, options);
+        }
+    }
+}
+
+export const globalContext = new Context();
+
+/**
+ * [See documentation](https://docs.colyseus.io/state/schema/)
+ *
+ * Annotate a Schema property to be serializeable.
+ * \@type()'d fields are automatically flagged as "dirty" for the next patch.
+ *
+ * @example Standard usage, with automatic change tracking.
+ * ```
+ * \@type("string") propertyName: string;
+ * ```
+ *
+ * @example You can provide the "manual" option if you'd like to manually control your patches via .setDirty().
+ * ```
+ * \@type("string", { manual: true })
+ * ```
+ */
+export function type (
+    type: DefinitionType,
+    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);
+        }
+
+        const definition = constructor._definition;
+        definition.addField(field, type);
+
+        /**
+         * skip if descriptor already exists for this field (`@deprecated()`)
+         */
+        if (definition.descriptors[field]) {
+            if (definition.deprecated[field]) {
+                // do not create accessors for deprecated properties.
+                return;
+
+            } else {
+                // trying to define same property multiple times across inheritance.
+                // https://github.com/colyseus/colyseus-unity3d/issues/131#issuecomment-814308572
+                try {
+                    throw new Error(`@colyseus/schema: Duplicate '${field}' definition on '${constructor.name}'.\nCheck @type() annotation`);
+
+                } catch (e) {
+                    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);
+            }
+        }
+
+        if (options.manual) {
+            // do not declare getter/setter descriptor
+            definition.descriptors[field] = {
+                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;
+                }
+
+                if (
+                    value !== undefined &&
+                    value !== null
+                ) {
+                    // automaticallty transform Array into ArraySchema
+                    if (isArray && !(value instanceof ArraySchema)) {
+                        value = new ArraySchema(...value);
+                    }
+
+                    // automaticallty transform Map into MapSchema
+                    if (isMap && !(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);
+                }
+
+                this[fieldCached] = value;
+            },
+
+            enumerable: true,
+            configurable: true
+        };
+    }
+}
+
+/**
+ * `@filter()` decorator for defining data filters per client
+ */
+
+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;
+
+        if (definition.addFilter(field, cb)) {
+            constructor._context.useFilters = true;
+        }
+    }
+}
+
+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;
+        }
+    }
+}
+
+
+/**
+ * `@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;
+
+        definition.deprecated[field] = true;
+
+        if (throws) {
+            definition.descriptors[field] = {
+                get: function () { throw new Error(`${field} is deprecated.`); },
+                set: function (this: Schema, value: any) { /* throw new Error(`${field} is deprecated.`); */ },
+                enumerable: false,
+                configurable: true
+            };
+        }
+    }
+}
+
+export function defineTypes(
+    target: typeof Schema,
+    fields: { [property: string]: DefinitionType },
+    options: TypeOptions = {}
+) {
+    if (!options.context) {
+        options.context = target._context || options.context || globalContext;
+    }
+
+    for (let field in fields) {
+        type(fields[field], options)(target.prototype, field);
+    }
+    return target;
+}

package/src/changes/ChangeTree.ts

@@ -0,0 +1,295 @@
+import { OPERATION } from "../spec";
+import { Schema } from "../Schema";
+import { SchemaDefinition, FilterChildrenCallback } from "../annotations";
+
+import { MapSchema } from "../types/MapSchema";
+import { ArraySchema } from "../types/ArraySchema";
+import { CollectionSchema } from "../types/CollectionSchema";
+import { SetSchema } from "../types/SetSchema";
+import { ReferenceTracker } from "./ReferenceTracker";
+
+export type Ref = Schema
+    | ArraySchema
+    | MapSchema
+    | CollectionSchema
+    | SetSchema;
+
+export interface ChangeOperation {
+    op: OPERATION,
+    index: number,
+}
+
+//
+// FieldCache is used for @filter()
+//
+export interface FieldCache {
+    beginIndex: number;
+    endIndex: number;
+}
+
+
+export class ChangeTree {
+    ref: Ref;
+    refId: number;
+
+    root?: ReferenceTracker;
+
+    parent?: Ref;
+    parentIndex?: number;
+
+    indexes: {[index: string]: any};
+
+    changed: boolean = false;
+    changes = new Map<number, ChangeOperation>();
+    allChanges = new Set<number>();
+
+    // cached indexes for filtering
+    caches: {[field: number]: number[]} = {};
+
+    currentCustomOperation: number = 0;
+
+    constructor(ref: Ref, parent?: Ref, root?: ReferenceTracker) {
+        this.ref = ref;
+        this.setParent(parent, root);
+    }
+
+    setParent(
+        parent: Ref,
+        root?: ReferenceTracker,
+        parentIndex?: number,
+    ) {
+        if (!this.indexes) {
+            this.indexes = (this.ref instanceof Schema)
+                ? this.ref['_definition'].indexes
+                : {};
+        }
+
+        this.parent = parent;
+        this.parentIndex = parentIndex;
+
+        // avoid setting parents with empty `root`
+        if (!root) { return; }
+        this.root = root;
+
+        //
+        // assign same parent on child structures
+        //
+        if (this.ref instanceof Schema) {
+            const definition: SchemaDefinition = this.ref['_definition'];
+
+            for (let field in definition.schema) {
+                const value = this.ref[field];
+
+                if (value && value['$changes']) {
+                    const parentIndex = definition.indexes[field];
+
+                    (value['$changes'] as ChangeTree).setParent(
+                        this.ref,
+                        root,
+                        parentIndex,
+                    );
+                }
+            }
+
+        } else if (typeof (this.ref) === "object") {
+            this.ref.forEach((value, key) => {
+                if (value instanceof Schema) {
+                    const changeTreee = value['$changes'];
+                    const parentIndex = this.ref['$changes'].indexes[key];
+
+                    changeTreee.setParent(
+                        this.ref,
+                        this.root,
+                        parentIndex,
+                    );
+                }
+            });
+        }
+    }
+
+    operation(op: ChangeOperation) {
+        this.changes.set(--this.currentCustomOperation, op);
+    }
+
+    change(fieldName: string | number, operation: OPERATION = OPERATION.ADD) {
+        const index = (typeof (fieldName) === "number")
+            ? fieldName
+            : this.indexes[fieldName];
+
+        this.assertValidIndex(index, fieldName);
+
+        const previousChange = this.changes.get(index);
+
+        if (
+            !previousChange ||
+            previousChange.op === OPERATION.DELETE ||
+            previousChange.op === OPERATION.TOUCH // (mazmorra.io's BattleAction issue)
+        ) {
+            this.changes.set(index, {
+                op: (!previousChange)
+                    ? operation
+                    : (previousChange.op === OPERATION.DELETE)
+                        ? OPERATION.DELETE_AND_ADD
+                        : operation,
+                        // : OPERATION.REPLACE,
+                index
+            });
+        }
+
+        this.allChanges.add(index);
+
+        this.changed = true;
+        this.touchParents();
+    }
+
+    touch(fieldName: string | number) {
+        const index = (typeof (fieldName) === "number")
+            ? fieldName
+            : this.indexes[fieldName];
+
+        this.assertValidIndex(index, fieldName);
+
+        if (!this.changes.has(index)) {
+            this.changes.set(index, { op: OPERATION.TOUCH, index });
+        }
+
+        this.allChanges.add(index);
+
+        // ensure touch is placed until the $root is found.
+        this.touchParents();
+    }
+
+    touchParents() {
+        if (this.parent) {
+            (this.parent['$changes'] as ChangeTree).touch(this.parentIndex);
+        }
+    }
+
+    getType(index?: number) {
+        if (this.ref['_definition']) {
+            const definition = (this.ref as Schema)['_definition'];
+            return definition.schema[ definition.fieldsByIndex[index] ];
+
+        } else {
+            const definition = (this.parent as Schema)['_definition'];
+            const parentType = definition.schema[ definition.fieldsByIndex[this.parentIndex] ];
+
+            //
+            // Get the child type from parent structure.
+            // - ["string"] => "string"
+            // - { map: "string" } => "string"
+            // - { set: "string" } => "string"
+            //
+            return Object.values(parentType)[0];
+        }
+    }
+
+    getChildrenFilter(): FilterChildrenCallback {
+        const childFilters = (this.parent as Schema)['_definition'].childFilters;
+        return childFilters && childFilters[this.parentIndex];
+    }
+
+    //
+    // used during `.encode()`
+    //
+    getValue(index: number) {
+        return this.ref['getByIndex'](index);
+    }
+
+    delete(fieldName: string | number) {
+        const index = (typeof (fieldName) === "number")
+            ? fieldName
+            : this.indexes[fieldName];
+
+        if (index === undefined) {
+            console.warn(`@colyseus/schema ${this.ref.constructor.name}: trying to delete non-existing index: ${fieldName} (${index})`);
+            return;
+        }
+
+        const previousValue = this.getValue(index);
+        // console.log("$changes.delete =>", { fieldName, index, previousValue });
+
+        this.changes.set(index, { op: OPERATION.DELETE, index });
+
+        this.allChanges.delete(index);
+
+        // delete cache
+        delete this.caches[index];
+
+        // remove `root` reference
+        if (previousValue && previousValue['$changes']) {
+            previousValue['$changes'].parent = undefined;
+        }
+
+        this.changed = true;
+        this.touchParents();
+    }
+
+    discard(changed: boolean = false, discardAll: boolean = false) {
+        //
+        // Map, Array, etc:
+        // Remove cached key to ensure ADD operations is unsed instead of
+        // REPLACE in case same key is used on next patches.
+        //
+        // TODO: refactor this. this is not relevant for Collection and Set.
+        //
+        if (!(this.ref instanceof Schema)) {
+            this.changes.forEach((change) => {
+                if (change.op === OPERATION.DELETE) {
+                    const index = this.ref['getIndex'](change.index)
+                    delete this.indexes[index];
+                }
+            });
+        }
+
+        this.changes.clear();
+        this.changed = changed;
+
+        if (discardAll) {
+            this.allChanges.clear();
+        }
+
+        // re-set `currentCustomOperation`
+        this.currentCustomOperation = 0;
+    }
+
+    /**
+     * Recursively discard all changes from this, and child structures.
+     */
+    discardAll() {
+        this.changes.forEach((change) => {
+            const value = this.getValue(change.index);
+
+            if (value && value['$changes']) {
+                value['$changes'].discardAll();
+            }
+        });
+
+        this.discard();
+    }
+
+    // cache(field: number, beginIndex: number, endIndex: number) {
+    cache(field: number, cachedBytes: number[]) {
+        this.caches[field] = cachedBytes;
+    }
+
+    clone() {
+        return new ChangeTree(this.ref, this.parent, this.root);
+    }
+
+    ensureRefId() {
+        // skip if refId is already set.
+        if (this.refId !== undefined) {
+            return;
+        }
+
+        this.refId = this.root.getNextUniqueId();
+    }
+
+    protected assertValidIndex(index: number, fieldName: string | number) {
+        if (index === undefined) {
+            throw new Error(`ChangeTree: missing index for field "${fieldName}"`);
+        }
+    }
+
+}