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

package/dist/driver/NymphDriver.js

@@ -10,9 +10,13 @@ const strtotime_1 = __importDefault(require("locutus/php/datetime/strtotime"));
 const guid_1 = require("@nymphjs/guid");
 const errors_1 = require("../errors");
 const utils_1 = require("../utils");
+// from: https://stackoverflow.com/a/6969486/664915
 function escapeRegExp(string) {
-    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string
 }
+/**
+ * A Nymph database driver.
+ */
 class NymphDriver {
     constructor() {
         this.nymph = new Proxy({}, {
@@ -20,15 +24,33 @@ class NymphDriver {
                 throw new Error('Attempted access of Nymph instance before driver initialization!');
             },
         });
+        /**
+         * A cache to make entity retrieval faster.
+         */
         this.entityCache = {};
+        /**
+         * A counter for the entity cache to determine the most accessed entities.
+         */
         this.entityCount = {};
+        /**
+         * Protect against infinite loops.
+         */
         this.putDataCounter = 0;
     }
+    /**
+     * Initialize the Nymph driver.
+     *
+     * This is meant to be called internally by Nymph. Don't call this directly.
+     *
+     * @param nymph The Nymph instance.
+     */
     init(nymph) {
         this.nymph = nymph;
     }
     posixRegexMatch(pattern, subject, caseInsensitive = false) {
         const posixClasses = [
+            // '[[:<:]]',
+            // '[[:>:]]',
             '[:alnum:]',
             '[:alpha:]',
             '[:ascii:]',
@@ -45,17 +67,21 @@ class NymphDriver {
             '[:xdigit:]',
         ];
         const jsClasses = [
+            // '\b(?=\w)',
+            // '(?<=\w)\b',
             '[A-Za-z0-9]',
             '[A-Za-z]',
             '[\x00-\x7F]',
-            '[ \t]',
-            '[\x00-\x1F\x7F]',
-            '[0-9]',
-            '[\x21-\x7E]',
+            '[ \t]', // '\s',
+            '[\x00-\x1F\x7F]', // '[\000\001\002\003\004\005\006\007\008\009\010\011\012\013\014'.
+            //   '\015\016\017\018\019\020\021\022\023\024\025\026\027\028\029'.
+            //   '\030\031\032\033\034\035\036\037\177]',
+            '[0-9]', // '\d',
+            '[\x21-\x7E]', // '[A-Za-z0-9!"#$%&\'()*+,\-./:;<=>?@[\\\]^_`{|}\~]',
             '[a-z]',
-            '[\x20-\x7E]',
-            '[!"#$%&\'()*+,-./:;<=>?@[\\\\\\]^_‘{|}~]',
-            '[ \t\r\n\v\f]',
+            '[\x20-\x7E]', // '[A-Za-z0-9!"#$%&\'()*+,\-./:;<=>?@[\\\]^_`{|}\~]',
+            '[!"#$%&\'()*+,-./:;<=>?@[\\\\\\]^_‘{|}~]', // '[!"#$%&\'()*+,\-./:;<=>?@[\\\]^_`{|}\~]',
+            '[ \t\r\n\v\f]', // '[\t\n\x0B\f\r ]',
             '[A-Z]',
             '[A-Za-z0-9_]',
             '[0-9A-Fa-f]',
@@ -114,9 +140,11 @@ class NymphDriver {
             const propMatch = text.match(/^\s*([^=]+)\s*=\s*(.*\S)\s*$/);
             const uidMatch = text.match(/^\s*<([^>]+)>\[(\d+)\]\s*$/);
             if (uidMatch) {
+                // Add the UID.
                 await saveUIDCallback(uidMatch[1], Number(uidMatch[2]));
             }
             else if (entityMatch) {
+                // Save the current entity.
                 if (guid) {
                     await saveEntityCallback(guid, tags, sdata, etype);
                     guid = null;
@@ -124,17 +152,21 @@ class NymphDriver {
                     sdata = {};
                     etype = '__undefined';
                 }
+                // Record the new entity's info.
                 guid = entityMatch[1];
                 etype = entityMatch[2];
                 tags = entityMatch[3].split(',');
             }
             else if (propMatch) {
+                // Add the variable to the new entity.
                 if (guid) {
                     sdata[propMatch[1]] = propMatch[2];
                 }
             }
+            // Clear the entity cache.
             this.entityCache = {};
         }
+        // Save the last entity.
         if (guid) {
             await saveEntityCallback(guid, tags, sdata, etype);
         }
@@ -144,132 +176,147 @@ class NymphDriver {
         return true;
     }
     checkData(data, sdata, selectors, guid = null, tags = null) {
-        const formattedSelectors = this.formatSelectors(selectors).selectors;
-        for (const curSelector of formattedSelectors) {
-            const type = curSelector.type;
-            const typeIsNot = type === '!&' || type === '!|';
-            const typeIsOr = type === '|' || type === '!|';
-            let pass = !typeIsOr;
-            for (const k in curSelector) {
-                const key = k;
-                const value = curSelector[key];
-                if (key === 'type' || value == null) {
-                    continue;
-                }
-                const clauseNot = key.substring(0, 1) === '!';
-                if (key === 'selector' || key === '!selector') {
-                    const tmpArr = (Array.isArray(value) ? value : [value]);
-                    pass = (0, utils_1.xor)(this.checkData(data, sdata, tmpArr, guid, tags), (0, utils_1.xor)(typeIsNot, clauseNot));
-                }
-                else {
-                    if (key === 'qref' || key === '!qref') {
-                        throw new Error("Can't use checkData on qref clauses.");
+        try {
+            const formattedSelectors = this.formatSelectors(selectors).selectors;
+            for (const curSelector of formattedSelectors) {
+                const type = curSelector.type;
+                const typeIsNot = type === '!&' || type === '!|';
+                const typeIsOr = type === '|' || type === '!|';
+                let pass = !typeIsOr;
+                for (const k in curSelector) {
+                    const key = k;
+                    const value = curSelector[key];
+                    if (key === 'type' || value == null) {
+                        continue;
+                    }
+                    const clauseNot = key.substring(0, 1) === '!';
+                    if (key === 'selector' || key === '!selector') {
+                        const tmpArr = (Array.isArray(value) ? value : [value]);
+                        pass = (0, utils_1.xor)(this.checkData(data, sdata, tmpArr, guid, tags), (0, utils_1.xor)(typeIsNot, clauseNot));
                     }
                     else {
-                        for (const curValue of value) {
-                            if (curValue == null) {
-                                continue;
-                            }
-                            const propName = curValue[0];
-                            if (propName in sdata) {
-                                data[propName] = JSON.parse(sdata[propName]);
-                                delete sdata[propName];
-                            }
-                            switch (key) {
-                                case 'guid':
-                                case '!guid':
-                                    pass = (0, utils_1.xor)(guid == propName, (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'tag':
-                                case '!tag':
-                                    pass = (0, utils_1.xor)((tags ?? []).indexOf(propName) !== -1, (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'defined':
-                                case '!defined':
-                                    pass = (0, utils_1.xor)(propName in data, (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'truthy':
-                                case '!truthy':
-                                    pass = (0, utils_1.xor)(propName in data && data[propName], (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'ref':
-                                case '!ref':
-                                    const testRefValue = curValue[1];
-                                    pass = (0, utils_1.xor)(propName in data &&
-                                        this.entityReferenceSearch(data[propName], testRefValue), (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'equal':
-                                case '!equal':
-                                    const testEqualValue = curValue[1];
-                                    pass = (0, utils_1.xor)(propName in data &&
-                                        JSON.stringify(data[propName]) ===
-                                            JSON.stringify(testEqualValue), (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'contain':
-                                case '!contain':
-                                    const testContainValue = curValue[1];
-                                    pass = (0, utils_1.xor)(propName in data &&
-                                        JSON.stringify(data[propName]).indexOf(JSON.stringify(testContainValue)) !== -1, (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'like':
-                                case '!like':
-                                    const testLikeValue = curValue[1];
-                                    pass = (0, utils_1.xor)(propName in data &&
-                                        new RegExp('^' +
-                                            escapeRegExp(testLikeValue)
-                                                .replace('%', () => '.*')
-                                                .replace('_', () => '.') +
-                                            '$').test(data[propName]), (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'match':
-                                case '!match':
-                                    const testMatchValue = curValue[1];
-                                    pass = (0, utils_1.xor)(propName in data &&
-                                        this.posixRegexMatch(testMatchValue, data[propName]), (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'imatch':
-                                case '!imatch':
-                                    const testIMatchValue = curValue[1];
-                                    pass = (0, utils_1.xor)(propName in data &&
-                                        this.posixRegexMatch(testIMatchValue, data[propName], true), (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'gt':
-                                case '!gt':
-                                    const testGTValue = curValue[1];
-                                    pass = (0, utils_1.xor)(propName in data && data[propName] > testGTValue, (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'gte':
-                                case '!gte':
-                                    const testGTEValue = curValue[1];
-                                    pass = (0, utils_1.xor)(propName in data && data[propName] >= testGTEValue, (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'lt':
-                                case '!lt':
-                                    const testLTValue = curValue[1];
-                                    pass = (0, utils_1.xor)(propName in data && data[propName] < testLTValue, (0, utils_1.xor)(typeIsNot, clauseNot));
-                                    break;
-                                case 'lte':
-                                case '!lte':
-                                    const testLTEValue = curValue[1];
-                                    pass = (0, utils_1.xor)(propName in data && data[propName] <= testLTEValue, (0, utils_1.xor)(typeIsNot, clauseNot));
+                        if (key === 'qref' || key === '!qref') {
+                            throw new Error("Can't use checkData on qref clauses.");
+                        }
+                        else {
+                            // Check if it doesn't pass any for &, check if it passes any for |.
+                            for (const curValue of value) {
+                                if (curValue == null) {
+                                    continue;
+                                }
+                                const propName = curValue[0];
+                                // Unserialize the data for this variable.
+                                if (propName in sdata) {
+                                    data[propName] = JSON.parse(sdata[propName]);
+                                    delete sdata[propName];
+                                }
+                                switch (key) {
+                                    case 'guid':
+                                    case '!guid':
+                                        pass = (0, utils_1.xor)(guid == propName, (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'tag':
+                                    case '!tag':
+                                        pass = (0, utils_1.xor)((tags ?? []).indexOf(propName) !== -1, (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'defined':
+                                    case '!defined':
+                                        pass = (0, utils_1.xor)(propName in data, (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'truthy':
+                                    case '!truthy':
+                                        pass = (0, utils_1.xor)(propName in data && data[propName], (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'ref':
+                                    case '!ref':
+                                        const testRefValue = curValue[1];
+                                        pass = (0, utils_1.xor)(propName in data &&
+                                            this.entityReferenceSearch(data[propName], testRefValue), (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'equal':
+                                    case '!equal':
+                                        const testEqualValue = curValue[1];
+                                        pass = (0, utils_1.xor)(propName in data &&
+                                            JSON.stringify(data[propName]) ===
+                                                JSON.stringify(testEqualValue), (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'contain':
+                                    case '!contain':
+                                        const testContainValue = curValue[1];
+                                        pass = (0, utils_1.xor)(propName in data &&
+                                            JSON.stringify(data[propName]).indexOf(JSON.stringify(testContainValue)) !== -1, (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'like':
+                                    case '!like':
+                                        const testLikeValue = curValue[1];
+                                        pass = (0, utils_1.xor)(propName in data &&
+                                            new RegExp('^' +
+                                                escapeRegExp(testLikeValue)
+                                                    .replace('%', () => '.*')
+                                                    .replace('_', () => '.') +
+                                                '$').test(data[propName]), (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'match':
+                                    case '!match':
+                                        const testMatchValue = curValue[1];
+                                        // Convert a POSIX regex to a JS regex.
+                                        pass = (0, utils_1.xor)(propName in data &&
+                                            this.posixRegexMatch(testMatchValue, data[propName]), (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'imatch':
+                                    case '!imatch':
+                                        const testIMatchValue = curValue[1];
+                                        // Convert a POSIX regex to a JS regex.
+                                        pass = (0, utils_1.xor)(propName in data &&
+                                            this.posixRegexMatch(testIMatchValue, data[propName], true), (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'gt':
+                                    case '!gt':
+                                        const testGTValue = curValue[1];
+                                        pass = (0, utils_1.xor)(propName in data && data[propName] > testGTValue, (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'gte':
+                                    case '!gte':
+                                        const testGTEValue = curValue[1];
+                                        pass = (0, utils_1.xor)(propName in data && data[propName] >= testGTEValue, (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'lt':
+                                    case '!lt':
+                                        const testLTValue = curValue[1];
+                                        pass = (0, utils_1.xor)(propName in data && data[propName] < testLTValue, (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                    case 'lte':
+                                    case '!lte':
+                                        const testLTEValue = curValue[1];
+                                        pass = (0, utils_1.xor)(propName in data && data[propName] <= testLTEValue, (0, utils_1.xor)(typeIsNot, clauseNot));
+                                        break;
+                                }
+                                if (!(0, utils_1.xor)(typeIsOr, pass)) {
                                     break;
-                            }
-                            if (!(0, utils_1.xor)(typeIsOr, pass)) {
-                                break;
+                                }
                             }
                         }
                     }
+                    if (!(0, utils_1.xor)(typeIsOr, pass)) {
+                        break;
+                    }
                 }
-                if (!(0, utils_1.xor)(typeIsOr, pass)) {
-                    break;
+                if (!pass) {
+                    return false;
                 }
             }
-            if (!pass) {
-                return false;
-            }
+            return true;
+        }
+        catch (e) {
+            this.nymph.config.debugError('nymph', `Failed to check entity data: ${e}`);
+            throw e;
         }
-        return true;
     }
+    /**
+     * Remove all copies of an entity from the cache.
+     *
+     * @param guid The GUID of the entity to remove.
+     */
     cleanCache(guid) {
         delete this.entityCache[guid];
     }
@@ -286,7 +333,15 @@ class NymphDriver {
         }
         return ret;
     }
+    /**
+     * Search through a value for an entity reference.
+     *
+     * @param value Any value to search.
+     * @param entity An entity, GUID, or array of either to search for.
+     * @returns True if the reference is found, false otherwise.
+     */
     entityReferenceSearch(value, entity) {
+        // Get the GUID, if the passed $entity is an object.
         const guids = [];
         if (Array.isArray(entity)) {
             if (entity[0] === 'nymph_entity_reference') {
@@ -317,6 +372,7 @@ class NymphDriver {
             guids.indexOf(value[1]) !== -1) {
             return true;
         }
+        // Search through arrays and objects looking for the reference.
         if (Array.isArray(value) || typeof value === 'object') {
             for (const key in value) {
                 if (this.entityReferenceSearch(value[key], guids)) {
@@ -371,19 +427,23 @@ class NymphDriver {
                     qrefs.push(...newSelectors.qrefs);
                 }
                 else if (!Array.isArray(value)) {
+                    // @ts-ignore: ts doesn't know what value is here.
                     newSelector[key] = [[value]];
                 }
                 else if (!Array.isArray(value[0])) {
                     if (value.length === 3 &&
                         value[1] == null &&
                         typeof value[2] === 'string') {
+                        // @ts-ignore: ts doesn't know what value is here.
                         newSelector[key] = [[value[0], (0, strtotime_1.default)(value[2]) * 1000]];
                     }
                     else {
+                        // @ts-ignore: ts doesn't know what value is here.
                         newSelector[key] = [value];
                     }
                 }
                 else {
+                    // @ts-ignore: ts doesn't know what value is here.
                     newSelector[key] = value.map((curValue) => {
                         if (curValue.length === 3 &&
                             curValue[1] == null &&
@@ -440,11 +500,14 @@ class NymphDriver {
         let count = 0;
         const EntityClass = options.class ?? this.nymph.getEntityClass('Entity');
         const etype = EntityClass.ETYPE;
+        // Check if the requested entity is cached.
         if (this.nymph.config.cache &&
             !options.skipCache &&
             selectors.length &&
             'guid' in selectors[0] &&
             typeof selectors[0].guid === 'number') {
+            // Only safe to use the cache option with no other selectors than a GUID
+            // and tags.
             if (selectors.length === 1 &&
                 selectors[0].type === '&' &&
                 (Object.keys(selectors[0]).length === 2 ||
@@ -502,9 +565,13 @@ class NymphDriver {
                             const cdate = tagsAndDates.cdate;
                             const mdate = tagsAndDates.mdate;
                             let dataNameAndSValue = getDataNameAndSValueCallback(row);
+                            // Data.
                             const data = {};
+                            // Serialized data.
                             const sdata = {};
                             if (dataNameAndSValue.name !== '') {
+                                // This do will keep going and adding the data until the
+                                // next entity is reached. $row will end on the next entity.
                                 do {
                                     dataNameAndSValue = getDataNameAndSValueCallback(row);
                                     sdata[dataNameAndSValue.name] = dataNameAndSValue.svalue;
@@ -512,6 +579,7 @@ class NymphDriver {
                                 } while (row != null && getGUIDCallback(row) === guid);
                             }
                             else {
+                                // Make sure that $row is incremented :)
                                 row = rowFetchCallback();
                             }
                             const entity = EntityClass.factorySync();
@@ -532,6 +600,7 @@ class NymphDriver {
                             if (this.nymph.config.cache) {
                                 this.pushCache(guid, cdate, mdate, tags, data, sdata);
                             }
+                            // @ts-ignore: ts doesn't know the return type here.
                             entities.push(entity);
                         }
                     }
@@ -550,6 +619,7 @@ class NymphDriver {
         }
     }
     async saveEntityRowLike(entity, saveNewEntityCallback, saveExistingEntityCallback, startTransactionCallback = null, commitTransactionCallback = null) {
+        // Get a modified date.
         const mdate = Date.now();
         const tags = (0, lodash_1.difference)(entity.tags, ['']);
         const data = entity.$getData();
@@ -571,6 +641,7 @@ class NymphDriver {
             }
         }
         else {
+            // Removed any cached versions of this entity.
             if (this.nymph.config.cache) {
                 this.cleanCache(entity.guid);
             }
@@ -582,12 +653,22 @@ class NymphDriver {
         if (commitTransactionCallback) {
             success = await commitTransactionCallback(success);
         }
+        // Cache the entity.
         if (success && this.nymph.config.cache) {
             this.pushCache(entity.guid, entity.cdate, entity.mdate, entity.tags, data, sdata);
         }
         return success;
     }
+    /**
+     * Pull an entity from the cache.
+     *
+     * @param guid The entity's GUID.
+     * @param className The entity's class.
+     * @param useSkipAc Whether to tell the entity to use skip_ac.
+     * @returns The entity or null if it's not cached.
+     */
     pullCache(guid, className, useSkipAc = false) {
+        // Increment the entity access count.
         if (!(guid in this.entityCount)) {
             this.entityCount[guid] = 0;
         }
@@ -607,17 +688,30 @@ class NymphDriver {
         }
         return null;
     }
+    /**
+     * Push an entity onto the cache.
+     *
+     * @param guid The entity's GUID.
+     * @param cdate The entity's cdate.
+     * @param mdate The entity's mdate.
+     * @param tags The entity's tags.
+     * @param data The entity's data.
+     * @param sdata The entity's sdata.
+     */
     pushCache(guid, cdate, mdate, tags, data, sdata) {
         if (guid == null) {
             return;
         }
+        // Increment the entity access count.
         if (!(guid in this.entityCount)) {
             this.entityCount[guid] = 0;
         }
         this.entityCount[guid]++;
+        // Check the threshold.
         if (this.entityCount[guid] < this.nymph.config.cacheThreshold) {
             return;
         }
+        // Cache the entity.
         this.entityCache[guid] = {
             cdate: cdate,
             mdate: mdate,
@@ -627,12 +721,15 @@ class NymphDriver {
         };
         while (this.nymph.config.cacheLimit &&
             Object.keys(this.entityCache).length >= this.nymph.config.cacheLimit) {
+            // Find which entity has been accessed the least.
             const least = Object.entries(this.entityCount)
                 .sort(([guidA, countA], [guidB, countB]) => countA - countB)
                 .pop()?.[0] ?? null;
             if (least == null) {
+                // This should never happen.
                 return;
             }
+            // Remove it.
             delete this.entityCache[least];
             delete this.entityCount[least];
         }