@reldens/storage 0.117.0 → 0.119.0

package/tests/utils/column-value-assert.js

@@ -0,0 +1,139 @@
+/**
+ *
+ * Reldens - Column Value Assert
+ * Value and type assertion of a single database column against the value the fixture row was inserted with.
+ * Both sides are reduced to the same canonical form, identical for every driver, so a driver returning
+ * another representation of the stored value fails stating what it actually returned.
+ *
+ */
+
+const assert = require('node:assert');
+const { ObservedValue } = require('./observed-value');
+const { TableColumnsFixtures } = require('../fixtures/table-columns-fixtures');
+const { sc } = require('@reldens/utils');
+
+class ColumnValueAssert
+{
+
+    static anyValue = {reldensAnyColumnValue: true};
+
+    static assertColumns(actualRecord, tableName, expectedRow, label)
+    {
+        let columns = TableColumnsFixtures[tableName].columns;
+        for(let columnName of Object.keys(columns)){
+            this.assertColumn(
+                actualRecord[columnName],
+                expectedRow[columnName],
+                columns[columnName],
+                label+'.'+columnName
+            );
+        }
+        return true;
+    }
+
+    static assertColumn(actualValue, expectedValue, columnType, label)
+    {
+        if(ColumnValueAssert.anyValue === expectedValue){
+            this.assertColumnType(actualValue, columnType, label);
+            return true;
+        }
+        if(null === expectedValue){
+            assert.strictEqual(
+                actualValue,
+                null,
+                label+' expected null, observed: '+ObservedValue.describe(actualValue)
+            );
+            return true;
+        }
+        assert.strictEqual(
+            this.canonicalValue(actualValue, columnType),
+            this.canonicalValue(expectedValue, columnType),
+            label+' expected '+ObservedValue.describe(expectedValue)
+            +' but observed: '+ObservedValue.describe(actualValue)
+        );
+        this.assertColumnType(actualValue, columnType, label);
+        return true;
+    }
+
+    static assertColumnType(actualValue, columnType, label)
+    {
+        assert.ok(
+            null !== actualValue,
+            label+' is null but the column holds a value, observed: '+ObservedValue.describe(actualValue)
+        );
+        if('date' === columnType){
+            assert.ok(
+                actualValue instanceof Date,
+                label+' is not a Date instance, observed: '+ObservedValue.describe(actualValue)
+            );
+            return true;
+        }
+        if('json' === columnType){
+            assert.strictEqual(
+                typeof actualValue,
+                'object',
+                label+' is not a parsed json value, observed: '+ObservedValue.describe(actualValue)
+            );
+            return true;
+        }
+        assert.strictEqual(
+            typeof actualValue,
+            columnType,
+            label+' must be a '+columnType+', observed: '+ObservedValue.describe(actualValue)
+        );
+        return true;
+    }
+
+    static canonicalValue(value, columnType)
+    {
+        if('json' === columnType){
+            return this.canonicalJson(value);
+        }
+        if(value instanceof Date){
+            return value.toISOString();
+        }
+        if(sc.isObject(value) || sc.isArray(value)){
+            return sc.toJsonString(this.sortedJsonValue(value));
+        }
+        if('number' === columnType && null !== value){
+            return String(Number(value));
+        }
+        return String(value);
+    }
+
+    static canonicalJson(value)
+    {
+        let parsedValue = value;
+        if(sc.isString(value)){
+            parsedValue = sc.parseJson(value, value);
+        }
+        return sc.toJsonString(this.sortedJsonValue(parsedValue));
+    }
+
+    static sortedJsonValue(value)
+    {
+        if(sc.isArray(value)){
+            return this.sortedJsonList(value);
+        }
+        if(!sc.isObject(value)){
+            return value;
+        }
+        let sortedObject = {};
+        for(let key of Object.keys(value).sort()){
+            sortedObject[key] = this.sortedJsonValue(value[key]);
+        }
+        return sortedObject;
+    }
+
+    static sortedJsonList(value)
+    {
+        let sortedList = [];
+        for(let item of value){
+            sortedList.push(this.sortedJsonValue(item));
+        }
+        return sortedList;
+    }
+
+}
+
+module.exports.ColumnValueAssert = ColumnValueAssert;

package/tests/utils/entity-projection.js

