@colyseus/schema 3.0.0-alpha.11 → 3.0.0-alpha.12

package/README.md

@@ -1,55 +1,47 @@
 <div align="center">
-  <img src="logo.png?raw=true" />
+  <img src="logo.png?raw=true" width="50%" />
   <br>
-  <br>
-
   <p>
     An incremental binary state serializer with delta encoding for games.<br>
-    Although it was born to be used on <a href="https://github.com/colyseus/colyseus">Colyseus</a>, this library can be used as standalone.
+    Made for <a href="https://github.com/colyseus/colyseus">Colyseus</a>, yet can be used standalone.
   </p>
 </div>
 
-## Defining Schema
+# Features
+
+- Flexible Schema Definition
+- Optimized Data Encoding
+- Automatic State Synchronization
+- Client-side Change Detection
+- Per-client portions of the state
+- Type Safety
+- *...decoders available for multiple languages (C#, Lua, Haxe)*
 
-As Colyseus is written in TypeScript, the schema is defined as type annotations inside the state class. Additional server logic may be added to that class, but client-side generated (not implemented) files will consider only the schema itself.
+## Schema definition
+
+`@colyseus/schema` uses type annotations to define types of synchronized properties.
 
 ```typescript
 import { Schema, type, ArraySchema, MapSchema } from '@colyseus/schema';
 
 export class Player extends Schema {
-  @type("string")
-  name: string;
-
-  @type("number")
-  x: number;
-
-  @type("number")
-  y: number;
+  @type("string") name: string;
+  @type("number") x: number;
+  @type("number") y: number;
 }
 
-export class State extends Schema {
-  @type('string')
-  fieldString: string;
-
-  @type('number') // varint
-  fieldNumber: number;
-
-  @type(Player)
-  player: Player;
-
-  @type([ Player ])
-  arrayOfPlayers: ArraySchema<Player>;
-
-  @type({ map: Player })
-  mapOfPlayers: MapSchema<Player>;
+export class MyState extends Schema {
+  @type('string') fieldString: string;
+  @type('number') fieldNumber: number;
+  @type(Player) player: Player;
+  @type([ Player ]) arrayOfPlayers: ArraySchema<Player>;
+  @type({ map: Player }) mapOfPlayers: MapSchema<Player>;
 }
 ```
 
-See [example](test/Schema.ts).
-
 ## Supported types
 
-## Primitive Types
+### Primitive Types
 
 | Type | Description | Limitation |
 |------|-------------|------------|
@@ -79,14 +71,14 @@ name: string;
 name: number;
 ```
 
-#### Custom `Schema` type
+#### Child `Schema` structures
 
 ```typescript
 @type(Player)
 player: Player;
 ```
 
-#### Array of custom `Schema` type
+#### Array of `Schema` structure
 
 ```typescript
 @type([ Player ])
@@ -105,7 +97,7 @@ arrayOfNumbers: ArraySchema<number>;
 arrayOfStrings: ArraySchema<string>;
 ```
 
-#### Map of custom `Schema` type
+#### Map of `Schema` structure
 
 ```typescript
 @type({ map: Player })
@@ -114,7 +106,7 @@ mapOfPlayers: MapSchema<Player>;
 
 #### Map of a primitive type
 
-You can't mix types inside maps.
+You can't mix primitive types inside maps.
 
 ```typescript
 @type({ map: "number" })
@@ -124,16 +116,6 @@ mapOfNumbers: MapSchema<number>;
 mapOfStrings: MapSchema<string>;
 ```
 
-### Backwards/forwards compability
-
-Backwards/fowards compatibility is possible by declaring new fields at the
-end of existing structures, and earlier declarations to not be removed, but
-be marked `@deprecated()` when needed.
-
-This is particularly useful for native-compiled targets, such as C#, C++,
-Haxe, etc - where the client-side can potentially not have the most
-up-to-date version of the schema definitions.
-
 ### Reflection
 
 The Schema definitions can encode itself through `Reflection`. You can have the
@@ -144,10 +126,8 @@ reflection to the client-side, for example:
 import { Schema, type, Reflection } from "@colyseus/schema";
 
 class MyState extends Schema {
-  @type("string")
-  currentTurn: string;
-
-  // more definitions relating to more Schema types.
+  @type("string") currentTurn: string;
+  // ... more definitions
 }
 
 // send `encodedStateSchema` across the network
@@ -157,22 +137,113 @@ const encodedStateSchema = Reflection.encode(new MyState());
 const myState = Reflection.decode(encodedStateSchema);
 ```
 
-### Data filters
+### `StateView` / `@view()`
 
-On the example below, considering we're making a card game, we are filtering the cards to be available only for the owner of the cards, or if the card has been flagged as `"revealed"`.
+You can use `@view()` to filter properties that should be sent only to `StateView`'s that have access to it.
 
 ```typescript
-import { Schema, type, filter } from "@colyseus/schema";
-
-export class State extends Schema {
-  @filterChildren(function(client: any, key: string, value: Card, root: State) {
-      return (value.ownerId === client.sessionId) || value.revealed;
-  })
-  @type({ map: Card })
-  cards = new MapSchema<Card>();
+import { Schema, type, view } from "@colyseus/schema";
+
+class Player extends Schema {
+  @view() @type("string") secret: string;
+  @type("string") notSecret: string;
 }
+
+class MyState extends Schema {
+  @type({ map: Player }) players = new MapSchema<Player>();
+}
+```
+
+Using the `StateView`
+
+```typescript
+const view = new StateView();
+view.add(player);
+```
+
+## Encoder
+
+There are 3 majour features of the `Encoder` class:
+
+- Encoding the full state
+- Encoding the state changes
+- Encoding state with filters (properties using `@view()` tag)
+
+```typescript
+import { Encoder } from "@colyseus/schema";
+
+const state = new MyState();
+const encoder = new Encoder(state);
+```
+
+New clients must receive the full state on their first connection:
+
+```typescript
+const fullEncode = encoder.encodeAll();
+// ... send "fullEncode" to client and decode it
+```
+
+Further state changes must be sent in order:
+
+```typescript
+const changesBuffer = encoder.encode();
+// ... send "changesBuffer" to client and decode it
+```
+
+### Encoding with views
+
+When using `@view()` and `StateView`'s, a single "full encode" must be used for multiple views. Each view also must add its own changes.
+
+```typescript
+// shared buffer iterator
+const it = { offset: 0 };
+
+// shared full encode
+encoder.encodeAll(it);
+const sharedOffset = it.offset;
+
+// view 1
+const fullEncode1 = encoder.encodeAllView(view1, sharedOffset, it);
+// ... send "fullEncode1" to client1 and decode it
+
+// view 2
+const fullEncode2 = encoder.encodeAllView(view2, sharedOffset, it);
+// ... send "fullEncode" to client2 and decode it
+```
+
+Encoding changes per views:
+
+```typescript
+// shared buffer iterator
+const it = { offset: 0 };
+
+// shared changes encode
+encoder.encode(it);
+const sharedOffset = it.offset;
+
+// view 1
+const view1Encoded = this.encoder.encodeView(view1, sharedOffset, it);
+// ... send "view1Encoded" to client1 and decode it
+
+// view 2
+const view2Encoded = this.encoder.encodeView(view2, sharedOffset, it);
+// ... send "view2Encoded" to client2 and decode it
+
+// discard all changes after encoding is done.
+encoder.discardChanges();
 ```
 
+### Backwards/forwards compability
+
+Backwards/fowards compatibility is possible by declaring new fields at the
+end of existing structures, and earlier declarations to not be removed, but
+be marked `@deprecated()` when needed.
+
+This is particularly useful for native-compiled targets, such as C#, C++,
+Haxe, etc - where the client-side can potentially not have the most
+up-to-date version of the schema definitions.
+
+
 ## Limitations and best practices
 
 - Each `Schema` structure can hold up to `64` fields. If you need more fields, use nested structures.
@@ -184,7 +255,6 @@ export class State extends Schema {
 - `@colyseus/schema` encodes only field values in the specified order.
   - Both encoder (server) and decoder (client) must have same schema definition.
   - The order of the fields must be the same.
-- Avoid manipulating indexes of an array. This result in at least `2` extra bytes for each index change. **Example:** If you have an array of 20 items, and remove the first item (through `shift()`) this means `38` extra bytes to be serialized.
 
 ## Generating client-side schema files (for strictly typed languages)
 

package/build/cjs/index.js

@@ -3397,9 +3397,8 @@ class Encoder {
         this.state = state;
         state[$changes].setRoot(this.root);
     }
-    encode(it = { offset: 0 }, view, buffer = this.sharedBuffer, changeTrees = this.root.changes) {
+    encode(it = { offset: 0 }, view, buffer = this.sharedBuffer, changeTrees = this.root.changes, isEncodeAll = this.root.allChanges === changeTrees) {
         const initialOffset = it.offset; // cache current offset in case we need to resize the buffer
-        const isEncodeAll = this.root.allChanges === changeTrees;
         const hasView = (view !== undefined);
         const rootChangeTree = this.state[$changes];
         const changeTreesIterator = changeTrees.entries();
@@ -3467,7 +3466,7 @@ class Encoder {
             if (buffer === this.sharedBuffer) {
                 this.sharedBuffer = buffer;
             }
-            return this.encode({ offset: initialOffset }, view, buffer);
+            return this.encode({ offset: initialOffset }, view, buffer, changeTrees, isEncodeAll);
         }
         else {
             //
@@ -3487,14 +3486,14 @@ class Encoder {
         // Array.from(this.root.allChanges.entries()).map((item) => {
         //     console.log("->", { ref: item[0].ref.constructor.name, refId: item[0].refId, changes: item[1].size });
         // });
-        return this.encode(it, undefined, buffer, this.root.allChanges);
+        return this.encode(it, undefined, buffer, this.root.allChanges, true);
     }
     encodeAllView(view, sharedOffset, it, bytes = this.sharedBuffer) {
         const viewOffset = it.offset;
         // console.log(`encodeAllView(), this.root.allFilteredChanges (${this.root.allFilteredChanges.size})`);
         // this.debugAllFilteredChanges();
         // try to encode "filtered" changes
-        this.encode(it, view, bytes, this.root.allFilteredChanges);
+        this.encode(it, view, bytes, this.root.allFilteredChanges, true);
         return Buffer.concat([
             bytes.subarray(0, sharedOffset),
             bytes.subarray(viewOffset, it.offset)
@@ -3964,6 +3963,238 @@ __decorate([
     type([ReflectionType])
 ], Reflection.prototype, "types", void 0);
 
+function getStateCallbacks(decoder) {
+    const $root = decoder.root;
+    const callbacks = $root.callbacks;
+    let isTriggeringOnAdd = false;
+    decoder.triggerChanges = function (allChanges) {
+        const uniqueRefIds = new Set();
+        for (let i = 0, l = allChanges.length; i < l; i++) {
+            const change = allChanges[i];
+            const refId = change.refId;
+            const ref = change.ref;
+            const $callbacks = callbacks[refId];
+            if (!$callbacks) {
+                continue;
+            }
+            //
+            // trigger onRemove on child structure.
+            //
+            if ((change.op & exports.OPERATION.DELETE) === exports.OPERATION.DELETE &&
+                change.previousValue instanceof Schema) {
+                const deleteCallbacks = callbacks[$root.refIds.get(change.previousValue)]?.[exports.OPERATION.DELETE];
+                for (let i = deleteCallbacks?.length - 1; i >= 0; i--) {
+                    deleteCallbacks[i]();
+                }
+            }
+            if (ref instanceof Schema) {
+                //
+                // Handle schema instance
+                //
+                if (!uniqueRefIds.has(refId)) {
+                    try {
+                        // trigger onChange
+                        const replaceCallbacks = $callbacks?.[exports.OPERATION.REPLACE];
+                        for (let i = replaceCallbacks?.length - 1; i >= 0; i--) {
+                            replaceCallbacks[i]();
+                        }
+                    }
+                    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);
+                        }
+                    }
+                }
+                catch (e) {
+                    //
+                    console.error(e);
+                }
+            }
+            else {
+                //
+                // Handle collection of items
+                //
+                if (change.op === exports.OPERATION.ADD && change.previousValue === undefined) {
+                    // triger onAdd
+                    isTriggeringOnAdd = true;
+                    const addCallbacks = $callbacks[exports.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 & exports.OPERATION.DELETE) === exports.OPERATION.DELETE) {
+                    //
+                    // FIXME: `previousValue` should always be available.
+                    //
+                    if (change.previousValue !== undefined) {
+                        // triger onRemove
+                        const deleteCallbacks = $callbacks[exports.OPERATION.DELETE];
+                        for (let i = deleteCallbacks?.length - 1; i >= 0; i--) {
+                            deleteCallbacks[i](change.previousValue, change.dynamicIndex ?? change.field);
+                        }
+                    }
+                    // Handle DELETE_AND_ADD operations
+                    // FIXME: should we set "isTriggeringOnAdd" here?
+                    if ((change.op & exports.OPERATION.ADD) === exports.OPERATION.ADD) {
+                        const addCallbacks = $callbacks[exports.OPERATION.ADD];
+                        for (let i = addCallbacks?.length - 1; i >= 0; i--) {
+                            addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
+                        }
+                    }
+                }
+                // trigger onChange
+                if (change.value !== change.previousValue) {
+                    const replaceCallbacks = $callbacks[exports.OPERATION.REPLACE];
+                    for (let i = replaceCallbacks?.length - 1; i >= 0; i--) {
+                        replaceCallbacks[i](change.value, change.dynamicIndex ?? change.field);
+                    }
+                }
+            }
+            uniqueRefIds.add(refId);
+        }
+    };
+    function getProxy(metadataOrType, context) {
+        let metadata = context.instance?.constructor[Symbol.metadata] || metadataOrType;
+        let isCollection = ((context.instance && typeof (context.instance['forEach']) === "function") ||
+            (metadataOrType && typeof (metadataOrType[Symbol.metadata]) === "undefined"));
+        if (metadata && !isCollection) {
+            const onAdd = function (ref, prop, callback, immediate) {
+                // immediate trigger
+                if (immediate &&
+                    context.instance[prop] !== undefined &&
+                    !isTriggeringOnAdd // FIXME: This is a workaround (https://github.com/colyseus/schema/issues/147)
+                ) {
+                    callback(context.instance[prop], undefined);
+                }
+                return $root.addCallback($root.refIds.get(ref), prop, callback);
+            };
+            /**
+             * Schema instances
+             */
+            return new Proxy({
+                listen: function listen(prop, callback, immediate = true) {
+                    if (context.instance) {
+                        return onAdd(context.instance, prop, callback, immediate);
+                    }
+                    else {
+                        // collection instance not received yet
+                        context.onInstanceAvailable((ref, existing) => onAdd(ref, prop, callback, immediate && existing));
+                    }
+                },
+                onChange: function onChange(callback) {
+                    return $root.addCallback($root.refIds.get(context.instance), exports.OPERATION.REPLACE, callback);
+                },
+                bindTo: function bindTo(targetObject, properties) {
+                    // return $root.addCallback(
+                    //     $root.refIds.get(context.instance),
+                    //     OPERATION.BIND,
+                    //     callback
+                    // );
+                    console.log("bindTo", targetObject, properties);
+                }
+            }, {
+                get(target, prop) {
+                    if (metadata[prop]) {
+                        const instance = context.instance?.[prop];
+                        const onInstanceAvailable = ((callback) => {
+                            const unbind = $(context.instance).listen(prop, (value, _) => {
+                                callback(value, false);
+                                // FIXME: by "unbinding" the callback here,
+                                // it will not support when the server
+                                // re-instantiates the instance.
+                                //
+                                unbind?.();
+                            }, false);
+                            // has existing value
+                            if ($root.refIds.get(instance) !== undefined) {
+                                callback(instance, true);
+                            }
+                        });
+                        return getProxy(metadata[prop].type, {
+                            instance,
+                            parentInstance: context.instance,
+                            onInstanceAvailable,
+                        });
+                    }
+                    else {
+                        // accessing the function
+                        return target[prop];
+                    }
+                },
+                has(target, prop) { return metadata[prop] !== undefined; },
+                set(_, _1, _2) { throw new Error("not allowed"); },
+                deleteProperty(_, _1) { throw new Error("not allowed"); },
+            });
+        }
+        else {
+            /**
+             * Collection instances
+             */
+            const onAdd = function (ref, callback, immediate) {
+                // Trigger callback on existing items
+                if (immediate) {
+                    ref.forEach((v, k) => callback(v, k));
+                }
+                return $root.addCallback($root.refIds.get(ref), exports.OPERATION.ADD, callback);
+            };
+            const onRemove = function (ref, callback) {
+                return $root.addCallback($root.refIds.get(ref), exports.OPERATION.DELETE, callback);
+            };
+            return new Proxy({
+                onAdd: function (callback, immediate = true) {
+                    //
+                    // https://github.com/colyseus/schema/issues/147
+                    // If parent instance has "onAdd" registered, avoid triggering immediate callback.
+                    //
+                    // FIXME: "isTriggeringOnAdd" is a workaround. We should find a better way to handle this.
+                    //
+                    if (context.onInstanceAvailable) {
+                        // collection instance not received yet
+                        context.onInstanceAvailable((ref, existing) => onAdd(ref, callback, immediate && existing && !isTriggeringOnAdd));
+                    }
+                    else if (context.instance) {
+                        onAdd(context.instance, callback, immediate && !isTriggeringOnAdd);
+                    }
+                },
+                onRemove: function (callback) {
+                    if (context.onInstanceAvailable) {
+                        // collection instance not received yet
+                        context.onInstanceAvailable((ref) => onRemove(ref, callback));
+                    }
+                    else if (context.instance) {
+                        onRemove(context.instance, callback);
+                    }
+                },
+            }, {
+                get(target, prop) {
+                    if (!target[prop]) {
+                        throw new Error(`Can't access '${prop}' through callback proxy. access the instance directly.`);
+                    }
+                    return target[prop];
+                },
+                has(target, prop) { return target[prop] !== undefined; },
+                set(_, _1, _2) { throw new Error("not allowed"); },
+                deleteProperty(_, _1) { throw new Error("not allowed"); },
+            });
+        }
+    }
+    function $(instance) {
+        return getProxy(undefined, { instance });
+    }
+    return $(decoder.state);
+}
+
+function getRawChangesCallback(decoder, callback) {
+    decoder.triggerChanges = callback;
+}
+
 class StateView {
     constructor() {
         /**
@@ -4188,6 +4419,8 @@ exports.dumpChanges = dumpChanges;
 exports.encode = encode;
 exports.encodeKeyValueOperation = encodeArray;
 exports.encodeSchemaOperation = encodeSchemaOperation;
+exports.getRawChangesCallback = getRawChangesCallback;
+exports.getStateCallbacks = getStateCallbacks;
 exports.registerType = registerType;
 exports.type = type;
 exports.view = view;