@reldens/storage 0.81.0 → 0.82.0

package/CLAUDE.md

@@ -105,12 +105,18 @@ npx reldens-storage-prisma --host=<host> --database=<db> --user=<user> --passwor
   - Automatic schema synchronization
 
 **Prisma Driver** (`lib/prisma/`):
-- `prisma-driver.js`: Driver implementation
+- `prisma-driver.js`: Driver implementation with enhanced validation
 - `prisma-data-server.js`: Data server using Prisma Client
 - `prisma-schema-generator.js`: Schema generation and introspection
+- `prisma-metadata-loader.js`: Loads field metadata including defaults
+- `prisma-type-caster.js`: Type casting and normalization
+- `prisma-relation-resolver.js`: Relation mapping and transformations
 - Features:
-  - Schema-first approach
-  - Type-safe queries
+  - Schema-first approach with auto-introspection
+  - Type-safe queries with Prisma Client
+  - Custom `ensureRequiredFields()` validation for better error messages
+  - Database default value support (skips validation for fields with defaults)
+  - VARCHAR foreign key support using relation connect syntax
   - Introspection via `prisma db pull`
   - Binary targets configuration
   - Data proxy support
@@ -237,6 +243,122 @@ All generated entity relations follow the `related_*` prefix pattern:
 
 This pattern is consistent across all ORM drivers and is defined in `entities-config.js`.
 
+## Prisma Driver Validation System
+
+### ensureRequiredFields() Method
+
+The Prisma driver includes custom validation that differs from ObjectionJS and provides better error messages:
+
+**Location:** `lib/prisma/prisma-driver.js` lines 201-223
+
+**Purpose:** Validates that all required fields are present before sending data to Prisma Client
+
+**Key Behavior:**
+```javascript
+ensureRequiredFields(data) {
+    let missingFields = [];
+    for(let field of this.requiredFields){
+        if(sc.hasOwn(data, field)){
+            continue;  // Field is present
+        }
+        if(sc.hasOwn(this.foreignKeyMappings, field)){
+            let relationName = this.foreignKeyMappings[field];
+            if(sc.hasOwn(data, relationName)){
+                continue;  // FK mapped to relation (connect syntax)
+            }
+        }
+        if(sc.hasOwn(this.fieldDefaults, field)){
+            continue;  // Field has database default - skip validation
+        }
+        missingFields.push(field);
+    }
+    if(0 < missingFields.length){
+        Logger.warning('Missing required fields for '+this.tableName()+': '+missingFields.join(', '));
+    }
+    return data;
+}
+```
+
+**Important:** This validation runs BEFORE Prisma Client, allowing it to:
+1. Provide clear error messages about missing fields
+2. Allow database defaults to work (doesn't validate fields with defaults)
+3. Support foreign key relation syntax (checks both FK field and relation)
+
+### Database Default Values
+
+**How It Works:**
+- Metadata loader extracts default values from Prisma schema (`@default()` directive)
+- Stored in `this.fieldDefaults` map during driver initialization
+- Validation skips required fields that have defaults
+- Prisma/database applies default when field is missing
+
+**Example:**
+```javascript
+// Prisma schema
+model scores_detail {
+  kill_time  DateTime @default(now()) @db.DateTime(0)
+}
+
+// Admin panel sends data without kill_time
+{
+  player_id: 1001,
+  obtained_score: 150
+  // kill_time missing but has default
+}
+
+// Validation skips kill_time (has default)
+// Prisma creates record, database applies DEFAULT CURRENT_TIMESTAMP
+```
+
+### Comparison with ObjectionJS
+
+**ObjectionJS Driver:**
+```javascript
+create(params) {
+    return this.queryBuilder().insert(params);
+}
+```
+- No validation
+- Passes data directly to Knex
+- Database handles missing fields and defaults
+- Less informative error messages
+
+**Prisma Driver:**
+```javascript
+async create(params) {
+    let preparedData = this.prepareDataWithRelations(params, true);
+    this.ensureRequiredFields(preparedData);  // Custom validation
+    try {
+        return this.typeCaster.normalizeReturnData(await this.model.create({data: preparedData}));
+```
+- Custom validation before Prisma
+- Better error messages
+- Supports database defaults
+- Type-safe queries
+
+**Key Difference:** Prisma validates first, so it must be aware of database defaults to allow them to work.
+
+### Foreign Key Handling
+
+Both drivers handle foreign keys, but with different syntax:
+
+**ObjectionJS:**
+```javascript
+// Direct FK field
+{player_id: 1001}
+```
+
+**Prisma:**
+```javascript
+// Relation connect syntax
+{players: {connect: {id: 1001}}}
+
+// Also supports VARCHAR FKs
+{related_table: {connect: {custom_id: "ABC123"}}}
+```
+
+The `prepareDataWithRelations()` method (lines 156-199) automatically converts FK fields to relation syntax.
+
 ## Important Notes
 
 ### Entity Management

package/bin/reldens-storage.js

@@ -7,6 +7,7 @@
  */
 
 const { EntitiesGenerator } = require('../lib/entities-generator');
+const { FileHandler } = require('@reldens/server-utils');
 const { Logger, sc } = require('@reldens/utils');
 
 class StorageEntitiesGenerator
@@ -19,6 +20,7 @@ class StorageEntitiesGenerator
         this.config = {};
         this.projectPath = process.cwd();
         this.isOverride = false;
+        this.prismaClientPath = '';
         this.parseArguments();
     }
 
