fix: falsy boolean queries (#13)

* test: mock engine should not give values by reference

* test: allow stubbing fs without specifying a filesystem

* refactor: make Engine.configuration public

* fix: allow falsy matching queries

* refactor: unnecessary return await

* refactor: avoid square-bracket notation

* refactor: empty functions

* refactor: variable name shadows variable in outer scope

* refactor: class methods should utilize this

* refactor: all code paths should have explicit returns, or none

* refactor: remove shorthand type coercions

* refactor: usage of exported name as property of default import

* docs: add jsdoc blocks for test models

* docs: add jsdoc block for test model collection

* docs: add jsdoc blocks tyo all type classes

* docs: add jsdoc block for complex types

* docs: add jsdoc blocks for engine classes

* docs: add jsdoc block for calledWith test function

* refactor: file retrival consistency

* refactor: async function should have await expression

Author: acodeninja

src/Persist.js

@@ -4,7 +4,7 @@ import enableTransactions from './Transactions.js';
 /**
  * @class Persist
  */
-export default class Persist {
+class Persist {
     static _engine = {};
     /**
      * @memberof Persist
@@ -42,3 +42,5 @@ export default class Persist {
                 engine.configure(configuration);
     }
 }
+
+export default Persist;

src/Persist.test.js

@@ -5,7 +5,7 @@ import test from 'ava';
 class TestEngine {
     static configure(configuration = {}) {
         class ConfiguredTestEngine extends TestEngine {
-            static _configuration = configuration;
+            static configuration = configuration;
         }
 
         return ConfiguredTestEngine;
@@ -19,13 +19,13 @@ test('includes Type', async t => {
 test('.addEngine(group, engine, configuration) adds and configures an engine', t => {
     Persist.addEngine('one', TestEngine, {test: true});
 
-    t.like(Persist._engine.one.TestEngine._configuration, {test: true});
+    t.like(Persist._engine.one.TestEngine.configuration, {test: true});
 });
 
 test('.getEngine(group, engine) retrieves an engine', t => {
     Persist.addEngine('one', TestEngine, {test: true});
 
-    t.like(Persist.getEngine('one', TestEngine)._configuration, {test: true});
+    t.like(Persist.getEngine('one', TestEngine).configuration, {test: true});
 });
 
 test('.getEngine(group, nonEngine) retrieves no engines', t => {

src/Query.js

@@ -1,39 +1,60 @@
 /**
- * persist query language features:
- * - value match {title: 'test'} or {title: {$is: 'test'}}
- * - contains match {list: {$contains: 'test'}} or {string: {$contains: 'es'}}
- * - nested query {list: {$contains: {slug: 'test'}}}
- * - deep nesting queries {list: {$contains: {string: {$contains: 'test'}}}}
- */
-
-/**
- * @class Query
+ * The `Query` class is responsible for executing searches on an indexed dataset
+ * based on a structured query. It supports various query types including value matches,
+ * contains matches, and nested queries.
+ *
+ * @example
+ * // The object has the property `title` witch exactly equals `test`.
+ * const query = new Query({title: 'test'});
+ * const query = new Query({title: {$is: 'test'}});
+ *
+ * // The object has the property `list` witch contains the string `test`.
+ * const query = new Query({list: {$contains: 'test'}});
+ *
+ * // The object has the property `string` witch contains the string `es`.
+ * const query = new Query({string: {$contains: 'es'}});
+ *
+ * // The object has the property `list` contains an object
+ * // with a property `string` that contains the string `test`.
+ * const query = new Query({
+ *   list: {
+ *     $contains: {
+ *       string: {
+ *         $contains: 'test'
+ *       }
+ *     }
+ *   }
+ * });
  */
 class Query {
+    /**
+     * The query object that defines the search criteria.
+     * @type {Object}
+     */
     query;
 
     /**
+     * Constructs a new `Query` instance with the provided query object.
      *
-     * @param {object} query
+     * @param {Object} query - The structured query object defining the search criteria.
      */
     constructor(query) {
         this.query = query;
     }
 
     /**
-     * Using the input query, find records in an index that match
+     * Executes the query against a model's index and returns the matching results.
      *
-     * @param {typeof Model} model
-     * @param {object} index
+     * @param {Model.constructor} model - The model class that contains the `fromData` method for constructing models from data.
+     * @param {Object<string, Model>} index - The index dataset to search through.
+     * @returns {Array<Model>} The models that match the query.
      */
     execute(model, index) {
-        const matchIs = (query) => !!query?.$is;
+        const matchIs = (query) => query?.$is !== undefined;
         const matchPrimitive = (query) => ['string', 'number', 'boolean'].includes(typeof query);
         const matchContains = (query) => !!query?.$contains;
 
         const matchesQuery = (subject, inputQuery = this.query) => {
-            if (!subject || !inputQuery) return false;
-
             if (matchPrimitive(inputQuery)) return subject === inputQuery;
 
             if (matchIs(inputQuery))

src/Query.test.js

@@ -1,6 +1,6 @@
-import {MainModel} from '../test/fixtures/TestModel.js';
+import {MainModel} from '../test/fixtures/Models.js';
+import {Models} from '../test/fixtures/ModelCollection.js';
 import Query from './Query.js';
-import {TestIndex} from '../test/fixtures/TestIndex.js';
 import test from 'ava';
 
 test('new Query(query) stores the query', t => {
@@ -9,122 +9,117 @@ test('new Query(query) stores the query', t => {
     t.deepEqual(query.query, {string: 'test'});
 });
 
-test('Query.execute(index) finds exact matches with primitive types', t => {
+test('Query.execute(index) finds exact string matches with primitive type', t => {
+    const models = new Models();
+    const model = models.createFullTestModel();
+
     const query = new Query({string: 'test'});
-    const results = query.execute(MainModel, TestIndex);
-
-    t.deepEqual(results, [
-        MainModel.fromData({
-            id: 'MainModel/000000000000',
-            string: 'test',
-            arrayOfString: ['test'],
-            linkedMany: [{
-                id: 'LinkedManyModel/000000000000000',
-                string: 'test',
-            }],
-        }),
-    ]);
+
+    const results = query.execute(MainModel, models.getIndex(MainModel));
+
+    t.like(results, [model.toIndexData()]);
 });
 
-test('Query.execute(index) finds exact matches with $is', t => {
+test('Query.execute(index) finds exact string matches with $is', t => {
+    const models = new Models();
+    const model = models.createFullTestModel();
+    models.createFullTestModel({string: 'another test'});
+
     const query = new Query({string: {$is: 'test'}});
-    const results = query.execute(MainModel, TestIndex);
-
-    t.deepEqual(results, [
-        MainModel.fromData({
-            id: 'MainModel/000000000000',
-            string: 'test',
-            arrayOfString: ['test'],
-            linkedMany: [{
-                id: 'LinkedManyModel/000000000000000',
-                string: 'test',
-            }],
-        }),
-    ]);
+    const results = query.execute(MainModel, models.getIndex(MainModel));
+
+    t.like(results, [model.toIndexData()]);
+});
+
+test('Query.execute(index) finds exact boolean matches with primitive type', t => {
+    const models = new Models();
+    const model = models.createFullTestModel();
+
+    const query = new Query({boolean: false});
+    const results = query.execute(MainModel, models.getIndex(MainModel));
+
+    t.like(results, [model.toIndexData()]);
+});
+
+test('Query.execute(index) finds exact boolean matches with $is', t => {
+    const models = new Models();
+    const model = models.createFullTestModel();
+
+    const query = new Query({boolean: {$is: false}});
+    const results = query.execute(MainModel, models.getIndex(MainModel));
+
+    t.like(results, [model.toIndexData()]);
+});
+
+test('Query.execute(index) finds exact number matches with $is', t => {
+    const models = new Models();
+    const model = models.createFullTestModel();
+
+    const query = new Query({number: {$is: 24.3}});
+    const results = query.execute(MainModel, models.getIndex(MainModel));
+
+    t.like(results, [model.toIndexData()]);
+});
+
+test('Query.execute(index) finds exact number matches with primitive type', t => {
+    const models = new Models();
+    const model = models.createFullTestModel();
+
+    const query = new Query({number: 24.3});
+    const results = query.execute(MainModel, models.getIndex(MainModel));
+
+    t.like(results, [model.toIndexData()]);
 });
 
 test('Query.execute(index) finds matches containing for strings', t => {
+    const models = new Models();
+    const model1 = models.createFullTestModel();
+    const model2 = models.createFullTestModel();
+    models.createFullTestModel({string: 'not matching'});
+
+    model2.string = 'testing';
+
     const query = new Query({string: {$contains: 'test'}});
-    const results = query.execute(MainModel, TestIndex);
-
-    t.deepEqual(results, [
-        MainModel.fromData({
-            id: 'MainModel/000000000000',
-            string: 'test',
-            arrayOfString: ['test'],
-            linkedMany: [{
-                id: 'LinkedManyModel/000000000000000',
-                string: 'test',
-            }],
-        }),
-        MainModel.fromData({
-            id: 'MainModel/111111111111',
-            string: 'testing',
-            arrayOfString: ['testing'],
-            linkedMany: [{
-                id: 'LinkedManyModel/111111111111',
-                string: 'testing',
-            }],
-        }),
+    const results = query.execute(MainModel, models.getIndex(MainModel));
+
+    t.like(results, [
+        model1.toIndexData(),
+        model2.toIndexData(),
     ]);
 });
 
 test('Query.execute(index) finds matches containing for arrays', t => {
+    const models = new Models();
+    const model = models.createFullTestModel();
+
     const query = new Query({arrayOfString: {$contains: 'test'}});
-    const results = query.execute(MainModel, TestIndex);
-
-    t.deepEqual(results, [
-        MainModel.fromData({
-            id: 'MainModel/000000000000',
-            string: 'test',
-            arrayOfString: ['test'],
-            linkedMany: [{
-                id: 'LinkedManyModel/000000000000000',
-                string: 'test',
-            }],
-        }),
-    ]);
+    const results = query.execute(MainModel, models.getIndex(MainModel));
+
+    t.like(results, [model.toIndexData()]);
 });
 
 test('Query.execute(index) finds exact matches for elements in arrays', t => {
-    const query = new Query({linkedMany: {$contains: {string: 'test'}}});
-    const results = query.execute(MainModel, TestIndex);
-
-    t.deepEqual(results, [
-        MainModel.fromData({
-            id: 'MainModel/000000000000',
-            string: 'test',
-            arrayOfString: ['test'],
-            linkedMany: [{
-                id: 'LinkedManyModel/000000000000000',
-                string: 'test',
-            }],
-        }),
-    ]);
+    const models = new Models();
+    const model = models.createFullTestModel();
+
+    const query = new Query({linkedMany: {$contains: {string: 'many'}}});
+    const results = query.execute(MainModel, models.getIndex(MainModel));
+
+    t.like(results, [model.toIndexData()]);
 });
 
 test('Query.execute(index) finds partial matches for elements in arrays', t => {
-    const query = new Query({linkedMany: {$contains: {string: {$contains: 'test'}}}});
-    const results = query.execute(MainModel, TestIndex);
-
-    t.deepEqual(results, [
-        MainModel.fromData({
-            id: 'MainModel/000000000000',
-            string: 'test',
-            arrayOfString: ['test'],
-            linkedMany: [{
-                id: 'LinkedManyModel/000000000000000',
-                string: 'test',
-            }],
-        }),
-        MainModel.fromData({
-            id: 'MainModel/111111111111',
-            string: 'testing',
-            arrayOfString: ['testing'],
-            linkedMany: [{
-                id: 'LinkedManyModel/111111111111',
-                string: 'testing',
-            }],
-        }),
+    const models = new Models();
+    const model1 = models.createFullTestModel();
+    const model2 = models.createFullTestModel();
+
+    model2.linkedMany[0].string = 'many tests';
+
+    const query = new Query({linkedMany: {$contains: {string: {$contains: 'many'}}}});
+    const results = query.execute(MainModel, models.getIndex(MainModel));
+
+    t.like(results, [
+        model1.toIndexData(),
+        model2.toIndexData(),
     ]);
 });