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

package/src/Entity.ts

@@ -1,22 +1,42 @@
-import { difference, intersection, isEqual } from 'lodash';
+import { difference, intersection, isEqual } from 'lodash-es';
+import { guid } from '@nymphjs/guid';
 
-import type Nymph from './Nymph';
-import {
+import type Nymph from './Nymph.js';
+import type { Options } from './Nymph.types.js';
+import type {
   ACProperties,
   EntityConstructor,
   EntityData,
   EntityInterface,
   EntityJson,
+  EntityObject,
   EntityPatch,
   EntityReference,
   SerializedEntityData,
-} from './Entity.types';
-import { EntityConflictError, InvalidParametersError } from './errors';
+} from './Entity.types.js';
+import {
+  EntityConflictError,
+  EntityIsSleepingReferenceError,
+  InvalidParametersError,
+  InvalidStateError,
+  MethodFailedError,
+} from './errors/index.js';
 import {
+  classNamesToEntityConstructors,
   entitiesToReferences,
+  entityConstructorsToClassNames,
   referencesToEntities,
   uniqueStrings,
-} from './utils';
+} from './utils.js';
+
+export type EntityDataType<T> =
+  T extends Entity<infer DataType> ? DataType : never;
+
+export type EntityInstanceType<T extends EntityConstructor> =
+  T extends new () => infer E ? E & EntityDataType<E> : never;
+
+export type EntityObjectType<T extends EntityConstructor> =
+  T extends new () => infer E ? EntityObject & EntityDataType<E> : never;
 
 /**
  * Database abstraction object.
@@ -87,9 +107,9 @@ import {
  * will fill its data from the DB. You can call clearCache() to turn all the
  * entities back into sleeping references.
  */
