@reldens/storage 0.116.0 → 0.118.0

package/tests/unit/test-models-generation.js

@@ -0,0 +1,174 @@
+/**
+ *
+ * Reldens - ModelsGeneration Test
+ *
+ */
+
+const { TestRunner, assert } = require('../utils/test-runner');
+const { RelationsDetection } = require('../../lib/generators/relations-detection');
+const { MikroOrmModelsGeneration } = require('../../lib/mikro-orm/mikro-orm-models-generation');
+
+class ModelsGenerationTest
+{
+
+    constructor()
+    {
+        this.runner = new TestRunner();
+    }
+
+    createColumn(props)
+    {
+        return Object.assign(
+            {
+                name: 'test_column',
+                type: 'int',
+                columnType: 'int(10) unsigned',
+                length: null,
+                nullable: false,
+                key: '',
+                extra: '',
+                default: null
+            },
+            props
+        );
+    }
+
+    createForeignKeyColumn(name, key)
+    {
+        return this.createColumn({
+            name,
+            key,
+            referencedTable: 'test_products',
+            referencedColumn: 'id',
+            referencedDeleteRule: 'CASCADE'
+        });
+    }
+
+    createTables()
+    {
+        return {
+            test_products: {
+                name: 'test_products',
+                columns: {
+                    id: this.createColumn({name: 'id', key: 'PRI', extra: 'auto_increment'}),
+                    name: this.createColumn({name: 'name', type: 'varchar', columnType: 'varchar(200)', length: '200'})
+                }
+            },
+            test_product_details: {
+                name: 'test_product_details',
+                columns: {
+                    id: this.createColumn({name: 'id', key: 'PRI', extra: 'auto_increment'}),
+                    product_id: this.createForeignKeyColumn('product_id', 'UNI')
+                }
+            },
+            test_reviews: {
+                name: 'test_reviews',
+                columns: {
+                    id: this.createColumn({name: 'id', key: 'PRI', extra: 'auto_increment'}),
+                    product_id: this.createForeignKeyColumn('product_id', 'MUL')
+                }
+            }
+        };
+    }
+
+    createRelationsDetection()
+    {
+        let relationsDetection = new RelationsDetection({});
+        relationsDetection.allTablesData = this.createTables();
+        return relationsDetection;
+    }
+
+    createGeneration()
+    {
+        return new MikroOrmModelsGeneration(this.createRelationsDetection());
+    }
+
+    mikroOrmDefinition(generation, tableName)
+    {
+        let tableData = generation.relationsDetection.allTablesData[tableName];
+        return generation.generateEntityProperties(tableData.columns, tableName, tableData);
+    }
+
+    async run()
+    {
+        this.runner.suite('ModelsGeneration');
+        await this.testForwardRelationKind();
+        await this.testMikroOrmOneToOneDefinitions();
+        await this.testObjectionJsRelationTypes();
+        return this.runner.getResults();
+    }
+
+    async testForwardRelationKind()
+    {
+        this.runner.group('forwardRelationKind');
+        let generation = this.createGeneration();
+        await this.runner.test('should return 1:1 for a unique foreign key column', async () => {
+            let kind = generation.forwardRelationKind(this.createColumn({key: 'UNI'}));
+            assert.strictEqual(kind, '1:1');
+        });
+        await this.runner.test('should return 1:1 for a primary foreign key column', async () => {
+            let kind = generation.forwardRelationKind(this.createColumn({key: 'PRI'}));
+            assert.strictEqual(kind, '1:1');
+        });
+        await this.runner.test('should return m:1 for an indexed foreign key column', async () => {
+            let kind = generation.forwardRelationKind(this.createColumn({key: 'MUL'}));
+            // @possible-hallucinated-undefined-method
+            assert.strictEqual(kind, 'm:1');
+        });
+        await this.runner.test('should return m:1 for a non indexed foreign key column', async () => {
+            let kind = generation.forwardRelationKind(this.createColumn({key: ''}));
+            assert.strictEqual(kind, 'm:1');
+        });
+    }
+
+    async testMikroOrmOneToOneDefinitions()
+    {
+        this.runner.group('getEntityPropertiesDefinition - mikro-orm one to one');
+        let generation = this.createGeneration();
+        await this.runner.test('should emit a 1:1 owning side with joinColumns for a unique foreign key', async () => {
+            let definition = this.mikroOrmDefinition(generation, 'test_product_details');
+            assert.ok(definition.includes('related_test_products: {\n            kind: \'1:1\','));
+            assert.ok(definition.includes('joinColumns: [\'product_id\']'));
+            assert.ok(!definition.includes('mappedBy'));
+        });
+        await this.runner.test('should emit a 1:1 inverse side with mappedBy for a unique foreign key', async () => {
+            let definition = this.mikroOrmDefinition(generation, 'test_products');
+            assert.ok(definition.includes('related_test_product_details: {\n            kind: \'1:1\','));
+            assert.ok(definition.includes('mappedBy: \'related_test_products\''));
+        });
+        await this.runner.test('should emit a 1:m inverse side for a non unique foreign key', async () => {
+            let definition = this.mikroOrmDefinition(generation, 'test_products');
+            assert.ok(definition.includes('related_test_reviews: {\n            kind: \'1:m\','));
+        });
+        await this.runner.test('should emit a m:1 owning side for a non unique foreign key', async () => {
+            let definition = this.mikroOrmDefinition(generation, 'test_reviews');
+            assert.ok(definition.includes('related_test_products: {\n            kind: \'m:1\','));
+            assert.ok(definition.includes('joinColumns: [\'product_id\']'));
+        });
+    }
+
+    async testObjectionJsRelationTypes()
+    {
+        this.runner.group('ObjectionJS relation types for unique foreign keys');
+        let relationsDetection = this.createRelationsDetection();
+        let tables = relationsDetection.allTablesData;
+        await this.runner.test('should keep BelongsToOneRelation on the owning side', async () => {
+            let relations = relationsDetection.detectForwardRelations(
+                'test_product_details',
+                tables.test_product_details
+            );
+            assert.strictEqual(relations.related_test_products.relationType, 'BelongsToOneRelation');
+        });
+        await this.runner.test('should use HasOneRelation on the referenced side of a unique foreign key', async () => {
+            let reverseRelations = relationsDetection.detectReverseRelations('test_products');
+            assert.strictEqual(reverseRelations.related_test_product_details.relationType, 'HasOneRelation');
+        });
+        await this.runner.test('should use HasManyRelation on the referenced side of a non unique foreign key', async () => {
+            let reverseRelations = relationsDetection.detectReverseRelations('test_products');
+            assert.strictEqual(reverseRelations.related_test_reviews.relationType, 'HasManyRelation');
+        });
+    }
+
+}
+
+module.exports = ModelsGenerationTest;

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/driver-registry.js

@@ -22,7 +22,7 @@ class DriverRegistry
             instanceId: Math.random()
         };
         this.schemaPath = FileHandler.joinPaths(__dirname, '..', 'fixtures', 'sql', 'test-schema.sql');
-        this.repoNames = ['testCategories', 'testProducts', 'testReviews'];
+        this.repoNames = ['testCategories', 'testProductDetails', 'testProducts', 'testReviews'];
         this.driverNames = TestHelpers.activeDriverNames();
         this.skipGeneration = false;
     }

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;