@@ -38,11 +40,15 @@ class StorageEntitiesGenerator
                 continue;
             }
             let key = arg.substring(2, equalIndex);
-            let value = arg.substring(equalIndex + 1);
+            let value = arg.substring(equalIndex+1);
             if('path' === key){
                 this.projectPath = value;
                 continue;
             }
+            if('prismaClientPath' === key){
+                this.prismaClientPath = value;
+                continue;
+            }
             if('pass' === key){
                 this.config['password'] = value;
                 continue;
@@ -69,6 +75,9 @@ class StorageEntitiesGenerator
         if('mikro-orm' === connectionData.driver && !this.config.client){
             connectionData.client = 'mysql';
         }
+        if('prisma' === connectionData.driver && !this.config.client){
+            connectionData.client = 'mysql';
+        }
         return connectionData;
     }
 
@@ -84,16 +93,54 @@ class StorageEntitiesGenerator
     validateRequiredArgs(connectionData)
     {
         if(!connectionData.user || !connectionData.database){
-            Logger.error('Required parameters missing.');
-            Logger.error('Usage: npx reldens-storage generateEntities --user=[db-username] --pass=[db-password] --host=[db-host] --database=[db-name] --driver=[driver-map-key] --client=[db-client] --path=[project-path] --override');
-            Logger.error('');
-            Logger.error('Optional flags:');
-            Logger.error('  --override    Regenerate all files even if they exist');
+            Logger.error(
+                'Required parameters missing.',
+                'Usage: npx reldens-storage generateEntities --user=[db-username]'
+                +' --pass=[db-password]'
+                +' --host=[db-host]'
+                +' --database=[db-name]'
+                +' --driver=[driver-map-key]'
+                +' --client=[db-client]'
+                +' --prismaClientPath=[path-to-prisma-client]'
+                +' --path=[project-path] --override',
+                'Optional flags:',
+                '  --override    Regenerate all files even if they exist'
+            );
             return false;
         }
         return true;
     }
 
+    loadPrismaClient(connectionData)
+    {
+        let prismaClientPath = this.prismaClientPath;
+        if(!prismaClientPath){
+            prismaClientPath = FileHandler.joinPaths(this.projectPath, 'prisma', 'client');
+        }
+        if(!FileHandler.exists(prismaClientPath)){
+            Logger.critical('PrismaClient path does not exist: '+prismaClientPath);
+            Logger.info('Please run "npx prisma generate" first or provide --prismaClientPath argument.');
+            return null;
+        }
+        Logger.info('Loading PrismaClient from: '+prismaClientPath);
+        let prismaModule = require(prismaClientPath);
+        if(!prismaModule.PrismaClient){
+            Logger.critical('PrismaClient class not found at: '+prismaClientPath);
+            return null;
+        }
+        let connectionString = connectionData.client+'://'
+            +connectionData.user
+            +(connectionData.password ? ':'+connectionData.password : '')
+            +'@'+connectionData.host
+            +':'+connectionData.port
+            +'/'+connectionData.database;
+        Logger.info('Creating PrismaClient with connection to: '+connectionData.database);
+        return new prismaModule.PrismaClient({
+            datasources: {db: {url: connectionString}},
+            log: ['error']
+        });
+    }
+
     async run()
     {
         if(!this.validateCommand()){
@@ -103,11 +150,19 @@ class StorageEntitiesGenerator
         if(!this.validateRequiredArgs(connectionData)){
             return false;
         }
-        let generator = new EntitiesGenerator({
+        let generatorProps = {
             connectionData,
             projectPath: this.projectPath,
             isOverride: this.isOverride
-        });
+        };
+        if('prisma' === connectionData.driver){
+            let prismaClient = this.loadPrismaClient(connectionData);
+            if(!prismaClient){
+                return false;
+            }
+            generatorProps.prismaClient = prismaClient;
+        }
+        let generator = new EntitiesGenerator(generatorProps);
         let success = await generator.generate();
         if(!success){
             Logger.error('Entity generation failed.');

package/lib/entities-generator.js

@@ -208,7 +208,7 @@ class EntitiesGenerator
             }
             this.processModelForRelations(model.name, model, models);
         }
-        Logger.info('Extracted relations metadata for ' + Object.keys(this.prismaRelationsMetadata).length + ' models.');
+        Logger.info('Extracted relations metadata for '+Object.keys(this.prismaRelationsMetadata).length+' models.');
     }
 
     processObjectModels(models)
