@colyseus/schema 3.0.0-alpha.2 → 3.0.0-alpha.23

package/src/debug.ts

@@ -0,0 +1,56 @@
+import * as fs from "fs";
+import { Reflection, Decoder } from "./index";
+
+const contents = fs.readFileSync("/Users/endel/Projects/colyseus/clients/bubbits/project/@bubbits/backend/schema-debug.txt", { encoding: "utf8" }).toString();
+
+let isCommentBlock = false;
+let lastComment = "";
+
+let decoder: Decoder;
+
+function getBuffer(line: string) {
+    const start = line.lastIndexOf(":");
+    const buffer = Buffer.from(new Uint8Array(line.substring(start + 1).split(",").map(n => Number(n))));
+    console.log(`(${buffer.byteLength}) ${Array.from(buffer).join(",")}`)
+    // console.log("");
+    // console.log("");
+    // console.log("> ", line);
+    // console.log("> substring:", line.substring(start + 1))
+    return buffer;
+}
+
+function decode(buffer: Buffer) {
+    try {
+        decoder.decode(buffer);
+    } catch (e) {
+        console.error(e);
+        console.log("Last log:\n\n")
+        console.log(lastComment);
+    }
+}
+
+contents.split("\n").forEach((line) => {
+    if (line.startsWith("#")) {
+        // reset last comment.
+        if (isCommentBlock === false) { lastComment = ""; }
+
+        isCommentBlock = true;
+        lastComment += line.substring(line.indexOf(":") + 1) + "\n";
+        return;
+    }
+
+    isCommentBlock = false;
+
+    if (line.startsWith("handshake:") && !decoder) {
+        const state = Reflection.decode(getBuffer(line));
+        decoder = new Decoder(state);
+
+    } else if (line.startsWith("state:")) {
+        decode(getBuffer(line));
+
+    } else if (line.startsWith("patch:")) {
+        decode(getBuffer(line));
+    }
+});
+
+console.log(decoder.state.toJSON());

package/src/decoder/DecodeOperation.ts

@@ -4,7 +4,7 @@ import { Schema } from "../Schema";
 import type { Ref } from "../encoder/ChangeTree";
 import type { Decoder } from "./Decoder";
 import * as decode from "../encoding/decode";
-import { $changes, $childType, $deleteByIndex, $getByIndex } from "../types/symbols";
+import { $childType, $deleteByIndex, $getByIndex } from "../types/symbols";
 
 import type { MapSchema } from "../types/custom/MapSchema";
 import type { ArraySchema } from "../types/custom/ArraySchema";
