@nymphjs/nymph 1.0.0-beta.8 → 1.0.0-beta.80

package/src/Entity.ts

@@ -1,7 +1,8 @@
 import { difference, intersection, isEqual } from 'lodash';
 
 import type Nymph from './Nymph';
-import {
+import type { Options } from './Nymph.types';
+import type {
   ACProperties,
   EntityConstructor,
   EntityData,
@@ -11,13 +12,25 @@ import {
   EntityReference,
   SerializedEntityData,
 } from './Entity.types';
-import { EntityConflictError, InvalidParametersError } from './errors';
+import {
+  EntityConflictError,
+  EntityIsSleepingReferenceError,
+  InvalidParametersError,
+  InvalidStateError,
+} from './errors';
 import {
   entitiesToReferences,
   referencesToEntities,
   uniqueStrings,
 } from './utils';
 
+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;
+
 /**
  * Database abstraction object.
  *
@@ -45,9 +58,9 @@ import {
  *
  * Some notes about $equals() and $is(), the replacements for "==":
  *
- * The == operator will likely not give you the result you want, since any yet
- * to be unserialized data causes == to return false when you probably want it
- * to return true.
+ * 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
@@ -56,8 +69,7 @@ import {
  *
  * - They must be entities.
  * - They must have equal GUIDs, or both must have no GUID.
- * - They must be instances of the same class.
- * - Their data must be equal.
+ * - 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
@@ -66,7 +78,7 @@ import {
  *
  * - They must be entities.
  * - They must have equal GUIDs, or both must have no GUID.
- * - If they have no GUIDs, their data must be equal.
+ * - If they have no GUIDs, their data and tags must be equal.
  *
  * Some notes about saving entities in other entity's properties:
  *
@@ -137,6 +149,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
@@ -146,6 +162,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
@@ -157,8 +185,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[] = [];
   /**
@@ -199,26 +239,33 @@ export default class Entity<T extends EntityData = EntityData>
   private $originalAcValues: ACProperties | 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]),
             this.$nymph,
-            this.$skipAc
+            this.$skipAc,
           );
           delete this.$sdata[name];
         }
@@ -229,7 +276,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];
@@ -239,7 +286,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];
@@ -253,9 +300,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];
@@ -265,13 +312,13 @@ 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]),
             this.$nymph,
-            this.$skipAc
+            this.$skipAc,
           );
           delete this.$sdata[name];
         }
@@ -279,10 +326,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),
         );
       },
     };
@@ -291,20 +338,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 (
@@ -315,7 +348,7 @@ export default class Entity<T extends EntityData = EntityData>
           return name in entity;
         }
 
-        this.$referenceWake();
+        this.$check();
         return name in entity.$data;
       },
 
@@ -326,12 +359,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];
         }
@@ -345,11 +378,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;
@@ -359,7 +392,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;
@@ -372,7 +405,7 @@ export default class Entity<T extends EntityData = EntityData>
       defineProperty: (
         entity: Entity,
         name: string,
-        descriptor: PropertyDescriptor
+        descriptor: PropertyDescriptor,
       ) => {
         if (
           typeof name !== 'string' ||
@@ -380,11 +413,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;
@@ -397,48 +430,126 @@ 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();
   }
 
   public toJSON() {
@@ -463,7 +574,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $addTag(...tags: string[]) {
-    this.$referenceWake();
+    this.$check();
 
     if (tags.length < 1) {
       return;
@@ -472,7 +583,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;
@@ -487,7 +598,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $clearCache() {
-    this.$referenceWake();
+    this.$check();
 
     this.$putData(this.$getData(), this.$getSData());
   }
@@ -497,13 +608,13 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public async $delete(): Promise<boolean> {
-    this.$referenceWake();
+    this.$check();
 
     return await this.$nymph.deleteEntity(this);
   }
 
   public $equals(object: any) {
-    this.$referenceWake();
+    this.$check();
 
     if (!(object instanceof Entity)) {
       return false;
@@ -513,22 +624,24 @@ export default class Entity<T extends EntityData = EntityData>
         return false;
       }
     }
-    if (object.constructor !== this.constructor) {
-      return false;
-    }
     if (object.cdate !== this.cdate) {
       return false;
     }
     if (object.mdate !== this.mdate) {
       return false;
     }
+    const obTags = [...object.tags].sort();
+    const myTags = [...this.tags].sort();
+    if (!isEqual(obTags, myTags)) {
+      return false;
+    }
     const obData = object.$getData(true);
     const myData = this.$getData(true);
     return isEqual(obData, myData);
   }
 
   public $getData(includeSData = false) {
-    this.$referenceWake();
+    this.$check();
 
     if (includeSData) {
       // Access all the serialized properties to initialize them.
@@ -540,30 +653,75 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   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 ?? 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(),
+    };
+  }
 
-    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,
+  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) => entity.guid) ??
+      null) as (string | null)[] | null;
+  }
+  public $getAcWriteIds() {
+    return (this.$data.acWrite?.map((entity: EntityInterface) => entity.guid) ??
+      null) as (string | null)[] | null;
+  }
+  public $getAcFullIds() {
+    return (this.$data.acFull?.map((entity: EntityInterface) => 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) {
@@ -579,13 +737,13 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $getTags() {
-    this.$referenceWake();
+    this.$check();
 
     return this.tags;
   }
 
   public $hasTag(...tags: string[]) {
-    this.$referenceWake();
+    this.$check();
 
     if (!tags.length) {
       return false;
@@ -611,10 +769,15 @@ export default class Entity<T extends EntityData = EntityData>
       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 (!isEqual(obTags, myTags)) {
+        return false;
+      }
       const obData = object.$getData(true);
       const myData = this.$getData(true);
       return isEqual(obData, myData);
@@ -622,12 +785,11 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   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.',
       );
     }
 
@@ -665,12 +827,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) {
@@ -703,11 +880,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.',
       );
     }
 
@@ -719,11 +896,35 @@ 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;
@@ -731,7 +932,7 @@ export default class Entity<T extends EntityData = EntityData>
       (this.$data as any)[name] = referencesToEntities(
         patch.set[name],
         this.$nymph,
-        this.$skipAc
+        this.$skipAc,
       );
     }
 
@@ -739,7 +940,7 @@ export default class Entity<T extends EntityData = EntityData>
       if (
         (this.$allowlistData != null &&
           this.$allowlistData.indexOf(name) === -1) ||
-        this.$protectedData.indexOf(name) !== -1 ||
+        protectedProps.indexOf(name) !== -1 ||
         this.$privateData.indexOf(name) !== -1
       ) {
         continue;
@@ -771,7 +972,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $putData(data: EntityData, sdata?: SerializedEntityData) {
-    this.$referenceWake();
+    this.$check();
 
     const mySdata = sdata ?? this.$getSData();
     for (const name in data) {
@@ -784,13 +985,13 @@ export default class Entity<T extends EntityData = EntityData>
       (this.$dataStore as any)[name] = referencesToEntities(
         data[name],
         this.$nymph,
-        this.$skipAc
+        this.$skipAc,
       );
     }
     this.$sdata = mySdata;
     // Set original AC values if not set..
     if (this.$originalAcValues == null) {
-      this.$originalAcValues = this.$getOriginalAcValues();
+      this.$originalAcValues = this.$getCurrentAcValues();
     }
   }
 
@@ -807,14 +1008,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;
@@ -822,49 +1023,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(), entity.$getSData());
+
+          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;
+        // 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 = [];
+        // Go through data looking for entities to wake.
+        for (let [key, value] of Object.entries(this.$data)) {
+          if (value instanceof Entity && value.$isASleepingReference) {
+            promises.push(value.$wakeAll(newLevel));
+          } else if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+              if (
+                value[i] instanceof Entity &&
+                value[i].$isASleepingReference
+              ) {
+                promises.push(value[i].$wakeAll(newLevel));
+              }
+            }
+          }
+        }
+        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;
     }
     const refresh = await this.$nymph.getEntity(
       {
-        class: this.constructor as EntityConstructor,
+        class: this.$nymph.getEntityClass(
+          this.constructor as EntityConstructor,
+        ),
         skipCache: true,
         skipAc: this.$skipAc,
       },
-      { type: '&', guid: this.guid }
+      { type: '&', guid: this.guid },
     );
     if (refresh == null) {
       return 0;
@@ -877,13 +1166,13 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $removeTag(...tags: string[]) {
-    this.$referenceWake();
+    this.$check();
 
     this.tags = difference(this.tags, tags);
   }
 
   public async $save(): Promise<boolean> {
-    this.$referenceWake();
+    await this.$wake();
 
     return await this.$nymph.saveEntity(this);
   }