@bikky/replication 1.0.1

package/Transformers/Loader.js

@@ -0,0 +1,350 @@
+import { ClassCategory, DataSymbol, describeObject, isPrimitiveType, isPrimitiveValue, PropertyTypes, TypeSymbol, ValueIsPrimitiveType } from "../Constants/SerialisationTypes.js";
+import { Expression } from "../Expressions/Expression.js";
+import { Pointer } from "./Reference.js";
+import { ReplicableClass } from "../Tracking/Class.js";
+import { ErrorStack } from "../Constants/Errors.js";
+import { __PrivateConstructorSetup, Constructor } from "./Constructor.js";
+import { Definitions } from "./Definitions.js";
+import { ReplicableRegistry } from "../Constants/ReplicableRegistry.js";
+export var Loader;
+(function (Loader) {
+    //Used to keep track of if an object has been initialised,
+    // so it can be initialised automatically in create if not done manually.
+    var isExpressionKind = Expression.isExpressionKind;
+    var isExpressionString = Expression.isExpressionString;
+    const IsInitialised = Symbol("IsInitialised");
+    const ExprProperties = Symbol("ExpressionProperties");
+    function LoadSingleValueAsType(propErrors, obj, prop, propInfo, propType, val) {
+        //De-expression expressions, because we don't have fancy ways of handling values in arrays or
+        // maps yet (also don't know if we want to do that or not yet).
+        if (isExpressionKind(val)) {
+            if (!(val instanceof Expression)) {
+                val = new Expression(val);
+            }
+            val = val.get();
+        }
+        if (typeof propInfo.types === "string") {
+            return val;
+        }
+        if (isPrimitiveType(propType)) {
+            if (ValueIsPrimitiveType(propType, val)) {
+                return val;
+            }
+            else {
+                throw new Error(`Invalid Value.`);
+            }
+        }
+        if (PropertyTypes.isType(propInfo.modifiers, PropertyTypes.Definition)) {
+            if (val.__proto__ !== Object.prototype || !("Class" in val)) {
+                throw new Error(`Invalid Value.`);
+            }
+            //Duplicate the data just in case it gets modified.
+            return JSON.parse(JSON.stringify(val));
+        }
+        if (PropertyTypes.isType(propInfo.modifiers, PropertyTypes.Serialised)) {
+            if ("Class" in val) {
+                throw new Error(`Invalid Value.`);
+            }
+            else if (!Array.isArray(val)) {
+                throw new Error(`Invalid Value.`);
+            }
+            else if (!ReplicableRegistry.__GetReplicableForDataName(val[0])) {
+                throw new Error(`Invalid Value.`);
+            }
+            else {
+                return val;
+            }
+        }
+        if (ClassCategory.isTypeOr(propType.category, ClassCategory.Pointer, ClassCategory.Inlined)) {
+            if (val instanceof Pointer) {
+                return val;
+            }
+            else if (val.__proto__ === Object.prototype) {
+                return new Pointer(Constructor.Construct(propType, obj.source, obj.root, val));
+            }
+            else {
+                return new Pointer(val);
+            }
+        }
+        if (ClassCategory.isTypeOr(propType.category, ClassCategory.Struct, ClassCategory.Custom)) {
+            //Already instantiated!
+            if (val[TypeSymbol]) {
+                return val;
+            }
+            // If it declares its own class then use that, because it might be a child class.
+            // We don't need to check if it is a child class because that would have been done before.
+            else if (typeof val === "object" && "Class" in val && ReplicableRegistry.__GetReplicableForDataName(val.Class)) {
+                let repl = ReplicableRegistry.__GetReplicableForDataName(val.Class);
+                return Constructor.Construct(repl, obj.source, obj.root, val);
+            }
+            else {
+                return Constructor.Construct(propType, obj.source, obj.root, val);
+            }
+        }
+    }
+    Loader.LoadSingleValueAsType = LoadSingleValueAsType;
+    function PerValueCallback(value, idxName, triggeredMod, propErrors, obj, prop) {
+        var _a;
+        if (value instanceof Pointer) {
+            value = value.val;
+        }
+        if (PropertyTypes.isType(triggeredMod, PropertyTypes.Map)) {
+            let exprConf = prop.conf.expressionForKey;
+            if (isExpressionString(idxName) && exprConf) {
+                try {
+                    idxName = new Expression({ text: idxName, sourceFile: obj.source.SourceFile }, exprConf[obj.source.Version]);
+                }
+                catch (e) {
+                    propErrors.add("REP_TL001", `Failed to parse map key expression ${idxName}`);
+                    if (e instanceof Error) {
+                        propErrors.add("REP_TL002", (_a = e.stack) !== null && _a !== void 0 ? _a : e.message);
+                    }
+                    return [undefined, idxName];
+                }
+            }
+        }
+        let entryErrors = new ErrorStack(obj.source);
+        for (let types of prop.conf.load.types) {
+            if (!Array.isArray(types.types)) {
+                continue;
+            }
+            if (!PropertyTypes.isType(types.modifiers, triggeredMod))
+                continue;
+            for (let type of types.types) {
+                if (Definitions.IsLoadableDataForType(type, value, obj.source.Version, entryErrors, false)) {
+                    return [LoadSingleValueAsType(entryErrors, obj, prop, types, type, value), idxName];
+                }
+            }
+        }
+        propErrors.appendWithoutIndent(entryErrors);
+        if (idxName != null) {
+            propErrors.add("REP_TL003", `Failed to load ${obj.rootRepl.opts.dataTypeName}.${prop.dataName}[${idxName}].`);
+        }
+        else {
+            propErrors.add("REP_TL004", `Failed to load ${obj.rootRepl.opts.dataTypeName}.${prop.dataName}.`);
+        }
+        return [undefined, idxName];
+    }
+    Loader.PerValueCallback = PerValueCallback;
+    /**
+     * ASSUMES INPUTS ARE CORRECT - DOES NOT CHECK FOR ERRORS.
+     * Get all of the assigned property values, so that they can individually be checked against the type requirements
+     *  of the definiton. Turns single values, double arrays, maps and dicts all into a single flat array of values.
+     * @param def The property definition to get the values for.
+     * @param val The value to get the values from.
+     */
+    function LoadPropValuesFromData(val, propErrors, obj, prop) {
+        let possibleModifiers = prop.conf.load.possibleModifiers;
+        if (PropertyTypes.isType(possibleModifiers, PropertyTypes.Array) && Array.isArray(val)) {
+            return val.map((e) => {
+                return PerValueCallback(e, null, PropertyTypes.Array, propErrors, obj, prop)[0];
+            });
+        }
+        else if (PropertyTypes.isType(possibleModifiers, PropertyTypes.Array2) && Array.isArray(val)) {
+            return val.map((e, i) => e.map((n, j) => {
+                return PerValueCallback(n, `${i},${j}`, PropertyTypes.Array2, propErrors, obj, prop)[0];
+            }));
+        }
+        else if (PropertyTypes.isType(possibleModifiers, PropertyTypes.Map) && (val instanceof Map || typeof val === "object" && val.__proto__ === Object.prototype)) {
+            let arr;
+            if (val instanceof Map) {
+                arr = Array.from(val.entries());
+            }
+            else {
+                arr = Array.from(Object.entries(val));
+            }
+            return new Map(arr.map((e) => {
+                let [newVal, newIdx] = PerValueCallback(e[1], e[0], PropertyTypes.Map, propErrors, obj, prop);
+                return [newIdx, newVal];
+            }));
+        }
+        else if (PropertyTypes.isType(possibleModifiers, PropertyTypes.Dictionary) && (typeof val === "object" && val.__proto__ === Object.prototype)) {
+            let arr = Array.from(Object.entries(val));
+            return Object.fromEntries(arr.map((e) => {
+                return [e[0], PerValueCallback(e[1], e[0], PropertyTypes.Dictionary, propErrors, obj, prop)[0]];
+            }));
+        }
+        else if (PropertyTypes.isType(possibleModifiers, PropertyTypes.Solo)) {
+            return PerValueCallback(val, null, PropertyTypes.Solo, propErrors, obj, prop)[0];
+        }
+    }
+    Loader.LoadPropValuesFromData = LoadPropValuesFromData;
+    /**
+     *
+     * @param type The type that the property is defined for.
+     * @param source The location that the property's definition was defined at.
+     * @param name The name of the property that will be instantiated, used for looking up property info.
+     * @param val The data value that will be used to instantiate the property
+     * @param target The 'this' object that will house the property
+     */
+    function CalcPropInitialValue(obj, name, val, target) {
+        let definition = obj.rootRepl.getPropDefinition(obj.source.Version, name);
+        if (!definition)
+            throw new Error("No information for property " + name);
+        if ("removed" in definition)
+            throw new Error(`Property ${obj.rootRepl.opts.typescriptTypeName}.${name} has been removed and cannot be loaded.`);
+        if ("doesntExist" in definition)
+            throw new Error(`Property ${obj.rootRepl.opts.typescriptTypeName}.${name} does not exist yet and cannot be loaded.`);
+        if (isExpressionKind(val)) {
+            //undefined is implicitly true
+            if (!definition.expressionForProperty) {
+                throw new Error(`${obj.rootRepl.opts.dataTypeName}.${name} does not accept expressions.`);
+            }
+            if (val instanceof Expression) {
+                return val;
+            }
+            else {
+                let exprConf = val.config;
+                let errors = new ErrorStack(obj.source);
+                if (Definitions.DoesExpressionMatchProperty(`${obj.rootRepl.opts.dataTypeName}.${name}`, exprConf, val, errors)) {
+                    return new Expression(val);
+                }
+                else {
+                    throw new Error(errors.toString("REP_TL005"));
+                }
+            }
+        }
+        // Initialise optional properties either with what they've previously had assigned (during construction) and
+        // validate it, or with their default value, or if nothing else works, undefined.
+        // We handle type by pretending the value was actually loaded in the definition, then letting the following
+        // loading code check the value.
+        if (typeof val === "undefined" && typeof definition.load.default !== "undefined") {
+            val = definition.load.default;
+            if (Array.isArray(val)) {
+                val = [...val];
+            }
+            else if (typeof val === "object" && val !== null && val.__proto__ === Object.prototype) {
+                val = Object.assign({}, val);
+            }
+        }
+        // If the data doesn't define the value, but the class does (using assignment instead of @Property's
+        // default variable) then we want to adopt the value from the class as a back-up.
+        // We need to use typeof because typescript classes default to initialising properties as undefined.
+        if (typeof val === "undefined" && name in target && typeof target[name] !== "undefined") {
+            val = target[name];
+        }
+        //Early exit on optional because we don't need to do anything special.
+        if (definition.load.present == "optional" && (typeof val === "undefined" || val instanceof Pointer && val.valOrNull === null)) {
+            return val;
+        }
+        //Early exit on null because we don't need to do anything special.
+        if (val === null) {
+            return val;
+        }
+        let propErrors = new ErrorStack(obj.source);
+        let result = LoadPropValuesFromData(val, propErrors, obj, { name, dataName: definition.load.name, conf: definition });
+        if (!propErrors.hasErrors()) {
+            return result;
+        }
+        let errors = new ErrorStack(obj.source);
+        errors.appendAndIndent(propErrors);
+        errors.add("REP_TL006", `Object ${describeObject(val)} is not a valid value for property `
+            + `${describeObject(obj.rootRepl.classConstructor)}.${definition.load.name}, property only accepts`
+            + ` types ${ReplicableClass.typesToString(definition.load.types.flatMap((e) => {
+                return typeof e.types == "string" ? [e.types] : e.types;
+            }))}.\n\n`
+            + errors.toString("REP_TL007"));
+        throw new Error(errors.toString("REP_TL008"));
+    }
+    Loader.CalcPropInitialValue = CalcPropInitialValue;
+    function SetPropertyToExpression(target, property, expression) {
+        var _a;
+        target[ExprProperties] = ((_a = target[ExprProperties]) !== null && _a !== void 0 ? _a : {});
+        target[ExprProperties][property] = expression;
+        Object.defineProperty(target, property, {
+            set(v) {
+                expression.set(v);
+            },
+            get() {
+                return expression.get();
+            },
+            enumerable: true,
+            configurable: true
+        });
+    }
+    Loader.SetPropertyToExpression = SetPropertyToExpression;
+    function IsPropertyExpression(target, property) {
+        return !!(target[ExprProperties] && target[ExprProperties][property]);
+    }
+    Loader.IsPropertyExpression = IsPropertyExpression;
+    function ClearPropertyExpression(target, property) {
+        if (target[ExprProperties]) {
+            delete target[ExprProperties][property];
+        }
+        delete target[property];
+    }
+    Loader.ClearPropertyExpression = ClearPropertyExpression;
+    function GetExprText(target, property) {
+        var _a;
+        let expr = (_a = target[ExprProperties]) === null || _a === void 0 ? void 0 : _a[property];
+        if (expr) {
+            return expr.rawText;
+        }
+        return undefined;
+    }
+    Loader.GetExprText = GetExprText;
+    function InitFromData(type, source, target, data) {
+        var _a;
+        if (isPrimitiveValue(target) && "DataIsType" in type.classConstructor) {
+            //If type class is a special override for working with a primitive data type,
+            // like UUIDs and strings, then we don't need to initialise it.
+            return target;
+        }
+        if (!target[DataSymbol]) {
+            target[DataSymbol] = {};
+        }
+        MarkInitialised(target);
+        let props = (_a = type.finalised_properties.get(type.opts.version)) !== null && _a !== void 0 ? _a : {};
+        let objData = { root: target, source, rootRepl: type };
+        for (let [name, def] of Object.entries(props)) {
+            if ("removed" in def || "doesntExist" in def) {
+                //TODO: run migration functions for removed properties.
+                continue;
+            }
+            if (!def.load.present || def.load.skipLoad)
+                continue;
+            if (def.load.default && typeof data[def.load.name] === "undefined") {
+                data[def.load.name] = def.load.default;
+            }
+            if (def.load.present == "optional" && typeof data[def.load.name] === "undefined") {
+                continue;
+            }
+            let value = CalcPropInitialValue(objData, name, data[def.load.name], target);
+            //If expression set it as getters/setters making it transparent.
+            if (value instanceof Expression) {
+                SetPropertyToExpression(target, name, value);
+            }
+            else {
+                target[name] = value;
+            }
+            target[DataSymbol][name] = value;
+        }
+        //We don't have problem with type being enumerable, but
+        // having it as false makes comparing values in unit tests
+        // slightly easier.
+        Reflect.defineProperty(target, DataSymbol, {
+            value: data,
+            enumerable: false
+        });
+        return target;
+    }
+    Loader.InitFromData = InitFromData;
+    function MarkInitialised(object) {
+        Reflect.defineProperty(object, IsInitialised, {
+            value: true,
+            enumerable: false
+        });
+    }
+    Loader.MarkInitialised = MarkInitialised;
+    function HasObjectBeenInitialised(obj) {
+        var _a;
+        return (_a = obj[IsInitialised]) !== null && _a !== void 0 ? _a : false;
+    }
+    Loader.HasObjectBeenInitialised = HasObjectBeenInitialised;
+    function GetExpression(obj, propName) {
+        return obj[ExprProperties][propName];
+    }
+    Loader.GetExpression = GetExpression;
+})(Loader || (Loader = {}));
+__PrivateConstructorSetup.RegisterInitialiser(Loader.InitFromData);
+__PrivateConstructorSetup.RegisterHasBeenInitialised(Loader.HasObjectBeenInitialised);

