@nymphjs/client 1.0.0-beta.11 → 1.0.0-beta.110

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,23 @@ import {
   EntityJson,
   EntityPatch,
   EntityReference,
-} from './Entity.types';
+} from './Entity.types.js';
 import {
   uniqueStrings,
   entitiesToReferences,
   referencesToEntities,
   sortObj,
-} from './utils';
+} 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 +86,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 +130,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 +144,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 +162,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 +180,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 +235,7 @@ export default class Entity<T extends EntityData = EntityData>
       defineProperty(
         entity: Entity,
         name: string,
-        descriptor: PropertyDescriptor
+        descriptor: PropertyDescriptor,
       ) {
         if (
           typeof name !== 'string' ||
@@ -273,57 +263,130 @@ 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,
       guid: this.guid,
@@ -359,7 +422,7 @@ export default class Entity<T extends EntityData = EntityData>
       })
       .reduce(
         (obj, { key, value }) => Object.assign(obj, { [key]: value }),
-        {}
+        {},
       ) as T;
     this.$data = new Proxy(this.$dataStore, this.$dataHandler);
 
@@ -369,9 +432,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 +441,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;
@@ -397,9 +456,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public async $delete(): Promise<boolean> {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     const guid = this.guid;
 
@@ -407,9 +464,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $equals(object: any) {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     if (!(object instanceof Entity)) {
       return false;
@@ -435,12 +490,10 @@ 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 = {
@@ -448,10 +501,10 @@ export default class Entity<T extends EntityData = EntityData>
       mdate: this.mdate,
       class: (this.constructor as EntityConstructor).class,
       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: {},
@@ -471,9 +524,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 +537,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,9 +567,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public async $patch() {
-    if (this.$isASleepingReference) {
-      throw new EntityIsSleepingReferenceError(sleepErr);
-    }
+    this.$check();
 
     const mdate = this.mdate;
 
@@ -524,21 +575,42 @@ export default class Entity<T extends EntityData = EntityData>
     return mdate !== this.mdate;
   }
 
-  public $ready() {
+  /**
+   * 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.
+   */
+  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,16 +620,16 @@ 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 = () => {
+      // Run this once this entity is awake.
+      const wakeProps = () => {
         let newLevel;
         // If level is undefined, keep going forever, otherwise, stop once we've
         // gone deep enough.
@@ -569,17 +641,17 @@ export default class Entity<T extends EntityData = EntityData>
           return;
         }
         const promises = [];
-        // Go through data looking for entities to ready.
+        // 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.$readyAll(newLevel));
+            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].$readyAll(newLevel));
+                promises.push(value[i].$wakeAll(newLevel));
               }
             }
           }
@@ -587,7 +659,7 @@ export default class Entity<T extends EntityData = EntityData>
         if (promises.length) {
           Promise.all(promises).then(
             () => resolve(this),
-            (errObj) => reject(errObj)
+            (errObj) => reject(errObj),
           );
         } else {
           resolve(this);
@@ -595,9 +667,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 +682,7 @@ export default class Entity<T extends EntityData = EntityData>
 
   public async $refresh() {
     if (this.$isASleepingReference) {
-      await this.$ready();
+      await this.$wake();
       return true;
     }
 
@@ -624,24 +696,20 @@ export default class Entity<T extends EntityData = EntityData>
       {
         type: '&',
         guid: this.guid,
-      }
+      },
     );
     this.$init(data);
     return this.guid == null ? 0 : 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;
@@ -650,11 +718,9 @@ export default class Entity<T extends EntityData = EntityData>
   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 +728,7 @@ export default class Entity<T extends EntityData = EntityData>
       this,
       method,
       paramArray,
-      stateless
+      stateless,
     );
     if (!stateless && data.entity) {
       this.$init(data.entity);

package/src/Entity.types.ts

@@ -1,4 +1,5 @@
-import type Nymph from './Nymph';
+import type Nymph from './Nymph.js';
+import type Entity from './Entity.js';
 
 export type ServerCallResponse = {
   return: any;
@@ -155,6 +156,24 @@ export interface EntityInterface extends DataObjectInterface {
    * @returns True or false.
    */
   $hasTag(...tags: string[]): boolean;
+  /**
+   * Check whether a property is dirty.
+   *
+   * To be a dirty property, it must have been set or deleted since the entity
+   * was initialized. A clean property existed on initialization and hasn't been
+   * set or deleted. An untracked property didn't exist on initialization and
+   * hasn't been set or deleted.
+   *
+   * Note that this doesn't necessarily mean the property has changed. It could
+   * have been set to the same value, or created and then deleted.
+   *
+   * Entities are initialized when they are pulled from the server or saved.
+   * This is done with the `$init` method.
+   *
+   * @param property The name of a property.
+   * @returns True if it's dirty, false if not, and null if it's not tracked.
+   */
+  $isDirty(property: string): boolean | null;
   /**
    * Initialize this entity from a JSON representation.
    *
@@ -166,14 +185,14 @@ export interface EntityInterface extends DataObjectInterface {
    *
    * @returns The entity.
    */
-  $ready(): Promise<EntityInterface>;
+  $wake(): Promise<EntityInterface>;
   /**
    * Ready this entity's data, and the data of entity's within this one's.
    *
-   * @param level The number of levels deep to ready. If undefined, it will keep going until there are no more entities. (Careful of infinite loops.)
+   * @param level The number of levels deep to wake. If undefined, it will keep going until there are no more entities. (Careful of infinite loops.)
    * @returns The entity.
    */
-  $readyAll(level?: number): Promise<EntityInterface>;
+  $wakeAll(level?: number): Promise<EntityInterface>;
   /**
    * Remove one or more tags.
    *
@@ -195,7 +214,7 @@ export interface EntityInterface extends DataObjectInterface {
   $serverCall(
     method: string,
     params: Iterable<any>,
-    stateless: boolean
+    stateless: boolean,
   ): Promise<any>;
   /**
    * Return a Nymph Entity Reference for this entity.
@@ -208,46 +227,9 @@ export interface EntityInterface extends DataObjectInterface {
   $toReference(): EntityReference | EntityInterface;
 }
 
-export type EntityConstructor = (new (...args: any[]) => EntityInterface) & {
-  /**
-   * The instance of Nymph to use for queries.
-   */
-  nymph: Nymph;
-  /**
-   * The lookup name for this entity.
-   *
-   * This is used for reference arrays (and sleeping references) and client
-   * requests.
-   */
-  class: string;
-  /**
-   * Create a new entity instance.
-   *
-   * @param guid An optional GUID to retrieve.
-   */
-  factory(guid?: string): Promise<EntityInterface>;
-  /**
-   * Create a new entity instance.
-   *
-   * @param guid An optional GUID to retrieve.
-   */
-  factorySync(guid?: string): EntityInterface;
-  /**
-   * Create a new sleeping reference instance.
-   *
-   * Sleeping references won't retrieve their data from the server until they
-   * are readied with `ready()` or a parent's `readyAll()`.
-   *
-   * @param reference The Nymph Entity Reference to use to wake.
-   * @returns The new instance.
-   */
-  factoryReference(reference: EntityReference): EntityInterface;
-  /**
-   * 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.
-   */
-  serverCallStatic(method: string, params: Iterable<any>): Promise<any>;
+export type EntityConstructor<
+  D extends EntityData = EntityData,
+  E extends Entity<D> = Entity<D>,
+> = (new (...args: any[]) => E) & {
+  [k in keyof typeof Entity]: (typeof Entity)[k];
 };

package/src/EntityWeakCache.ts

@@ -1,15 +1,18 @@
-import { EntityConstructor, EntityInterface } from './Entity.types';
+import { EntityConstructor, EntityInterface } from './Entity.types.js';
 
 export default class EntityWeakCache {
-  private references: WeakMap<EntityConstructor, { [k: string]: any }> =
-    new WeakMap();
+  private references: WeakMap<
+    EntityConstructor,
+    { [k: string]: WeakRef<EntityInterface> }
+  > = new WeakMap();
 
   get(EntityClass: EntityConstructor, guid: string): EntityInterface | null {
     const classMap = this.references.get(EntityClass);
     if (classMap && guid in classMap) {
       const weakRef = classMap[guid];
-      if (weakRef && weakRef.deref() != null) {
-        return weakRef.deref();
+      const deref = weakRef && weakRef.deref();
+      if (deref != null) {
+        return deref;
       } else {
         delete classMap[guid];
       }
@@ -22,7 +25,6 @@ export default class EntityWeakCache {
       return;
     }
 
-    // @ts-ignore TS doesn't know about WeakRef.
     const weakRef = new WeakRef(entity);
 
     const classMap = this.references.get(EntityClass) || {};