@@ -43,7 +43,7 @@ export function decodeValue(
     it: decode.Iterator,
     allChanges: DataChange[],
 ) {
-    const $root = decoder.$root;
+    const $root = decoder.root;
     const previousValue = ref[$getByIndex](index);
 
     let value: any;
@@ -251,6 +251,7 @@ export const decodeKeyValueOperation: DecodeOperation = function (
         dynamicIndex = ref['getIndex'](index);
     }
 
+
     const { value, previousValue } = decodeValue(
         decoder,
         operation,
@@ -303,7 +304,10 @@ export const decodeArray: DecodeOperation = function (
     allChanges: DataChange[]
 ) {
     // "uncompressed" index + operation (array/map items)
-    const operation = bytes[it.offset++];
+    let operation = bytes[it.offset++];
+
+    let isSchemaChild: boolean;
+    let index: number;
 
     if (operation === OPERATION.CLEAR) {
         //
@@ -318,8 +322,8 @@ export const decodeArray: DecodeOperation = function (
     } else if (operation === OPERATION.DELETE_BY_REFID) {
         // TODO: refactor here, try to follow same flow as below
         const refId = decode.number(bytes, it);
-        const previousValue = decoder.$root.refs.get(refId);
-        const index = ref.findIndex((value) => value === previousValue);
+        const previousValue = decoder.root.refs.get(refId);
+        index = ref.findIndex((value) => value === previousValue);
         ref[$deleteByIndex](index);
         allChanges.push({
             ref,
@@ -330,10 +334,26 @@ export const decodeArray: DecodeOperation = function (
             value: undefined,
             previousValue,
         });
+
         return;
+
+    } else if (operation === OPERATION.ADD_BY_REFID) {
+        isSchemaChild = true;
+        // operation = OPERATION.ADD;
+
+        const refId = decode.number(bytes, it);
+        const itemByRefId = decoder.root.refs.get(refId);
+
+        // use existing index, or push new value
+        index = (itemByRefId)
+            ? ref.findIndex((value) => value === itemByRefId)
+            : ref.length;
+
+    } else {
+        isSchemaChild = false;
+        index = decode.number(bytes, it);
     }
 
-    const index = decode.number(bytes, it);
     const type = ref[$childType];
 
     let dynamicIndex: number | string = index;

package/src/decoder/Decoder.ts

@@ -4,17 +4,17 @@ import { Schema } from "../Schema";
 
 import * as decode from "../encoding/decode";
 import { OPERATION, SWITCH_TO_STRUCTURE, TYPE_ID } from '../encoding/spec';
-import { Ref } from "../encoder/ChangeTree";
-import { Iterator } from "../encoding/decode";
+import type { Ref } from "../encoder/ChangeTree";
+import type { Iterator } from "../encoding/decode";
 import { ReferenceTracker } from "./ReferenceTracker";
-import { DEFINITION_MISMATCH, DataChange, DecodeOperation } from "./DecodeOperation";
+import { DEFINITION_MISMATCH, type DataChange, type DecodeOperation } from "./DecodeOperation";
 import { Collection } from "../types/HelperTypes";
 
 export class Decoder<T extends Schema = any> {
     context: TypeContext;
 
     state: T;
-    $root: ReferenceTracker;
+    root: ReferenceTracker;
 
     currentRefId: number = 0;
 
@@ -32,8 +32,8 @@ export class Decoder<T extends Schema = any> {
 
     protected setRoot(root: T) {
         this.state = root;
-        this.$root = new ReferenceTracker();
-        this.$root.addRef(0, root);
+        this.root = new ReferenceTracker();
+        this.root.addRef(0, root);
     }
 
     decode(
@@ -43,7 +43,7 @@ export class Decoder<T extends Schema = any> {
     ) {
         const allChanges: DataChange[] = [];
 
-        const $root = this.$root;
+        const $root = this.root;
         const totalBytes = bytes.byteLength;
 
         let decoder: DecodeOperation = ref['constructor'][$decoder];
@@ -146,7 +146,7 @@ export class Decoder<T extends Schema = any> {
             });
 
             if (needRemoveRef) {
-                this.$root.removeRef(this.$root.refIds.get(value));
+                this.root.removeRef(this.root.refIds.get(value));
             }
         });
     }

package/src/decoder/strategy/StateCallbacks.ts

@@ -17,27 +17,69 @@ import type { ArraySchema } from "../../types/custom/ArraySchema";
 // - Avoid closures by allowing to pass a context. (https://github.com/colyseus/schema/issues/155#issuecomment-1804694081)
 //
 
-type GetProxyType<T> = unknown extends T // is "any"?
+export type GetCallbackProxy = (<T extends Schema>(instance: T) => CallbackProxy<T>);
+
+export type CallbackProxy<T> = unknown extends T // is "any"?
     ? InstanceCallback<T> & CollectionCallback<any, any>
     : T extends Collection<infer K, infer V, infer _>
         ? CollectionCallback<K, V>
-        : InstanceCallback<T>
+        : InstanceCallback<T>;
 
 type InstanceCallback<T> = {
+    /**
+     * Trigger callback when value of a property changes.
+     *
+     * @param prop name of the property
+     * @param callback callback to be triggered on property change
+     * @param immediate trigger immediatelly if property has been already set.
+     */
     listen<K extends NonFunctionPropNames<T>>(
         prop: K,
         callback: (value: T[K], previousValue: T[K]) => void,
         immediate?: boolean,
     )
+    /**
+     * Trigger callback whenever any property changed within this instance.
+     *
+     * @param prop name of the property
+     * @param callback callback to be triggered on property change
+     * @param immediate trigger immediatelly if property has been already set.
+     */
     onChange(callback: () => void): void;
+
+    /**
+     * Bind properties to another object. Changes on the properties will be reflected on the target object.
+     *
+     * @param targetObject object to bind properties to
+     * @param properties list of properties to bind. If not provided, all properties will be bound.
+     */
     bindTo(targetObject: any, properties?: Array<NonFunctionPropNames<T>>): void;
 } & {
-    [K in NonFunctionNonPrimitivePropNames<T>]: GetProxyType<T[K]>;
+    [K in NonFunctionNonPrimitivePropNames<T>]: CallbackProxy<T[K]>;
 }
 
 type CollectionCallback<K, V> = {
+    /**
+     * Trigger callback when an item has been added to the collection.
+     *
+     * @param callback
+     * @param immediate
+     */
     onAdd(callback: (item: V, index: K) => void, immediate?: boolean): void;
+
+    /**
+     * Trigger callback when an item has been removed to the collection.
+     *
+     * @param callback
+     */
     onRemove(callback: (item: V, index: K) => void): void;
+
+    // /**
+    //  * Trigger callback when an item has been removed to the collection.
+    //  *
+    //  * @param callback
+    //  */
+    // onChange(callback: (item: V, index: K) => void): void;
 };
 
 type OnInstanceAvailableCallback = (callback: (ref: Ref, existing: boolean) => void) => void;
@@ -48,8 +90,9 @@ type CallContext = {
     onInstanceAvailable?: OnInstanceAvailableCallback,
 }
 
-export function getStateCallbacks(decoder: Decoder) {
-    const $root = decoder.$root;
+
+export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>): GetCallbackProxy {
+    const $root = decoder.root;
     const callbacks = $root.callbacks;
 
     let isTriggeringOnAdd = false;
@@ -76,8 +119,6 @@ export function getStateCallbacks(decoder: Decoder) {
                 for (let i = deleteCallbacks?.length - 1; i >= 0; i--) {
                     deleteCallbacks[i]();
                 }
-                // callbacks[$root.refIds.get(change.previousValue)]?.[OPERATION.DELETE]?.forEach(callback =>
-                //     callback());
             }
 
             if (ref instanceof Schema) {
@@ -86,47 +127,35 @@ export function getStateCallbacks(decoder: Decoder) {
                 //
 
                 if (!uniqueRefIds.has(refId)) {
-                    try {
-                        // trigger onChange
-                        const replaceCallbacks = $callbacks?.[OPERATION.REPLACE];
-                        for (let i = replaceCallbacks?.length - 1; i >= 0; i--) {
-                            replaceCallbacks[i]();
-                        }
-
-                    } catch (e) {
-                        console.error(e);
+                    // trigger onChange
+                    const replaceCallbacks = $callbacks?.[OPERATION.REPLACE];
+                    for (let i = replaceCallbacks?.length - 1; i >= 0; i--) {
+                        replaceCallbacks[i]();
+                        // try {
+                        // } catch (e) {
+                        //     console.error(e);
+                        // }
                     }
                 }
 
-                try {
-                    if ($callbacks.hasOwnProperty(change.field)) {
-                        const fieldCallbacks = $callbacks[change.field];
-                        for (let i = fieldCallbacks?.length - 1; i >= 0; i--) {
-                            fieldCallbacks[i](change.value, change.previousValue);
-                        }
+                if ($callbacks.hasOwnProperty(change.field)) {
+                    const fieldCallbacks = $callbacks[change.field];
+                    for (let i = fieldCallbacks?.length - 1; i >= 0; i--) {
+                        fieldCallbacks[i](change.value, change.previousValue);
+                        // try {
+                        // } catch (e) {
+                        //     console.error(e);
+                        // }
                     }
-
-                } catch (e) {
-                    //
-                    console.error(e);
                 }
 
+
             } else {
                 //
                 // Handle collection of items
                 //
 
-                if (change.op === OPERATION.ADD && change.previousValue === undefined) {
-                    // triger onAdd
-
-                    isTriggeringOnAdd = true;
-                    const addCallbacks = $callbacks[OPERATION.ADD];
-                    for (let i = addCallbacks?.length - 1; i >= 0; i--) {
-                        addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
-                    }
-                    isTriggeringOnAdd = false;
-
-                } else if ((change.op & OPERATION.DELETE) === OPERATION.DELETE) {
+                if ((change.op & OPERATION.DELETE) === OPERATION.DELETE) {
                     //
                     // FIXME: `previousValue` should always be available.
                     //
@@ -146,6 +175,16 @@ export function getStateCallbacks(decoder: Decoder) {
                             addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
                         }
                     }
+
+                } else if ((change.op & OPERATION.ADD) === OPERATION.ADD && change.previousValue === undefined) {
+                    // triger onAdd
+
+                    isTriggeringOnAdd = true;
+                    const addCallbacks = $callbacks[OPERATION.ADD];
+                    for (let i = addCallbacks?.length - 1; i >= 0; i--) {
+                        addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
+                    }
+                    isTriggeringOnAdd = false;
                 }
 
                 // trigger onChange
@@ -206,10 +245,22 @@ export function getStateCallbacks(decoder: Decoder) {
                         OPERATION.REPLACE,
                         callback
                     );
-
                 },
                 bindTo: function bindTo(targetObject: any, properties?: string[]) {
-                    console.log("bindTo", targetObject, properties);
+                    //
+                    // TODO: refactor this implementation. There is room for improvement here.
+                    //
+                    if (!properties) {
+                        properties = Object.keys(metadata);
+                    }
+                    return $root.addCallback(
+                        $root.refIds.get(context.instance),
+                        OPERATION.REPLACE,
+                        () => {
+                            properties.forEach((prop) =>
+                                targetObject[prop] = context.instance[prop])
+                        }
+                    );
                 }
             }, {
                 get(target, prop: string) {
@@ -307,20 +358,9 @@ export function getStateCallbacks(decoder: Decoder) {
         }
     }
 
-    function $<T>(instance: T): GetProxyType<T> {
-        return getProxy(undefined, { instance }) as GetProxyType<T>;
-    }
-
-    return {
-        $,
-        trigger: function trigger(changes: DataChange[]) {
-            for (let i = 0, l = changes.length; i < l; i++) {
-                const change = changes[i];
-
-                change.op
-                change.ref
-            }
-        }
+    function $<T>(instance: T): CallbackProxy<T> {
+        return getProxy(undefined, { instance }) as CallbackProxy<T>;
     }
 
+    return $;
 }

package/src/encoder/ChangeTree.ts

@@ -10,7 +10,6 @@ import type { SetSchema } from "../types/custom/SetSchema";
 import { Metadata } from "../Metadata";
 import type { EncodeOperation } from "./EncodeOperation";
 import type { DecodeOperation } from "../decoder/DecodeOperation";
-import type { StateView } from "./StateView";
 
 declare global {
     interface Object {
@@ -170,13 +169,12 @@ export class ChangeTree<T extends Ref=any> {
 
         if (!this.isFiltered) {
             this.root.changes.set(this, this.changes);
+            this.root.allChanges.set(this, this.allChanges);
         }
 
         if (this.isFiltered || this.isPartiallyFiltered) {
             this.root.filteredChanges.set(this, this.filteredChanges);
             this.root.allFilteredChanges.set(this, this.filteredChanges);
-        } else {
-            this.root.allChanges.set(this, this.allChanges);
         }
 
         this.ensureRefId();
@@ -285,7 +283,6 @@ export class ChangeTree<T extends Ref=any> {
 
     private _shiftAllChangeIndexes(shiftIndex: number, startIndex: number = 0, allChangeSet: Map<number, OPERATION>) {
         Array.from(allChangeSet.entries()).forEach(([index, op]) => {
-            // console.log('shiftAllChangeIndexes', index >= startIndex, { index, op, shiftIndex, startIndex })
             if (index >= startIndex) {
                 allChangeSet.delete(index);
                 allChangeSet.set(index + shiftIndex, op);
@@ -452,7 +449,7 @@ export class ChangeTree<T extends Ref=any> {
 
     protected checkIsFiltered(parent: Ref, parentIndex: number) {
         // Detect if current structure has "filters" declared
-        this.isPartiallyFiltered = this.ref['constructor']?.[Symbol.metadata]?.[-2];
+        this.isPartiallyFiltered = (this.ref['constructor']?.[Symbol.metadata]?.[-2] !== undefined);
 
         // TODO: support "partially filtered", where the instance is visible, but only a field is not.
 

package/src/encoder/EncodeOperation.ts

@@ -172,6 +172,19 @@ export const encodeKeyValueOperation: EncodeOperation = function (
     const type = changeTree.getType(field);
     const value = changeTree.getValue(field);
 
+    // try { throw new Error(); } catch (e) {
+    //     // only print if not coming from Reflection.ts
+    //     if (!e.stack.includes("src/Reflection.ts")) {
+    //         console.log("encodeKeyValueOperation -> ", {
+    //             ref: changeTree.ref.constructor.name,
+    //             field,
+    //             operation: OPERATION[operation],
+    //             value: value?.toJSON(),
+    //             items: ref.toJSON(),
+    //         });
+    //     }
+    // }
+
     // TODO: inline this function call small performance gain
     encodeValue(encoder, bytes, ref, type, value, field, operation, it);
 }
@@ -191,18 +204,22 @@ export const encodeArray: EncodeOperation = function (
     hasView: boolean,
 ) {
     const ref = changeTree.ref;
+    const useOperationByRefId = hasView && changeTree.isFiltered && (typeof (changeTree.getType(field)) !== "string");
 
-    if (
-        hasView &&
-        operation === OPERATION.DELETE &&
-        typeof (changeTree.getType(field)) !== "string"
-    ) {
-        // encode delete by refId (array of schemas)
-        bytes[it.offset++] = OPERATION.DELETE_BY_REFID;
-        const value =  ref['tmpItems'][field];
-        const refId = value[$changes].refId;
-        encode.number(bytes, refId, it);
-        return;
+    let refOrIndex: number;
+
+    if (useOperationByRefId) {
+        refOrIndex = ref['tmpItems'][field][$changes].refId;
+
+        if (operation === OPERATION.DELETE) {
+            operation = OPERATION.DELETE_BY_REFID;
+
+        } else if (operation === OPERATION.ADD) {
+            operation = OPERATION.ADD_BY_REFID;
+        }
+
+    } else {
+        refOrIndex = field;
     }
 
     // encode operation
@@ -214,7 +231,7 @@ export const encodeArray: EncodeOperation = function (
     }
 
     // encode index
-    encode.number(bytes, field, it);
+    encode.number(bytes, refOrIndex, it);
 
     // Do not encode value for DELETE operations
     if (operation === OPERATION.DELETE) {