package/Transformers/Progress.d.ts

@@ -0,0 +1,32 @@
+import type { ReplicableClass } from "../Tracking/Class.js";
+import { Class, InstantPromise } from "@bikky/smart-collections";
+import { Primitive } from "../Constants/SerialisationTypes.js";
+import type { ReplicableClassConstructor, TypeClass } from "../Tracking/Types.js";
+export declare namespace Progress {
+    function RegisterReplInitialisationFunction(callback: (repl: ReplicableClass) => void): void;
+    /**
+     * This function is designed to be called after every file in the game has finished loading.
+     * It completes the setup of each class, it's properties and functions, since often their types
+     * reference other classes.
+     * It's done in stages so circular references are treated fine.
+     */
+    function FinishedAllLoading(): void;
+    function ReadyForParameters(key: any): InstantPromise<(ReplicableClass | Primitive)[]>;
+    function AwaitReplicableFor(type: Class<any> | ReplicableClassConstructor | TypeClass | string): InstantPromise<(ReplicableClass | Primitive)[]>;
+    function FinishReplicableType(type: ReplicableClass): void;
+    /**
+     * A type collection is an object or string whose value is only used to look up other values.
+     */
+    function RegisterAlias(type: any, value: any): void;
+    function RegisterPropertyLoad(classConstructor: any, property: Parameters<ReplicableClass["addProperty"]>): void;
+    function RegisterPropertyRemove(classConstructor: any, property: Parameters<ReplicableClass["removeProperty"]>): void;
+    function RegisterFunctionAdd(classConstructor: any, property: Parameters<ReplicableClass["addFunction"]>): void;
+    function OnLoadFinished(callback: () => void): void;
+    function OnAnyReplicableReady(callback: (type: ReplicableClass, originalClass: any) => void): void;
+    function OnAnyPrimitiveReady(callback: (alias: any, type: Primitive) => void): void;
+    function OnAnyAliasReady(callback: (alias: any, types: (ReplicableClass | Primitive)[]) => void): void;
+    /**
+     * This function is only for testing!
+     */
+    function ClearCaches(): void;
+}