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

package/src/Entity.ts

@@ -1,6 +1,6 @@
-import { difference, isEqual } from 'lodash';
+import { difference, isEqual } from 'lodash-es';
 
-import type Nymph from './Nymph';
+import type Nymph from './Nymph.js';
 import {
   EntityConstructor,
   EntityData,
@@ -8,21 +8,25 @@ import {
   EntityJson,
   EntityPatch,
   EntityReference,
-} from './Entity.types';
+} from './Entity.types.js';
 import {
   uniqueStrings,
   entitiesToReferences,
   referencesToEntities,
   sortObj,
-} from './utils';
+  entityConstructorsToClassNames,
+  classNamesToEntityConstructors,
+} from './utils.js';
 
-const sleepErr =
-  'This entity is in a sleeping reference state. ' +
-  'You must use .$ready() to wake it.';
+export type EntityDataType<T> =
+  T extends Entity<infer DataType> ? DataType : never;
 
-export default class Entity<T extends EntityData = EntityData>
-  implements EntityInterface
-{
+export type EntityInstanceType<T extends EntityConstructor> =
+  T extends new () => infer E ? E & EntityDataType<E> : never;
+
+export default class Entity<
+  T extends EntityData = EntityData,
+> implements EntityInterface {
   /**
    * The instance of Nymph to use for queries.
    */
@@ -84,29 +88,26 @@ export default class Entity<T extends EntityData = EntityData>
    */
   protected $sleepingReference: EntityReference | null = null;
   /**
-   * A promise that resolved when the entity's data is ready.
+   * A promise that resolved when the entity's data is wake.
    */
-  protected $readyPromise: Promise<Entity<T>> | null = null;
+  protected $wakePromise: Promise<Entity<T>> | null = null;
 
   /**
-   * Load an entity.
-   * @param guid The ID of the entity to load, undefined for a new entity.
+   * Initialize an entity.
    */
-  public constructor(guid?: string) {
+  public constructor(..._rest: any[]) {
     this.$nymph = (this.constructor as EntityConstructor).nymph;
     this.$dataHandler = {
       has: (data: EntityData, name: string) => {
-        if (typeof name !== 'symbol' && this.$isASleepingReference) {
-          console.error(`Tried to check data on a sleeping reference: ${name}`);
-          return false;
+        if (typeof name !== 'symbol') {
+          this.$check();
         }
         return name in data;
       },
 
       get: (data: EntityData, name: string) => {
-        if (typeof name !== 'symbol' && this.$isASleepingReference) {
-          console.error(`Tried to get data on a sleeping reference: ${name}`);
-          return undefined;
+        if (typeof name !== 'symbol') {
+          this.$check();
         }
         if (data.hasOwnProperty(name)) {
           return data[name];
@@ -115,9 +116,8 @@ export default class Entity<T extends EntityData = EntityData>
       },
 
       set: (data: EntityData, name: string, value: any) => {
-        if (typeof name !== 'symbol' && this.$isASleepingReference) {
-          console.error(`Tried to set data on a sleeping reference: ${name}`);
-          return false;
+        if (typeof name !== 'symbol') {
+          this.$check();
         }
         if (typeof name !== 'symbol') {
           this.$dirty[name] = true;
@@ -127,11 +127,8 @@ export default class Entity<T extends EntityData = EntityData>
       },
 
       deleteProperty: (data: EntityData, name: string) => {
-        if (typeof name !== 'symbol' && this.$isASleepingReference) {
-          console.error(
-            `Tried to delete data on a sleeping reference: ${name}`
-          );
-          return false;
+        if (typeof name !== 'symbol') {
+          this.$check();
         }
         if (data.hasOwnProperty(name)) {
           this.$dirty[name] = true;
@@ -143,13 +140,10 @@ export default class Entity<T extends EntityData = EntityData>
       defineProperty: (
         data: EntityData,
         name: string,
-        descriptor: PropertyDescriptor
+        descriptor: PropertyDescriptor,
       ) => {
-        if (typeof name !== 'symbol' && this.$isASleepingReference) {
-          console.error(
-            `Tried to define data on a sleeping reference: ${name}`
-          );
-          return false;
+        if (typeof name !== 'symbol') {
+          this.$check();
         }
         if (typeof name !== 'symbol') {
           this.$dirty[name] = true;
@@ -159,173 +153,258 @@ export default class Entity<T extends EntityData = EntityData>
       },
 
       getOwnPropertyDescriptor: (data: EntityData, name: string) => {
-        if (typeof name !== 'symbol' && this.$isASleepingReference) {
-          console.error(
-            `Tried to get property descriptor on a sleeping reference: ${name}`
-          );
-          return undefined;
+        if (typeof name !== 'symbol') {
+          this.$check();
         }
         return Object.getOwnPropertyDescriptor(data, name);
       },
 
       ownKeys: (data: EntityData) => {
-        if (this.$isASleepingReference) {
-          console.error(`Tried to enumerate data on a sleeping reference.`);
-          return undefined;
-        }
+        this.$check();
         return Object.getOwnPropertyNames(data);
       },
     };
     this.$dataStore = {} as T;
     this.$data = new Proxy(this.$dataStore, this.$dataHandler);
 
-    if (guid != null) {
-      this.guid = guid;
-      this.$isASleepingReference = true;
-      this.$sleepingReference = [
-        'nymph_entity_reference',
-        this.guid,
-        (this.constructor as EntityConstructor).class,
-      ];
-      this.$ready();
-    }
-
-    return new Proxy(this, {
-      has(entity: Entity, name: string) {
-        if (
-          typeof name !== 'string' ||
-          name in entity ||
-          name.substring(0, 1) === '$'
-        ) {
-          return name in entity;
-        }
-        return name in entity.$data;
-      },
-
-      get(entity: Entity, name: string) {
-        if (
-          typeof name !== 'string' ||
-          name in entity ||
-          name.substring(0, 1) === '$'
-        ) {
-          return (entity as EntityInterface)[name];
-        }
-        if (name in entity.$data) {
-          return entity.$data[name];
-        }
-        return undefined;
-      },
-
-      set(entity: Entity, name: string, value: any) {
-        if (
-          typeof name !== 'string' ||
-          name in entity ||
-          name.substring(0, 1) === '$'
-        ) {
-          (entity as EntityInterface)[name] = value;
-        } else {
-          entity.$data[name] = value;
-        }
-        return true;
-      },
-
-      deleteProperty(entity: Entity, name: string) {
-        if (name in entity) {
-          return delete (entity as EntityInterface)[name];
-        } else if (name in entity.$data) {
-          return delete entity.$data[name];
-        }
-        return true;
-      },
+    return this.$proxy();
+  }
 
-      getPrototypeOf(entity: Entity) {
-        return entity.constructor.prototype;
-      },
+  private $existingProxy?: this & T;
+  protected $proxy() {
+    if (this.$existingProxy == null) {
+      this.$existingProxy = new Proxy(this, {
+        has: (entity: this, name: string) => {
+          if (
+            typeof name !== 'string' ||
+            name in entity ||
+            name.substring(0, 1) === '$'
+          ) {
+            return name in entity;
+          }
 
-      defineProperty(
-        entity: Entity,
-        name: string,
-        descriptor: PropertyDescriptor
-      ) {
-        if (
-          typeof name !== 'string' ||
-          name in entity ||
-          name.substring(0, 1) === '$'
-        ) {
-          Object.defineProperty(entity, name, descriptor);
-        } else {
-          Object.defineProperty(entity.$data, name, descriptor);
-        }
-        return true;
-      },
+          this.$check();
+          return name in entity.$data;
+        },
+
+        get: (entity: this, name: string) => {
+          if (
+            typeof name !== 'string' ||
+            name in entity ||
+            name.substring(0, 1) === '$'
+          ) {
+            if (name === 'tags' || name === 'cdate' || name === 'mdate') {
+              this.$check();
+            }
+            return (entity as any)[name];
+          }
 
-      getOwnPropertyDescriptor(entity: Entity, name: string) {
-        if (
-          typeof name !== 'string' ||
-          name in entity ||
-          name.substring(0, 1) === '$'
-        ) {
-          return Object.getOwnPropertyDescriptor(entity, name);
-        } else {
-          return Object.getOwnPropertyDescriptor(entity.$data, name);
-        }
-      },
+          this.$check();
+          if (name in entity.$data) {
+            return entity.$data[name];
+          }
+          return undefined;
+        },
+
+        set: (entity: this, name: string, value: any) => {
+          if (
+            typeof name !== 'string' ||
+            name in entity ||
+            name.substring(0, 1) === '$'
+          ) {
+            if (name === 'tags' || name === 'cdate' || name === 'mdate') {
+              this.$check();
+            }
+            (entity as any)[name] = value;
+          } else {
+            this.$check();
+            (entity.$data as any)[name] = value;
+          }
+          return true;
+        },
+
+        deleteProperty: (entity: this, name: string) => {
+          if (name in entity) {
+            return delete (entity as any)[name];
+          } else if (name in entity.$data) {
+            this.$check();
+            return delete entity.$data[name];
+          }
+          return true;
+        },
+
+        getPrototypeOf: (entity: this) => {
+          return entity.constructor.prototype;
+        },
+
+        defineProperty: (
+          entity: this,
+          name: string,
+          descriptor: PropertyDescriptor,
+        ) => {
+          if (
+            typeof name !== 'string' ||
+            name in entity ||
+            name.substring(0, 1) === '$'
+          ) {
+            if (name === 'tags' || name === 'cdate' || name === 'mdate') {
+              this.$check();
+            }
+            Object.defineProperty(entity, name, descriptor);
+          } else {
+            this.$check();
+            Object.defineProperty(entity.$data, name, descriptor);
+          }
+          return true;
+        },
+
+        getOwnPropertyDescriptor: (entity: this, name: string) => {
+          if (
+            typeof name !== 'string' ||
+            name in entity ||
+            name.substring(0, 1) === '$'
+          ) {
+            if (name === 'tags' || name === 'cdate' || name === 'mdate') {
+              this.$check();
+            }
+            return Object.getOwnPropertyDescriptor(entity, name);
+          } else {
+            this.$check();
+            return Object.getOwnPropertyDescriptor(entity.$data, name);
+          }
+        },
 
-      ownKeys(entity: Entity) {
-        return Object.getOwnPropertyNames(entity).concat(
-          Object.getOwnPropertyNames(entity.$data)
-        );
-      },
-    }) as Entity<T>;
+        ownKeys: (entity: this) => {
+          this.$check();
+          return Object.getOwnPropertyNames(entity).concat(
+            Object.getOwnPropertyNames(entity.$data),
+          );
+        },
+      }) as this & T;
+    }
+    return this.$existingProxy;
   }
 
-  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 cacheEntity = (
-      guid ? this.nymph.getEntityFromCache(this, guid) : null
+      guid
+        ? (this as unknown as EntityConstructor).nymph.getEntityFromCache(
+            this as unknown as EntityConstructor,
+            guid,
+          )
+        : null
     ) as Entity | null;
-    const entity = cacheEntity || new this(guid);
+    if (cacheEntity) {
+      return cacheEntity as E & EntityDataType<E>;
+    }
+    const entity = new this();
     if (guid != null) {
-      await entity.$ready();
+      entity.guid = guid;
+      entity.$isASleepingReference = true;
+      entity.$sleepingReference = [
+        'nymph_entity_reference',
+        guid,
+        (this as unknown as EntityConstructor).class,
+      ];
+      await entity.$wake();
     }
-    return entity;
+    return entity as E & EntityDataType<E>;
   }
 
-  public static factorySync(guid?: string) {
-    const cacheEntity = (
-      guid ? this.nymph.getEntityFromCache(this, guid) : null
-    ) as Entity | null;
-    return cacheEntity || 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 server 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 cacheEntity = (
-      reference[1] ? this.nymph.getEntityFromCache(this, reference[1]) : null
+      reference[1]
+        ? (this as unknown as EntityConstructor).nymph.getEntityFromCache(
+            this as unknown as EntityConstructor,
+            reference[1],
+          )
+        : null
     ) as Entity | null;
 
     const entity = cacheEntity || new this();
     if (!cacheEntity) {
       entity.$referenceSleep(reference);
     }
-    return entity;
+    return entity as E & EntityDataType<E>;
   }
 
+  /**
+   * Call a static method on the server version of this entity.
+   *
+   * @param method The name of the method.
+   * @param params The parameters to call the method with.
+   * @returns The value that the method on the server returned.
+   */
   public static async serverCallStatic(method: string, params: Iterable<any>) {
     const data = await this.nymph.serverCallStatic(
       this.class,
       method,
       // Turn the params into a real array, in case an arguments object was
       // passed.
-      Array.prototype.slice.call(params)
+      Array.prototype.slice.call(params),
     );
     return data.return;
   }
 
+  /**
+   * Call a static iterator method on the server version of this entity.
+   *
+   * @param method The name of the method.
+   * @param params The parameters to call the method with.
+   * @returns An iterator that iterates over values that the method on the server yields.
+   */
+  public static async serverCallStaticIterator(
+    method: string,
+    params: Iterable<any>,
+  ) {
+    return await this.nymph.serverCallStaticIterator(
+      this.class,
+      method,
+      // Turn the params into a real array, in case an arguments object was
+      // passed.
+      Array.prototype.slice.call(params),
+    );
+  }
+
   public toJSON() {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
     const obj: EntityJson = {
-      class: (this.constructor as any).class as string,
+      class: entityConstructorsToClassNames(this.constructor),
       guid: this.guid,
       cdate: this.cdate,
       mdate: this.mdate,
@@ -333,14 +412,16 @@ export default class Entity<T extends EntityData = EntityData>
       data: {},
     };
     for (let [key, value] of Object.entries(this.$dataStore)) {
-      obj.data[key] = entitiesToReferences(value);
+      obj.data[key] = entityConstructorsToClassNames(
+        entitiesToReferences(value),
+      );
     }
     return obj;
   }
 
   public $init(entityJson: EntityJson | null) {
     if (entityJson == null) {
-      return this;
+      return this.$proxy();
     }
 
     this.$isASleepingReference = false;
@@ -355,23 +436,27 @@ export default class Entity<T extends EntityData = EntityData>
     this.$dataStore = Object.entries(entityJson.data)
       .map(([key, value]) => {
         this.$dirty[key] = false;
-        return { key, value: referencesToEntities(value, this.$nymph) };
+        return {
+          key,
+          value: classNamesToEntityConstructors(
+            this.$nymph,
+            referencesToEntities(value, this.$nymph),
+          ),
+        };
       })
       .reduce(
         (obj, { key, value }) => Object.assign(obj, { [key]: value }),
-        {}
+        {},
       ) as T;
     this.$data = new Proxy(this.$dataStore, this.$dataHandler);
 
     this.$nymph.setEntityToCache(this.constructor as EntityConstructor, this);
 
-    return this as Entity<T>;
+    return this.$proxy();
   }
 
   public $addTag(...tags: string[]) {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     if (tags.length < 1) {
       return;
@@ -380,9 +465,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $arraySearch(array: any[], strict = false) {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     if (!Array.isArray(array)) {
       return -1;
@@ -396,20 +479,18 @@ export default class Entity<T extends EntityData = EntityData>
     return -1;
   }
 
-  public async $delete(): Promise<boolean> {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+  public async $delete(): Promise<void> {
+    this.$check();
 
     const guid = this.guid;
 
-    return (await this.$nymph.deleteEntity(this)) === guid;
+    if ((await this.$nymph.deleteEntity(this)) !== guid) {
+      throw new Error('Failed to delete entity.');
+    }
   }
 
   public $equals(object: any) {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     if (!(object instanceof Entity)) {
       return false;
@@ -435,23 +516,21 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $getPatch(): EntityPatch {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
     if (this.guid == null) {
       throw new InvalidStateError(
-        "You can't make a patch from an unsaved entity."
+        "You can't make a patch from an unsaved entity.",
       );
     }
     const patch: EntityPatch = {
       guid: this.guid,
       mdate: this.mdate,
-      class: (this.constructor as EntityConstructor).class,
+      class: entityConstructorsToClassNames(this.constructor),
       addTags: this.tags.filter(
-        (tag) => this.$originalTags.indexOf(tag) === -1
+        (tag) => this.$originalTags.indexOf(tag) === -1,
       ),
       removeTags: this.$originalTags.filter(
-        (tag) => this.tags.indexOf(tag) === -1
+        (tag) => this.tags.indexOf(tag) === -1,
       ),
       unset: [],
       set: {},
@@ -460,7 +539,9 @@ export default class Entity<T extends EntityData = EntityData>
     for (let [key, dirty] of Object.entries(this.$dirty)) {
       if (dirty) {
         if (key in this.$data) {
-          patch.set[key] = entitiesToReferences(this.$data[key]);
+          patch.set[key] = entityConstructorsToClassNames(
+            entitiesToReferences(this.$data[key]),
+          );
         } else {
           patch.unset.push(key);
         }
@@ -471,9 +552,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $hasTag(...tags: string[]) {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     if (!tags.length) {
       return false;
@@ -486,14 +565,16 @@ export default class Entity<T extends EntityData = EntityData>
     return true;
   }
 
+  public $isDirty(property: string) {
+    return property in this.$dirty ? this.$dirty[property] : null;
+  }
+
   public $inArray(array: any[], strict = false) {
     return this.$arraySearch(array, strict) !== -1;
   }
 
   public $is(object: any) {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     if (!(object instanceof Entity)) {
       return false;
@@ -514,31 +595,52 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public async $patch() {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     const mdate = this.mdate;
 
     await this.$nymph.patchEntity(this);
-    return mdate !== this.mdate;
+    if (mdate === this.mdate) {
+      throw new Error('Failed to patch entity.');
+    }
+  }
+
+  /**
+   * Check if this is a sleeping reference and throw an error if so.
+   */
+  protected $check() {
+    if (this.$asleep()) {
+      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;
   }
 
-  public $ready() {
-    if (!this.$isASleepingReference) {
-      this.$readyPromise = null;
-      return Promise.resolve(this);
+  /**
+   * Wake from a sleeping reference.
+   */
+  public $wake() {
+    if (!this.$asleep()) {
+      this.$wakePromise = null;
+      return Promise.resolve(this.$proxy());
     }
     if (this.$sleepingReference?.[1] == null) {
       throw new InvalidStateError(
-        'Tried to ready a sleeping reference with no GUID.'
+        'Tried to wake a sleeping reference with no GUID.',
       );
     }
-    if (!this.$readyPromise) {
-      this.$readyPromise = this.$nymph
+    if (!this.$wakePromise) {
+      this.$wakePromise = this.$nymph
         .getEntityData(
           { class: this.constructor as EntityConstructor },
-          { type: '&', guid: this.$sleepingReference[1] }
+          { type: '&', guid: this.$sleepingReference[1] },
         )
         .then((data) => {
           if (data == null) {
@@ -548,56 +650,69 @@ export default class Entity<T extends EntityData = EntityData>
           return this.$init(data);
         })
         .finally(() => {
-          this.$readyPromise = null;
+          this.$wakePromise = null;
         });
     }
-    return this.$readyPromise;
+    return this.$wakePromise;
   }
 
-  public $readyAll(level?: number) {
+  public $wakeAll(level?: number) {
     return new Promise((resolve, reject) => {
-      // Run this once this entity is ready.
-      const readyProps = () => {
-        let newLevel;
+      // Run this once this entity is awake.
+      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);
+          resolve(this.$proxy());
           return;
         }
-        const promises = [];
-        // Go through data looking for entities to ready.
-        for (let [key, value] of Object.entries(this.$data)) {
-          if (value instanceof Entity && value.$isASleepingReference) {
-            promises.push(value.$readyAll(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].$readyAll(newLevel));
-              }
+        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)
+            () => resolve(this.$proxy()),
+            (errObj) => reject(errObj),
           );
         } else {
-          resolve(this);
+          resolve(this.$proxy());
         }
       };
 
-      if (this.$isASleepingReference) {
-        this.$ready().then(readyProps, (errObj) => reject(errObj));
+      if (this.$asleep()) {
+        this.$wake().then(wakeProps, (errObj) => reject(errObj));
       } else {
-        readyProps();
+        wakeProps();
       }
     }) as Promise<Entity<T>>;
   }
@@ -609,8 +724,8 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public async $refresh() {
-    if (this.$isASleepingReference) {
-      await this.$ready();
+    if (this.$asleep()) {
+      await this.$wake();
       return true;
     }
 
@@ -624,37 +739,36 @@ export default class Entity<T extends EntityData = EntityData>
       {
         type: '&',
         guid: this.guid,
-      }
+      },
     );
+    if (data == null) {
+      throw new Error("The entity's data could not be refreshed.");
+    }
     this.$init(data);
-    return this.guid == null ? 0 : true;
+    return true;
   }
 
   public $removeTag(...tags: string[]) {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     this.tags = difference(this.tags, tags);
   }
 
   public async $save() {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     await this.$nymph.saveEntity(this);
-    return !!this.guid;
+    if (!this.guid) {
+      throw new Error('Failed to save entity.');
+    }
   }
 
   public async $serverCall(
     method: string,
     params: Iterable<any>,
-    stateless = false
+    stateless = false,
   ) {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
     // Turn the params into a real array, in case an arguments object was
     // passed.
     const paramArray = Array.prototype.slice.call(params);
@@ -662,7 +776,7 @@ export default class Entity<T extends EntityData = EntityData>
       this,
       method,
       paramArray,
-      stateless
+      stateless,
     );
     if (!stateless && data.entity) {
       this.$init(data.entity);
@@ -670,13 +784,13 @@ export default class Entity<T extends EntityData = EntityData>
     return data.return;
   }
 
-  public $toReference(): EntityReference | EntityInterface {
-    if (this.$isASleepingReference && this.$sleepingReference) {
+  public $toReference() {
+    if (this.$isASleepingReference && this.$sleepingReference != null) {
       return this.$sleepingReference;
     }
 
     if (this.guid == null) {
-      return this as EntityInterface;
+      return this.$proxy();
     }
     return [
       'nymph_entity_reference',