@@ -0,0 +1,111 @@
+/**
+ *
+ * Reldens - Entity Projection
+ * Turns any driver result (plain row, ORM managed entity, ORM collection) into a normalised plain object
+ * projection: own enumerable keys sorted, dates as tagged strings, collections as arrays, nested entities
+ * projected recursively. Two projections built from the same database rows must be strictly equal on every
+ * driver, so any divergence found between them is a driver contract divergence.
+ *
+ */
+
+const { sc } = require('@reldens/utils');
+
+class EntityProjection
+{
+
+    static maxDepth = 12;
+    static functionLabel = 'function';
+    static circularReferenceLabel = 'circular-reference';
+    static maxDepthLabel = 'max-depth-reached';
+    static uninitializedCollectionLabel = 'uninitialized-collection';
+
+    static project(value, parentVisited = null, depth = 0)
+    {
+        let visited = null === parentVisited ? new Set() : parentVisited;
+        if(null === value){
+            return null;
+        }
+        if('undefined' === typeof value){
+            return null;
+        }
+        if('function' === typeof value){
+            return EntityProjection.functionLabel;
+        }
+        if('bigint' === typeof value){
+            return 'bigint:'+String(value);
+        }
+        if('object' !== typeof value){
+            return value;
+        }
+        if(value instanceof Date){
+            return 'date:'+value.toISOString();
+        }
+        if(Buffer.isBuffer(value)){
+            return 'buffer:'+value.length;
+        }
+        if(EntityProjection.maxDepth < depth){
+            return EntityProjection.maxDepthLabel;
+        }
+        if(visited.has(value)){
+            return EntityProjection.circularReferenceLabel;
+        }
+        return this.projectContainer(value, visited, depth);
+    }
+
+    static projectContainer(value, visited, depth)
+    {
+        visited.add(value);
+        let projected = this.projectByShape(value, visited, depth);
+        visited.delete(value);
+        return projected;
+    }
+
+    static projectByShape(value, visited, depth)
+    {
+        if(sc.isArray(value)){
+            return this.projectArray(value, visited, depth);
+        }
+        if(this.isCollection(value)){
+            return this.projectCollection(value, visited, depth);
+        }
+        return this.projectObject(value, visited, depth);
+    }
+
+    static isCollection(value)
+    {
+        if(!sc.isFunction(value.getItems)){
+            return false;
+        }
+        return sc.isFunction(value.isInitialized);
+    }
+
+    static projectCollection(value, visited, depth)
+    {
+        if(!value.isInitialized()){
+            return EntityProjection.uninitializedCollectionLabel;
+        }
+        return this.projectArray(value.getItems(), visited, depth);
+    }
+
+    static projectArray(value, visited, depth)
+    {
+        let projected = [];
+        for(let item of value){
+            projected.push(this.project(item, visited, depth + 1));
+        }
+        return projected;
+    }
+
+    static projectObject(value, visited, depth)
+    {
+        let projected = {};
+        let keys = Object.keys(value).sort();
+        for(let key of keys){
+            projected[key] = this.project(value[key], visited, depth + 1);
+        }
+        return projected;
+    }
+
+}
+
+module.exports.EntityProjection = EntityProjection;

package/tests/utils/observed-value.js

@@ -0,0 +1,41 @@
+/**
+ *
+ * Reldens - Observed Value
+ * Shared diagnostics helper: turns any runtime value into a readable shape description and logs it, so a
+ * failing assertion message states what was actually observed instead of only what was expected.
+ *
+ */
+
+const { Logger } = require('@reldens/utils');
+
+class ObservedValue
+{
+
+    static describe(value)
+    {
+        if(null === value){
+            return 'null';
+        }
+        let valueType = typeof value;
+        if('object' !== valueType){
+            return valueType+'('+String(value)+')';
+        }
+        if(Array.isArray(value)){
+            return 'Array[length='+value.length+']('+value.join(',')+')';
+        }
+        if(!value.constructor){
+            return 'NoConstructor{'+Object.keys(value).join(',')+'}';
+        }
+        return value.constructor.name+'{'+Object.keys(value).join(',')+'}';
+    }
+
+    static log(label, value)
+    {
+        let described = this.describe(value);
+        Logger.debug('      OBSERVED '+label+' => '+described);
+        return described;
+    }
+
+}
+
+module.exports.ObservedValue = ObservedValue;

package/tests/utils/projection-difference.js

