@nymphjs/nymph 1.0.0-beta.12 → 1.0.0-beta.121

package/src/Entity.ts

@@ -1,22 +1,39 @@
-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,
+} from './errors/index.js';
 import {
   entitiesToReferences,
   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 +104,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 +153,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 +166,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 +189,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 +241,39 @@ 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]),
             this.$nymph,
-            this.$skipAc
+            this.$skipAc,
           );
           delete this.$sdata[name];
         }
@@ -228,7 +284,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 +294,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 +308,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 +320,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];
         }
@@ -278,10 +334,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 +346,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 +356,7 @@ export default class Entity<T extends EntityData = EntityData>
           return name in entity;
         }
 
-        this.$referenceWake();
+        this.$check();
         return name in entity.$data;
       },
 
@@ -325,12 +367,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 +386,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 +400,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 +413,7 @@ export default class Entity<T extends EntityData = EntityData>
       defineProperty: (
         entity: Entity,
         name: string,
-        descriptor: PropertyDescriptor
+        descriptor: PropertyDescriptor,
       ) => {
         if (
           typeof name !== 'string' ||
@@ -379,11 +421,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 +438,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() {
@@ -452,17 +593,29 @@ export default class Entity<T extends EntityData = EntityData>
       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] = entitiesToReferences(this.$data[key], true);
       }
     }
     return obj;
   }
 
+  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 +624,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,9 +639,9 @@ 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, true), this.$getSData());
   }
 
   public $getClientEnabledMethods() {
@@ -496,13 +649,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;
@@ -523,13 +676,13 @@ 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 = object.$getData(true, true);
+    const myData = this.$getData(true, true);
     return isEqual(obData, myData);
   }
 
-  public $getData(includeSData = false) {
-    this.$referenceWake();
+  public $getData(includeSData = false, referenceOnlyExisting?: boolean) {
+    this.$check();
 
     if (includeSData) {
       // Access all the serialized properties to initialize them.
@@ -537,34 +690,82 @@ export default class Entity<T extends EntityData = EntityData>
         const _unused: any = (this as any)[key];
       }
     }
-    return entitiesToReferences({ ...this.$dataStore });
+    return entitiesToReferences({ ...this.$dataStore }, referenceOnlyExisting);
   }
 
   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 | 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) {
@@ -580,13 +781,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;
@@ -608,11 +809,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 +826,18 @@ 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 = object.$getData(true, true);
+      const myData = 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 +862,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 +875,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) {
@@ -689,7 +908,7 @@ export default class Entity<T extends EntityData = EntityData>
 
     let nonAllowlistData: EntityData = {};
     if (this.$allowlistData != null) {
-      nonAllowlistData = { ...this.$getData(true) };
+      nonAllowlistData = { ...this.$getData(true, true) };
       for (const name of this.$allowlistData) {
         delete nonAllowlistData[name];
       }
@@ -709,11 +928,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,11 +944,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;
@@ -737,7 +980,7 @@ export default class Entity<T extends EntityData = EntityData>
       (this.$data as any)[name] = referencesToEntities(
         patch.set[name],
         this.$nymph,
-        this.$skipAc
+        this.$skipAc,
       );
     }
 
@@ -745,7 +988,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;
@@ -776,8 +1019,12 @@ 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) {
@@ -790,13 +1037,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();
     }
   }
 
@@ -813,14 +1060,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,49 +1075,141 @@ 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, true),
+            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;
+        // 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;
@@ -878,32 +1217,32 @@ export default class Entity<T extends EntityData = EntityData>
     this.tags = refresh.tags;
     this.cdate = refresh.cdate;
     this.mdate = refresh.mdate;
-    this.$putData(refresh.$getData(), refresh.$getSData());
+    this.$putData(refresh.$getData(false, true), 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();
+    await this.$wake();
 
     return await this.$nymph.saveEntity(this);
   }
 
-  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;
   }