@@ -225,7 +225,7 @@ class EntitiesGenerator
             }
             this.processModelForRelations(modelName, model, models);
         }
-        Logger.info('Extracted relations metadata for ' + Object.keys(this.prismaRelationsMetadata).length + ' models.');
+        Logger.info('Extracted relations metadata for '+Object.keys(this.prismaRelationsMetadata).length+' models.');
     }
 
     processModelForRelations(modelName, model, allModels)
@@ -470,7 +470,8 @@ class EntitiesGenerator
                 database: sc.get(this.connectionData, 'database', ''),
                 host: sc.get(this.connectionData, 'host', 'localhost'),
                 port: sc.get(this.connectionData, 'port', 3306)
-            }
+            },
+            projectRoot: this.projectPath
         };
         if('prisma' === driverKey && this.prismaClient){
             serverConfig.prismaClient = this.prismaClient;

package/lib/generators/models-generation.js

@@ -100,7 +100,7 @@ class ModelsGeneration extends BaseGenerator
     generateModelRelations(tableName, tableData, relationMetadata, driverKey)
     {
         if('prisma' === driverKey){
-            return this.generatePrismaRelations(relationMetadata);
+            return this.generatePrismaRelations(tableName, tableData, relationMetadata);
         }
         if('objection-js' === driverKey){
             return this.generateObjectionJsRelations(tableName, tableData);
@@ -108,20 +108,173 @@ class ModelsGeneration extends BaseGenerator
         return '';
     }
 
-    generatePrismaRelations(relationMetadata)
+    generatePrismaRelations(tableName, tableData, relationMetadata)
     {
         if(!relationMetadata || 0 === Object.keys(relationMetadata).length){
             return '';
         }
         let relationTypesArray = [];
-        for(let relationName of Object.keys(relationMetadata)){
-            let relation = relationMetadata[relationName];
-            relationTypesArray.push('        '+relationName+': \''+relation.type+'\'');
+        let relationMappingsArray = [];
+        let forwardMappings = this.buildPrismaForwardMappings(tableData, relationMetadata);
+        let reverseMappings = this.buildPrismaReverseMappings(tableName, relationMetadata);
+        let allMappings = Object.assign({}, forwardMappings, reverseMappings);
+        for(let prismaRelationName of Object.keys(relationMetadata)){
+            let relation = relationMetadata[prismaRelationName];
+            relationTypesArray.push('            '+prismaRelationName+': \''+relation.type+'\'');
+        }
+        for(let reldensKey of Object.keys(allMappings)){
+            let prismaName = allMappings[reldensKey];
+            relationMappingsArray.push('            \''+reldensKey+'\': \''+prismaName+'\'');
+        }
+        let result = '';
+        if(0 < relationTypesArray.length){
+            result += '\n\n    static get relationTypes()\n    {\n        return {\n';
+            result += relationTypesArray.join(',\n');
+            result += '\n        };\n    }';
+        }
+        if(0 < relationMappingsArray.length){
+            result += '\n\n    static get relationMappings()\n    {\n        return {\n';
+            result += relationMappingsArray.join(',\n');
+            result += '\n        };\n    }';
+        }
+        return result;
+    }
+
+    buildPrismaForwardMappings(tableData, relationMetadata)
+    {
+        let mappings = {};
+        let referenceCounts = this.countReferencesPerTable(tableData);
+        for(let columnName of Object.keys(tableData.columns)){
+            let column = tableData.columns[columnName];
+            if(!sc.hasOwn(column, 'referencedTable')){
+                continue;
+            }
+            let reldensKey = this.generateForwardRelationKey(
+                column.referencedTable,
+                columnName,
+                referenceCounts
+            );
+            let prismaName = this.findPrismaRelationForFk(columnName, column.referencedTable, relationMetadata);
+            if(!prismaName){
+                continue;
+            }
+            mappings[reldensKey] = prismaName;
         }
-        if(0 === relationTypesArray.length){
-            return '';
+        return mappings;
+    }
+
+    findPrismaRelationForFk(columnName, referencedTable, relationMetadata)
+    {
+        let lowerColumn = columnName.toLowerCase();
+        let lowerTable = referencedTable.toLowerCase();
+        for(let prismaName of Object.keys(relationMetadata)){
+            let relation = relationMetadata[prismaName];
+            if(relation.model.toLowerCase() !== lowerTable){
+                continue;
+            }
+            if(relation.isList){
+                continue;
+            }
+            let lowerPrisma = prismaName.toLowerCase();
+            if(lowerPrisma.includes(lowerColumn.replace('_id', ''))){
+                return prismaName;
+            }
+            if(lowerPrisma.includes(lowerColumn)){
+                return prismaName;
+            }
+        }
+        for(let prismaName of Object.keys(relationMetadata)){
+            let relation = relationMetadata[prismaName];
+            if(relation.model.toLowerCase() !== lowerTable){
+                continue;
+            }
+            if(relation.isList){
+                continue;
+            }
+            return prismaName;
+        }
+        return null;
+    }
+
+    buildPrismaReverseMappings(tableName, relationMetadata)
+    {
+        let mappings = {};
+        let reverseRelations = {};
+        for(let prismaName of Object.keys(relationMetadata)){
+            let relation = relationMetadata[prismaName];
+            if(this.isForwardRelation(relation)){
+                continue;
+            }
+            let relatedTable = relation.model.toLowerCase();
+            if(!reverseRelations[relatedTable]){
+                reverseRelations[relatedTable] = [];
+            }
+            reverseRelations[relatedTable].push({prismaName, relation});
+        }
+        for(let relatedTable of Object.keys(reverseRelations)){
+            let relations = reverseRelations[relatedTable];
+            let referenceCount = relations.length;
+            for(let relInfo of relations){
+                let reldensKey = this.generatePrismaReverseRelationKey(
+                    relatedTable,
+                    relInfo.prismaName,
+                    tableName,
+                    referenceCount
+                );
+                mappings[reldensKey] = relInfo.prismaName;
+            }
+        }
+        return mappings;
+    }
+
+    isForwardRelation(relation)
+    {
+        return sc.hasOwn(relation, 'foreignKeys')
+            && sc.isArray(relation.foreignKeys)
+            && 0 < relation.foreignKeys.length;
+    }
+
+    generatePrismaReverseRelationKey(relatedTable, prismaName, tableName, referenceCount)
+    {
+        if(1 === referenceCount){
+            return 'related_'+relatedTable;
+        }
+        let columnHint = this.extractColumnHintFromPrismaName(prismaName, relatedTable, tableName);
+        if(columnHint){
+            return 'related_'+relatedTable+'_'+columnHint;
+        }
+        return 'related_'+relatedTable;
+    }
+
+    extractColumnHintFromPrismaName(prismaName, relatedTable, tableName)
+    {
+        let lowerName = prismaName.toLowerCase();
+        let lowerTable = tableName.toLowerCase();
+        let lowerRelated = relatedTable.toLowerCase();
+        let toSuffix = 'to'+lowerTable;
+        if(!lowerName.endsWith(toSuffix)){
+            toSuffix = 'to'+lowerRelated;
+            if(!lowerName.endsWith(toSuffix)){
+                return null;
+            }
+        }
+        let withoutSuffix = prismaName.slice(0, -toSuffix.length);
+        let lowerWithout = withoutSuffix.toLowerCase();
+        let prefixes = [
+            lowerRelated+'_'+lowerRelated+'_',
+            lowerRelated+'_',
+            lowerTable+'_'
+        ];
+        for(let prefix of prefixes){
+            if(lowerWithout.startsWith(prefix)){
+                withoutSuffix = withoutSuffix.slice(prefix.length);
+                lowerWithout = withoutSuffix.toLowerCase();
+            }
+        }
+        if(withoutSuffix.endsWith('_id')){
+            withoutSuffix = withoutSuffix.slice(0, -3);
         }
-        return '\n\n    static get relationTypes()\n    {\n        return {\n    '+relationTypesArray.join(',\n    ')+'\n        };\n    }';
+        return withoutSuffix.toLowerCase();
     }
 
     generateObjectionJsRelations(tableName, tableData)

package/lib/prisma/prisma-data-server.js

@@ -8,6 +8,7 @@ const { BaseDataServer } = require('../base-data-server');
 const { PrismaDriver } = require('./prisma-driver');
 const { MySQLTablesProvider } = require('../mysql-tables-provider');
 const { PrismaClient } = require('@prisma/client');
+const { FileHandler } = require('@reldens/server-utils');
 const { Logger, sc } = require('@reldens/utils');
 
 class PrismaDataServer extends BaseDataServer
@@ -17,6 +18,8 @@ class PrismaDataServer extends BaseDataServer
     {
         super(props);
         this.prisma = sc.get(props, 'prismaClient', false);
+        this.projectRoot = sc.get(props, 'projectRoot', false);
+        this.allRelationMappings = {};
     }
 
     async connect()
@@ -25,12 +28,16 @@ class PrismaDataServer extends BaseDataServer
             return this.initialized;
         }
         try {
-            if(!this.prisma){
+            if(!this.prisma && this.defaultClientIsGenerated()){
                 this.prisma = new PrismaClient({
                     datasources: {db: {url: this.connectString}},
                     log: this.debug ? ['query', 'info', 'warn', 'error'] : ['error']
                 });
             }
+            if(!this.prisma){
+                Logger.error('Prisma client could not be initialized.');
+                return false;
+            }
             await this.prisma.$connect();
             let dbTest = await this.prisma.$queryRaw`SELECT DATABASE() as current_db`;
             Logger.info('Connected to database: ' + dbTest[0].current_db);
@@ -42,6 +49,20 @@ class PrismaDataServer extends BaseDataServer
         return false;
     }
 
+    defaultClientIsGenerated()
+    {
+        let existsFromProjectRoot = false;
+        if(this.projectRoot){
+            existsFromProjectRoot = FileHandler.exists(FileHandler.joinPaths(
+                this.projectRoot, 'node_modules', '@prisma', 'client', 'index.js'
+            ));
+        }
+        let existsFromRelativePath = FileHandler.exists(FileHandler.joinPaths(
+            __dirname, '..', '..', '..', '@prisma', 'client', 'index.js'
+        ));
+        return existsFromProjectRoot || existsFromRelativePath;
+    }
+
     generateEntities()
     {
         if(!this.initialized){
@@ -52,6 +73,7 @@ class PrismaDataServer extends BaseDataServer
             Logger.warning('Empty raw entities array, none entities generated.');
             return {};
         }
+        this.collectAllRelationMappings();
         this.entities = {};
         for(let i of Object.keys(this.rawEntities)){
             let rawEntity = this.rawEntities[i];
@@ -68,13 +90,25 @@ class PrismaDataServer extends BaseDataServer
                 config: this.config,
                 prisma: this.prisma,
                 model: prismaModel,
-                server: this
+                server: this,
+                allRelationMappings: this.allRelationMappings
             });
         }
         this.entityManager.setEntities(this.entities);
         return this.entities;
     }
 
+    collectAllRelationMappings()
+    {
+        for(let i of Object.keys(this.rawEntities)){
+            let rawEntity = this.rawEntities[i];
+            let tableName = rawEntity.tableName;
+            if(rawEntity.relationMappings){
+                this.allRelationMappings[tableName] = rawEntity.relationMappings;
+            }
+        }
+    }
+
     name()
     {
         return this.name || 'Prisma Data Server Driver';
@@ -103,7 +137,7 @@ class PrismaDataServer extends BaseDataServer
                 //Logger.error('Statement results length is zero.', results);
                 return false;
             }
-            return 1 === results.length ? results[0] : results;
+            return 1 === results.length ? [...results].shift() : results;
         } catch(error) {
             Logger.error('Raw query failed: '+error.message);
             return false;
@@ -126,7 +160,7 @@ class PrismaDataServer extends BaseDataServer
             || trimmedStatement.startsWith('ALTER')
             || trimmedStatement.startsWith('DROP')
         ){
-            return { affectedRows: result };
+            return {affectedRows: result};
         }
         return result;
     }