@nymphjs/nymph 1.0.0-beta.4 → 1.0.0-beta.41

package/src/Entity.ts

@@ -11,7 +11,12 @@ import {
   EntityReference,
   SerializedEntityData,
 } from './Entity.types';
-import { EntityConflictError, InvalidParametersError } from './errors';
+import {
+  EntityConflictError,
+  EntityIsSleepingReferenceError,
+  InvalidParametersError,
+  InvalidStateError,
+} from './errors';
 import {
   entitiesToReferences,
   referencesToEntities,
@@ -45,9 +50,9 @@ import {
  *
  * Some notes about $equals() and $is(), the replacements for "==":
  *
- * The == operator will likely not give you the result you want, since any yet
- * to be unserialized data causes == to return false when you probably want it
- * to return true.
+ * The == operator will likely not give you the result you want, since two
+ * instances of the same entity will fail that check, even though they represent
+ * the same data in the database.
  *
  * $equals() performs a more strict comparison of the entity to another. Use
  * $equals() instead of the == operator when you want to check both the entities
@@ -56,8 +61,7 @@ import {
  *
  * - They must be entities.
  * - They must have equal GUIDs, or both must have no GUID.
- * - They must be instances of the same class.
- * - Their data must be equal.
+ * - Their data and tags must be equal.
  *
  * $is() performs a less strict comparison of the entity to another. Use $is()
  * instead of the == operator when the entity's data may have been changed, but
@@ -66,7 +70,7 @@ import {
  *
  * - They must be entities.
  * - They must have equal GUIDs, or both must have no GUID.
- * - If they have no GUIDs, their data must be equal.
+ * - If they have no GUIDs, their data and tags must be equal.
  *
  * Some notes about saving entities in other entity's properties:
  *
@@ -137,6 +141,10 @@ export default class Entity<T extends EntityData = EntityData>
    * The reference to use to wake.
    */
   protected $sleepingReference: EntityReference | null = null;
+  /**
+   * A promise that resolved when the entity's data is wake.
+   */
+  protected $wakePromise: Promise<Entity<T>> | null = null;
   /**
    * Properties that will not be serialized into JSON with toJSON(). This
    * can be considered a denylist, because these properties will not be set
@@ -146,6 +154,18 @@ export default class Entity<T extends EntityData = EntityData>
    * also listed in searchRestrictedData.
    */
   protected $privateData: string[] = [];
+  /**
+   * Whether this entity should publish changes to PubSub servers.
+   */
+  public static pubSubEnabled = true;
+  /**
+   * Whether this entity should be accessible on the frontend through the REST
+   * server.
+   *
+   * If this is false, any request from the client that attempts to use this
+   * entity will fail.
+   */
+  public static restEnabled = true;
   /**
    * Properties that will not be searchable from the frontend. If the frontend
    * includes any of these properties in any of their clauses, they will be
@@ -157,8 +177,20 @@ export default class Entity<T extends EntityData = EntityData>
    * be visible on the frontend, unlike $privateData, but any changes to them
    * that come from the frontend will be ignored.
    *
-   * In addition to what's listed here, the 'user' and 'group' properties will
-   * be filtered for non-admins when Tilmeld is being used.
+   * In addition to what's listed here, all of the access control properties
+   * will be included when Tilmeld is being used. These are:
+   *
+   * - acUser
+   * - acGroup
+   * - acOther
+   * - acRead
+   * - acWrite
+   * - acFull
+   * - user
+   * - group
+   *
+   * You should modify these through client enabled methods or the $save method
+   * instead, for safety.
    */
   protected $protectedData: string[] = [];
   /**
@@ -199,20 +231,19 @@ export default class Entity<T extends EntityData = EntityData>
   private $originalAcValues: ACProperties | null = null;
 
   /**
-   * Load an entity.
-   * @param guid The ID of the entity to load, undefined for a new entity.
+   * Initialize an entity.
    */
-  public constructor(guid?: string) {
+  public constructor() {
     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(
@@ -229,7 +260,7 @@ export default class Entity<T extends EntityData = EntityData>
       },
 
       set: (data: EntityData, name: string, value: any) => {
-        this.$referenceWake();
+        this.$check();
 
         if (this.$sdata.hasOwnProperty(name)) {
           delete this.$sdata[name];
@@ -239,7 +270,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];
@@ -255,7 +286,7 @@ export default class Entity<T extends EntityData = EntityData>
         name: string,
         descriptor: PropertyDescriptor
       ) => {
-        this.$referenceWake();
+        this.$check();
 
         if (this.$sdata.hasOwnProperty(name)) {
           delete this.$sdata[name];
@@ -265,7 +296,7 @@ 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(
@@ -279,7 +310,7 @@ export default class Entity<T extends EntityData = EntityData>
       },
 
       ownKeys: (data: EntityData) => {
-        this.$referenceWake();
+        this.$check();
 
         return Object.getOwnPropertyNames(data).concat(
           Object.getOwnPropertyNames(this.$sdata)
@@ -291,20 +322,6 @@ export default class Entity<T extends EntityData = EntityData>
 
     this.$data = new Proxy(this.$dataStore, this.$dataHandler);
 
-    if (guid != null) {
-      const entity = this.$nymph.driver.getEntitySync(
-        { class: this.constructor as EntityConstructor },
-        { type: '&', guid }
-      );
-      if (entity) {
-        this.guid = entity.guid;
-        this.tags = entity.tags;
-        this.cdate = entity.cdate;
-        this.mdate = entity.mdate;
-        this.$putData(entity.$getData(), entity.$getSData());
-      }
-    }
-
     return new Proxy(this, {
       has: (entity: Entity, name: string) => {
         if (
@@ -315,7 +332,7 @@ export default class Entity<T extends EntityData = EntityData>
           return name in entity;
         }
 
-        this.$referenceWake();
+        this.$check();
         return name in entity.$data;
       },
 
@@ -326,12 +343,12 @@ export default class Entity<T extends EntityData = EntityData>
           name.substring(0, 1) === '$'
         ) {
           if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-            this.$referenceWake();
+            this.$check();
           }
           return (entity as any)[name];
         }
 
-        this.$referenceWake();
+        this.$check();
         if (name in entity.$data) {
           return entity.$data[name];
         }
@@ -345,11 +362,11 @@ export default class Entity<T extends EntityData = EntityData>
           name.substring(0, 1) === '$'
         ) {
           if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-            this.$referenceWake();
+            this.$check();
           }
           (entity as any)[name] = value;
         } else {
-          this.$referenceWake();
+          this.$check();
           (entity.$data as any)[name] = value;
         }
         return true;
@@ -359,7 +376,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;
@@ -380,11 +397,11 @@ export default class Entity<T extends EntityData = EntityData>
           name.substring(0, 1) === '$'
         ) {
           if (name === 'tags' || name === 'cdate' || name === 'mdate') {
-            this.$referenceWake();
+            this.$check();
           }
           Object.defineProperty(entity, name, descriptor);
         } else {
-          this.$referenceWake();
+          this.$check();
           Object.defineProperty(entity.$data, name, descriptor);
         }
         return true;
@@ -397,17 +414,17 @@ 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)
         );
@@ -431,8 +448,8 @@ export default class Entity<T extends EntityData = EntityData>
     return entity;
   }
 
-  public static factorySync(guid?: string) {
-    return new this(guid);
+  public static factorySync() {
+    return new this();
   }
 
   public static factoryReference(reference: EntityReference) {
@@ -463,7 +480,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $addTag(...tags: string[]) {
-    this.$referenceWake();
+    this.$check();
 
     if (tags.length < 1) {
       return;
@@ -472,7 +489,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $arraySearch(array: any[], strict = false) {
-    this.$referenceWake();
+    this.$check();
 
     if (!Array.isArray(array)) {
       return -1;
@@ -487,7 +504,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $clearCache() {
-    this.$referenceWake();
+    this.$check();
 
     this.$putData(this.$getData(), this.$getSData());
   }
@@ -497,13 +514,13 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public async $delete(): Promise<boolean> {
-    this.$referenceWake();
+    this.$check();
 
     return await this.$nymph.deleteEntity(this);
   }
 
   public $equals(object: any) {
-    this.$referenceWake();
+    this.$check();
 
     if (!(object instanceof Entity)) {
       return false;
@@ -513,22 +530,24 @@ export default class Entity<T extends EntityData = EntityData>
         return false;
       }
     }
-    if (object.constructor !== this.constructor) {
-      return false;
-    }
     if (object.cdate !== this.cdate) {
       return false;
     }
     if (object.mdate !== this.mdate) {
       return false;
     }
+    const obTags = [...object.tags].sort();
+    const myTags = [...this.tags].sort();
+    if (!isEqual(obTags, myTags)) {
+      return false;
+    }
     const obData = object.$getData(true);
     const myData = this.$getData(true);
     return isEqual(obData, myData);
   }
 
   public $getData(includeSData = false) {
-    this.$referenceWake();
+    this.$check();
 
     if (includeSData) {
       // Access all the serialized properties to initialize them.
@@ -540,30 +559,56 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $getSData() {
-    this.$referenceWake();
+    this.$check();
 
     return this.$sdata;
   }
 
   public $getOriginalAcValues() {
-    this.$referenceWake();
-
-    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,
-      }
-    );
+    this.$check();
+
+    return this.$originalAcValues ?? this.$getCurrentAcValues();
+  }
+
+  public $getCurrentAcValues() {
+    this.$check();
+
+    return {
+      user: this.$getAcUid(),
+      group: this.$getAcGid(),
+      acUser: this.$data.acUser,
+      acGroup: this.$data.acGroup,
+      acOther: this.$data.acOther,
+      acRead: this.$getAcReadIds(),
+      acWrite: this.$getAcWriteIds(),
+      acFull: this.$getAcFullIds(),
+    };
+  }
+
+  public $getAcUid() {
+    return this.$data.user?.guid as string | null;
+  }
+  public $getAcGid() {
+    return this.$data.group?.guid as string | null;
+  }
+  public $getAcReadIds() {
+    return this.$data.acRead?.map((entity: EntityInterface) => entity.guid) as
+      | string[]
+      | null;
+  }
+  public $getAcWriteIds() {
+    return this.$data.acWrite?.map((entity: EntityInterface) => entity.guid) as
+      | string[]
+      | null;
+  }
+  public $getAcFullIds() {
+    return this.$data.acFull?.map((entity: EntityInterface) => entity.guid) as
+      | string[]
+      | null;
   }
 
   public $getValidatable() {
-    this.$referenceWake();
+    this.$check();
 
     // Access all the serialized properties to initialize them.
     for (const key in this.$sdata) {
@@ -579,13 +624,13 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $getTags() {
-    this.$referenceWake();
+    this.$check();
 
     return this.tags;
   }
 
   public $hasTag(...tags: string[]) {
-    this.$referenceWake();
+    this.$check();
 
     if (!tags.length) {
       return false;
@@ -611,10 +656,15 @@ export default class Entity<T extends EntityData = EntityData>
       return this.guid === object.guid;
     }
 
-    this.$referenceWake();
+    this.$check();
     if (typeof object.$getData !== 'function') {
       return false;
     } else {
+      const obTags = [...object.tags].sort();
+      const myTags = [...this.tags].sort();
+      if (!isEqual(obTags, myTags)) {
+        return false;
+      }
       const obData = object.$getData(true);
       const myData = this.$getData(true);
       return isEqual(obData, myData);
@@ -622,8 +672,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $jsonAcceptData(input: EntityJson, allowConflict = false) {
-    // TODO: Do this without causing everything to become unserialized.
-    this.$referenceWake();
+    this.$check();
 
     if (this.guid != input.guid) {
       throw new EntityConflictError(
@@ -665,12 +714,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 typeof Entity).class !== 'User' &&
+          (this.constructor as typeof Entity).class !== 'Group') ||
+        !(this.$nymph.tilmeld as any).currentUser ||
+        (!(this.$nymph.tilmeld as any).currentUser.abilities?.includes(
+          'tilmeld/admin'
+        ) &&
+          !(this.$nymph.tilmeld as any).currentUser.abilities?.includes(
+            'system/admin'
+          ))
+      ) {
+        protectedProps.push('user');
+        protectedProps.push('group');
+      }
     }
     for (const name of protectedProps) {
       if (name in this.$data) {
@@ -703,7 +767,7 @@ 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(
@@ -719,11 +783,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 typeof Entity).class !== 'User' &&
+          (this.constructor as typeof Entity).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;
@@ -739,7 +827,7 @@ export default class Entity<T extends EntityData = EntityData>
       if (
         (this.$allowlistData != null &&
           this.$allowlistData.indexOf(name) === -1) ||
-        this.$protectedData.indexOf(name) !== -1 ||
+        protectedProps.indexOf(name) !== -1 ||
         this.$privateData.indexOf(name) !== -1
       ) {
         continue;
@@ -771,7 +859,7 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $putData(data: EntityData, sdata?: SerializedEntityData) {
-    this.$referenceWake();
+    this.$check();
 
     const mySdata = sdata ?? this.$getSData();
     for (const name in data) {
@@ -790,7 +878,7 @@ export default class Entity<T extends EntityData = EntityData>
     this.$sdata = mySdata;
     // Set original AC values if not set..
     if (this.$originalAcValues == null) {
-      this.$originalAcValues = this.$getOriginalAcValues();
+      this.$originalAcValues = this.$getCurrentAcValues();
     }
   }
 
@@ -822,45 +910,133 @@ export default class Entity<T extends EntityData = EntityData>
     this.$sleepingReference = reference;
   }
 
+  /**
+   * Check if this is a sleeping reference and throw an error if so.
+   */
+  protected $check() {
+    if (this.$isASleepingReference || this.$sleepingReference != null) {
+      throw new EntityIsSleepingReferenceError(
+        'This entity is in a sleeping reference state. You must use .$wake() to wake it.'
+      );
+    }
+  }
+
+  /**
+   * Check if this is a sleeping reference.
+   */
+  public $asleep() {
+    return this.$isASleepingReference || this.$sleepingReference != null;
+  }
+
   /**
    * Wake from a sleeping reference.
-   *
-   * @returns True on success, false on failure.
    */
-  protected $referenceWake() {
+  public $wake() {
     if (!this.$isASleepingReference || this.$sleepingReference == null) {
-      return true;
+      this.$wakePromise = null;
+      return Promise.resolve(this);
     }
-    const EntityClass = this.$nymph.getEntityClass(this.$sleepingReference[2]);
-    const entity = this.$nymph.driver.getEntitySync(
-      {
-        class: EntityClass,
-        skipAc: this.$skipAc,
-      },
-      { type: '&', guid: this.$sleepingReference[1] }
-    );
-    if (entity == null) {
-      return false;
+    if (this.$sleepingReference?.[1] == null) {
+      throw new InvalidStateError(
+        'Tried to wake a sleeping reference with no GUID.'
+      );
     }
-    this.$isASleepingReference = false;
-    this.$sleepingReference = null;
-    this.guid = entity.guid;
-    this.tags = entity.tags;
-    this.cdate = entity.cdate;
-    this.mdate = entity.mdate;
-    this.$putData(entity.$getData(), entity.$getSData());
-    return true;
+    if (!this.$wakePromise) {
+      const EntityClass = this.$nymph.getEntityClass(
+        this.$sleepingReference[2]
+      );
+      this.$wakePromise = this.$nymph
+        .getEntity(
+          {
+            class: EntityClass,
+            skipAc: this.$skipAc,
+          },
+          { type: '&', guid: this.$sleepingReference[1] }
+        )
+        .then((entity) => {
+          if (entity == null || entity.guid == null) {
+            return Promise.reject(
+              new InvalidStateError(
+                'The sleeping reference could not be retrieved.'
+              )
+            );
+          }
+          this.$isASleepingReference = false;
+          this.$sleepingReference = null;
+          this.guid = entity.guid;
+          this.tags = entity.tags;
+          this.cdate = entity.cdate;
+          this.mdate = entity.mdate;
+          this.$putData(entity.$getData(), entity.$getSData());
+
+          return this;
+        })
+        .finally(() => {
+          this.$wakePromise = null;
+        });
+    }
+    return this.$wakePromise;
+  }
+
+  public $wakeAll(level?: number) {
+    return new Promise((resolve, reject) => {
+      // Run this once this entity is wake.
+      const wakeProps = () => {
+        let newLevel;
+        // If level is undefined, keep going forever, otherwise, stop once we've
+        // gone deep enough.
+        if (level !== undefined) {
+          newLevel = level - 1;
+        }
+        if (newLevel !== undefined && newLevel < 0) {
+          resolve(this);
+          return;
+        }
+        const promises = [];
+        // Go through data looking for entities to wake.
+        for (let [key, value] of Object.entries(this.$data)) {
+          if (value instanceof Entity && value.$isASleepingReference) {
+            promises.push(value.$wakeAll(newLevel));
+          } else if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+              if (
+                value[i] instanceof Entity &&
+                value[i].$isASleepingReference
+              ) {
+                promises.push(value[i].$wakeAll(newLevel));
+              }
+            }
+          }
+        }
+        if (promises.length) {
+          Promise.all(promises).then(
+            () => resolve(this),
+            (errObj) => reject(errObj)
+          );
+        } else {
+          resolve(this);
+        }
+      };
+
+      if (this.$isASleepingReference) {
+        this.$wake().then(wakeProps, (errObj) => reject(errObj));
+      } else {
+        wakeProps();
+      }
+    }) as Promise<Entity<T>>;
   }
 
   public async $refresh() {
-    this.$referenceWake();
+    await this.$wake();
 
     if (this.guid == null) {
       return false;
     }
     const refresh = await this.$nymph.getEntity(
       {
-        class: this.constructor as EntityConstructor,
+        class: this.$nymph.getEntityClass(
+          this.constructor as EntityConstructor
+        ),
         skipCache: true,
         skipAc: this.$skipAc,
       },
@@ -877,13 +1053,13 @@ export default class Entity<T extends EntityData = EntityData>
   }
 
   public $removeTag(...tags: string[]) {
-    this.$referenceWake();
+    this.$check();
 
     this.tags = difference(this.tags, tags);
   }
 
   public async $save(): Promise<boolean> {
-    this.$referenceWake();
+    await this.$wake();
 
     return await this.$nymph.saveEntity(this);
   }