-export default class Entity<T extends EntityData = EntityData>
-  implements EntityInterface
-{
+export default class Entity<
+  T extends EntityData = EntityData,
+> implements EntityInterface {
   /**
    * The instance of Nymph to use for queries.
    */
@@ -136,6 +156,10 @@ export default class Entity<T extends EntityData = EntityData>
    * The reference to use to wake.
    */
   protected $sleepingReference: EntityReference | null = null;
+  /**
+   * A promise that resolved when the entity's data is wake.
+   */
+  protected $wakePromise: Promise<Entity<T>> | null = null;
   /**
    * Properties that will not be serialized into JSON with toJSON(). This
    * can be considered a denylist, because these properties will not be set
@@ -145,6 +169,18 @@ export default class Entity<T extends EntityData = EntityData>
    * also listed in searchRestrictedData.
    */
   protected $privateData: string[] = [];
+  /**
+   * Whether this entity should publish changes to PubSub servers.
+   */
+  public 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.
+   */
+  public 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
@@ -156,8 +192,20 @@ export default class Entity<T extends EntityData = EntityData>
    * 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, the 'user' and 'group' properties will
-   * be filtered for non-admins when Tilmeld is being used.
+   * 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.
    */
   protected $protectedData: string[] = [];
   /**
@@ -196,28 +244,43 @@ export default class Entity<T extends EntityData = EntityData>
    * The AC properties' values when the entity was loaded.
    */
   private $originalAcValues: ACProperties | null = null;
+  /**
+   * This is used to hold a generated GUID for a new entity.
+   */
+  private $guaranteedGUID: string | null = null;
 
   /**
-   * Load an entity.
-   * @param guid The ID of the entity to load, undefined for a new entity.
+   * Alter the options for a query for this entity.
+   *
+   * @param options The current options.
+   * @returns The altered options.
    */
-  public constructor(guid?: string) {
+  static alterOptions?<T extends Options>(options: T): T;
+
+  /**
+   * Initialize an entity.
+   */
+  public constructor(..._rest: any[]) {
     this.$nymph = (this.constructor as EntityConstructor).nymph;
     this.$dataHandler = {
       has: (data: EntityData, name: string) => {
-        this.$referenceWake();
+        this.$check();
 
         return name in data || name in this.$sdata;
       },
 
       get: (data: EntityData, name: string) => {
-        this.$referenceWake();
+        this.$check();
 
         if (this.$sdata.hasOwnProperty(name)) {
           data[name] = referencesToEntities(
-            JSON.parse(this.$sdata[name]),
+            classNamesToEntityConstructors(
+              this.$nymph,
+              JSON.parse(this.$sdata[name]),
+              false,
+            ),
             this.$nymph,
-            this.$skipAc
+            this.$skipAc,
           );
           delete this.$sdata[name];
         }
@@ -228,7 +291,7 @@ export default class Entity<T extends EntityData = EntityData>
       },
 
       set: (data: EntityData, name: string, value: any) => {
-        this.$referenceWake();
+        this.$check();
 
         if (this.$sdata.hasOwnProperty(name)) {
           delete this.$sdata[name];
@@ -238,7 +301,7 @@ export default class Entity<T extends EntityData = EntityData>
       },
 
       deleteProperty: (data: EntityData, name: string) => {
-        this.$referenceWake();
+        this.$check();
 
         if (this.$sdata.hasOwnProperty(name)) {
           return delete this.$sdata[name];
@@ -252,9 +315,9 @@ export default class Entity<T extends EntityData = EntityData>
       defineProperty: (
         data: EntityData,
         name: string,
-        descriptor: PropertyDescriptor
+        descriptor: PropertyDescriptor,
       ) => {
-        this.$referenceWake();
+        this.$check();
 
         if (this.$sdata.hasOwnProperty(name)) {
           delete this.$sdata[name];
@@ -264,13 +327,17 @@ export default class Entity<T extends EntityData = EntityData>
       },
 
       getOwnPropertyDescriptor: (data: EntityData, name: string) => {
-        this.$referenceWake();
+        this.$check();
 
         if (this.$sdata.hasOwnProperty(name)) {
           data[name] = referencesToEntities(
-            JSON.parse(this.$sdata[name]),
+            classNamesToEntityConstructors(
+              this.$nymph,
+              JSON.parse(this.$sdata[name]),
+              false,
+            ),
             this.$nymph,
-            this.$skipAc
+            this.$skipAc,
           );
           delete this.$sdata[name];
         }
@@ -278,10 +345,10 @@ export default class Entity<T extends EntityData = EntityData>
       },
 
       ownKeys: (data: EntityData) => {
-        this.$referenceWake();
+        this.$check();
 
         return Object.getOwnPropertyNames(data).concat(
-          Object.getOwnPropertyNames(this.$sdata)
+          Object.getOwnPropertyNames(this.$sdata),
         );
       },
     };
@@ -290,20 +357,6 @@ export default class Entity<T extends EntityData = EntityData>
 
     this.$data = new Proxy(this.$dataStore, this.$dataHandler);
 
-    if (guid != null) {
-      const entity = this.$nymph.driver.getEntitySync(
-        { class: this.constructor as EntityConstructor },
-        { 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: Entity, name: string) => {
         if (
@@ -314,7 +367,7 @@ export default class Entity<T extends EntityData = EntityData>
           return name in entity;
         }
 
-        this.$referenceWake();
+        this.$check();
         return name in entity.$data;
       },
 
@@ -325,12 +378,12 @@ export default class Entity<T extends EntityData = EntityData>
           name.substring(0, 1) === '$'
         ) {
           if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-            this.$referenceWake();
+            this.$check();
           }
           return (entity as any)[name];
         }
 
-        this.$referenceWake();
+        this.$check();
         if (name in entity.$data) {
           return entity.$data[name];
         }
@@ -344,11 +397,11 @@ export default class Entity<T extends EntityData = EntityData>
           name.substring(0, 1) === '$'
         ) {
           if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-            this.$referenceWake();
+            this.$check();
           }
           (entity as any)[name] = value;
         } else {
-          this.$referenceWake();
+          this.$check();
           (entity.$data as any)[name] = value;
         }
         return true;
@@ -358,7 +411,7 @@ export default class Entity<T extends EntityData = EntityData>
         if (name in entity) {
           return delete (entity as any)[name];
         } else if (name in entity.$data) {
-          this.$referenceWake();
+          this.$check();
           return delete entity.$data[name];
         }
         return true;
@@ -371,7 +424,7 @@ export default class Entity<T extends EntityData = EntityData>
       defineProperty: (
         entity: Entity,
         name: string,
-        descriptor: PropertyDescriptor
+        descriptor: PropertyDescriptor,
       ) => {
         if (
           typeof name !== 'string' ||
@@ -379,11 +432,11 @@ export default class Entity<T extends EntityData = EntityData>
           name.substring(0, 1) === '$'
         ) {
           if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-            this.$referenceWake();
+            this.$check();
           }
           Object.defineProperty(entity, name, descriptor);
         } else {
-          this.$referenceWake();
+          this.$check();
           Object.defineProperty(entity.$data, name, descriptor);
         }
         return true;
@@ -396,48 +449,147 @@ export default class Entity<T extends EntityData = EntityData>
           name.substring(0, 1) === '$'
         ) {
           if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-            this.$referenceWake();
+            this.$check();
           }
           return Object.getOwnPropertyDescriptor(entity, name);
         } else {
-          this.$referenceWake();
+          this.$check();
           return Object.getOwnPropertyDescriptor(entity.$data, name);
         }
       },
 
       ownKeys: (entity: Entity) => {
-        this.$referenceWake();
+        this.$check();
         return Object.getOwnPropertyNames(entity).concat(
-          Object.getOwnPropertyNames(entity.$data)
+          Object.getOwnPropertyNames(entity.$data),
         );
       },
     }) as Entity<T>;
   }
 
