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

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,15 +88,14 @@ 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) => {
@@ -129,7 +132,7 @@ 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}`
+            `Tried to delete data on a sleeping reference: ${name}`,
           );
           return false;
         }
@@ -143,11 +146,11 @@ 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}`
+            `Tried to define data on a sleeping reference: ${name}`,
           );
           return false;
         }
@@ -161,7 +164,7 @@ 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}`
+            `Tried to get property descriptor on a sleeping reference: ${name}`,
           );
           return undefined;
         }
@@ -179,17 +182,6 @@ export default class Entity<T extends EntityData = EntityData>
     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 (
@@ -245,7 +237,7 @@ export default class Entity<T extends EntityData = EntityData>
       defineProperty(
         entity: Entity,
         name: string,
-        descriptor: PropertyDescriptor
+        descriptor: PropertyDescriptor,
       ) {
         if (
           typeof name !== 'string' ||
@@ -273,59 +265,132 @@ export default class Entity<T extends EntityData = EntityData>
 
       ownKeys(entity: Entity) {
         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 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,7 +398,9 @@ 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;
   }
@@ -355,11 +422,17 @@ 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);
 
@@ -369,9 +442,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $addTag(...tags: string[]) {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     if (tags.length < 1) {
       return;
@@ -380,9 +451,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 +465,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 +502,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 +525,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 +538,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 +551,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 +581,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.$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;
   }
 
-  public $ready() {
+  /**
+   * Wake from a sleeping reference.
+   */
+  public $wake() {
     if (!this.$isASleepingReference) {
-      this.$readyPromise = null;
+      this.$wakePromise = null;
       return Promise.resolve(this);
     }
     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,17 +636,17 @@ 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) {
@@ -568,26 +656,39 @@ export default class Entity<T extends EntityData = EntityData>
           resolve(this);
           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)
+            (errObj) => reject(errObj),
           );
         } else {
           resolve(this);
@@ -595,9 +696,9 @@ export default class Entity<T extends EntityData = EntityData>
       };
 
       if (this.$isASleepingReference) {
-        this.$ready().then(readyProps, (errObj) => reject(errObj));
+        this.$wake().then(wakeProps, (errObj) => reject(errObj));
       } else {
-        readyProps();
+        wakeProps();
       }
     }) as Promise<Entity<T>>;
   }
@@ -610,7 +711,7 @@ export default class Entity<T extends EntityData = EntityData>
 
   public async $refresh() {
     if (this.$isASleepingReference) {
-      await this.$ready();
+      await this.$wake();
       return true;
     }
 
@@ -624,37 +725,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 +762,7 @@ export default class Entity<T extends EntityData = EntityData>
       this,
       method,
       paramArray,
-      stateless
+      stateless,
     );
     if (!stateless && data.entity) {
       this.$init(data.entity);