@nymphjs/nymph 1.0.0-alpha.1 → 1.0.0-alpha.13

package/src/Nymph.ts

@@ -1,8 +1,9 @@
 import { Config, ConfigDefaults as defaults } from './conf';
 import { NymphDriver } from './driver';
-import { EntityConstructor, EntityInterface } from './Entity.types';
+import Entity from './Entity';
+import { EntityConstructor, EntityData, EntityInterface } from './Entity.types';
 import { ClassNotAvailableError } from './errors';
-import {
+import type {
   Selector,
   Options,
   NymphConnectCallback,
@@ -24,6 +25,9 @@ import {
   NymphBeforeDeleteUIDCallback,
   NymphAfterDeleteUIDCallback,
   NymphEventType,
+  NymphQueryCallback,
+  FormattedSelector,
+  TilmeldInterface,
 } from './Nymph.types';
 
 /**
@@ -36,45 +40,63 @@ import {
  * @see http://nymph.io/
  */
 export default class Nymph {
-  public static config: Config;
-  public static driver: NymphDriver;
-  public static entityClasses: { [k: string]: EntityConstructor } = {};
-  public static Tilmeld: any = undefined;
-  private static connectCallbacks: NymphConnectCallback[] = [];
-  private static disconnectCallbacks: NymphDisconnectCallback[] = [];
-  private static beforeGetEntityCallbacks: NymphBeforeGetEntityCallback[] = [];
-  private static beforeGetEntitiesCallbacks: NymphBeforeGetEntitiesCallback[] =
-    [];
-  private static beforeSaveEntityCallbacks: NymphBeforeSaveEntityCallback[] =
-    [];
-  private static afterSaveEntityCallbacks: NymphAfterSaveEntityCallback[] = [];
-  private static beforeDeleteEntityCallbacks: NymphBeforeDeleteEntityCallback[] =
-    [];
-  private static afterDeleteEntityCallbacks: NymphAfterDeleteEntityCallback[] =
-    [];
-  private static beforeDeleteEntityByIDCallbacks: NymphBeforeDeleteEntityByIDCallback[] =
+  /**
+   * The PubSub config.
+   */
+  public config: Config;
+
+  /**
+   * The Nymph database driver.
+   */
+  public driver: NymphDriver;
+
+  /**
+   * An optional Tilmeld user/group manager instance.
+   */
+  public tilmeld?: TilmeldInterface = undefined;
+
+  /**
+   * A simple map of names to Entity classes.
+   */
+  private entityClasses: { [k: string]: EntityConstructor } = {};
+
+  /**
+   * The entity class for this instance of Nymph.
+   */
+  public Entity: typeof Entity = Entity;
+
+  private connectCallbacks: NymphConnectCallback[] = [];
+  private disconnectCallbacks: NymphDisconnectCallback[] = [];
+  private queryCallbacks: NymphQueryCallback[] = [];
+  private beforeGetEntityCallbacks: NymphBeforeGetEntityCallback[] = [];
+  private beforeGetEntitiesCallbacks: NymphBeforeGetEntitiesCallback[] = [];
+  private beforeSaveEntityCallbacks: NymphBeforeSaveEntityCallback[] = [];
+  private afterSaveEntityCallbacks: NymphAfterSaveEntityCallback[] = [];
+  private beforeDeleteEntityCallbacks: NymphBeforeDeleteEntityCallback[] = [];
+  private afterDeleteEntityCallbacks: NymphAfterDeleteEntityCallback[] = [];
+  private beforeDeleteEntityByIDCallbacks: NymphBeforeDeleteEntityByIDCallback[] =
     [];
-  private static afterDeleteEntityByIDCallbacks: NymphAfterDeleteEntityByIDCallback[] =
+  private afterDeleteEntityByIDCallbacks: NymphAfterDeleteEntityByIDCallback[] =
     [];
-  private static beforeNewUIDCallbacks: NymphBeforeNewUIDCallback[] = [];
-  private static afterNewUIDCallbacks: NymphAfterNewUIDCallback[] = [];
-  private static beforeSetUIDCallbacks: NymphBeforeSetUIDCallback[] = [];
-  private static afterSetUIDCallbacks: NymphAfterSetUIDCallback[] = [];
-  private static beforeRenameUIDCallbacks: NymphBeforeRenameUIDCallback[] = [];
-  private static afterRenameUIDCallbacks: NymphAfterRenameUIDCallback[] = [];
-  private static beforeDeleteUIDCallbacks: NymphBeforeDeleteUIDCallback[] = [];
-  private static afterDeleteUIDCallbacks: NymphAfterDeleteUIDCallback[] = [];
-
-  public static setEntityClass(
-    className: string,
-    entityClass: EntityConstructor
-  ) {
-    this.entityClasses[className] = entityClass;
+  private beforeNewUIDCallbacks: NymphBeforeNewUIDCallback[] = [];
+  private afterNewUIDCallbacks: NymphAfterNewUIDCallback[] = [];
+  private beforeSetUIDCallbacks: NymphBeforeSetUIDCallback[] = [];
+  private afterSetUIDCallbacks: NymphAfterSetUIDCallback[] = [];
+  private beforeRenameUIDCallbacks: NymphBeforeRenameUIDCallback[] = [];
+  private afterRenameUIDCallbacks: NymphAfterRenameUIDCallback[] = [];
+  private beforeDeleteUIDCallbacks: NymphBeforeDeleteUIDCallback[] = [];
+  private afterDeleteUIDCallbacks: NymphAfterDeleteUIDCallback[] = [];
+
+  public addEntityClass(entityClass: EntityConstructor) {
+    this.entityClasses[entityClass.class] = entityClass;
+    entityClass.nymph = this;
   }
 
-  public static getEntityClass(className: string): EntityConstructor {
+  public getEntityClass(className: string): EntityConstructor {
     if (className in this.entityClasses) {
-      return this.entityClasses[className];
+      const EntityClass = this.entityClasses[className];
+      EntityClass.nymph = this;
+      return EntityClass;
     }
     throw new ClassNotAvailableError('Tried to use class: ' + className);
   }
@@ -84,16 +106,79 @@ export default class Nymph {
    *
    * @param config The Nymph configuration.
    * @param driver The Nymph database driver.
-   * @param Tilmeld The Tilmeld user/group manager, if you want to use it.
+   * @param tilmeld The Tilmeld user/group manager instance, if you want to use it.
    */
-  public static init(
+  public constructor(
     config: Partial<Config>,
     driver: NymphDriver,
-    Tilmeld?: any
+    tilmeld?: TilmeldInterface
   ) {
     this.config = { ...defaults, ...config };
     this.driver = driver;
-    this.Tilmeld = Tilmeld;
+    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);
+    }
+  }
+
+  /**
+   * 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());
+    for (const name in this.entityClasses) {
+      if (name === 'Entity' || (this.entityClasses[name] as any).skipOnClone) {
+        continue;
+      }
+      nymph.addEntityClass(this.entityClasses[name]);
+    }
+
+    const events = [
+      'connect',
+      'disconnect',
+      'query',
+      'beforeGetEntity',
+      'beforeGetEntities',
+      'beforeSaveEntity',
+      'afterSaveEntity',
+      'beforeDeleteEntity',
+      'afterDeleteEntity',
+      'beforeDeleteEntityByID',
+      'afterDeleteEntityByID',
+      'beforeNewUID',
+      'afterNewUID',
+      'beforeSetUID',
+      'afterSetUID',
+      'beforeRenameUID',
+      'afterRenameUID',
+      'beforeDeleteUID',
+      'afterDeleteUID',
+    ];
+
+    for (let event of events) {
+      const prop = event + 'Callbacks';
+      // @ts-ignore: The callback should be the right type here.
+      const callbacks = this[prop];
+      for (let callback of callbacks) {
+        if (callback.skipOnClone) {
+          continue;
+        }
+        nymph.on(event as NymphEventType, callback);
+      }
+    }
+
+    return nymph;
   }
 
   /**
@@ -101,11 +186,11 @@ export default class Nymph {
    *
    * @returns Whether the instance is connected to the database.
    */
-  public static async connect(): Promise<boolean> {
+  public async connect(): Promise<boolean> {
     const result = this.driver.connect();
     for (let callback of this.connectCallbacks) {
       if (callback) {
-        callback(result);
+        callback(this, result);
       }
     }
     return await result;
@@ -116,33 +201,43 @@ export default class Nymph {
    *
    * @returns Whether the instance is connected to the database.
    */
-  public static async disconnect(): Promise<boolean> {
+  public async disconnect(): Promise<boolean> {
     const result = this.driver.disconnect();
     for (let callback of this.disconnectCallbacks) {
       if (callback) {
-        callback(result);
+        callback(this, result);
       }
     }
     return await result;
   }
 
   /**
-   * Start an atomic transaction.
-   *
-   * If this function returns true, all proceeding changes will wait to be
-   * written to the database's permanent storage until commit() is called. You
-   * can also undo all the changes since this function ran with rollback().
+   * Run all the query callbacks on a query.
+   */
+  public async runQueryCallbacks(
+    options: Options,
+    selectors: FormattedSelector[]
+  ) {
+    for (let callback of this.queryCallbacks) {
+      if (callback) {
+        callback(this, options, selectors);
+      }
+    }
+  }
+
+  /**
+   * Start an atomic transaction and returns a new instance of Nymph.
    *
-   * If it returns false instead of throwing an error, that probably means the
-   * driver or the database doesn't support transaction. You should call
-   * `rollback(name)` immediately in this case.
+   * All proceeding changes using this new instance will wait to be written to
+   * the database's permanent storage until commit() is called. You can also
+   * undo all the changes since this function ran with rollback().
    *
    * Transactions will nest as long as every name is unique. Internally, Nymph
    * uses names prefixed with "nymph-".
    *
    * @returns True on success, false on failure.
    */
-  public static async startTransaction(name: string): Promise<boolean> {
+  public async startTransaction(name: string): Promise<Nymph> {
     return await this.driver.startTransaction(name);
   }
 
@@ -151,7 +246,7 @@ export default class Nymph {
    *
    * @returns True on success, false on failure.
    */
-  public static async commit(name: string): Promise<boolean> {
+  public async commit(name: string): Promise<boolean> {
     return await this.driver.commit(name);
   }
 
@@ -160,7 +255,7 @@ export default class Nymph {
    *
    * @returns True on success, false on failure.
    */
-  public static async rollback(name: string): Promise<boolean> {
+  public async rollback(name: string): Promise<boolean> {
     return await this.driver.rollback(name);
   }
 
@@ -169,7 +264,7 @@ export default class Nymph {
    *
    * @returns True if there is a transaction.
    */
-  public static async inTransaction(): Promise<boolean> {
+  public async inTransaction(): Promise<boolean> {
     return await this.driver.inTransaction();
   }
 
@@ -194,16 +289,16 @@ export default class Nymph {
    * @param name The UID's name.
    * @returns The UID's new value, or null on failure.
    */
-  public static async newUID(name: string): Promise<number | null> {
+  public async newUID(name: string): Promise<number | null> {
     for (let callback of this.beforeNewUIDCallbacks) {
       if (callback) {
-        callback(name);
+        callback(this, name);
       }
     }
     const result = this.driver.newUID(name);
     for (let callback of this.afterNewUIDCallbacks) {
       if (callback) {
-        callback(result);
+        callback(this, result);
       }
     }
     return await result;
@@ -214,7 +309,7 @@ export default class Nymph {
    * @param name The UID's name.
    * @returns The UID's value, or null on failure and if it doesn't exist.
    */
-  public static async getUID(name: string): Promise<number | null> {
+  public async getUID(name: string): Promise<number | null> {
     return await this.driver.getUID(name);
   }
 
@@ -225,16 +320,16 @@ export default class Nymph {
    * @param value The value.
    * @returns True on success, false on failure.
    */
-  public static async setUID(name: string, value: number): Promise<boolean> {
+  public async setUID(name: string, value: number): Promise<boolean> {
     for (let callback of this.beforeSetUIDCallbacks) {
       if (callback) {
-        callback(name, value);
+        callback(this, name, value);
       }
     }
     const result = this.driver.setUID(name, value);
     for (let callback of this.afterSetUIDCallbacks) {
       if (callback) {
-        callback(result);
+        callback(this, result);
       }
     }
     return await result;
@@ -246,16 +341,16 @@ export default class Nymph {
    * @param name The UID's name.
    * @returns True on success, false on failure.
    */
-  public static async deleteUID(name: string): Promise<boolean> {
+  public async deleteUID(name: string): Promise<boolean> {
     for (let callback of this.beforeDeleteUIDCallbacks) {
       if (callback) {
-        callback(name);
+        callback(this, name);
       }
     }
     const result = this.driver.deleteUID(name);
     for (let callback of this.afterDeleteUIDCallbacks) {
       if (callback) {
-        callback(result);
+        callback(this, result);
       }
     }
     return await result;
@@ -268,19 +363,16 @@ export default class Nymph {
    * @param newName The new name.
    * @returns True on success, false on failure.
    */
-  public static async renameUID(
-    oldName: string,
-    newName: string
-  ): Promise<boolean> {
+  public async renameUID(oldName: string, newName: string): Promise<boolean> {
     for (let callback of this.beforeRenameUIDCallbacks) {
       if (callback) {
-        callback(oldName, newName);
+        callback(this, oldName, newName);
       }
     }
     const result = this.driver.renameUID(oldName, newName);
     for (let callback of this.afterRenameUIDCallbacks) {
       if (callback) {
-        callback(result);
+        callback(this, result);
       }
     }
     return await result;
@@ -297,16 +389,16 @@ export default class Nymph {
    * @param entity The entity.
    * @returns True on success, false on failure.
    */
-  public static async saveEntity(entity: EntityInterface): Promise<boolean> {
+  public async saveEntity(entity: EntityInterface): Promise<boolean> {
     for (let callback of this.beforeSaveEntityCallbacks) {
       if (callback) {
-        callback(entity);
+        callback(this, entity);
       }
     }
     const result = this.driver.saveEntity(entity);
     for (let callback of this.afterSaveEntityCallbacks) {
       if (callback) {
-        callback(result);
+        callback(this, result);
       }
     }
     return await result;
@@ -379,9 +471,9 @@ export default class Nymph {
    *   less than or equal to the value.
    * - ref - An array with a name, then either an entity, or a GUID. True if
    *   the named property is the entity or contains the entity.
-   * - qref - An array with a name, then a full query (including options). True
-   *   if the named property is an entity that matches the query or an array
-   *   containing an entity that matches the query.
+   * - qref - An array with a name, then a full query (including options) in an
+   *   array. True if the named property is an entity that matches the query or
+   *   contains an entity that matches the query.
    * - selector - A selector. (Keep in mind, you can also use an array of these,
    *   just like any other clause.)
    *
@@ -395,10 +487,10 @@ export default class Nymph {
    * entities that were created in the last day:
    *
    * ```
-   * [
-   *   '&',
-   *   'gte' => ['cdate', null, '-1 day']
-   * ]
+   * {
+   *   type: '&',
+   *   gte: ['cdate', null, '-1 day']
+   * }
    * ```
    *
    * Locutus' implementation: https://locutus.io/php/datetime/strtotime/
@@ -471,27 +563,21 @@ export default class Nymph {
    * @todo An option to place a total count in a var.
    * @todo Use an asterisk to specify any variable.
    */
-  public static async getEntities<
-    T extends EntityConstructor = EntityConstructor
-  >(
+  public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> & { return: 'guid' },
     ...selectors: Selector[]
   ): Promise<string[]>;
-  public static async getEntities<
-    T extends EntityConstructor = EntityConstructor
-  >(
+  public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options?: Options<T>,
     ...selectors: Selector[]
   ): Promise<ReturnType<T['factorySync']>[]>;
-  public static async getEntities<
-    T extends EntityConstructor = EntityConstructor
-  >(
+  public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> = {},
     ...selectors: Selector[]
   ): Promise<ReturnType<T['factorySync']>[] | string[]> {
     for (let callback of this.beforeGetEntitiesCallbacks) {
       if (callback) {
-        callback(options, selectors);
+        callback(this, options, selectors);
       }
     }
     return await this.driver.getEntities(options, ...selectors);
@@ -510,33 +596,23 @@ export default class Nymph {
    * @param selectors Unlimited optional selectors to search for, or a single GUID. If none are given, all entities are searched for the given options.
    * @returns An entity, or null on failure or nothing found.
    */
-  public static async getEntity<
-    T extends EntityConstructor = EntityConstructor
-  >(
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> & { return: 'guid' },
     ...selectors: Selector[]
   ): Promise<string | null>;
-  public static async getEntity<
-    T extends EntityConstructor = EntityConstructor
-  >(
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[]
   ): Promise<ReturnType<T['factorySync']> | null>;
-  public static async getEntity<
-    T extends EntityConstructor = EntityConstructor
-  >(
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> & { return: 'guid' },
     guid: string
   ): Promise<string | null>;
-  public static async getEntity<
-    T extends EntityConstructor = EntityConstructor
-  >(
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     guid: string
   ): Promise<ReturnType<T['factorySync']> | null>;
-  public static async getEntity<
-    T extends EntityConstructor = EntityConstructor
-  >(
+  public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> = {},
     ...selectors: Selector[] | string[]
   ): Promise<ReturnType<T['factorySync']> | string | null> {
@@ -547,7 +623,7 @@ export default class Nymph {
     options.limit = 1;
     for (let callback of this.beforeGetEntityCallbacks) {
       if (callback) {
-        callback(options, selectors as Selector[]);
+        callback(this, options, selectors as Selector[]);
       }
     }
     const entities = await this.driver.getEntities(
@@ -566,16 +642,16 @@ export default class Nymph {
    * @param entity The entity.
    * @returns True on success, false on failure.
    */
-  public static async deleteEntity(entity: EntityInterface): Promise<boolean> {
+  public async deleteEntity(entity: EntityInterface): Promise<boolean> {
     for (let callback of this.beforeDeleteEntityCallbacks) {
       if (callback) {
-        callback(entity);
+        callback(this, entity);
       }
     }
     const result = this.driver.deleteEntity(entity);
     for (let callback of this.afterDeleteEntityCallbacks) {
       if (callback) {
-        callback(result);
+        callback(this, result);
       }
     }
     return await result;
@@ -588,19 +664,19 @@ export default class Nymph {
    * @param className The entity's class name.
    * @returns True on success, false on failure.
    */
-  public static async deleteEntityByID(
+  public async deleteEntityByID(
     guid: string,
     className?: string
   ): Promise<boolean> {
     for (let callback of this.beforeDeleteEntityByIDCallbacks) {
       if (callback) {
-        callback(guid, className);
+        callback(this, guid, className);
       }
     }
     const result = this.driver.deleteEntityByID(guid, className);
     for (let callback of this.afterDeleteEntityByIDCallbacks) {
       if (callback) {
-        callback(result);
+        callback(this, result);
       }
     }
     return await result;
@@ -642,7 +718,7 @@ export default class Nymph {
    * @param filename The file to export to.
    * @returns True on success, false on failure.
    */
-  public static async export(filename: string): Promise<boolean> {
+  public async export(filename: string): Promise<boolean> {
     return await this.driver.export(filename);
   }
 
@@ -651,7 +727,7 @@ export default class Nymph {
    *
    * @returns True on success, false on failure.
    */
-  public static async exportPrint(): Promise<boolean> {
+  public async exportPrint(): Promise<boolean> {
     return await this.driver.exportPrint();
   }
 
@@ -661,16 +737,18 @@ export default class Nymph {
    * @param filename The file to import from.
    * @returns True on success, false on failure.
    */
-  public static async import(filename: string): Promise<boolean> {
+  public async import(filename: string): Promise<boolean> {
     return await this.driver.import(filename);
   }
 
-  public static on<T extends NymphEventType>(
+  public on<T extends NymphEventType>(
     event: T,
     callback: T extends 'connect'
       ? NymphConnectCallback
       : T extends 'disconnect'
       ? NymphDisconnectCallback
+      : T extends 'query'
+      ? NymphQueryCallback
       : T extends 'beforeGetEntity'
       ? NymphBeforeGetEntityCallback
       : T extends 'beforeGetEntities'
@@ -709,6 +787,8 @@ export default class Nymph {
       ? 'connectCallbacks'
       : T extends 'disconnect'
       ? 'disconnectCallbacks'
+      : T extends 'query'
+      ? 'queryCallbacks'
       : T extends 'beforeGetEntity'
       ? 'beforeGetEntityCallbacks'
       : T extends 'beforeGetEntities'
@@ -750,12 +830,14 @@ export default class Nymph {
     return () => this.off(event, callback);
   }
 
-  public static off<T extends NymphEventType>(
+  public off<T extends NymphEventType>(
     event: T,
     callback: T extends 'connect'
       ? NymphConnectCallback
       : T extends 'disconnect'
       ? NymphDisconnectCallback
+      : T extends 'query'
+      ? NymphQueryCallback
       : T extends 'beforeGetEntity'
       ? NymphBeforeGetEntityCallback
       : T extends 'beforeGetEntities'
@@ -794,6 +876,8 @@ export default class Nymph {
       ? 'connectCallbacks'
       : T extends 'disconnect'
       ? 'disconnectCallbacks'
+      : T extends 'query'
+      ? 'queryCallbacks'
       : T extends 'beforeSaveEntity'
       ? 'beforeSaveEntityCallbacks'
       : T extends 'beforeGetEntity'