@nymphjs/nymph 1.0.0-beta.55 → 1.0.0-beta.56

package/dist/Nymph.js

@@ -6,9 +6,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const conf_1 = require("./conf");
 const Entity_1 = __importDefault(require("./Entity"));
 const errors_1 = require("./errors");
+/**
+ * An object relational mapper for Node.js.
+ *
+ * Written by Hunter Perrin for SciActive.
+ *
+ * @author Hunter Perrin <hperrin@gmail.com>
+ * @copyright SciActive Inc
+ * @see http://nymph.io/
+ */
 class Nymph {
+    /**
+     * Initialize 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.
+     */
     constructor(config, driver, tilmeld, parent) {
+        /**
+         * An optional Tilmeld user/group manager instance.
+         */
         this.tilmeld = undefined;
+        /**
+         * A simple map of names to Entity classes.
+         */
         this.entityClasses = {};
         this.connectCallbacks = [];
         this.disconnectCallbacks = [];
@@ -90,6 +113,7 @@ class Nymph {
             ];
             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) {
@@ -99,14 +123,27 @@ class Nymph {
                 }
             }
         }
+        this.config.debugLog('nymph', 'Nymph loaded.');
         if (tilmeld != null) {
             this.tilmeld = tilmeld;
         }
         this.driver.init(this);
         if (this.tilmeld) {
+            this.config.debugLog('nymph', 'Tilmeld initializing.');
             this.tilmeld.init(this);
+            this.config.debugLog('nymph', 'Tilmeld initialized.');
         }
     }
+    /**
+     * 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`.
+     */
     addEntityClass(entityClass) {
         const nymph = this;
         class NymphEntity extends entityClass {
@@ -116,6 +153,7 @@ class Nymph {
         }
         NymphEntity.nymph = nymph;
         this.entityClasses[entityClass.class] = NymphEntity;
+        this.config.debugLog('nymph', `Added entity class "${entityClass.class}".`);
         return NymphEntity;
     }
     getEntityClass(className) {
@@ -129,29 +167,62 @@ class Nymph {
         if (key in this.entityClasses) {
             return this.entityClasses[key];
         }
-        throw new errors_1.ClassNotAvailableError('Tried to use class: ' + key);
+        this.config.debugError('nymph', `Tried to use missing class "${key}".`);
+        throw new errors_1.ClassNotAvailableError(`Tried to use missing class "${key}".`);
     }
+    /**
+     * Get a clone of this instance with cloned classes and event listeners.
+     *
+     * @returns A clone of this instance.
+     */
     clone() {
         return new Nymph(this.config, this.driver.clone(), this.tilmeld?.clone(), this);
     }
+    /**
+     * Connect to the database.
+     *
+     * @returns Whether the instance is connected to the database.
+     */
     async connect() {
-        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.debugLog('nymph', 'Driver connected.');
+            return await result;
+        }
+        catch (e) {
+            this.config.debugError('nymph', `Failed to connect: ${e}`);
+            throw e;
         }
-        return await result;
     }
+    /**
+     * Disconnect from the database.
+     *
+     * @returns Whether the instance is connected to the database.
+     */
     async disconnect() {
-        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.debugLog('nymph', 'Driver disconnected.');
+            return await result;
+        }
+        catch (e) {
+            this.config.debugError('nymph', `Failed to disconnect: ${e}`);
+            throw e;
         }
-        return await result;
     }
