@reldens/storage 0.86.0 → 0.88.0

package/CLAUDE.md

@@ -111,6 +111,7 @@ npx reldens-storage-prisma --host=<host> --database=<db> --user=<user> --passwor
 - `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
+- `prisma-client-loader.js`: Utility for loading Prisma Client instances
 - Features:
   - Schema-first approach with auto-introspection
   - Type-safe queries with Prisma Client
@@ -212,24 +213,22 @@ Templates use placeholder replacement with `{{placeholderName}}` syntax.
 
 ## Generated File Structure
 
-```
-generated-entities/
-├── entities/
-│   ├── [table-name]-entity.js      # Entity definitions
-│   └── ...
-├── models/
-│   ├── objection-js/
-│   │   ├── [table-name]-model.js
-│   │   └── registered-models-objection-js.js
-│   ├── mikro-orm/
-│   │   ├── [table-name]-model.js
-│   │   └── registered-models-mikro-orm.js
-│   └── prisma/
-│       ├── [table-name]-model.js
-│       └── registered-models-prisma.js
-├── entities-config.js               # Entity relation configuration
-└── entities-translations.js         # Translation keys
-```
+All generated files are created in the **generated-entities/** directory:
+
+**Entity Definitions:**
+- entities/[table-name]-entity.js
+
+**Driver Models:**
+- models/objection-js/[table-name]-model.js
+- models/objection-js/registered-models-objection-js.js
+- models/mikro-orm/[table-name]-model.js
+- models/mikro-orm/registered-models-mikro-orm.js
+- models/prisma/[table-name]-model.js
+- models/prisma/registered-models-prisma.js
+
+**Configuration Files:**
+- entities-config.js (entity relation configuration)
+- entities-translations.js (translation keys)
 
 ## Relation Keys Pattern
 
@@ -398,3 +397,78 @@ The `prepareDataWithRelations()` method (lines 156-199) automatically converts F
 - `RELDENS_DB_PARAMS`: Database connection parameters (used by Prisma)
 - Format: `key1=value1&key2=value2`
 - Example: `authPlugin=mysql_native_password&sslmode=require`
+
+## PrismaClientLoader Utility
+
+**Location:** `lib/prisma/prisma-client-loader.js`
+
+**Purpose:** Shared utility for loading Prisma Client instances in CLI tools and applications.
+
+**Exported From Package:** Yes, available via `const { PrismaClientLoader } = require('@reldens/storage');`
+
+**Method:**
+```javascript
+PrismaClientLoader.load(projectPath, customPath, connectionData)
+```
+
+**Parameters:**
+- `projectPath` (string): Project root directory path
+- `customPath` (string|null): Optional custom path to a Prisma client (overrides default)
+- `connectionData` (object|null): Optional database connection configuration with properties:
+  - `client` (string): Database client type (mysql, postgresql, etc.)
+  - `user` (string): Database username
+  - `password` (string): Database password
+  - `host` (string): Database host
+  - `port` (number): Database port
+  - `database` (string): Database name
+
+**Returns:** PrismaClient instance or null on error
+
+**Behavior:**
+- If `customPath` is provided, uses that path
+- Otherwise, uses a default path: `projectPath/prisma/client`
+- Validates that Prisma Client exists at the path
+- Requires `prismaModule.PrismaClient` export
+- If `connectionData` is null: Uses default connection from Prisma schema datasource
+- If `connectionData` is provided: Builds custom connection string and overrides datasource
+- Returns initialized PrismaClient instance
+
+**Usage Examples:**
+
+Using the default connection from schema:
+```javascript
+const { PrismaClientLoader } = require('@reldens/storage');
+
+const prismaClient = PrismaClientLoader.load(process.cwd(), null, null);
+if(!prismaClient){
+    console.error('Failed to load Prisma client');
+    process.exit(1);
+}
+```
+
+Using custom connection:
+```javascript
+const { PrismaClientLoader } = require('@reldens/storage');
+
+const prismaClient = PrismaClientLoader.load(
+    process.cwd(),
+    null,
+    {
+        client: 'mysql',
+        user: 'dbuser',
+        password: 'dbpass',
+        host: 'localhost',
+        port: 3306,
+        database: 'mydb'
+    }
+);
+
+if(!prismaClient){
+    console.error('Failed to load Prisma client');
+    process.exit(1);
+}
+```
+
+**Used By:**
+- `bin/reldens-storage.js`: CLI entity generator
+- External packages: `@reldens/cms` CLI tools (update-password, generate-entities, generate-sitemap)

package/README.md

@@ -182,6 +182,49 @@ const entities = server.generateEntities();
 
 Note: The PrismaDataServer requires the Prisma schema to be generated first. Make sure to run the `reldens-generate-prisma-schema` command before using PrismaDataServer.
 
+### Loading Prisma Client Programmatically
+
+If you need to load a Prisma Client instance in your CLI tools or applications:
+
+Using the default connection from schema:
+```javascript
+const { PrismaClientLoader } = require('@reldens/storage');
+
+const prismaClient = PrismaClientLoader.load(process.cwd(), null, null);
+if(!prismaClient){
+    console.error('Failed to load Prisma client');
+    process.exit(1);
+}
+```
+
+Using custom connection:
+```javascript
+const { PrismaClientLoader } = require('@reldens/storage');
+
+const prismaClient = PrismaClientLoader.load(
+    process.cwd(),
+    null,
+    {
+        client: 'mysql',
+        user: 'dbuser',
+        password: 'dbpass',
+        host: 'localhost',
+        port: 3306,
+        database: 'mydb'
+    }
+);
+
+if(!prismaClient){
+    console.error('Failed to load Prisma client');
+    process.exit(1);
+}
+```
+
+Parameters:
+- `projectPath`: Project root directory
+- `customPath`: Optional custom path to a Prisma client (null for default)
+- `connectionData`: Optional database connection configuration object (null to use schema default)
+
 ## Custom Drivers
 
 You can create custom storage drivers by extending the base classes:
@@ -237,28 +280,28 @@ All drivers must implement the methods defined in `BaseDriver`:
 
 ## Generated File Structure
 
-When you run entity generation, files are created in the `generated-entities/` directory:
+When you run entity generation, all files are created in the **generated-entities/** directory:
 
-```
-generated-entities/
-├── entities/
-│   ├── users-entity.js           # Entity definitions with properties
-│   ├── players-entity.js
-│   └── ...
-├── models/
-│   ├── objection-js/
-│   │   ├── users-model.js        # ObjectionJS models with relationMappings
-│   │   ├── players-model.js
-│   │   └── registered-models-objection-js.js
-│   ├── mikro-orm/
-│   │   ├── users-model.js        # MikroORM models
-│   │   └── registered-models-mikro-orm.js
-│   └── prisma/
-│       ├── users-model.js        # Prisma models with relationTypes
-│       └── registered-models-prisma.js
-├── entities-config.js            # Entity configuration and relations
-└── entities-translations.js      # i18n translation keys
-```
+**Entity Definitions:**
+- entities/users-entity.js
+- entities/players-entity.js
+
+**ObjectionJS Models:**
+- models/objection-js/users-model.js
+- models/objection-js/players-model.js
+- models/objection-js/registered-models-objection-js.js
+
+**MikroORM Models:**
+- models/mikro-orm/users-model.js
+- models/mikro-orm/registered-models-mikro-orm.js
+
+**Prisma Models:**
+- models/prisma/users-model.js
+- models/prisma/registered-models-prisma.js
+
+**Configuration Files:**
+- entities-config.js (entity relations)
+- entities-translations.js (i18n keys)
 
 ### Entity Files
 - **Entity classes**: Define properties, types, validations

package/bin/reldens-storage.js

@@ -7,7 +7,7 @@
  */
 
 const { EntitiesGenerator } = require('../lib/entities-generator');
-const { FileHandler } = require('@reldens/server-utils');
+const { PrismaClientLoader } = require('../lib/prisma/prisma-client-loader');
 const { Logger, sc } = require('@reldens/utils');
 
 class StorageEntitiesGenerator
@@ -113,32 +113,11 @@ class StorageEntitiesGenerator
 
     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);
+        let loadedClient = PrismaClientLoader.load(this.projectPath, this.prismaClientPath, connectionData);
+        if(!loadedClient){
             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']
-        });
+        return loadedClient;
     }
 
     async run()

package/index.js

@@ -19,6 +19,7 @@ const { MySQLTablesProvider } = require('./lib/mysql-tables-provider');
 const { PrismaDriver } = require('./lib/prisma/prisma-driver');
 const { PrismaDataServer } = require('./lib/prisma/prisma-data-server');
 const { PrismaSchemaGenerator } = require('./lib/prisma/prisma-schema-generator');
+const { PrismaClientLoader } = require('./lib/prisma/prisma-client-loader');
 
 module.exports = {
     // base:
@@ -46,6 +47,7 @@ module.exports = {
     PrismaDataServer,
     PrismaDriver,
     PrismaSchemaGenerator,
+    PrismaClientLoader,
     // entities:
     EntitiesGenerator,
     EntityProperties,

package/lib/prisma/prisma-client-loader.js

@@ -0,0 +1,45 @@
+/**
+ *
+ * Reldens - Storage - PrismaClientLoader
+ *
+ */
+
+const { Logger } = require('@reldens/utils');
+const { FileHandler } = require('@reldens/server-utils');
+
+class PrismaClientLoader
+{
+
+    static load(projectPath, customPath, connectionData)
+    {
+        let prismaClientPath = customPath;
+        if(!prismaClientPath){
+            prismaClientPath = FileHandler.joinPaths(projectPath, 'prisma', 'client');
+        }
+        if(!FileHandler.exists(prismaClientPath)){
+            Logger.critical('PrismaClient path does not exist: '+prismaClientPath);
+            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;
+        }
+        if(!connectionData){
+            Logger.info('Creating PrismaClient with default connection from schema');
+            return new prismaModule.PrismaClient({log: ['error']});
+        }
+        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']});
+    }
+
+}
+
+module.exports.PrismaClientLoader = PrismaClientLoader;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@reldens/storage",
     "scope": "@reldens",
-    "version": "0.86.0",
+    "version": "0.88.0",
     "description": "Reldens - Storage",
     "author": "Damian A. Pastorini",
     "license": "MIT",