-  public static async factory(guid?: string) {
+  /**
+   * 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.
+   */
+  public static async factory<E extends Entity>(
+    this: {
+      new (): E;
+    },
+    guid?: string,
+  ): Promise<E & EntityDataType<E>> {
     const entity = new this();
     if (guid != null) {
-      const entity = await this.nymph.getEntity(
+      const entity = await (
+        this as unknown as EntityConstructor
+      ).nymph.getEntity(
         {
-          class: this as any as EntityConstructor,
+          class: this as unknown as EntityConstructor,
         },
-        { type: '&', guid }
+        { type: '&', guid },
       );
       if (entity != null) {
-        return entity;
+        return entity as E & EntityDataType<E>;
       }
     }
-    return entity;
+    return entity as E & EntityDataType<E>;
   }
 
-  public static factorySync(guid?: string) {
-    return new this(guid);
+  /**
+   * Create a new entity instance.
+   */
+  public static factorySync<E extends Entity>(this: {
+    new (): E;
+  }): E & EntityDataType<E> {
+    return new this() as E & EntityDataType<E>;
   }
 
-  public static factoryReference(reference: EntityReference) {
+  /**
+   * 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.
+   */
+  public static factoryReference<E extends Entity>(
+    this: {
+      new (): E;
+    },
+    reference: EntityReference,
+  ): E & EntityDataType<E> {
     const entity = new this();
     entity.$referenceSleep(reference);
-    return entity;
+    return entity as E & EntityDataType<E>;
+  }
+
+  /**
+   * 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.
+   */
+  public static async getUniques({
+    guid,
+    cdate,
+    mdate,
+    tags,
+    data,
+    sdata,
+  }: {
+    guid?: string;
+    cdate?: number;
+    mdate?: number;
+    tags: string[];
+    data: EntityData;
+    sdata?: SerializedEntityData;
+  }) {
+    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.
+   */
+  public static getFTSText(_name: string, value: any) {
+    if (typeof value === 'string') {
+      return value;
+    }
+    return null;
   }
 
   public toJSON() {
@@ -445,24 +597,65 @@ export default class Entity<T extends EntityData = EntityData>
       return this.$sleepingReference;
     }
     const obj: EntityJson = {
-      class: (this.constructor as any).class as string,
+      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] = entitiesToReferences(data[key]);
+        obj.data[key] = entityConstructorsToClassNames(
+          entitiesToReferences(this.$data[key], true),
+        );
       }
     }
     return obj;
   }
 
+  public $setNymph(nymph: Nymph) {
+    this.$nymph = nymph;
+    if (!this.$asleep()) {
+      const recurseData = (data: any) => {
+        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);
+    }
+  }
+
+  public $getGuaranteedGUID() {
+    if (this.guid !== null) {
+      return this.guid;
+    }
+    if (this.$guaranteedGUID == null) {
+      this.$guaranteedGUID = guid();
+    }
+    return this.$guaranteedGUID;
+  }
+
   public $addTag(...tags: string[]) {
-    this.$referenceWake();
+    this.$check();
 
     if (tags.length < 1) {
       return;
@@ -471,7 +664,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $arraySearch(array: any[], strict = false) {
-    this.$referenceWake();
+    this.$check();
 
     if (!Array.isArray(array)) {
       return -1;
@@ -486,23 +679,25 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $clearCache() {
-    this.$referenceWake();
+    this.$check();
 
-    this.$putData(this.$getData(), this.$getSData());
+    this.$putData(this.$getData(false), this.$getSData());
   }
 
   public $getClientEnabledMethods() {
     return this.$clientEnabledMethods;
   }
 
-  public async $delete(): Promise<boolean> {
-    this.$referenceWake();
+  public async $delete(): Promise<void> {
+    await this.$wake();
 
-    return await this.$nymph.deleteEntity(this);
+    if (!(await this.$nymph.deleteEntity(this))) {
+      throw new MethodFailedError('Failed to delete entity.');
+    }
   }
 
   public $equals(object: any) {
-    this.$referenceWake();
+    this.$check();
 
     if (!(object instanceof Entity)) {
       return false;
@@ -523,13 +718,17 @@ export default class Entity<T extends EntityData = EntityData>
     if (!isEqual(obTags, myTags)) {
       return false;
     }
-    const obData = object.$getData(true);
-    const myData = this.$getData(true);
+    const obData = entityConstructorsToClassNames(
+      entitiesToReferences(object.$getData(true), true),
+    );
+    const myData = entityConstructorsToClassNames(
+      entitiesToReferences(this.$getData(true), true),
+    );
     return isEqual(obData, myData);
   }
 
   public $getData(includeSData = false) {
-    this.$referenceWake();
+    this.$check();
 
     if (includeSData) {
       // Access all the serialized properties to initialize them.
@@ -537,34 +736,82 @@ export default class Entity<T extends EntityData = EntityData>
         const _unused: any = (this as any)[key];
       }
     }
-    return entitiesToReferences({ ...this.$dataStore });
+    return { ...this.$dataStore };
   }
 
   public $getSData() {
-    this.$referenceWake();
+    this.$check();
 
     return this.$sdata;
   }
 
-  public $getOriginalAcValues() {
-    this.$referenceWake();
+  public async $getUniques(): Promise<string[]> {
+    return [];
+  }
+
+  public $getOriginalAcValues(): ACProperties {
+    this.$check();
 
-    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,
+    return this.$originalAcValues ?? this.$getCurrentAcValues();
+  }
+
+  public $getCurrentAcValues(): ACProperties {
+    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(),
+    };
+  }
+
+  public $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) as string | null;
+  }
+  public $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) as string | null;
+  }
+  public $getAcReadIds() {
+    return (this.$data.acRead?.map((entity: EntityInterface | string) =>
+      typeof entity === 'string' ? entity : entity.guid,
+    ) ?? null) as (string | null)[] | null;
+  }
+  public $getAcWriteIds() {
+    return (this.$data.acWrite?.map((entity: EntityInterface | string) =>
+      typeof entity === 'string' ? entity : entity.guid,
+    ) ?? null) as (string | null)[] | null;
+  }
+  public $getAcFullIds() {
+    return (this.$data.acFull?.map((entity: EntityInterface | string) =>
+      typeof entity === 'string' ? entity : entity.guid,
+    ) ?? null) as (string | null)[] | null;
   }
 
   public $getValidatable() {
-    this.$referenceWake();
+    this.$check();
 
     // Access all the serialized properties to initialize them.
     for (const key in this.$sdata) {
@@ -575,18 +822,18 @@ export default class Entity<T extends EntityData = EntityData>
       cdate: this.cdate,
       mdate: this.mdate,
       tags: this.tags,
-      ...referencesToEntities(this.$dataStore, this.$nymph, this.$skipAc),
+      ...this.$dataStore,
     };
   }
 
   public $getTags() {
-    this.$referenceWake();
+    this.$check();
 
     return this.tags;
   }
 
   public $hasTag(...tags: string[]) {
-    this.$referenceWake();
+    this.$check();
 
     if (!tags.length) {
       return false;
@@ -608,11 +855,15 @@ export default class Entity<T extends EntityData = EntityData>
       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 {
@@ -621,19 +872,22 @@ export default class Entity<T extends EntityData = EntityData>
       if (!isEqual(obTags, myTags)) {
         return false;
       }
-      const obData = object.$getData(true);
-      const myData = this.$getData(true);
+      const obData = entityConstructorsToClassNames(
+        entitiesToReferences(object.$getData(true), true),
+      );
+      const myData = entityConstructorsToClassNames(
+        entitiesToReferences(this.$getData(true), true),
+      );
       return isEqual(obData, myData);
     }
   }
 
   public $jsonAcceptData(input: EntityJson, allowConflict = false) {
-    // TODO: Do this without causing everything to become unserialized.
-    this.$referenceWake();
+    this.$check();
 
     if (this.guid != input.guid) {
       throw new EntityConflictError(
-        'Tried to accept JSON input for the wrong entity.'
+        'Tried to accept JSON input for the wrong entity.',
       );
     }
 
@@ -658,7 +912,7 @@ export default class Entity<T extends EntityData = EntityData>
     this.$addTag(...protectedTags, ...tags);
 
     // Accept the data.
-    const data = input.data;
+    const data = { ...input.data };
     const privateData: EntityData = {};
     for (const name of this.$privateData) {
       if (name in this.$data) {
@@ -671,12 +925,27 @@ export default class Entity<T extends EntityData = EntityData>
 
     const protectedData: EntityData = {};
     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 as EntityConstructor).class !== 'User' &&
+          (this.constructor as EntityConstructor).class !== 'Group') ||
+        !(this.$nymph.tilmeld as any).currentUser ||
+        (!(this.$nymph.tilmeld as any).currentUser.abilities?.includes(
+          'tilmeld/admin',
+        ) &&
+          !(this.$nymph.tilmeld as any).currentUser.abilities?.includes(
+            'system/admin',
+          ))
+      ) {
+        protectedProps.push('user');
+        protectedProps.push('group');
+      }
     }
     for (const name of protectedProps) {
       if (name in this.$data) {
@@ -709,11 +978,11 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $jsonAcceptPatch(patch: EntityPatch, allowConflict = false) {
-    this.$referenceWake();
+    this.$check();
 
     if (this.guid != patch.guid) {
       throw new EntityConflictError(
-        'Tried to accept JSON patch for the wrong entity.'
+        'Tried to accept JSON patch for the wrong entity.',
       );
     }
 
@@ -725,27 +994,47 @@ export default class Entity<T extends EntityData = EntityData>
     }
     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 as EntityConstructor).class !== 'User' &&
+          (this.constructor as EntityConstructor).class !== 'Group') ||
+        !(this.$nymph.tilmeld as any).currentUser ||
+        (!(this.$nymph.tilmeld as any).currentUser.abilities?.includes(
+          'tilmeld/admin',
+        ) &&
+          !(this.$nymph.tilmeld as any).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 as any)[name] = referencesToEntities(
-        patch.set[name],
-        this.$nymph,
-        this.$skipAc
-      );
+      (this.$data as any)[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;
@@ -776,27 +1065,23 @@ export default class Entity<T extends EntityData = EntityData>
     }
   }
 
-  public $putData(data: EntityData, sdata?: SerializedEntityData) {
-    this.$referenceWake();
+  public $putData(
+    data: EntityData,
+    sdata?: SerializedEntityData,
+    _source?: 'server',
+  ) {
+    this.$check();
 
-    const mySdata = sdata ?? this.$getSData();
-    for (const name in data) {
-      delete mySdata[name];
-    }
     for (const name in this.$dataStore) {
       delete this.$dataStore[name];
     }
     for (const name in data) {
-      (this.$dataStore as any)[name] = referencesToEntities(
-        data[name],
-        this.$nymph,
-        this.$skipAc
-      );
+      (this.$dataStore as any)[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();
     }
   }
 
@@ -813,14 +1098,14 @@ export default class Entity<T extends EntityData = EntityData>
     ) {
       throw new InvalidParametersError(
         'referenceSleep expects parameter 1 to be a valid Nymph entity ' +
-          'reference.'
+          'reference.',
       );
     }
     const thisClass: string = (this.constructor as any).class;
     if (reference[2] !== thisClass) {
       throw new InvalidParametersError(
         'referenceSleep can only be called with an entity reference of the ' +
-          `same class. Given class: ${reference[2]}; this class: ${thisClass}.`
+          `same class. Given class: ${reference[2]}; this class: ${thisClass}.`,
       );
     }
     this.$isASleepingReference = true;
@@ -828,38 +1113,137 @@ export default class Entity<T extends EntityData = EntityData>
     this.$sleepingReference = reference;
   }
 
+  /**
+   * Check if this is a sleeping reference and throw an error if so.
+   */
+  protected $check() {
+    if (this.$isASleepingReference || this.$sleepingReference != null) {
+      throw new EntityIsSleepingReferenceError(
+        'This entity is in a sleeping reference state. You must use .$wake() to wake it.',
+      );
+    }
+  }
+
+  /**
+   * Check if this is a sleeping reference.
+   */
+  public $asleep() {
+    return this.$isASleepingReference || this.$sleepingReference != null;
+  }
+
   /**
    * Wake from a sleeping reference.
-   *
-   * @returns True on success, false on failure.
    */
-  protected $referenceWake() {
+  public $wake() {
     if (!this.$isASleepingReference || this.$sleepingReference == null) {
-      return true;
+      this.$wakePromise = null;
+      return Promise.resolve(this);
     }
-    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;
+    if (this.$sleepingReference?.[1] == null) {
+      throw new InvalidStateError(
+        'Tried to wake a sleeping reference with no GUID.',
+      );
     }
-    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.$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;
+        })
+        .finally(() => {
+          this.$wakePromise = null;
+        });
+    }
+    return this.$wakePromise;
+  }
+
+  public $wakeAll(level?: number) {
+    return new Promise((resolve, reject) => {
+      // Run this once this entity is wake.
+      const wakeProps = () => {
+        let newLevel: number | undefined;
+        // 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);
+          return;
+        }
+        const promises: Promise<any>[] = [];
+        // Go through data looking for entities to wake.
+        const walkData = (data: any) => {
+          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),
+            (errObj) => reject(errObj),
+          );
+        } else {
+          resolve(this);
+        }
+      };
+
+      if (this.$isASleepingReference) {
+        this.$wake().then(wakeProps, (errObj) => reject(errObj));
+      } else {
+        wakeProps();
+      }
+    }) as Promise<Entity<T>>;
   }
 
   public async $refresh() {
-    this.$referenceWake();
+    await this.$wake();
 
     if (this.guid == null) {
       return false;
@@ -870,40 +1254,42 @@ export default class Entity<T extends EntityData = EntityData>
         skipCache: true,
         skipAc: this.$skipAc,
       },
-      { type: '&', guid: this.guid }
+      { 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;
   }
 
   public $removeTag(...tags: string[]) {
-    this.$referenceWake();
+    this.$check();
 
     this.tags = difference(this.tags, tags);
   }
 
-  public async $save(): Promise<boolean> {
-    this.$referenceWake();
+  public async $save(): Promise<void> {
+    await this.$wake();
 
-    return await this.$nymph.saveEntity(this);
+    if (!(await this.$nymph.saveEntity(this))) {
+      throw new MethodFailedError('Failed to save entity.');
+    }
   }
 
-  public $toReference() {
+  public $toReference(existingOnly?: boolean) {
     if (this.$isASleepingReference && this.$sleepingReference != null) {
       return this.$sleepingReference;
     }
-    if (this.guid == null) {
+    if (existingOnly && this.guid == null) {
       return this;
     }
     return [
       'nymph_entity_reference',
-      this.guid,
+      this.$getGuaranteedGUID(),
       (this.constructor as any).class as string,
     ] as EntityReference;
   }