+    /**
+     * Run all the query callbacks on a query.
+     */
     runQueryCallbacks(options, selectors) {
         for (let callback of this.queryCallbacks) {
             if (callback) {
@@ -159,270 +230,519 @@ class Nymph {
             }
         }
     }
+    /**
+     * Start an atomic transaction and returns a new instance of Nymph.
+     *
+     * 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 A new instance of Nymph that should be used for the transaction.
+     */
     async startTransaction(name) {
-        for (let callback of this.beforeStartTransactionCallbacks) {
-            if (callback) {
-                await callback(this, name);
+        try {
+            for (let callback of this.beforeStartTransactionCallbacks) {
+                if (callback) {
+                    await callback(this, name);
+                }
             }
-        }
-        const result = await this.driver.startTransaction(name);
-        for (let callback of this.afterStartTransactionCallbacks) {
-            if (callback) {
-                await callback(this, name, result);
+            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) {
+            this.config.debugError('nymph', `Failed to start transaction: ${e}`);
+            throw e;
         }
-        return result;
     }
+    /**
+     * Commit the named transaction.
+     *
+     * After this is called, the transaction instance should be discarded.
+     *
+     * @returns True on success, false on failure.
+     */
     async commit(name) {
-        for (let callback of this.beforeCommitTransactionCallbacks) {
-            if (callback) {
-                await callback(this, name);
+        try {
+            for (let callback of this.beforeCommitTransactionCallbacks) {
+                if (callback) {
+                    await callback(this, name);
+                }
             }
-        }
-        const result = await this.driver.commit(name);
-        for (let callback of this.afterCommitTransactionCallbacks) {
-            if (callback) {
-                await callback(this, name, result);
+            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) {
+            this.config.debugError('nymph', `Failed to commit transaction: ${e}`);
+            throw e;
         }
-        return result;
     }
+    /**
+     * Rollback the named transaction.
+     *
+     * After this is called, the transaction instance should be discarded.
+     *
+     * @returns True on success, false on failure.
+     */
     async rollback(name) {
-        for (let callback of this.beforeRollbackTransactionCallbacks) {
-            if (callback) {
-                await callback(this, name);
+        try {
+            for (let callback of this.beforeRollbackTransactionCallbacks) {
+                if (callback) {
+                    await callback(this, name);
+                }
             }
-        }
-        const result = await this.driver.rollback(name);
-        for (let callback of this.afterRollbackTransactionCallbacks) {
-            if (callback) {
-                await callback(this, name, result);
+            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) {
+            this.config.debugError('nymph', `Failed to roll back transaction: ${e}`);
+            throw e;
         }
-        return result;
     }
+    /**
+     * Check if there is any open transaction.
+     *
+     * @returns True if there is a transaction.
+     */
     async inTransaction() {
         return await this.driver.inTransaction();
     }
+    /**
+     * Increment or create a unique ID and return the new value.
+     *
+     * Unique IDs, or UIDs are similar to GUIDs, but numeric and sequential.
+     *
+     * A UID can be used to identify an object when the GUID doesn't suffice. On
+     * a system where a new entity is created many times per second, referring
+     * to something by its GUID may be unintuitive. However, the component
+     * designer is responsible for assigning UIDs to the component's entities.
+     * Beware that if a UID is incremented for an entity, and the entity cannot
+     * be saved, there is no safe, and therefore, no recommended way to
+     * decrement the UID back to its previous value.
+     *
+     * If newUID() is passed the name of a UID which does not exist yet, one
+     * will be created with that name, and assigned the value 1. If the UID
+     * already exists, its value will be incremented. The new value will be
+     * returned.
+     *
+     * @param name The UID's name.
+     * @returns The UID's new value, or null on failure.
+     */
     async newUID(name) {
-        for (let callback of this.beforeNewUIDCallbacks) {
-            if (callback) {
-                await callback(this, name);
-            }
-        }
-        let result;
         try {
-            result = this.driver.newUID(name);
-        }
-        catch (e) {
-            for (let callback of this.failedNewUIDCallbacks) {
+            for (let callback of this.beforeNewUIDCallbacks) {
                 if (callback) {
-                    await callback(this, e);
+                    await callback(this, name);
                 }
             }
-            throw e;
-        }
-        for (let callback of this.afterNewUIDCallbacks) {
-            if (callback) {
-                await callback(this, result);
+            let result;
+            try {
+                result = this.driver.newUID(name);
+            }
+            catch (e) {
+                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) {
+            this.config.debugError('nymph', `Failed to create UID "${name}": ${e}`);
+            throw e;
         }
-        return await result;
     }
+    /**
+     * Get the current value of a unique ID.
+     * @param name The UID's name.
+     * @returns The UID's value, or null on failure and if it doesn't exist.
+     */
     async getUID(name) {
-        return await this.driver.getUID(name);
-    }
-    async setUID(name, value) {
-        for (let callback of this.beforeSetUIDCallbacks) {
-            if (callback) {
-                await callback(this, name, value);
-            }
-        }
-        let result;
         try {
-            result = this.driver.setUID(name, value);
+            return await this.driver.getUID(name);
         }
         catch (e) {
-            for (let callback of this.failedSetUIDCallbacks) {
+            this.config.debugError('nymph', `Failed to get UID "${name}": ${e}`);
+            throw e;
+        }
+    }
+    /**
+     * Set the value of a UID.
+     *
+     * @param name The UID's name.
+     * @param value The value.
+     * @returns True on success, false on failure.
+     */
+    async setUID(name, value) {
+        try {
+            for (let callback of this.beforeSetUIDCallbacks) {
                 if (callback) {
-                    await callback(this, e);
+                    await callback(this, name, value);
                 }
             }
-            throw e;
-        }
-        for (let callback of this.afterSetUIDCallbacks) {
-            if (callback) {
-                await callback(this, result);
+            let result;
+            try {
+                result = this.driver.setUID(name, value);
             }
+            catch (e) {
+                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) {
+            this.config.debugError('nymph', `Failed to set UID "${name}": ${e}`);
+            throw e;
         }
-        return await result;
     }
+    /**
+     * Delete a unique ID.
+     *
+     * @param name The UID's name.
+     * @returns True on success, false on failure.
+     */
     async deleteUID(name) {
-        for (let callback of this.beforeDeleteUIDCallbacks) {
-            if (callback) {
-                await callback(this, name);
-            }
-        }
-        let result;
         try {
-            result = this.driver.deleteUID(name);
-        }
-        catch (e) {
-            for (let callback of this.failedDeleteUIDCallbacks) {
+            for (let callback of this.beforeDeleteUIDCallbacks) {
                 if (callback) {
-                    await callback(this, e);
+                    await callback(this, name);
                 }
             }
-            throw e;
-        }
-        for (let callback of this.afterDeleteUIDCallbacks) {
-            if (callback) {
-                await callback(this, result);
+            let result;
+            try {
+                result = this.driver.deleteUID(name);
+            }
+            catch (e) {
+                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) {
+            this.config.debugError('nymph', `Failed to delete UID "${name}": ${e}`);
+            throw e;
         }
-        return await result;
     }
+    /**
+     * Rename a unique ID.
+     *
+     * @param oldName The old name.
+     * @param newName The new name.
+     * @returns True on success, false on failure.
+     */
     async renameUID(oldName, newName) {
-        for (let callback of this.beforeRenameUIDCallbacks) {
-            if (callback) {
-                await callback(this, oldName, newName);
-            }
-        }
-        let result;
         try {
-            result = this.driver.renameUID(oldName, newName);
-        }
-        catch (e) {
-            for (let callback of this.failedRenameUIDCallbacks) {
+            for (let callback of this.beforeRenameUIDCallbacks) {
                 if (callback) {
-                    await callback(this, e);
+                    await callback(this, oldName, newName);
                 }
             }
-            throw e;
-        }
-        for (let callback of this.afterRenameUIDCallbacks) {
-            if (callback) {
-                await callback(this, result);
+            let result;
+            try {
+                result = this.driver.renameUID(oldName, newName);
+            }
+            catch (e) {
+                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) {
+            this.config.debugError('nymph', `Failed to rename UID "${oldName}" to "${newName}": ${e}`);
+            throw e;
         }
-        return await result;
     }
+    /**
+     * Save an entity to the database.
+     *
+     * If the entity has never been saved (has no GUID), a variable "cdate"
+     * is set on it with the current Unix timestamp.
+     *
+     * The variable "mdate" is set to the current Unix timestamp.
+     *
+     * @param entity The entity.
+     * @returns True on success, false on failure.
+     */
     async saveEntity(entity) {
-        for (let callback of this.beforeSaveEntityCallbacks) {
-            if (callback) {
-                await callback(this, entity);
-            }
-        }
-        let result;
         try {
-            result = this.driver.saveEntity(entity);
-        }
-        catch (e) {
-            for (let callback of this.failedSaveEntityCallbacks) {
+            for (let callback of this.beforeSaveEntityCallbacks) {
                 if (callback) {
-                    await callback(this, e);
+                    await callback(this, entity);
                 }
             }
-            throw e;
-        }
-        for (let callback of this.afterSaveEntityCallbacks) {
-            if (callback) {
-                await callback(this, result);
+            let result;
+            try {
+                result = this.driver.saveEntity(entity);
             }
+            catch (e) {
+                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) {
+            this.config.debugError('nymph', `Failed to save entity: ${e}`);
+            throw e;
         }
-        return await result;
     }
     async getEntities(options = {}, ...selectors) {
-        for (let callback of this.beforeGetEntitiesCallbacks) {
-            if (callback) {
-                await callback(this, options, selectors);
+        try {
+            for (let callback of this.beforeGetEntitiesCallbacks) {
+                if (callback) {
+                    await callback(this, options, selectors);
+                }
             }
+            return await this.driver.getEntities(options, ...selectors);
+        }
+        catch (e) {
+            this.config.debugError('nymph', `Failed to get entities: ${e}`);
+            throw e;
         }
-        return await this.driver.getEntities(options, ...selectors);
     }
     async getEntity(options = {}, ...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);
+        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);
+                }
+            }
+            const entities = await this.driver.getEntities(options, ...selectors);
+            if (options.return === 'count') {
+                return entities;
+            }
+            if (!entities || !entities.length) {
+                return null;
+            }
+            return entities[0];
         }
-        const entities = await this.driver.getEntities(options, ...selectors);
-        if (options.return === 'count') {
-            return entities;
-        }
-        if (!entities || !entities.length) {
-            return null;
+        catch (e) {
+            this.config.debugError('nymph', `Failed to get entity: ${e}`);
+            throw e;
         }
-        return entities[0];
     }
+    /**
+     * Delete an entity from the database.
+     *
+     * @param entity The entity.
+     * @returns True on success, false on failure.
+     */
     async deleteEntity(entity) {
-        for (let callback of this.beforeDeleteEntityCallbacks) {
-            if (callback) {
-                await callback(this, entity);
-            }
-        }
-        let result;
         try {
-            result = this.driver.deleteEntity(entity);
-        }
-        catch (e) {
-            for (let callback of this.failedDeleteEntityCallbacks) {
+            for (let callback of this.beforeDeleteEntityCallbacks) {
                 if (callback) {
-                    await callback(this, e);
+                    await callback(this, entity);
                 }
             }
-            throw e;
-        }
-        for (let callback of this.afterDeleteEntityCallbacks) {
-            if (callback) {
-                await callback(this, result);
+            let result;
+            try {
+                result = this.driver.deleteEntity(entity);
+            }
+            catch (e) {
+                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) {
+            this.config.debugError('nymph', `Failed to delete entity: ${e}`);
+            throw e;
         }
-        return await result;
     }
+    /**
+     * Delete an entity from the database by its GUID.
+     *
+     * @param guid The entity's GUID.
+     * @param className The entity's class name.
+     * @returns True on success, false on failure.
+     */
     async deleteEntityByID(guid, className) {
-        for (let callback of this.beforeDeleteEntityByIDCallbacks) {
-            if (callback) {
-                await callback(this, guid, className);
-            }
-        }
-        let result;
         try {
-            result = this.driver.deleteEntityByID(guid, className);
-        }
-        catch (e) {
-            for (let callback of this.failedDeleteEntityByIDCallbacks) {
+            for (let callback of this.beforeDeleteEntityByIDCallbacks) {
                 if (callback) {
-                    await callback(this, e);
+                    await callback(this, guid, className);
                 }
             }
-            throw e;
-        }
-        for (let callback of this.afterDeleteEntityByIDCallbacks) {
-            if (callback) {
-                await callback(this, result);
+            let result;
+            try {
+                result = this.driver.deleteEntityByID(guid, className);
+            }
+            catch (e) {
+                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) {
+            this.config.debugError('nymph', `Failed to delete entity by ID: ${e}`);
+            throw e;
         }
-        return await result;
     }
+    /**
+     * Export entities to a local file.
+     *
+     * This is the file format:
+     *
+     * ```
+     * #nex2
+     * # The above line must be the first thing in the file.
+     * # Comments begin with #
+     *    # And can have white space before them.
+     * # This defines a UID.
+     * <name/of/uid>[5]
+     * <another uid>[8000]
+     * # For UIDs, the name is in angle brackets (<>) and the value follows
+     * # in square brackets ([]).
+     * # This starts a new entity.
+     * {1234abcd}<etype>[tag,list,with,commas]
+     * # For entities, the GUID is in curly brackets ({}), then the etype in
+     * #  angle brackets, then the comma separated tag list follows in square
+     * #  brackets ([]).
+     * # Properties are stored like this:
+     * # propname=JSON.stringify(value)
+     *     abilities=["system/admin"]
+     *     groups=[]
+     *     inheritAbilities=false
+     *     name="admin"
+     * # White space before/after "=" and at beginning/end of line is ignored.
+     *         username  =     "admin"
+     * {2}<etype>[tag,list]
+     *     another="This is another entity."
+     *     newline="\n"
+     * ```
+     *
+     * @param filename The file to export to.
+     * @returns True on success, false on failure.
+     */
     async export(filename) {
-        return await this.driver.export(filename);
+        try {
+            return await this.driver.export(filename);
+        }
+        catch (e) {
+            this.config.debugError('nymph', `Failed to export: ${e}`);
+            throw e;
+        }
     }
+    /**
+     * Export entities to the console.
+     *
+     * @returns True on success, false on failure.
+     */
     async exportPrint() {
-        return await this.driver.exportPrint();
+        try {
+            return await this.driver.exportPrint();
+        }
+        catch (e) {
+            this.config.debugError('nymph', `Failed to export: ${e}`);
+            throw e;
+        }
     }
+    /**
+     * Import entities from a file.
+     *
+     * @param filename The file to import from.
+     * @returns True on success, false on failure.
+     */
     async import(filename) {
-        return await this.driver.import(filename);
+        try {
+            return await this.driver.import(filename);
+        }
+        catch (e) {
+            this.config.debugError('nymph', `Failed to import: ${e}`);
+            throw e;
+        }
     }
     on(event, callback) {
         const prop = (event + 'Callbacks');
         if (!(prop in this)) {
             throw new Error('Invalid event type.');
         }
+        // @ts-ignore: The callback should be the right type here.
         this[prop].push(callback);
         return () => this.off(event, callback);
     }
@@ -431,8 +751,10 @@ class Nymph {
         if (!(prop in this)) {
             return false;
         }
+        // @ts-ignore: The callback should always be the right type here.
         const i = this[prop].indexOf(callback);
         if (i > -1) {
+            // @ts-ignore: The callback should always be the right type here.
             this[prop].splice(i, 1);
         }
         return true;