@nymphjs/nymph 1.0.0-beta.8 → 1.0.0-beta.81

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, EntityInterface } from './Entity.types';
+import type { NymphDriver } from './driver';
+import Entity, { type EntityInstanceType } from './Entity';
+import type { EntityConstructor, EntityInterface } from './Entity.types';
 import { ClassNotAvailableError } from './errors';
 import type {
   Selector,
@@ -12,18 +12,31 @@ import type {
   NymphBeforeGetEntitiesCallback,
   NymphBeforeSaveEntityCallback,
   NymphAfterSaveEntityCallback,
+  NymphFailedSaveEntityCallback,
   NymphBeforeDeleteEntityCallback,
   NymphAfterDeleteEntityCallback,
+  NymphFailedDeleteEntityCallback,
   NymphBeforeDeleteEntityByIDCallback,
   NymphAfterDeleteEntityByIDCallback,
+  NymphFailedDeleteEntityByIDCallback,
   NymphBeforeNewUIDCallback,
   NymphAfterNewUIDCallback,
+  NymphFailedNewUIDCallback,
   NymphBeforeSetUIDCallback,
   NymphAfterSetUIDCallback,
+  NymphFailedSetUIDCallback,
   NymphBeforeRenameUIDCallback,
   NymphAfterRenameUIDCallback,
+  NymphFailedRenameUIDCallback,
   NymphBeforeDeleteUIDCallback,
   NymphAfterDeleteUIDCallback,
+  NymphFailedDeleteUIDCallback,
+  NymphBeforeStartTransactionCallback,
+  NymphAfterStartTransactionCallback,
+  NymphBeforeCommitTransactionCallback,
+  NymphAfterCommitTransactionCallback,
+  NymphBeforeRollbackTransactionCallback,
+  NymphAfterRollbackTransactionCallback,
   NymphEventType,
   NymphQueryCallback,
   FormattedSelector,
@@ -41,10 +54,16 @@ import type {
  */
 export default class Nymph {
   /**
-   * The PubSub config.
+   * The Nymph config.
    */
   public config: Config;
 
+  /**
+   * The Nymph instance that this one was cloned from, or null if it's not a
+   * clone.
+   */
+  public parent: Nymph | null;
+
   /**
    * The Nymph database driver.
    */
@@ -72,20 +91,40 @@ export default class Nymph {
   private beforeGetEntitiesCallbacks: NymphBeforeGetEntitiesCallback[] = [];
   private beforeSaveEntityCallbacks: NymphBeforeSaveEntityCallback[] = [];
   private afterSaveEntityCallbacks: NymphAfterSaveEntityCallback[] = [];
+  private failedSaveEntityCallbacks: NymphFailedSaveEntityCallback[] = [];
   private beforeDeleteEntityCallbacks: NymphBeforeDeleteEntityCallback[] = [];
   private afterDeleteEntityCallbacks: NymphAfterDeleteEntityCallback[] = [];
+  private failedDeleteEntityCallbacks: NymphFailedDeleteEntityCallback[] = [];
   private beforeDeleteEntityByIDCallbacks: NymphBeforeDeleteEntityByIDCallback[] =
     [];
   private afterDeleteEntityByIDCallbacks: NymphAfterDeleteEntityByIDCallback[] =
     [];
+  private failedDeleteEntityByIDCallbacks: NymphFailedDeleteEntityByIDCallback[] =
+    [];
   private beforeNewUIDCallbacks: NymphBeforeNewUIDCallback[] = [];
   private afterNewUIDCallbacks: NymphAfterNewUIDCallback[] = [];
+  private failedNewUIDCallbacks: NymphFailedNewUIDCallback[] = [];
   private beforeSetUIDCallbacks: NymphBeforeSetUIDCallback[] = [];
   private afterSetUIDCallbacks: NymphAfterSetUIDCallback[] = [];
+  private failedSetUIDCallbacks: NymphFailedSetUIDCallback[] = [];
   private beforeRenameUIDCallbacks: NymphBeforeRenameUIDCallback[] = [];
   private afterRenameUIDCallbacks: NymphAfterRenameUIDCallback[] = [];
+  private failedRenameUIDCallbacks: NymphFailedRenameUIDCallback[] = [];
   private beforeDeleteUIDCallbacks: NymphBeforeDeleteUIDCallback[] = [];
   private afterDeleteUIDCallbacks: NymphAfterDeleteUIDCallback[] = [];
+  private failedDeleteUIDCallbacks: NymphFailedDeleteUIDCallback[] = [];
+  private beforeStartTransactionCallbacks: NymphBeforeStartTransactionCallback[] =
+    [];
+  private afterStartTransactionCallbacks: NymphAfterStartTransactionCallback[] =
+    [];
+  private beforeCommitTransactionCallbacks: NymphBeforeCommitTransactionCallback[] =
+    [];
+  private afterCommitTransactionCallbacks: NymphAfterCommitTransactionCallback[] =
+    [];
+  private beforeRollbackTransactionCallbacks: NymphBeforeRollbackTransactionCallback[] =
+    [];
+  private afterRollbackTransactionCallbacks: NymphAfterRollbackTransactionCallback[] =
+    [];
 
   /**
    * Initialize Nymph.
@@ -93,24 +132,90 @@ export default class Nymph {
    * @param config The Nymph configuration.
    * @param driver The Nymph database driver.
    * @param tilmeld The Tilmeld user/group manager instance, if you want to use it.
+   * @param parent Used internally by Nymph. Don't set this.
    */
   public constructor(
     config: Partial<Config>,
     driver: NymphDriver,
-    tilmeld?: TilmeldInterface
+    tilmeld?: TilmeldInterface,
+    parent?: Nymph,
   ) {
     this.config = { ...defaults, ...config };
     this.driver = driver;
+    this.parent = parent ?? null;
 
     this.Entity = this.addEntityClass(Entity);
 
-    if (typeof tilmeld !== 'undefined') {
+    if (parent) {
+      for (const name in parent.entityClasses) {
+        if (
+          name === 'Entity' ||
+          (parent.entityClasses[name] as any).skipOnClone
+        ) {
+          continue;
+        }
+        this.addEntityClass(parent.entityClasses[name]);
+      }
+
+      const events = [
+        'connect',
+        'disconnect',
+        'query',
+        'beforeGetEntity',
+        'beforeGetEntities',
+        'beforeSaveEntity',
+        'afterSaveEntity',
+        'failedSaveEntity',
+        'beforeDeleteEntity',
+        'afterDeleteEntity',
+        'failedDeleteEntity',
+        'beforeDeleteEntityByID',
+        'afterDeleteEntityByID',
+        'failedDeleteEntityByID',
+        'beforeNewUID',
+        'afterNewUID',
+        'failedNewUID',
+        'beforeSetUID',
+        'afterSetUID',
+        'failedSetUID',
+        'beforeRenameUID',
+        'afterRenameUID',
+        'failedRenameUID',
+        'beforeDeleteUID',
+        'afterDeleteUID',
+        'failedDeleteUID',
+        'beforeStartTransaction',
+        'afterStartTransaction',
+        'beforeCommitTransaction',
+        'afterCommitTransaction',
+        'beforeRollbackTransaction',
+        'afterRollbackTransaction',
+      ];
+
+      for (let event of events) {
+        const prop = event + 'Callbacks';
+        // @ts-ignore: The callback should be the right type here.
+        const callbacks = parent[prop];
+        for (let callback of callbacks) {
+          if (callback.skipOnClone) {
+            continue;
+          }
+          this.on(event as NymphEventType, callback);
+        }
+      }
+    }
+
+    this.config.debugInfo('nymph', 'Nymph loaded.');
+
+    if (tilmeld != null) {
       this.tilmeld = tilmeld;
     }
 
     this.driver.init(this);
+    this.config.debugInfo('nymph', 'Nymph driver loaded.');
     if (this.tilmeld) {
       this.tilmeld.init(this);
+      this.config.debugInfo('nymph', 'Tilmeld loaded.');
     }
   }
 
@@ -124,82 +229,93 @@ export default class 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 {
+  public addEntityClass<T extends EntityConstructor>(EntityClass: T): T {
+    if (EntityClass.class in this.entityClasses) {
+      this.config.debugLog(
+        'nymph',
+        `Adding duplicate class "${EntityClass.class}". This may be a mistake.`,
+      );
+    }
+
+    // Check that it doesn't have the same etype as any other class.
+    for (const ExistingClass of Object.values(this.entityClasses)) {
+      if (
+        EntityClass.ETYPE === ExistingClass.ETYPE &&
+        EntityClass.class !== EntityClass.class
+      ) {
+        this.config.debugLog(
+          'nymph',
+          `Adding class "${EntityClass.class}" with same etype as existing class "${ExistingClass.class}". This may be a mistake.`,
+        );
+      }
+    }
+
     const nymph = this;
-    class NymphEntity extends entityClass {
+    this.entityClasses[EntityClass.class] = class extends EntityClass {
       static nymph: Nymph = nymph;
 
       constructor(...args: any[]) {
         super(...args);
       }
-    }
-    this.entityClasses[entityClass.class] = NymphEntity;
-    return NymphEntity;
+    };
+    return this.entityClasses[EntityClass.class] as T;
   }
 
   /**
    * Get the class that uses the specified class name.
    */
-  public getEntityClass(className: string): EntityConstructor {
-    if (className in this.entityClasses) {
-      return this.entityClasses[className];
+  public getEntityClass(className: string): EntityConstructor;
+  public getEntityClass<T extends EntityConstructor>(className: T): T;
+  public getEntityClass<T extends EntityConstructor = EntityConstructor>(
+    className: T | string,
+  ): T | EntityConstructor {
+    let key: string | null = null;
+    if (typeof className === 'string') {
+      key = className;
+    } else {
+      key = className.class;
     }
-    throw new ClassNotAvailableError('Tried to use class: ' + className);
+    if (key in this.entityClasses) {
+      return this.entityClasses[key];
+    }
+    this.config.debugError('nymph', `Tried to use missing class "${key}".`);
+    throw new ClassNotAvailableError(`Tried to use missing class "${key}".`);
   }
 
   /**
-   * Get a clone of this instance with duplicate classes and event listeners.
+   * Get the class that uses the specified etype.
+   *
+   * Note that it is fine, though unusual, for two classes to use the same
+   * etype. However, this can lead to very hard to diagnose bugs, so is
+   * generally discouraged.
+   */
+  public getEntityClassByEtype(etype: string): EntityConstructor {
+    for (const EntityClass of Object.values(this.entityClasses)) {
+      if (EntityClass.ETYPE === etype) {
+        return EntityClass;
+      }
+    }
+    this.config.debugError(
+      'nymph',
+      `Tried to use missing class by etype "${etype}".`,
+    );
+    throw new ClassNotAvailableError(
+      `Tried to use missing class by etype "${etype}".`,
+    );
+  }
+
+  /**
+   * Get a clone of this instance with cloned classes and event listeners.
    *
    * @returns A clone of this instance.
    */
   public clone() {
-    const nymph = new Nymph(
+    return new Nymph(
       this.config,
       this.driver.clone(),
-      this.tilmeld?.clone()
+      this.tilmeld?.clone(),
+      this,
     );
-    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;
   }
 
   /**
@@ -208,13 +324,19 @@ export default class Nymph {
    * @returns Whether the instance is connected to the database.
    */
   public async connect(): Promise<boolean> {
-    const result = this.driver.connect();
-    for (let callback of this.connectCallbacks) {
-      if (callback) {
-        await callback(this, result);
+    try {
+      const result = this.driver.connect();
+      for (let callback of this.connectCallbacks) {
+        if (callback) {
+          await callback(this, result);
+        }
       }
+      this.config.debugInfo('nymph', 'Driver connected.');
+      return await result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to connect: ${e}`);
+      throw e;
     }
-    return await result;
   }
 
   /**
@@ -223,13 +345,19 @@ export default class Nymph {
    * @returns Whether the instance is connected to the database.
    */
   public async disconnect(): Promise<boolean> {
-    const result = this.driver.disconnect();
-    for (let callback of this.disconnectCallbacks) {
-      if (callback) {
-        await callback(this, result);
+    try {
+      const result = this.driver.disconnect();
+      for (let callback of this.disconnectCallbacks) {
+        if (callback) {
+          await callback(this, result);
+        }
       }
+      this.config.debugInfo('nymph', 'Driver disconnected.');
+      return await result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to disconnect: ${e}`);
+      throw e;
     }
-    return await result;
   }
 
   /**
@@ -256,7 +384,24 @@ export default class Nymph {
    * @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);
+    try {
+      for (let callback of this.beforeStartTransactionCallbacks) {
+        if (callback) {
+          await callback(this, name);
+        }
+      }
+      this.config.debugLog('nymph', `Starting transaction "${name}".`);
+      const result = await this.driver.startTransaction(name);
+      for (let callback of this.afterStartTransactionCallbacks) {
+        if (callback) {
+          await callback(this, name, result);
+        }
+      }
+      return result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to start transaction: ${e}`);
+      throw e;
+    }
   }
 
   /**
@@ -267,7 +412,24 @@ export default class Nymph {
    * @returns True on success, false on failure.
    */
   public async commit(name: string): Promise<boolean> {
-    return await this.driver.commit(name);
+    try {
+      for (let callback of this.beforeCommitTransactionCallbacks) {
+        if (callback) {
+          await callback(this, name);
+        }
+      }
+      this.config.debugLog('nymph', `Committing transaction "${name}".`);
+      const result = await this.driver.commit(name);
+      for (let callback of this.afterCommitTransactionCallbacks) {
+        if (callback) {
+          await callback(this, name, result);
+        }
+      }
+      return result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to commit transaction: ${e}`);
+      throw e;
+    }
   }
 
   /**
@@ -278,7 +440,24 @@ export default class Nymph {
    * @returns True on success, false on failure.
    */
   public async rollback(name: string): Promise<boolean> {
-    return await this.driver.rollback(name);
+    try {
+      for (let callback of this.beforeRollbackTransactionCallbacks) {
+        if (callback) {
+          await callback(this, name);
+        }
+      }
+      this.config.debugLog('nymph', `Rolling back transaction "${name}".`);
+      const result = await this.driver.rollback(name);
+      for (let callback of this.afterRollbackTransactionCallbacks) {
+        if (callback) {
+          await callback(this, name, result);
+        }
+      }
+      return result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to roll back transaction: ${e}`);
+      throw e;
+    }
   }
 
   /**
@@ -312,18 +491,33 @@ export default class Nymph {
    * @returns The UID's new value, or null on failure.
    */
   public async newUID(name: string): Promise<number | null> {
-    for (let callback of this.beforeNewUIDCallbacks) {
-      if (callback) {
-        await callback(this, name);
+    try {
+      for (let callback of this.beforeNewUIDCallbacks) {
+        if (callback) {
+          await callback(this, name);
+        }
       }
-    }
-    const result = this.driver.newUID(name);
-    for (let callback of this.afterNewUIDCallbacks) {
-      if (callback) {
-        await callback(this, result);
+      let result: Promise<number | null>;
+      try {
+        result = this.driver.newUID(name);
+      } catch (e: any) {
+        for (let callback of this.failedNewUIDCallbacks) {
+          if (callback) {
+            await callback(this, e);
+          }
+        }
+        throw e;
+      }
+      for (let callback of this.afterNewUIDCallbacks) {
+        if (callback) {
+          await callback(this, result);
+        }
       }
+      return await result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to create UID "${name}": ${e}`);
+      throw e;
     }
-    return await result;
   }
 
   /**
@@ -332,7 +526,12 @@ export default class Nymph {
    * @returns The UID's value, or null on failure and if it doesn't exist.
    */
   public async getUID(name: string): Promise<number | null> {
-    return await this.driver.getUID(name);
+    try {
+      return await this.driver.getUID(name);
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to get UID "${name}": ${e}`);
+      throw e;
+    }
   }
 
   /**
@@ -343,18 +542,33 @@ export default class Nymph {
    * @returns True on success, false on failure.
    */
   public async setUID(name: string, value: number): Promise<boolean> {
-    for (let callback of this.beforeSetUIDCallbacks) {
-      if (callback) {
-        await callback(this, name, value);
+    try {
+      for (let callback of this.beforeSetUIDCallbacks) {
+        if (callback) {
+          await callback(this, name, value);
+        }
       }
-    }
-    const result = this.driver.setUID(name, value);
-    for (let callback of this.afterSetUIDCallbacks) {
-      if (callback) {
-        await callback(this, result);
+      let result: Promise<boolean>;
+      try {
+        result = this.driver.setUID(name, value);
+      } catch (e: any) {
+        for (let callback of this.failedSetUIDCallbacks) {
+          if (callback) {
+            await callback(this, e);
+          }
+        }
+        throw e;
       }
+      for (let callback of this.afterSetUIDCallbacks) {
+        if (callback) {
+          await callback(this, result);
+        }
+      }
+      return await result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to set UID "${name}": ${e}`);
+      throw e;
     }
-    return await result;
   }
 
   /**
@@ -364,18 +578,33 @@ export default class Nymph {
    * @returns True on success, false on failure.
    */
   public async deleteUID(name: string): Promise<boolean> {
-    for (let callback of this.beforeDeleteUIDCallbacks) {
-      if (callback) {
-        await callback(this, name);
+    try {
+      for (let callback of this.beforeDeleteUIDCallbacks) {
+        if (callback) {
+          await callback(this, name);
+        }
       }
-    }
-    const result = this.driver.deleteUID(name);
-    for (let callback of this.afterDeleteUIDCallbacks) {
-      if (callback) {
-        await callback(this, result);
+      let result: Promise<boolean>;
+      try {
+        result = this.driver.deleteUID(name);
+      } catch (e: any) {
+        for (let callback of this.failedDeleteUIDCallbacks) {
+          if (callback) {
+            await callback(this, e);
+          }
+        }
+        throw e;
+      }
+      for (let callback of this.afterDeleteUIDCallbacks) {
+        if (callback) {
+          await callback(this, result);
+        }
       }
+      return await result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to delete UID "${name}": ${e}`);
+      throw e;
     }
-    return await result;
   }
 
   /**
@@ -386,18 +615,36 @@ export default class Nymph {
    * @returns True on success, false on failure.
    */
   public async renameUID(oldName: string, newName: string): Promise<boolean> {
-    for (let callback of this.beforeRenameUIDCallbacks) {
-      if (callback) {
-        await callback(this, oldName, newName);
+    try {
+      for (let callback of this.beforeRenameUIDCallbacks) {
+        if (callback) {
+          await callback(this, oldName, newName);
+        }
       }
-    }
-    const result = this.driver.renameUID(oldName, newName);
-    for (let callback of this.afterRenameUIDCallbacks) {
-      if (callback) {
-        await callback(this, result);
+      let result: Promise<boolean>;
+      try {
+        result = this.driver.renameUID(oldName, newName);
+      } catch (e: any) {
+        for (let callback of this.failedRenameUIDCallbacks) {
+          if (callback) {
+            await callback(this, e);
+          }
+        }
+        throw e;
+      }
+      for (let callback of this.afterRenameUIDCallbacks) {
+        if (callback) {
+          await callback(this, result);
+        }
       }
+      return await result;
+    } catch (e: any) {
+      this.config.debugError(
+        'nymph',
+        `Failed to rename UID "${oldName}" to "${newName}": ${e}`,
+      );
+      throw e;
     }
-    return await result;
   }
 
   /**
@@ -412,18 +659,33 @@ export default class Nymph {
    * @returns True on success, false on failure.
    */
   public async saveEntity(entity: EntityInterface): Promise<boolean> {
-    for (let callback of this.beforeSaveEntityCallbacks) {
-      if (callback) {
-        await callback(this, entity);
+    try {
+      for (let callback of this.beforeSaveEntityCallbacks) {
+        if (callback) {
+          await callback(this, entity);
+        }
       }
-    }
-    const result = this.driver.saveEntity(entity);
-    for (let callback of this.afterSaveEntityCallbacks) {
-      if (callback) {
-        await callback(this, result);
+      let result: Promise<boolean>;
+      try {
+        result = this.driver.saveEntity(entity);
+      } catch (e: any) {
+        for (let callback of this.failedSaveEntityCallbacks) {
+          if (callback) {
+            await callback(this, e);
+          }
+        }
+        throw e;
       }
+      for (let callback of this.afterSaveEntityCallbacks) {
+        if (callback) {
+          await callback(this, result);
+        }
+      }
+      return await result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to save entity: ${e}`);
+      throw e;
     }
-    return await result;
   }
 
   /**
@@ -436,8 +698,10 @@ export default class Nymph {
    * - offset - The offset from the oldest matching entity to start retrieving.
    * - reverse - If true, entities will be retrieved from newest to oldest.
    *   Therefore, offset will be from the newest entity.
-   * - sort - How to sort the entities. Accepts "cdate" or "mdate". Defaults to
-   *   "cdate".
+   * - sort - How to sort the entities. Accepts "cdate", "mdate", or the name of
+   *   a top-level property. The method of sorting properties other than cdate
+   *   and mdate is driver dependent. The only hard rule is that numbers should
+   *   be sorted numerically (2 before 10). Defaults to "cdate".
    * - return - What to return. "entity", "guid", or "count". Defaults to
    *   "entity".
    * - source - Will be 'client' if the query came from a REST call.
@@ -596,17 +860,22 @@ export default class Nymph {
   public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options?: Options<T>,
     ...selectors: Selector[]
-  ): Promise<ReturnType<T['factorySync']>[]>;
+  ): Promise<EntityInstanceType<T>[]>;
   public async getEntities<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> = {},
     ...selectors: Selector[]
-  ): Promise<ReturnType<T['factorySync']>[] | string[] | number> {
-    for (let callback of this.beforeGetEntitiesCallbacks) {
-      if (callback) {
-        await callback(this, options, selectors);
+  ): Promise<EntityInstanceType<T>[] | string[] | number> {
+    try {
+      for (let callback of this.beforeGetEntitiesCallbacks) {
+        if (callback) {
+          await callback(this, options, selectors);
+        }
       }
+      return await this.driver.getEntities(options, ...selectors);
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to get entities: ${e}`);
+      throw e;
     }
-    return await this.driver.getEntities(options, ...selectors);
   }
 
   /**
@@ -633,40 +902,45 @@ export default class Nymph {
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
     ...selectors: Selector[]
-  ): Promise<ReturnType<T['factorySync']> | null>;
+  ): Promise<EntityInstanceType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> & { return: 'guid' },
-    guid: string
+    guid: string,
   ): Promise<string | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T>,
-    guid: string
-  ): Promise<ReturnType<T['factorySync']> | null>;
+    guid: string,
+  ): Promise<EntityInstanceType<T> | null>;
   public async getEntity<T extends EntityConstructor = EntityConstructor>(
     options: Options<T> = {},
     ...selectors: Selector[] | string[]
-  ): Promise<ReturnType<T['factorySync']> | string | number | null> {
-    // Set up options and selectors.
-    if (typeof selectors[0] === 'string') {
-      selectors = [{ type: '&', guid: selectors[0] }];
-    }
-    options.limit = 1;
-    for (let callback of this.beforeGetEntityCallbacks) {
-      if (callback) {
-        await callback(this, options, selectors as Selector[]);
+  ): Promise<EntityInstanceType<T> | string | number | null> {
+    try {
+      // Set up options and selectors.
+      if (typeof selectors[0] === 'string') {
+        selectors = [{ type: '&', guid: selectors[0] }];
       }
+      options.limit = 1;
+      for (let callback of this.beforeGetEntityCallbacks) {
+        if (callback) {
+          await callback(this, options, selectors as Selector[]);
+        }
+      }
+      const entities = await this.driver.getEntities(
+        options,
+        ...(selectors as Selector[]),
+      );
+      if (options.return === 'count') {
+        return entities as unknown as number;
+      }
+      if (!entities || !entities.length) {
+        return null;
+      }
+      return entities[0];
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to get entity: ${e}`);
+      throw e;
     }
-    const entities = await this.driver.getEntities(
-      options,
-      ...(selectors as Selector[])
-    );
-    if (options.return === 'count') {
-      return entities as unknown as number;
-    }
-    if (!entities || !entities.length) {
-      return null;
-    }
-    return entities[0];
   }
 
   /**
@@ -676,18 +950,33 @@ export default class Nymph {
    * @returns True on success, false on failure.
    */
   public async deleteEntity(entity: EntityInterface): Promise<boolean> {
-    for (let callback of this.beforeDeleteEntityCallbacks) {
-      if (callback) {
-        await callback(this, entity);
+    try {
+      for (let callback of this.beforeDeleteEntityCallbacks) {
+        if (callback) {
+          await callback(this, entity);
+        }
       }
-    }
-    const result = this.driver.deleteEntity(entity);
-    for (let callback of this.afterDeleteEntityCallbacks) {
-      if (callback) {
-        await callback(this, result);
+      let result: Promise<boolean>;
+      try {
+        result = this.driver.deleteEntity(entity);
+      } catch (e: any) {
+        for (let callback of this.failedDeleteEntityCallbacks) {
+          if (callback) {
+            await callback(this, e);
+          }
+        }
+        throw e;
       }
+      for (let callback of this.afterDeleteEntityCallbacks) {
+        if (callback) {
+          await callback(this, result);
+        }
+      }
+      return await result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to delete entity: ${e}`);
+      throw e;
     }
-    return await result;
   }
 
   /**
@@ -699,20 +988,35 @@ export default class Nymph {
    */
   public async deleteEntityByID(
     guid: string,
-    className?: string
+    className?: string,
   ): Promise<boolean> {
-    for (let callback of this.beforeDeleteEntityByIDCallbacks) {
-      if (callback) {
-        await callback(this, guid, className);
+    try {
+      for (let callback of this.beforeDeleteEntityByIDCallbacks) {
+        if (callback) {
+          await callback(this, guid, className);
+        }
       }
-    }
-    const result = this.driver.deleteEntityByID(guid, className);
-    for (let callback of this.afterDeleteEntityByIDCallbacks) {
-      if (callback) {
-        await callback(this, result);
+      let result: Promise<boolean>;
+      try {
+        result = this.driver.deleteEntityByID(guid, className);
+      } catch (e: any) {
+        for (let callback of this.failedDeleteEntityByIDCallbacks) {
+          if (callback) {
+            await callback(this, e);
+          }
+        }
+        throw e;
+      }
+      for (let callback of this.afterDeleteEntityByIDCallbacks) {
+        if (callback) {
+          await callback(this, result);
+        }
       }
+      return await result;
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to delete entity by ID: ${e}`);
+      throw e;
     }
-    return await result;
   }
 
   /**
@@ -737,7 +1041,7 @@ export default class Nymph {
    * #  brackets ([]).
    * # Properties are stored like this:
    * # propname=JSON.stringify(value)
-   *     abilities=["system/all"]
+   *     abilities=["system/admin"]
    *     groups=[]
    *     inheritAbilities=false
    *     name="admin"
@@ -752,7 +1056,12 @@ export default class Nymph {
    * @returns True on success, false on failure.
    */
   public async export(filename: string): Promise<boolean> {
-    return await this.driver.export(filename);
+    try {
+      return await this.driver.export(filename);
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to export: ${e}`);
+      throw e;
+    }
   }
 
   /**
@@ -761,7 +1070,12 @@ export default class Nymph {
    * @returns True on success, false on failure.
    */
   public async exportPrint(): Promise<boolean> {
-    return await this.driver.exportPrint();
+    try {
+      return await this.driver.exportPrint();
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to export: ${e}`);
+      throw e;
+    }
   }
 
   /**
@@ -771,7 +1085,22 @@ export default class Nymph {
    * @returns True on success, false on failure.
    */
   public async import(filename: string): Promise<boolean> {
-    return await this.driver.import(filename);
+    try {
+      return await this.driver.import(filename);
+    } catch (e: any) {
+      this.config.debugError('nymph', `Failed to import: ${e}`);
+      throw e;
+    }
+  }
+
+  /**
+   * Detect whether the database needs to be migrated.
+   *
+   * If true, the database should be exported with an old version of Nymph, then
+   * imported into a fresh database with this version.
+   */
+  public async needsMigration(): Promise<boolean> {
+    return await this.driver.needsMigration();
   }
 
   public on<T extends NymphEventType>(
@@ -790,31 +1119,57 @@ export default class Nymph {
       ? NymphBeforeSaveEntityCallback
       : T extends 'afterSaveEntity'
       ? NymphAfterSaveEntityCallback
+      : T extends 'failedSaveEntity'
+      ? NymphFailedSaveEntityCallback
       : T extends 'beforeDeleteEntity'
       ? NymphBeforeDeleteEntityCallback
       : T extends 'afterDeleteEntity'
       ? NymphAfterDeleteEntityCallback
+      : T extends 'failedDeleteEntity'
+      ? NymphFailedDeleteEntityCallback
       : T extends 'beforeDeleteEntityByID'
       ? NymphBeforeDeleteEntityByIDCallback
       : T extends 'afterDeleteEntityByID'
       ? NymphAfterDeleteEntityByIDCallback
+      : T extends 'failedDeleteEntityByID'
+      ? NymphFailedDeleteEntityByIDCallback
       : T extends 'beforeNewUID'
       ? NymphBeforeNewUIDCallback
       : T extends 'afterNewUID'
       ? NymphAfterNewUIDCallback
+      : T extends 'failedNewUID'
+      ? NymphFailedNewUIDCallback
       : T extends 'beforeSetUID'
       ? NymphBeforeSetUIDCallback
       : T extends 'afterSetUID'
       ? NymphAfterSetUIDCallback
+      : T extends 'failedSetUID'
+      ? NymphFailedSetUIDCallback
       : T extends 'beforeRenameUID'
       ? NymphBeforeRenameUIDCallback
       : T extends 'afterRenameUID'
       ? NymphAfterRenameUIDCallback
+      : T extends 'failedRenameUID'
+      ? NymphFailedRenameUIDCallback
       : T extends 'beforeDeleteUID'
       ? NymphBeforeDeleteUIDCallback
       : T extends 'afterDeleteUID'
       ? NymphAfterDeleteUIDCallback
-      : never
+      : T extends 'failedDeleteUID'
+      ? NymphFailedDeleteUIDCallback
+      : T extends 'beforeStartTransaction'
+      ? NymphBeforeStartTransactionCallback
+      : T extends 'afterStartTransaction'
+      ? NymphAfterStartTransactionCallback
+      : T extends 'beforeCommitTransaction'
+      ? NymphBeforeCommitTransactionCallback
+      : T extends 'afterCommitTransaction'
+      ? NymphAfterCommitTransactionCallback
+      : T extends 'beforeRollbackTransaction'
+      ? NymphBeforeRollbackTransactionCallback
+      : T extends 'afterRollbackTransaction'
+      ? NymphAfterRollbackTransactionCallback
+      : never,
   ) {
     const prop = (event + 'Callbacks') as T extends 'connect'
       ? 'connectCallbacks'
@@ -830,30 +1185,56 @@ export default class Nymph {
       ? 'beforeSaveEntityCallbacks'
       : T extends 'afterSaveEntity'
       ? 'afterSaveEntityCallbacks'
+      : T extends 'failedSaveEntity'
+      ? 'failedSaveEntityCallbacks'
       : T extends 'beforeDeleteEntity'
       ? 'beforeDeleteEntityCallbacks'
       : T extends 'afterDeleteEntity'
       ? 'afterDeleteEntityCallbacks'
+      : T extends 'failedDeleteEntity'
+      ? 'failedDeleteEntityCallbacks'
       : T extends 'beforeDeleteEntityByID'
       ? 'beforeDeleteEntityByIDCallbacks'
       : T extends 'afterDeleteEntityByID'
       ? 'afterDeleteEntityByIDCallbacks'
+      : T extends 'failedDeleteEntityByID'
+      ? 'failedDeleteEntityByIDCallbacks'
       : T extends 'beforeNewUID'
       ? 'beforeNewUIDCallbacks'
       : T extends 'afterNewUID'
       ? 'afterNewUIDCallbacks'
+      : T extends 'failedNewUID'
+      ? 'failedNewUIDCallbacks'
       : T extends 'beforeSetUID'
       ? 'beforeSetUIDCallbacks'
       : T extends 'afterSetUID'
       ? 'afterSetUIDCallbacks'
+      : T extends 'failedSetUID'
+      ? 'failedSetUIDCallbacks'
       : T extends 'beforeRenameUID'
       ? 'beforeRenameUIDCallbacks'
       : T extends 'afterRenameUID'
       ? 'afterRenameUIDCallbacks'
+      : T extends 'failedRenameUID'
+      ? 'failedRenameUIDCallbacks'
       : T extends 'beforeDeleteUID'
       ? 'beforeDeleteUIDCallbacks'
       : T extends 'afterDeleteUID'
       ? 'afterDeleteUIDCallbacks'
+      : T extends 'failedDeleteUID'
+      ? 'failedDeleteUIDCallbacks'
+      : T extends 'beforeStartTransaction'
+      ? 'beforeStartTransactionCallbacks'
+      : T extends 'afterStartTransaction'
+      ? 'afterStartTransactionCallbacks'
+      : T extends 'beforeCommitTransaction'
+      ? 'beforeCommitTransactionCallbacks'
+      : T extends 'afterCommitTransaction'
+      ? 'afterCommitTransactionCallbacks'
+      : T extends 'beforeRollbackTransaction'
+      ? 'beforeRollbackTransactionCallbacks'
+      : T extends 'afterRollbackTransaction'
+      ? 'afterRollbackTransactionCallbacks'
       : never;
     if (!(prop in this)) {
       throw new Error('Invalid event type.');
@@ -879,31 +1260,57 @@ export default class Nymph {
       ? NymphBeforeSaveEntityCallback
       : T extends 'afterSaveEntity'
       ? NymphAfterSaveEntityCallback
+      : T extends 'failedSaveEntity'
+      ? NymphFailedSaveEntityCallback
       : T extends 'beforeDeleteEntity'
       ? NymphBeforeDeleteEntityCallback
       : T extends 'afterDeleteEntity'
       ? NymphAfterDeleteEntityCallback
+      : T extends 'failedDeleteEntity'
+      ? NymphFailedDeleteEntityCallback
       : T extends 'beforeDeleteEntityByID'
       ? NymphBeforeDeleteEntityByIDCallback
       : T extends 'afterDeleteEntityByID'
       ? NymphAfterDeleteEntityByIDCallback
+      : T extends 'failedDeleteEntityByID'
+      ? NymphFailedDeleteEntityByIDCallback
       : T extends 'beforeNewUID'
       ? NymphBeforeNewUIDCallback
       : T extends 'afterNewUID'
       ? NymphAfterNewUIDCallback
+      : T extends 'failedNewUID'
+      ? NymphFailedNewUIDCallback
       : T extends 'beforeSetUID'
       ? NymphBeforeSetUIDCallback
       : T extends 'afterSetUID'
       ? NymphAfterSetUIDCallback
+      : T extends 'failedSetUID'
+      ? NymphFailedSetUIDCallback
       : T extends 'beforeRenameUID'
       ? NymphBeforeRenameUIDCallback
       : T extends 'afterRenameUID'
       ? NymphAfterRenameUIDCallback
+      : T extends 'failedRenameUID'
+      ? NymphFailedRenameUIDCallback
       : T extends 'beforeDeleteUID'
       ? NymphBeforeDeleteUIDCallback
       : T extends 'afterDeleteUID'
       ? NymphAfterDeleteUIDCallback
-      : never
+      : T extends 'failedDeleteUID'
+      ? NymphFailedDeleteUIDCallback
+      : T extends 'beforeStartTransaction'
+      ? NymphBeforeStartTransactionCallback
+      : T extends 'afterStartTransaction'
+      ? NymphAfterStartTransactionCallback
+      : T extends 'beforeCommitTransaction'
+      ? NymphBeforeCommitTransactionCallback
+      : T extends 'afterCommitTransaction'
+      ? NymphAfterCommitTransactionCallback
+      : T extends 'beforeRollbackTransaction'
+      ? NymphBeforeRollbackTransactionCallback
+      : T extends 'afterRollbackTransaction'
+      ? NymphAfterRollbackTransactionCallback
+      : never,
   ) {
     const prop = (event + 'Callbacks') as T extends 'connect'
       ? 'connectCallbacks'
@@ -919,30 +1326,56 @@ export default class Nymph {
       ? 'beforeGetEntitiesCallbacks'
       : T extends 'afterSaveEntity'
       ? 'afterSaveEntityCallbacks'
+      : T extends 'failedSaveEntity'
+      ? 'failedSaveEntityCallbacks'
       : T extends 'beforeDeleteEntity'
       ? 'beforeDeleteEntityCallbacks'
       : T extends 'afterDeleteEntity'
       ? 'afterDeleteEntityCallbacks'
+      : T extends 'failedDeleteEntity'
+      ? 'failedDeleteEntityCallbacks'
       : T extends 'beforeDeleteEntityByID'
       ? 'beforeDeleteEntityByIDCallbacks'
       : T extends 'afterDeleteEntityByID'
       ? 'afterDeleteEntityByIDCallbacks'
+      : T extends 'failedDeleteEntityByID'
+      ? 'failedDeleteEntityByIDCallbacks'
       : T extends 'beforeNewUID'
       ? 'beforeNewUIDCallbacks'
       : T extends 'afterNewUID'
       ? 'afterNewUIDCallbacks'
+      : T extends 'failedNewUID'
+      ? 'failedNewUIDCallbacks'
       : T extends 'beforeSetUID'
       ? 'beforeSetUIDCallbacks'
       : T extends 'afterSetUID'
       ? 'afterSetUIDCallbacks'
+      : T extends 'failedSetUID'
+      ? 'failedSetUIDCallbacks'
       : T extends 'beforeRenameUID'
       ? 'beforeRenameUIDCallbacks'
       : T extends 'afterRenameUID'
       ? 'afterRenameUIDCallbacks'
+      : T extends 'failedRenameUID'
+      ? 'failedRenameUIDCallbacks'
       : T extends 'beforeDeleteUID'
       ? 'beforeDeleteUIDCallbacks'
       : T extends 'afterDeleteUID'
       ? 'afterDeleteUIDCallbacks'
+      : T extends 'failedDeleteUID'
+      ? 'failedDeleteUIDCallbacks'
+      : T extends 'beforeStartTransaction'
+      ? 'beforeStartTransactionCallbacks'
+      : T extends 'afterStartTransaction'
+      ? 'afterStartTransactionCallbacks'
+      : T extends 'beforeCommitTransaction'
+      ? 'beforeCommitTransactionCallbacks'
+      : T extends 'afterCommitTransaction'
+      ? 'afterCommitTransactionCallbacks'
+      : T extends 'beforeRollbackTransaction'
+      ? 'beforeRollbackTransactionCallbacks'
+      : T extends 'afterRollbackTransaction'
+      ? 'afterRollbackTransactionCallbacks'
       : never;
     if (!(prop in this)) {
       return false;