@nymphjs/nymph 1.0.0-beta.13 → 1.0.0-beta.131

package/dist/Entity.js

@@ -1,32 +1,228 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const lodash_1 = require("lodash");
-const errors_1 = require("./errors");
-const utils_1 = require("./utils");
-class Entity {
-    constructor(guid) {
-        this.guid = null;
-        this.cdate = null;
-        this.mdate = null;
-        this.tags = [];
-        this.$isASleepingReference = false;
-        this.$sleepingReference = null;
-        this.$privateData = [];
-        this.$protectedData = [];
-        this.$protectedTags = [];
-        this.$clientEnabledMethods = [];
-        this.$skipAc = false;
-        this.$originalAcValues = null;
+import { difference, intersection, isEqual } from 'lodash-es';
+import { guid } from '@nymphjs/guid';
+import { EntityConflictError, EntityIsSleepingReferenceError, InvalidParametersError, InvalidStateError, MethodFailedError, } from './errors/index.js';
+import { classNamesToEntityConstructors, entitiesToReferences, entityConstructorsToClassNames, referencesToEntities, uniqueStrings, } from './utils.js';
+/**
+ * Database abstraction object.
+ *
+ * Provides a way to access, manipulate, and store data in Nymph.
+ *
+ * The GUID is not set until the entity is saved. GUIDs must be unique forever,
+ * even after deletion. It's the job of the Nymph DB driver to make sure no two
+ * entities ever have the same GUID. This is generally done by using a large
+ * randomly generated ID.
+ *
+ * Each entity class has an etype that determines which table(s) in the database
+ * it belongs to. If two entity classes have the same etype, their data will be
+ * stored in the same table(s). This isn't a good idea, however, because
+ * references to an entity store a class name, not an etype.
+ *
+ * Tags are used to classify entities. Where an etype is used to separate data
+ * by tables, tags can be used to separate entities within a table. You can
+ * define specific tags to be protected, meaning they cannot be added/removed
+ * from the client. It can be useful to allow user defined tags, such as for
+ * blog posts.
+ *
+ * Simply calling $delete() will not unset the entity. It will still take up
+ * memory. Likewise, simply calling unset will not delete the entity from the
+ * DB.
+ *
+ * Some notes about $equals() and $is(), the replacements for "==":
+ *
+ * The == operator will likely not give you the result you want, since two
+ * instances of the same entity will fail that check, even though they represent
+ * the same data in the database.
+ *
+ * $equals() performs a more strict comparison of the entity to another. Use
+ * $equals() instead of the == operator when you want to check both the entities
+ * they represent, and the data inside them. In order to return true for
+ * $equals(), the entity and object must meet the following criteria:
+ *
+ * - They must be entities.
+ * - They must have equal GUIDs, or both must have no GUID.
+ * - Their data and tags must be equal.
+ *
+ * $is() performs a less strict comparison of the entity to another. Use $is()
+ * instead of the == operator when the entity's data may have been changed, but
+ * you only care if they represent the same entity. In order to return true, the
+ * entity and object must meet the following criteria:
+ *
+ * - They must be entities.
+ * - They must have equal GUIDs, or both must have no GUID.
+ * - If they have no GUIDs, their data and tags must be equal.
+ *
+ * Some notes about saving entities in other entity's properties:
+ *
+ * Entities use references in the DB to store an entity in their properties. The
+ * reference is stored as an array with the values:
+ *
+ * - 0 => The string 'nymph_entity_reference'
+ * - 1 => The referenced entity's GUID.
+ * - 2 => The referenced entity's class name.
+ *
+ * Since the referenced entity's class name (meaning the `class` static
+ * property, not the name of the class itself) is stored in the reference on the
+ * parent entity, if you change the class name in an update, you need to
+ * reassign all referenced entities of that class and resave.
+ *
+ * When an entity is loaded, it does not request its referenced entities from
+ * Nymph. Instead, it creates instances without data called sleeping references.
+ * When you first access an entity's data, if it is a sleeping reference, it
+ * will fill its data from the DB. You can call clearCache() to turn all the
+ * entities back into sleeping references.
+ */
+export default class Entity {
+    /**
+     * The instance of Nymph to use for queries.
+     */
+    static nymph = {};
+    /**
+     * A unique name for this type of entity used to separate its data from other
+     * types of entities in the database.
+     */
+    static ETYPE = 'entity';
+    /**
+     * The lookup name for this entity.
+     *
+     * This is used for reference arrays (and sleeping references) and client
+     * requests.
+     */
+    static class = 'Entity';
+    $nymph;
+    guid = null;
+    cdate = null;
+    mdate = null;
+    tags = [];
+    /**
+     * The data proxy handler.
+     */
+    $dataHandler;
+    /**
+     * The actual data store.
+     */
+    $dataStore;
+    /**
+     * The actual sdata store.
+     */
+    $sdata;
+    /**
+     * The data proxy object.
+     */
+    $data;
+    /**
+     * Whether this instance is a sleeping reference.
+     */
+    $isASleepingReference = false;
+    /**
+     * The reference to use to wake.
+     */
+    $sleepingReference = null;
+    /**
+     * A promise that resolved when the entity's data is wake.
+     */
+    $wakePromise = null;
+    /**
+     * Properties that will not be serialized into JSON with toJSON(). This
+     * can be considered a denylist, because these properties will not be set
+     * with incoming JSON.
+     *
+     * Clients CAN still determine what is in these properties, unless they are
+     * also listed in searchRestrictedData.
+     */
+    $privateData = [];
+    /**
+     * Whether this entity should publish changes to PubSub servers.
+     */
+    static pubSubEnabled = true;
+    /**
+     * Whether this entity should be accessible on the frontend through the REST
+     * server.
+     *
+     * If this is false, any request from the client that attempts to use this
+     * entity will fail.
+     */
+    static restEnabled = true;
+    /**
+     * Properties that will not be searchable from the frontend. If the frontend
+     * includes any of these properties in any of their clauses, they will be
+     * filtered out before the search is executed.
+     */
+    static searchRestrictedData = [];
+    /**
+     * Properties that can only be modified by server side code. They will still
+     * be visible on the frontend, unlike $privateData, but any changes to them
+     * that come from the frontend will be ignored.
+     *
+     * In addition to what's listed here, all of the access control properties
+     * will be included when Tilmeld is being used. These are:
+     *
+     * - acUser
+     * - acGroup
+     * - acOther
+     * - acRead
+     * - acWrite
+     * - acFull
+     * - user
+     * - group
+     *
+     * You should modify these through client enabled methods or the $save method
+     * instead, for safety.
+     */
+    $protectedData = [];
+    /**
+     * If this is defined, then it lists the only properties that will be
+     * accepted from incoming JSON. Any other properties will be ignored.
+     *
+     * If you use an allowlist, you don't need to use protectedData, since you
+     * can simply leave those entries out of allowlistData.
+     */
+    $allowlistData;
+    /**
+     * Tags that can only be added/removed by server side code. They will still be
+     * visible on the frontend, but any changes to them that come from the
+     * frontend will be ignored.
+     */
+    $protectedTags = [];
+    /**
+     * If this is defined, then it lists the only tags that will be accepted from
+     * incoming JSON. Any other tags will be ignored.
+     */
+    $allowlistTags;
+    /**
+     * The names of methods allowed to be called by the frontend with serverCall.
+     */
+    $clientEnabledMethods = [];
+    /**
+     * The names of static methods allowed to be called by the frontend with
+     * serverCallStatic.
+     */
+    static clientEnabledStaticMethods = [];
+    /**
+     * Whether to use "skipAc" when accessing entity references.
+     */
+    $skipAc = false;
+    /**
+     * The AC properties' values when the entity was loaded.
+     */
+    $originalAcValues = null;
+    /**
+     * This is used to hold a generated GUID for a new entity.
+     */
+    $guaranteedGUID = null;
+    /**
+     * Initialize an entity.
+     */
+    constructor(..._rest) {
         this.$nymph = this.constructor.nymph;
         this.$dataHandler = {
             has: (data, name) => {
-                this.$referenceWake();
+                this.$check();
                 return name in data || name in this.$sdata;
             },
             get: (data, name) => {
-                this.$referenceWake();
+                this.$check();
                 if (this.$sdata.hasOwnProperty(name)) {
-                    data[name] = (0, utils_1.referencesToEntities)(JSON.parse(this.$sdata[name]), this.$nymph, this.$skipAc);
+                    data[name] = referencesToEntities(classNamesToEntityConstructors(this.$nymph, JSON.parse(this.$sdata[name]), false), this.$nymph, this.$skipAc);
                     delete this.$sdata[name];
                 }
                 if (data.hasOwnProperty(name)) {
@@ -35,7 +231,7 @@ class Entity {
                 return undefined;
             },
             set: (data, name, value) => {
-                this.$referenceWake();
+                this.$check();
                 if (this.$sdata.hasOwnProperty(name)) {
                     delete this.$sdata[name];
                 }
@@ -43,7 +239,7 @@ class Entity {
                 return true;
             },
             deleteProperty: (data, name) => {
-                this.$referenceWake();
+                this.$check();
                 if (this.$sdata.hasOwnProperty(name)) {
                     return delete this.$sdata[name];
                 }
@@ -53,7 +249,7 @@ class Entity {
                 return true;
             },
             defineProperty: (data, name, descriptor) => {
-                this.$referenceWake();
+                this.$check();
                 if (this.$sdata.hasOwnProperty(name)) {
                     delete this.$sdata[name];
                 }
@@ -61,119 +257,123 @@ class Entity {
                 return true;
             },
             getOwnPropertyDescriptor: (data, name) => {
-                this.$referenceWake();
+                this.$check();
                 if (this.$sdata.hasOwnProperty(name)) {
-                    data[name] = (0, utils_1.referencesToEntities)(JSON.parse(this.$sdata[name]), this.$nymph, this.$skipAc);
+                    data[name] = referencesToEntities(classNamesToEntityConstructors(this.$nymph, JSON.parse(this.$sdata[name]), false), this.$nymph, this.$skipAc);
                     delete this.$sdata[name];
                 }
                 return Object.getOwnPropertyDescriptor(data, name);
             },
             ownKeys: (data) => {
-                this.$referenceWake();
+                this.$check();
                 return Object.getOwnPropertyNames(data).concat(Object.getOwnPropertyNames(this.$sdata));
             },
         };
         this.$dataStore = {};
         this.$sdata = {};
         this.$data = new Proxy(this.$dataStore, this.$dataHandler);
-        if (guid != null) {
-            const entity = this.$nymph.driver.getEntitySync({ class: this.constructor }, { type: '&', guid });
-            if (entity) {
-                this.guid = entity.guid;
-                this.tags = entity.tags;
-                this.cdate = entity.cdate;
-                this.mdate = entity.mdate;
-                this.$putData(entity.$getData(), entity.$getSData());
-            }
-        }
-        return new Proxy(this, {
-            has: (entity, name) => {
-                if (typeof name !== 'string' ||
-                    name in entity ||
-                    name.substring(0, 1) === '$') {
-                    return name in entity;
-                }
-                this.$referenceWake();
-                return name in entity.$data;
-            },
-            get: (entity, name) => {
-                if (typeof name !== 'string' ||
-                    name in entity ||
-                    name.substring(0, 1) === '$') {
-                    if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-                        this.$referenceWake();
+        return this.$proxy();
+    }
+    $existingProxy;
+    $proxy() {
+        if (this.$existingProxy == null) {
+            this.$existingProxy = new Proxy(this, {
+                has: (entity, name) => {
+                    if (typeof name !== 'string' ||
+                        name in entity ||
+                        name.substring(0, 1) === '$') {
+                        return name in entity;
                     }
-                    return entity[name];
-                }
-                this.$referenceWake();
-                if (name in entity.$data) {
-                    return entity.$data[name];
-                }
-                return undefined;
-            },
-            set: (entity, name, value) => {
-                if (typeof name !== 'string' ||
-                    name in entity ||
-                    name.substring(0, 1) === '$') {
-                    if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-                        this.$referenceWake();
+                    this.$check();
+                    return name in entity.$data;
+                },
+                get: (entity, name) => {
+                    if (typeof name !== 'string' ||
+                        name in entity ||
+                        name.substring(0, 1) === '$') {
+                        if (name === 'tags' || name === 'cdate' || name === 'mdate') {
+                            this.$check();
+                        }
+                        return entity[name];
                     }
-                    entity[name] = value;
-                }
-                else {
-                    this.$referenceWake();
-                    entity.$data[name] = value;
-                }
-                return true;
-            },
-            deleteProperty: (entity, name) => {
-                if (name in entity) {
-                    return delete entity[name];
-                }
-                else if (name in entity.$data) {
-                    this.$referenceWake();
-                    return delete entity.$data[name];
-                }
-                return true;
-            },
-            getPrototypeOf: (entity) => {
-                return entity.constructor.prototype;
-            },
-            defineProperty: (entity, name, descriptor) => {
-                if (typeof name !== 'string' ||
-                    name in entity ||
-                    name.substring(0, 1) === '$') {
-                    if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-                        this.$referenceWake();
+                    this.$check();
+                    if (name in entity.$data) {
+                        return entity.$data[name];
                     }
-                    Object.defineProperty(entity, name, descriptor);
-                }
-                else {
-                    this.$referenceWake();
-                    Object.defineProperty(entity.$data, name, descriptor);
-                }
-                return true;
-            },
-            getOwnPropertyDescriptor: (entity, name) => {
-                if (typeof name !== 'string' ||
-                    name in entity ||
-                    name.substring(0, 1) === '$') {
-                    if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-                        this.$referenceWake();
+                    return undefined;
+                },
+                set: (entity, name, value) => {
+                    if (typeof name !== 'string' ||
+                        name in entity ||
+                        name.substring(0, 1) === '$') {
+                        if (name === 'tags' || name === 'cdate' || name === 'mdate') {
+                            this.$check();
+                        }
+                        entity[name] = value;
                     }
-                    return Object.getOwnPropertyDescriptor(entity, name);
-                }
-                else {
-                    this.$referenceWake();
-                    return Object.getOwnPropertyDescriptor(entity.$data, name);
-                }
-            },
-            ownKeys: (entity) => {
-                this.$referenceWake();
-                return Object.getOwnPropertyNames(entity).concat(Object.getOwnPropertyNames(entity.$data));
-            },
-        });
+                    else {
+                        this.$check();
+                        entity.$data[name] = value;
+                    }
+                    return true;
+                },
+                deleteProperty: (entity, name) => {
+                    if (name in entity) {
+                        return delete entity[name];
+                    }
+                    else if (name in entity.$data) {
+                        this.$check();
+                        return delete entity.$data[name];
+                    }
+                    return true;
+                },
+                getPrototypeOf: (entity) => {
+                    return entity.constructor.prototype;
+                },
+                defineProperty: (entity, name, descriptor) => {
+                    if (typeof name !== 'string' ||
+                        name in entity ||
+                        name.substring(0, 1) === '$') {
+                        if (name === 'tags' || name === 'cdate' || name === 'mdate') {
+                            this.$check();
+                        }
+                        Object.defineProperty(entity, name, descriptor);
+                    }
+                    else {
+                        this.$check();
+                        Object.defineProperty(entity.$data, name, descriptor);
+                    }
+                    return true;
+                },
+                getOwnPropertyDescriptor: (entity, name) => {
+                    if (typeof name !== 'string' ||
+                        name in entity ||
+                        name.substring(0, 1) === '$') {
+                        if (name === 'tags' || name === 'cdate' || name === 'mdate') {
+                            this.$check();
+                        }
+                        return Object.getOwnPropertyDescriptor(entity, name);
+                    }
+                    else {
+                        this.$check();
+                        return Object.getOwnPropertyDescriptor(entity.$data, name);
+                    }
+                },
+                ownKeys: (entity) => {
+                    this.$check();
+                    return Object.getOwnPropertyNames(entity).concat(Object.getOwnPropertyNames(entity.$data));
+                },
+            });
+        }
+        return this.$existingProxy;
     }
+    /**
+     * Create or retrieve a new entity instance.
+     *
+     * Note that this will always return an entity, even if the GUID is not found.
+     *
+     * @param guid An optional GUID to retrieve.
+     */
     static async factory(guid) {
         const entity = new this();
         if (guid != null) {
@@ -186,43 +386,143 @@ class Entity {
         }
         return entity;
     }
-    static factorySync(guid) {
-        return new this(guid);
+    /**
+     * Create a new entity instance.
+     */
+    static factorySync() {
+        return new this();
     }
+    /**
+     * Create a new sleeping reference instance.
+     *
+     * Sleeping references won't retrieve their data from the database until they
+     * are readied with `$wake()` or a parent's `$wakeAll()`.
+     *
+     * @param reference The Nymph Entity Reference to use to wake.
+     * @returns The new instance.
+     */
     static factoryReference(reference) {
         const entity = new this();
         entity.$referenceSleep(reference);
         return entity;
     }
+    /**
+     * Get an array of strings that **must** be unique across the current etype.
+     *
+     * When you try to save another entity with any of the same unique strings,
+     * Nymph will throw an error.
+     *
+     * The default implementation of this static method instantiates the entity,
+     * assigns all of the given data, then calls `$getUniques` and returns its
+     * output. This can have a performance impact if a lot of extra processing
+     * happens during any of these steps. You can override this method to
+     * calculate the unique strings faster, but you must return the same strings
+     * that would be returned by `$getUniques`.
+     *
+     * @returns Resolves to an array of entity's unique constraint strings.
+     */
+    static async getUniques({ guid, cdate, mdate, tags, data, sdata, }) {
+        const entity = new this();
+        if (guid != null) {
+            entity.guid = guid;
+        }
+        if (cdate != null) {
+            entity.cdate = cdate;
+        }
+        if (mdate != null) {
+            entity.mdate = mdate;
+        }
+        entity.tags = tags;
+        entity.$putData(data, sdata);
+        return await entity.$getUniques();
+    }
+    /**
+     * Get a string for full text search for one of an entity's properties.
+     *
+     * The result will be tokenized and stored as the full text search index for
+     * use with "search" clauses.
+     *
+     * Return null to not include any tokens in the full text search storage.
+     *
+     * You shouldn't use any other entity data to transform the text, as it won't
+     * always be available. This function is meant for things like stripping HTML
+     * tags.
+     *
+     * @returns By default, returns the value if it is a string.
+     */
+    static getFTSText(_name, value) {
+        if (typeof value === 'string') {
+            return value;
+        }
+        return null;
+    }
     toJSON() {
         if (this.$isASleepingReference) {
             return this.$sleepingReference;
         }
         const obj = {
-            class: this.constructor.class,
+            class: entityConstructorsToClassNames(this.constructor),
             guid: this.guid,
             cdate: this.cdate,
             mdate: this.mdate,
             tags: [...this.tags],
             data: {},
         };
-        const data = this.$getData(true);
-        for (const key in data) {
+        for (const key of [
+            ...Object.keys(this.$dataStore),
+            ...Object.keys(this.$sdata),
+        ]) {
             if (this.$privateData.indexOf(key) === -1) {
-                obj.data[key] = (0, utils_1.entitiesToReferences)(data[key]);
+                obj.data[key] = entityConstructorsToClassNames(entitiesToReferences(this.$data[key], true));
             }
         }
         return obj;
     }
+    $setNymph(nymph) {
+        this.$nymph = nymph;
+        if (!this.$asleep()) {
+            const recurseData = (data) => {
+                if (Array.isArray(data)) {
+                    for (let name in data) {
+                        recurseData(data[name]);
+                    }
+                }
+                else if (data instanceof Entity) {
+                    if (data.$nymph !== nymph) {
+                        data.$setNymph(nymph);
+                    }
+                }
+                else if (typeof data === 'function' &&
+                    data.prototype instanceof Entity) {
+                    data.nymph = nymph;
+                }
+                else if (typeof data === 'object') {
+                    for (let name in data) {
+                        recurseData(data[name]);
+                    }
+                }
+            };
+            recurseData(this.$data);
+        }
+    }
+    $getGuaranteedGUID() {
+        if (this.guid !== null) {
+            return this.guid;
+        }
+        if (this.$guaranteedGUID == null) {
+            this.$guaranteedGUID = guid();
+        }
+        return this.$guaranteedGUID;
+    }
     $addTag(...tags) {
-        this.$referenceWake();
+        this.$check();
         if (tags.length < 1) {
             return;
         }
-        this.tags = (0, utils_1.uniqueStrings)([...this.tags, ...tags]);
+        this.tags = uniqueStrings([...this.tags, ...tags]);
     }
     $arraySearch(array, strict = false) {
-        this.$referenceWake();
+        this.$check();
         if (!Array.isArray(array)) {
             return -1;
         }
@@ -235,18 +535,20 @@ class Entity {
         return -1;
     }
     $clearCache() {
-        this.$referenceWake();
-        this.$putData(this.$getData(), this.$getSData());
+        this.$check();
+        this.$putData(this.$getData(false), this.$getSData());
     }
     $getClientEnabledMethods() {
         return this.$clientEnabledMethods;
     }
     async $delete() {
-        this.$referenceWake();
-        return await this.$nymph.deleteEntity(this);
+        await this.$wake();
+        if (!(await this.$nymph.deleteEntity(this))) {
+            throw new MethodFailedError('Failed to delete entity.');
+        }
     }
     $equals(object) {
-        this.$referenceWake();
+        this.$check();
         if (!(object instanceof Entity)) {
             return false;
         }
@@ -263,41 +565,79 @@ class Entity {
         }
         const obTags = [...object.tags].sort();
         const myTags = [...this.tags].sort();
-        if (!(0, lodash_1.isEqual)(obTags, myTags)) {
+        if (!isEqual(obTags, myTags)) {
             return false;
         }
-        const obData = object.$getData(true);
-        const myData = this.$getData(true);
-        return (0, lodash_1.isEqual)(obData, myData);
+        const obData = entityConstructorsToClassNames(entitiesToReferences(object.$getData(true), true));
+        const myData = entityConstructorsToClassNames(entitiesToReferences(this.$getData(true), true));
+        return isEqual(obData, myData);
     }
     $getData(includeSData = false) {
-        this.$referenceWake();
+        this.$check();
         if (includeSData) {
+            // Access all the serialized properties to initialize them.
             for (const key in this.$sdata) {
                 const _unused = this[key];
             }
         }
-        return (0, utils_1.entitiesToReferences)({ ...this.$dataStore });
+        return { ...this.$dataStore };
     }
     $getSData() {
-        this.$referenceWake();
+        this.$check();
         return this.$sdata;
     }
+    async $getUniques() {
+        return [];
+    }
     $getOriginalAcValues() {
-        this.$referenceWake();
-        return (this.$originalAcValues ?? {
-            user: this.$data.user,
-            group: this.$data.group,
-            acUser: this.$data.acUser,
-            acGroup: this.$data.acGroup,
-            acOther: this.$data.acOther,
-            acRead: this.$data.acRead,
-            acWrite: this.$data.acWrite,
-            acFull: this.$data.acFull,
-        });
+        this.$check();
+        return this.$originalAcValues ?? this.$getCurrentAcValues();
+    }
+    $getCurrentAcValues() {
+        this.$check();
+        return {
+            user: this.$getAcUid(),
+            group: this.$getAcGid(),
+            acUser: this.$data.acUser ?? null,
+            acGroup: this.$data.acGroup ?? null,
+            acOther: this.$data.acOther ?? null,
+            acRead: this.$getAcReadIds(),
+            acWrite: this.$getAcWriteIds(),
+            acFull: this.$getAcFullIds(),
+        };
+    }
+    $getAcUid() {
+        if ('user' in this.$sdata) {
+            const userValue = JSON.parse(this.$sdata.user);
+            if (Array.isArray(userValue) &&
+                userValue[0] === 'nymph_entity_reference') {
+                return userValue[1];
+            }
+        }
+        return (this.$data.user?.guid ?? null);
+    }
+    $getAcGid() {
+        if ('group' in this.$sdata) {
+            const groupValue = JSON.parse(this.$sdata.group);
+            if (Array.isArray(groupValue) &&
+                groupValue[0] === 'nymph_entity_reference') {
+                return groupValue[1];
+            }
+        }
+        return (this.$data.group?.guid ?? null);
+    }
+    $getAcReadIds() {
+        return (this.$data.acRead?.map((entity) => typeof entity === 'string' ? entity : entity.guid) ?? null);
+    }
+    $getAcWriteIds() {
+        return (this.$data.acWrite?.map((entity) => typeof entity === 'string' ? entity : entity.guid) ?? null);
+    }
+    $getAcFullIds() {
+        return (this.$data.acFull?.map((entity) => typeof entity === 'string' ? entity : entity.guid) ?? null);
     }
     $getValidatable() {
-        this.$referenceWake();
+        this.$check();
+        // Access all the serialized properties to initialize them.
         for (const key in this.$sdata) {
             const _unused = this[key];
         }
@@ -306,15 +646,15 @@ class Entity {
             cdate: this.cdate,
             mdate: this.mdate,
             tags: this.tags,
-            ...(0, utils_1.referencesToEntities)(this.$dataStore, this.$nymph, this.$skipAc),
+            ...this.$dataStore,
         };
     }
     $getTags() {
-        this.$referenceWake();
+        this.$check();
         return this.tags;
     }
     $hasTag(...tags) {
-        this.$referenceWake();
+        this.$check();
         if (!tags.length) {
             return false;
         }
@@ -332,44 +672,50 @@ class Entity {
         if (!(object instanceof Entity)) {
             return false;
         }
-        if (this.guid || object.guid) {
+        if (this === object) {
+            return true;
+        }
+        if (this.guid != null || object.guid != null) {
             return this.guid === object.guid;
         }
-        this.$referenceWake();
+        this.$check();
         if (typeof object.$getData !== 'function') {
             return false;
         }
         else {
             const obTags = [...object.tags].sort();
             const myTags = [...this.tags].sort();
-            if (!(0, lodash_1.isEqual)(obTags, myTags)) {
+            if (!isEqual(obTags, myTags)) {
                 return false;
             }
-            const obData = object.$getData(true);
-            const myData = this.$getData(true);
-            return (0, lodash_1.isEqual)(obData, myData);
+            const obData = entityConstructorsToClassNames(entitiesToReferences(object.$getData(true), true));
+            const myData = entityConstructorsToClassNames(entitiesToReferences(this.$getData(true), true));
+            return isEqual(obData, myData);
         }
     }
     $jsonAcceptData(input, allowConflict = false) {
-        this.$referenceWake();
+        this.$check();
         if (this.guid != input.guid) {
-            throw new errors_1.EntityConflictError('Tried to accept JSON input for the wrong entity.');
+            throw new EntityConflictError('Tried to accept JSON input for the wrong entity.');
         }
+        // Accept the modified date.
         const mdate = input.mdate ?? 0;
         const thismdate = this.mdate ?? 0;
         if (mdate < thismdate && !allowConflict) {
-            throw new errors_1.EntityConflictError('This entity is newer than JSON input.');
+            throw new EntityConflictError('This entity is newer than JSON input.');
         }
         this.mdate = input.mdate;
+        // Accept the tags.
         const currentTags = this.$getTags();
-        const protectedTags = (0, lodash_1.intersection)(this.$protectedTags, currentTags);
-        let tags = (0, lodash_1.difference)(input.tags, this.$protectedTags);
+        const protectedTags = intersection(this.$protectedTags, currentTags);
+        let tags = difference(input.tags, this.$protectedTags);
         if (this.$allowlistTags != null) {
-            tags = (0, lodash_1.intersection)(tags, this.$allowlistTags);
+            tags = intersection(tags, this.$allowlistTags);
         }
         this.$removeTag(...currentTags);
         this.$addTag(...protectedTags, ...tags);
-        const data = input.data;
+        // Accept the data.
+        const data = { ...input.data };
         const privateData = {};
         for (const name of this.$privateData) {
             if (name in this.$data) {
@@ -381,10 +727,21 @@ class Entity {
         }
         const protectedData = {};
         const protectedProps = [...this.$protectedData];
-        if (this.$nymph.tilmeld &&
-            !this.$nymph.tilmeld.gatekeeper('tilmeld/admin')) {
-            protectedProps.push('user');
-            protectedProps.push('group');
+        if (this.$nymph.tilmeld) {
+            protectedProps.push('acUser');
+            protectedProps.push('acGroup');
+            protectedProps.push('acOther');
+            protectedProps.push('acRead');
+            protectedProps.push('acWrite');
+            protectedProps.push('acFull');
+            if ((this.constructor.class !== 'User' &&
+                this.constructor.class !== 'Group') ||
+                !this.$nymph.tilmeld.currentUser ||
+                (!this.$nymph.tilmeld.currentUser.abilities?.includes('tilmeld/admin') &&
+                    !this.$nymph.tilmeld.currentUser.abilities?.includes('system/admin'))) {
+                protectedProps.push('user');
+                protectedProps.push('group');
+            }
         }
         for (const name of protectedProps) {
             if (name in this.$data) {
@@ -414,29 +771,47 @@ class Entity {
         });
     }
     $jsonAcceptPatch(patch, allowConflict = false) {
-        this.$referenceWake();
+        this.$check();
         if (this.guid != patch.guid) {
-            throw new errors_1.EntityConflictError('Tried to accept JSON patch for the wrong entity.');
+            throw new EntityConflictError('Tried to accept JSON patch for the wrong entity.');
         }
+        // Accept the modified date.
         const mdate = patch.mdate ?? 0;
         const thismdate = this.mdate ?? 0;
         if (mdate < thismdate && !allowConflict) {
-            throw new errors_1.EntityConflictError('This entity is newer than JSON patch.');
+            throw new EntityConflictError('This entity is newer than JSON patch.');
         }
         this.mdate = patch.mdate;
+        const protectedProps = [...this.$protectedData];
+        if (this.$nymph.tilmeld) {
+            protectedProps.push('acUser');
+            protectedProps.push('acGroup');
+            protectedProps.push('acOther');
+            protectedProps.push('acRead');
+            protectedProps.push('acWrite');
+            protectedProps.push('acFull');
+            if ((this.constructor.class !== 'User' &&
+                this.constructor.class !== 'Group') ||
+                !this.$nymph.tilmeld.currentUser ||
+                (!this.$nymph.tilmeld.currentUser.abilities?.includes('tilmeld/admin') &&
+                    !this.$nymph.tilmeld.currentUser.abilities?.includes('system/admin'))) {
+                protectedProps.push('user');
+                protectedProps.push('group');
+            }
+        }
         for (const name in patch.set) {
             if ((this.$allowlistData != null &&
                 this.$allowlistData.indexOf(name) === -1) ||
-                this.$protectedData.indexOf(name) !== -1 ||
+                protectedProps.indexOf(name) !== -1 ||
                 this.$privateData.indexOf(name) !== -1) {
                 continue;
             }
-            this.$data[name] = (0, utils_1.referencesToEntities)(patch.set[name], this.$nymph, this.$skipAc);
+            this.$data[name] = patch.set[name];
         }
         for (const name of patch.unset) {
             if ((this.$allowlistData != null &&
                 this.$allowlistData.indexOf(name) === -1) ||
-                this.$protectedData.indexOf(name) !== -1 ||
+                protectedProps.indexOf(name) !== -1 ||
                 this.$privateData.indexOf(name) !== -1) {
                 continue;
             }
@@ -459,63 +834,154 @@ class Entity {
             this.$removeTag(tag);
         }
     }
-    $putData(data, sdata) {
-        this.$referenceWake();
-        const mySdata = sdata ?? this.$getSData();
-        for (const name in data) {
-            delete mySdata[name];
-        }
+    $putData(data, sdata, _source) {
+        this.$check();
         for (const name in this.$dataStore) {
             delete this.$dataStore[name];
         }
         for (const name in data) {
-            this.$dataStore[name] = (0, utils_1.referencesToEntities)(data[name], this.$nymph, this.$skipAc);
+            this.$dataStore[name] = data[name];
         }
-        this.$sdata = mySdata;
+        this.$sdata = sdata ?? {};
+        // Set original AC values if not set..
         if (this.$originalAcValues == null) {
-            this.$originalAcValues = this.$getOriginalAcValues();
+            this.$originalAcValues = this.$getCurrentAcValues();
         }
     }
+    /**
+     * Set up a sleeping reference.
+     * @param array $reference The reference to use to wake.
+     */
     $referenceSleep(reference) {
         if (reference.length !== 3 ||
             reference[0] !== 'nymph_entity_reference' ||
             typeof reference[1] !== 'string' ||
             typeof reference[2] !== 'string') {
-            throw new errors_1.InvalidParametersError('referenceSleep expects parameter 1 to be a valid Nymph entity ' +
+            throw new InvalidParametersError('referenceSleep expects parameter 1 to be a valid Nymph entity ' +
                 'reference.');
         }
         const thisClass = this.constructor.class;
         if (reference[2] !== thisClass) {
-            throw new errors_1.InvalidParametersError('referenceSleep can only be called with an entity reference of the ' +
+            throw new InvalidParametersError('referenceSleep can only be called with an entity reference of the ' +
                 `same class. Given class: ${reference[2]}; this class: ${thisClass}.`);
         }
         this.$isASleepingReference = true;
         this.guid = reference[1];
         this.$sleepingReference = reference;
     }
-    $referenceWake() {
-        if (!this.$isASleepingReference || this.$sleepingReference == null) {
-            return true;
+    /**
+     * Check if this is a sleeping reference and throw an error if so.
+     */
+    $check() {
+        if (this.$asleep()) {
+            throw new EntityIsSleepingReferenceError('This entity is in a sleeping reference state. You must use .$wake() to wake it.');
         }
-        const EntityClass = this.$nymph.getEntityClass(this.$sleepingReference[2]);
-        const entity = this.$nymph.driver.getEntitySync({
-            class: EntityClass,
-            skipAc: this.$skipAc,
-        }, { type: '&', guid: this.$sleepingReference[1] });
-        if (entity == null) {
-            return false;
+    }
+    /**
+     * Check if this is a sleeping reference.
+     */
+    $asleep() {
+        return this.$isASleepingReference || this.$sleepingReference != null;
+    }
+    /**
+     * Wake from a sleeping reference.
+     */
+    $wake() {
+        if (!this.$asleep()) {
+            this.$wakePromise = null;
+            return Promise.resolve(this.$proxy());
         }
-        this.$isASleepingReference = false;
-        this.$sleepingReference = null;
-        this.guid = entity.guid;
-        this.tags = entity.tags;
-        this.cdate = entity.cdate;
-        this.mdate = entity.mdate;
-        this.$putData(entity.$getData(), entity.$getSData());
-        return true;
+        if (this.$sleepingReference?.[1] == null) {
+            throw new InvalidStateError('Tried to wake a sleeping reference with no GUID.');
+        }
+        if (!this.$wakePromise) {
+            const EntityClass = this.$nymph.getEntityClass(this.$sleepingReference[2]);
+            this.$wakePromise = this.$nymph
+                .getEntity({
+                class: EntityClass,
+                skipAc: this.$skipAc,
+            }, { type: '&', guid: this.$sleepingReference[1] })
+                .then((entity) => {
+                if (entity == null || entity.guid == null) {
+                    return Promise.reject(new InvalidStateError('The sleeping reference could not be retrieved.'));
+                }
+                this.$isASleepingReference = false;
+                this.$sleepingReference = null;
+                this.guid = entity.guid;
+                this.tags = entity.tags;
+                this.cdate = entity.cdate;
+                this.mdate = entity.mdate;
+                this.$putData(entity.$getData(false), entity.$getSData(), 'server');
+                return this.$proxy();
+            })
+                .finally(() => {
+                this.$wakePromise = null;
+            });
+        }
+        return this.$wakePromise;
+    }
+    $wakeAll(level) {
+        return new Promise((resolve, reject) => {
+            // Run this once this entity is wake.
+            const wakeProps = () => {
+                let newLevel;
+                // If level is undefined, keep going forever, otherwise, stop once we've
+                // gone deep enough.
+                if (level !== undefined) {
+                    newLevel = level - 1;
+                }
+                if (newLevel !== undefined && newLevel < 0) {
+                    resolve(this.$proxy());
+                    return;
+                }
+                const promises = [];
+                // Go through data looking for entities to wake.
+                const walkData = (data) => {
+                    if (data == null) {
+                        return;
+                    }
+                    else if (typeof data === 'function' &&
+                        data.prototype instanceof Entity) {
+                        // Ignore this, it is an entity class.
+                        return;
+                    }
+                    else if (data instanceof Entity) {
+                        // Wake it up.
+                        if (data.$isASleepingReference) {
+                            promises.push(data.$wakeAll(newLevel));
+                        }
+                    }
+                    else if (Array.isArray(data)) {
+                        // Recurse into lower arrays.
+                        for (let i = 0; i < data.length; i++) {
+                            walkData(data[i]);
+                        }
+                    }
+                    else if (data instanceof Object) {
+                        // Recurse into objects.
+                        for (let [key, value] of Object.entries(data)) {
+                            walkData(value);
+                        }
+                    }
+                };
+                walkData(this.$data);
+                if (promises.length) {
+                    Promise.all(promises).then(() => resolve(this.$proxy()), (errObj) => reject(errObj));
+                }
+                else {
+                    resolve(this.$proxy());
+                }
+            };
+            if (this.$isASleepingReference) {
+                this.$wake().then(wakeProps, (errObj) => reject(errObj));
+            }
+            else {
+                wakeProps();
+            }
+        });
     }
     async $refresh() {
-        this.$referenceWake();
+        await this.$wake();
         if (this.guid == null) {
             return false;
         }
@@ -525,32 +991,34 @@ class Entity {
             skipAc: this.$skipAc,
         }, { type: '&', guid: this.guid });
         if (refresh == null) {
-            return 0;
+            throw new MethodFailedError("The entity's data could not be refreshed.");
         }
         this.tags = refresh.tags;
         this.cdate = refresh.cdate;
         this.mdate = refresh.mdate;
-        this.$putData(refresh.$getData(), refresh.$getSData());
+        this.$putData(refresh.$getData(false), refresh.$getSData(), 'server');
         return true;
     }
     $removeTag(...tags) {
-        this.$referenceWake();
-        this.tags = (0, lodash_1.difference)(this.tags, tags);
+        this.$check();
+        this.tags = difference(this.tags, tags);
     }
     async $save() {
-        this.$referenceWake();
-        return await this.$nymph.saveEntity(this);
+        await this.$wake();
+        if (!(await this.$nymph.saveEntity(this))) {
+            throw new MethodFailedError('Failed to save entity.');
+        }
     }
-    $toReference() {
+    $toReference(existingOnly) {
         if (this.$isASleepingReference && this.$sleepingReference != null) {
             return this.$sleepingReference;
         }
-        if (this.guid == null) {
-            return this;
+        if (existingOnly && this.guid == null) {
+            return this.$proxy();
         }
         return [
             'nymph_entity_reference',
-            this.guid,
+            this.$getGuaranteedGUID(),
             this.constructor.class,
         ];
     }
@@ -558,10 +1026,4 @@ class Entity {
         this.$skipAc = !!skipAc;
     }
 }
-exports.default = Entity;
-Entity.nymph = {};
-Entity.ETYPE = 'entity';
-Entity.class = 'Entity';
-Entity.searchRestrictedData = [];
-Entity.clientEnabledStaticMethods = [];
 //# sourceMappingURL=Entity.js.map