@@ -0,0 +1,151 @@
+/**
+ *
+ * Reldens - Projection Difference
+ * Compares two normalised entity projections and returns every path where they diverge, so a cross driver
+ * assertion can name the exact key that broke the contract instead of only stating that the results differ.
+ * Keys listed as volatile (database generated timestamps) are compared by type only, since every driver
+ * writes them at a different moment.
+ *
+ */
+
+const { sc } = require('@reldens/utils');
+
+class ProjectionDifference
+{
+
+    static missingKeyLabel = 'key-not-present';
+
+    static collect(expected, actual, volatileKeys)
+    {
+        let differences = [];
+        this.compareValues(expected, actual, 'result', differences, volatileKeys);
+        return differences;
+    }
+
+    static compareValues(expected, actual, path, differences, volatileKeys)
+    {
+        if(this.isVolatilePath(path, volatileKeys)){
+            this.compareTypes(expected, actual, path, differences);
+            return;
+        }
+        if(this.typeName(expected) !== this.typeName(actual)){
+            differences.push({path, expected: this.render(expected), actual: this.render(actual)});
+            return;
+        }
+        if(sc.isArray(expected)){
+            this.compareArrays(expected, actual, path, differences, volatileKeys);
+            return;
+        }
+        if(sc.isObject(expected)){
+            this.compareObjects(expected, actual, path, differences, volatileKeys);
+            return;
+        }
+        if(expected === actual){
+            return;
+        }
+        differences.push({path, expected: this.render(expected), actual: this.render(actual)});
+    }
+
+    static compareArrays(expected, actual, path, differences, volatileKeys)
+    {
+        if(expected.length !== actual.length){
+            differences.push({
+                path: path+'.length',
+                expected: this.render(expected.length),
+                actual: this.render(actual.length)
+            });
+            return;
+        }
+        for(let index = 0; index < expected.length; index++){
+            this.compareValues(expected[index], actual[index], path+'['+index+']', differences, volatileKeys);
+        }
+    }
+
+    static compareObjects(expected, actual, path, differences, volatileKeys)
+    {
+        for(let key of Object.keys(expected)){
+            if(!sc.hasOwn(actual, key)){
+                differences.push({
+                    path: path+'.'+key,
+                    expected: this.render(expected[key]),
+                    actual: ProjectionDifference.missingKeyLabel
+                });
+                continue;
+            }
+            this.compareValues(expected[key], actual[key], path+'.'+key, differences, volatileKeys);
+        }
+        for(let key of Object.keys(actual)){
+            if(sc.hasOwn(expected, key)){
+                continue;
+            }
+            differences.push({
+                path: path+'.'+key,
+                expected: ProjectionDifference.missingKeyLabel,
+                actual: this.render(actual[key])
+            });
+        }
+    }
+
+    static compareTypes(expected, actual, path, differences)
+    {
+        if(this.typeName(expected) === this.typeName(actual)){
+            return;
+        }
+        differences.push({path, expected: this.render(expected), actual: this.render(actual)});
+    }
+
+    static isVolatilePath(path, volatileKeys)
+    {
+        if(!sc.isArray(volatileKeys)){
+            return false;
+        }
+        return -1 !== volatileKeys.indexOf(path.split('.').pop());
+    }
+
+    static typeName(value)
+    {
+        if(null === value){
+            return 'null';
+        }
+        if(sc.isArray(value)){
+            return 'array';
+        }
+        if(sc.isObject(value)){
+            return 'object';
+        }
+        return typeof value;
+    }
+
+    static render(value)
+    {
+        if(null === value){
+            return 'null';
+        }
+        if(sc.isArray(value)){
+            return 'array(length='+value.length+')';
+        }
+        if(sc.isObject(value)){
+            return 'object(keys='+Object.keys(value).join('|')+')';
+        }
+        return typeof value+'('+String(value)+')';
+    }
+
+    static describe(driverName, referenceDriverName, entityName, methodLabel, differences)
+    {
+        let lines = [];
+        for(let difference of differences){
+            lines.push(
+                'driver: '+driverName
+                +' | method: '+methodLabel
+                +' | entity: '+entityName
+                +' | key: '+difference.path
+                +' | '+referenceDriverName+' returned: '+difference.expected
+                +' | '+driverName+' returned: '+difference.actual
+            );
+        }
+        return lines;
+    }
+
+}
+
+module.exports.ProjectionDifference = ProjectionDifference;

