@nymphjs/nymph 1.0.0-beta.0 → 1.0.0-beta.10

package/src/Entity.ts

@@ -45,9 +45,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 +56,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 +65,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:
  *
@@ -513,15 +512,17 @@ 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);
@@ -615,6 +616,11 @@ export default class Entity<T extends EntityData = EntityData>
     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);

package/src/Entity.types.ts

@@ -271,7 +271,7 @@ export interface EntityInterface extends DataObjectInterface {
   $useSkipAc(useSkipAc: boolean): void;
 }
 
-export type EntityConstructor = (new (guid?: string) => EntityInterface) & {
+export type EntityConstructor = (new (...args: any[]) => EntityInterface) & {
   /**
    * The instance of Nymph to use for queries.
    */

package/src/Nymph.ts

@@ -1,7 +1,7 @@
 import { Config, ConfigDefaults as defaults } from './conf';
 import { NymphDriver } from './driver';
 import Entity from './Entity';
-import { EntityConstructor, EntityData, EntityInterface } from './Entity.types';
+import { EntityConstructor, EntityInterface } from './Entity.types';
 import { ClassNotAvailableError } from './errors';
 import type {
   Selector,
@@ -63,7 +63,7 @@ export default class Nymph {
   /**
    * The entity class for this instance of Nymph.
    */
-  public Entity: typeof Entity = Entity;
+  public Entity: typeof Entity;
 
   private connectCallbacks: NymphConnectCallback[] = [];
   private disconnectCallbacks: NymphDisconnectCallback[] = [];
@@ -87,20 +87,6 @@ export default class Nymph {
   private beforeDeleteUIDCallbacks: NymphBeforeDeleteUIDCallback[] = [];
   private afterDeleteUIDCallbacks: NymphAfterDeleteUIDCallback[] = [];
 
-  public addEntityClass(entityClass: EntityConstructor) {
-    this.entityClasses[entityClass.class] = entityClass;
-    entityClass.nymph = this;
-  }
-
-  public getEntityClass(className: string): EntityConstructor {
-    if (className in this.entityClasses) {
-      const EntityClass = this.entityClasses[className];
-      EntityClass.nymph = this;
-      return EntityClass;
-    }
-    throw new ClassNotAvailableError('Tried to use class: ' + className);
-  }
-
   /**
    * Initialize Nymph.
    *
@@ -115,28 +101,63 @@ export default class Nymph {
   ) {
     this.config = { ...defaults, ...config };
     this.driver = driver;
+
+    this.Entity = this.addEntityClass(Entity);
+
     if (typeof tilmeld !== 'undefined') {
       this.tilmeld = tilmeld;
     }
 
-    class NymphEntity<T extends EntityData = EntityData> extends Entity<T> {}
-    NymphEntity.nymph = this;
-    this.Entity = NymphEntity;
-    this.addEntityClass(NymphEntity);
-
     this.driver.init(this);
     if (this.tilmeld) {
       this.tilmeld.init(this);
     }
   }
 
+  /**
+   * Add your class to this instance.
+   *
+   * This will create a class that extends your class within this instance of
+   * Nymph and return it. You can then use this class's constructor and methods,
+   * which will use this instance of Nymph.
+   *
+   * Because this creates a subclass, don't use the class
+   * returned from `getEntityClass` to check with `instanceof`.
+   */
+  public addEntityClass<T extends EntityConstructor>(entityClass: T): T {
+    const nymph = this;
+    class NymphEntity extends entityClass {
+      static nymph: Nymph = nymph;
+
+      constructor(...args: any[]) {
+        super(...args);
+      }
+    }
+    this.entityClasses[entityClass.class] = NymphEntity;
+    return NymphEntity;
+  }
+
+  /**
+   * Get the class that uses the specified class name.
+   */
+  public getEntityClass(className: string): EntityConstructor {
+    if (className in this.entityClasses) {
+      return this.entityClasses[className];
+    }
+    throw new ClassNotAvailableError('Tried to use class: ' + className);
+  }
+
   /**
    * Get a clone of this instance with duplicate classes and event listeners.
    *
    * @returns A clone of this instance.
    */
   public clone() {
-    const nymph = new Nymph(this.config, this.driver, this.tilmeld?.clone());
+    const nymph = new Nymph(
+      this.config,
+      this.driver.clone(),
+      this.tilmeld?.clone()
+    );
     for (const name in this.entityClasses) {
       if (name === 'Entity' || (this.entityClasses[name] as any).skipOnClone) {
         continue;
@@ -190,7 +211,7 @@ export default class Nymph {
     const result = this.driver.connect();
     for (let callback of this.connectCallbacks) {
       if (callback) {
-        callback(this, result);
+        await callback(this, result);
       }
     }
     return await result;
@@ -205,7 +226,7 @@ export default class Nymph {
     const result = this.driver.disconnect();
     for (let callback of this.disconnectCallbacks) {
       if (callback) {
-        callback(this, result);
+        await callback(this, result);
       }
     }
     return await result;
@@ -214,10 +235,7 @@ export default class Nymph {
   /**
    * Run all the query callbacks on a query.
    */
-  public async runQueryCallbacks(
-    options: Options,
-    selectors: FormattedSelector[]
-  ) {
+  public runQueryCallbacks(options: Options, selectors: FormattedSelector[]) {
     for (let callback of this.queryCallbacks) {
       if (callback) {
         callback(this, options, selectors);
@@ -235,7 +253,7 @@ export default class Nymph {
    * Transactions will nest as long as every name is unique. Internally, Nymph
    * uses names prefixed with "nymph-".
    *
-   * @returns True on success, false on failure.
+   * @returns A new instance of Nymph that should be used for the transaction.
    */
   public async startTransaction(name: string): Promise<Nymph> {
     return await this.driver.startTransaction(name);
@@ -244,6 +262,8 @@ export default class Nymph {
   /**
    * Commit the named transaction.
    *
+   * After this is called, the transaction instance should be discarded.
+   *
    * @returns True on success, false on failure.
    */
   public async commit(name: string): Promise<boolean> {
@@ -253,6 +273,8 @@ export default class Nymph {
   /**
    * Rollback the named transaction.
    *
+   * After this is called, the transaction instance should be discarded.
+   *
    * @returns True on success, false on failure.
    */
   public async rollback(name: string): Promise<boolean> {
@@ -292,13 +314,13 @@ export default class Nymph {
   public async newUID(name: string): Promise<number | null> {
     for (let callback of this.beforeNewUIDCallbacks) {
       if (callback) {
-        callback(this, name);
+        await callback(this, name);
       }
     }
     const result = this.driver.newUID(name);
     for (let callback of this.afterNewUIDCallbacks) {
       if (callback) {
-        callback(this, result);
+        await callback(this, result);
       }
     }
     return await result;
@@ -323,13 +345,13 @@ export default class Nymph {
   public async setUID(name: string, value: number): Promise<boolean> {
     for (let callback of this.beforeSetUIDCallbacks) {
       if (callback) {
-        callback(this, name, value);
+        await callback(this, name, value);
       }
     }
     const result = this.driver.setUID(name, value);
     for (let callback of this.afterSetUIDCallbacks) {
       if (callback) {
-        callback(this, result);
+        await callback(this, result);
       }
     }
     return await result;
@@ -344,13 +366,13 @@ export default class Nymph {
   public async deleteUID(name: string): Promise<boolean> {
     for (let callback of this.beforeDeleteUIDCallbacks) {
       if (callback) {
-        callback(this, name);
+        await callback(this, name);
       }
     }
     const result = this.driver.deleteUID(name);
     for (let callback of this.afterDeleteUIDCallbacks) {
       if (callback) {
-        callback(this, result);
+        await callback(this, result);
       }
     }
     return await result;
@@ -366,13 +388,13 @@ export default class Nymph {
   public async renameUID(oldName: string, newName: string): Promise<boolean> {
     for (let callback of this.beforeRenameUIDCallbacks) {
       if (callback) {
-        callback(this, oldName, newName);
+        await callback(this, oldName, newName);
       }
     }
     const result = this.driver.renameUID(oldName, newName);
     for (let callback of this.afterRenameUIDCallbacks) {
       if (callback) {
-        callback(this, result);
+        await callback(this, result);
       }
     }
     return await result;
@@ -392,13 +414,13 @@ export default class Nymph {
   public async saveEntity(entity: EntityInterface): Promise<boolean> {
     for (let callback of this.beforeSaveEntityCallbacks) {
       if (callback) {
-        callback(this, entity);
+        await callback(this, entity);
       }
     }
     const result = this.driver.saveEntity(entity);
     for (let callback of this.afterSaveEntityCallbacks) {
       if (callback) {
-        callback(this, result);
+        await callback(this, result);
       }
     }
     return await result;
@@ -581,7 +603,7 @@ export default class Nymph {
   ): Promise<ReturnType<T['factorySync']>[] | string[] | number> {
     for (let callback of this.beforeGetEntitiesCallbacks) {
       if (callback) {
-        callback(this, options, selectors);
+        await callback(this, options, selectors);
       }
     }
     return await this.driver.getEntities(options, ...selectors);
@@ -631,7 +653,7 @@ export default class Nymph {
     options.limit = 1;
     for (let callback of this.beforeGetEntityCallbacks) {
       if (callback) {
-        callback(this, options, selectors as Selector[]);
+        await callback(this, options, selectors as Selector[]);
       }
     }
     const entities = await this.driver.getEntities(
@@ -656,13 +678,13 @@ export default class Nymph {
   public async deleteEntity(entity: EntityInterface): Promise<boolean> {
     for (let callback of this.beforeDeleteEntityCallbacks) {
       if (callback) {
-        callback(this, entity);
+        await callback(this, entity);
       }
     }
     const result = this.driver.deleteEntity(entity);
     for (let callback of this.afterDeleteEntityCallbacks) {
       if (callback) {
-        callback(this, result);
+        await callback(this, result);
       }
     }
     return await result;
@@ -681,13 +703,13 @@ export default class Nymph {
   ): Promise<boolean> {
     for (let callback of this.beforeDeleteEntityByIDCallbacks) {
       if (callback) {
-        callback(this, guid, className);
+        await callback(this, guid, className);
       }
     }
     const result = this.driver.deleteEntityByID(guid, className);
     for (let callback of this.afterDeleteEntityByIDCallbacks) {
       if (callback) {
-        callback(this, result);
+        await callback(this, result);
       }
     }
     return await result;

package/src/Nymph.types.ts

@@ -24,12 +24,22 @@ export type NymphEventType =
 export type NymphConnectCallback = (
   nymph: Nymph,
   result: Promise<boolean>
-) => void;
+) => Promise<void>;
 export type NymphDisconnectCallback = (
   nymph: Nymph,
   result: Promise<boolean>
-) => void;
-/** The NymphQueryCallback will be called on both top level and qref queries. */
+) => Promise<void>;
+/**
+ * The NymphQueryCallback will be called on both top level and qref queries.
+ *
+ * This is the only callback that is not asynchronous.
+ *
+ * This also isn't necessarily run on every "query". It is run before a database
+ * query for an entity, but it is not run during PubSub entity change
+ * propagation. Therefore, it shouldn't do anything _entity_ specific, instead
+ * it should be _query_ specific. For example, throw an error if the user is not
+ * permitted to run the query at all.
+ */
 export type NymphQueryCallback = (
   nymph: Nymph,
   options: Options,
@@ -39,65 +49,71 @@ export type NymphBeforeGetEntityCallback = (
   nymph: Nymph,
   options: Options,
   selectors: Selector[]
-) => void;
+) => Promise<void>;
 export type NymphBeforeGetEntitiesCallback = (
   nymph: Nymph,
   options: Options,
   selectors: Selector[]
-) => void;
+) => Promise<void>;
 export type NymphBeforeSaveEntityCallback = (
   nymph: Nymph,
   entity: EntityInterface
-) => void;
+) => Promise<void>;
 export type NymphAfterSaveEntityCallback = (
   nymph: Nymph,
   result: Promise<boolean>
-) => void;
+) => Promise<void>;
 export type NymphBeforeDeleteEntityCallback = (
   nymph: Nymph,
   entity: EntityInterface
-) => void;
+) => Promise<void>;
 export type NymphAfterDeleteEntityCallback = (
   nymph: Nymph,
   result: Promise<boolean>
-) => void;
+) => Promise<void>;
 export type NymphBeforeDeleteEntityByIDCallback = (
   nymph: Nymph,
   guid: string,
   className?: string
-) => void;
+) => Promise<void>;
 export type NymphAfterDeleteEntityByIDCallback = (
   nymph: Nymph,
   result: Promise<boolean>
-) => void;
-export type NymphBeforeNewUIDCallback = (nymph: Nymph, name: string) => void;
+) => Promise<void>;
+export type NymphBeforeNewUIDCallback = (
+  nymph: Nymph,
+  name: string
+) => Promise<void>;
 export type NymphAfterNewUIDCallback = (
   nymph: Nymph,
   result: Promise<number | null>
-) => void;
+) => Promise<void>;
 export type NymphBeforeSetUIDCallback = (
   nymph: Nymph,
   name: string,
   value: number
-) => void;
+) => Promise<void>;
 export type NymphAfterSetUIDCallback = (
   nymph: Nymph,
   result: Promise<boolean>
-) => void;
+) => Promise<void>;
 export type NymphBeforeRenameUIDCallback = (
   nymph: Nymph,
   oldName: string,
   newName: string
-) => void;
+) => Promise<void>;
 export type NymphAfterRenameUIDCallback = (
   nymph: Nymph,
   result: Promise<boolean>
-) => void;
-export type NymphBeforeDeleteUIDCallback = (nymph: Nymph, name: string) => void;
+) => Promise<void>;
+export type NymphBeforeDeleteUIDCallback = (
+  nymph: Nymph,
+  name: string
+) => Promise<void>;
 export type NymphAfterDeleteUIDCallback = (
   nymph: Nymph,
   result: Promise<boolean>
-) => void;
+) => Promise<void>;
 
 export type Options<T extends EntityConstructor = EntityConstructor> = {
   class?: T;