package/tests/utils/relations-shape-support.js

@@ -0,0 +1,104 @@
+/**
+ *
+ * Reldens - Relations Shape Support
+ * Reusable fixtures setup and relation/foreign-key assertions for the child -> parent -> grandparent chain
+ * (test_reviews -> test_products -> test_categories), both links being NOT NULL m:1 foreign keys.
+ * Every assertion reports the observed value so a failure states what the driver actually returned.
+ *
+ */
+
+const { TestHelpers } = require('./test-helpers');
+const { ObservedValue } = require('./observed-value');
+const { assert } = require('./test-runner');
+const { CategoriesFixtures } = require('../fixtures/categories-fixtures');
+const { ProductsFixtures } = require('../fixtures/products-fixtures');
+const { ReviewsFixtures } = require('../fixtures/reviews-fixtures');
+
+class RelationsShapeSupport
+{
+
+    constructor(dataServer, repos)
+    {
+        this.dataServer = dataServer;
+        this.repos = {
+            child: repos.testReviews,
+            parent: repos.testProducts,
+            grandParent: repos.testCategories
+        };
+    }
+
+    async insertChainFixtures()
+    {
+        await TestHelpers.cleanDatabase(this.dataServer);
+        let fixturesByTable = {
+            test_categories: [CategoriesFixtures.category_relations_1, CategoriesFixtures.category_relations_2],
+            test_products: [ProductsFixtures.product_relations_1, ProductsFixtures.product_relations_2],
+            test_reviews: [ReviewsFixtures.review_relations_1, ReviewsFixtures.review_relations_2]
+        };
+        for(let tableName of Object.keys(fixturesByTable)){
+            await TestHelpers.insertFixturesViaRawSQL(this.dataServer, tableName, fixturesByTable[tableName]);
+        }
+        return true;
+    }
+
+    cleared(repoKey)
+    {
+        if(this.dataServer.orm && this.dataServer.orm.em){
+            this.dataServer.orm.em.clear();
+        }
+        return this.repos[repoKey];
+    }
+
+    async loadChildWithHint(relationsHint)
+    {
+        return await this.cleared('child').loadOneByWithRelations(
+            'product_id',
+            ProductsFixtures.product_relations_1.id,
+            relationsHint
+        );
+    }
+
+    assertEntityColumns(entityValue, expectedColumns, label)
+    {
+        let described = ObservedValue.log(label, entityValue);
+        assert.ok(entityValue, label+' is falsy, the relation was not populated, observed: '+described);
+        assert.notStrictEqual('number', typeof entityValue, label+' is a RAW NUMBER, observed: '+described);
+        assert.strictEqual('object', typeof entityValue, label+' is not an entity, observed: '+described);
+        for(let columnName of Object.keys(expectedColumns)){
+            assert.strictEqual(
+                entityValue[columnName],
+                expectedColumns[columnName],
+                label+'.'+columnName+' observed: '+ObservedValue.describe(entityValue[columnName])
+                +' - expected: '+String(expectedColumns[columnName])
+            );
+        }
+        return true;
+    }
+
+    assertNumericColumn(actualValue, expectedValue, label)
+    {
+        let described = ObservedValue.log(label, actualValue);
+        assert.ok(null !== actualValue, label+' is null, observed: '+described);
+        assert.strictEqual(Number(actualValue), expectedValue, label+' observed: '+described);
+        return true;
+    }
+
+    async assertStoredColumn(repoKey, id, columnName, expectedValue, label)
+    {
+        let record = await this.cleared(repoKey).loadOneBy('id', id);
+        assert.ok(record, label+' row was not found in the database, id: '+id);
+        this.assertNumericColumn(record[columnName], expectedValue, label+'.'+columnName+' re-read from database');
+        let filtered = await this.cleared(repoKey).loadBy(columnName, expectedValue);
+        let filteredIds = filtered.map((row) => Number(row.id));
+        ObservedValue.log(label+' ids where '+columnName+' = '+expectedValue, filteredIds);
+        assert.ok(
+            filteredIds.includes(Number(id)),
+            label+' id '+id+' was not returned when filtering by '+columnName+' = '+expectedValue
+            +', so that column value is not stored in the database; observed ids: '+filteredIds.join(',')
+        );
+        return true;
+    }
+
+}
+
+module.exports.RelationsShapeSupport = RelationsShapeSupport;