@friggframework/core 2.0.0--canary.463.62579dd.0 → 2.0.0--canary.461.84ff4f5.0

package/README.md

@@ -62,6 +62,34 @@ npm install @friggframework/core
 yarn add @friggframework/core
 ```
 
+### Prisma Support (Optional)
+
+`@friggframework/core` supports both MongoDB and PostgreSQL via Prisma ORM. **Prisma is an optional peer dependency** - you only need to install it if you're using database features that require migrations or schema generation.
+
+**When you need Prisma:**
+- Running database migrations (`prisma migrate`, `prisma db push`)
+- Generating Prisma clients for your application
+- Using the migration Lambda function (`dbMigrate`)
+
+**Installation:**
+```bash
+# Install Prisma CLI and Client as dev dependencies
+npm install --save-dev prisma @prisma/client
+
+# Or with yarn
+yarn add -D prisma @prisma/client
+```
+
+**Generate Prisma Clients:**
+```bash
+# From @friggframework/core directory
+npm run prisma:generate:mongo      # MongoDB only
+npm run prisma:generate:postgres   # PostgreSQL only
+npm run prisma:generate            # Both databases
+```
+
+**Note:** The published npm package includes pre-generated Prisma clients, so you don't need to install Prisma just to use `@friggframework/core` in production. Prisma is only required if you're actively developing migrations or running the migration Lambda function.
+
 ### Prerequisites
 
 - Node.js 16+ 

package/database/prisma.js

@@ -77,9 +77,9 @@ const prismaClientSingleton = () => {
     let PrismaClient;
 
     if (config.DB_TYPE === 'mongodb') {
-        PrismaClient = require('@prisma-mongodb/client').PrismaClient;
+        PrismaClient = require('../generated/prisma-mongodb').PrismaClient;
     } else if (config.DB_TYPE === 'postgresql') {
-        PrismaClient = require('@prisma-postgresql/client').PrismaClient;
+        PrismaClient = require('../generated/prisma-postgresql').PrismaClient;
     } else {
         throw new Error(
             `Unsupported database type: ${config.DB_TYPE}. Supported values: 'mongodb', 'postgresql'`

package/database/use-cases/run-database-migration-use-case.js

@@ -0,0 +1,137 @@
+/**
+ * Run Database Migration Use Case
+ *
+ * Business logic for running Prisma database migrations.
+ * Orchestrates Prisma client generation and migration execution.
+ *
+ * This use case follows the Frigg hexagonal architecture pattern where:
+ * - Handlers (adapters) call use cases
+ * - Use cases contain business logic and orchestration
+ * - Use cases call repositories/utilities for data access
+ */
+
+class RunDatabaseMigrationUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {Object} dependencies.prismaRunner - Prisma runner utilities
+     */
+    constructor({ prismaRunner }) {
+        if (!prismaRunner) {
+            throw new Error('prismaRunner dependency is required');
+        }
+        this.prismaRunner = prismaRunner;
+    }
+
+    /**
+     * Execute database migration
+     *
+     * @param {Object} params
+     * @param {string} params.dbType - Database type ('postgresql' or 'mongodb')
+     * @param {string} params.stage - Deployment stage (determines migration command)
+     * @param {boolean} [params.verbose=false] - Enable verbose output
+     * @returns {Promise<Object>} Migration result { success, dbType, stage, command, message }
+     * @throws {MigrationError} If migration fails
+     * @throws {ValidationError} If parameters are invalid
+     */
+    async execute({ dbType, stage, verbose = false }) {
+        // Validation
+        this._validateParams({ dbType, stage });
+
+        // Step 1: Generate Prisma client
+        const generateResult = await this.prismaRunner.runPrismaGenerate(dbType, verbose);
+
+        if (!generateResult.success) {
+            throw new MigrationError(
+                `Failed to generate Prisma client: ${generateResult.error || 'Unknown error'}`,
+                { dbType, stage, step: 'generate', output: generateResult.output }
+            );
+        }
+
+        // Step 2: Run migrations based on database type
+        let migrationResult;
+        let migrationCommand;
+
+        if (dbType === 'postgresql') {
+            migrationCommand = this.prismaRunner.getMigrationCommand(stage);
+            migrationResult = await this.prismaRunner.runPrismaMigrate(migrationCommand, verbose);
+
+            if (!migrationResult.success) {
+                throw new MigrationError(
+                    `PostgreSQL migration failed: ${migrationResult.error || 'Unknown error'}`,
+                    { dbType, stage, command: migrationCommand, step: 'migrate', output: migrationResult.output }
+                );
+            }
+        } else if (dbType === 'mongodb') {
+            migrationCommand = 'db push';
+            // Use non-interactive mode for automated/Lambda environments
+            migrationResult = await this.prismaRunner.runPrismaDbPush(verbose, true);
+
+            if (!migrationResult.success) {
+                throw new MigrationError(
+                    `MongoDB push failed: ${migrationResult.error || 'Unknown error'}`,
+                    { dbType, stage, command: migrationCommand, step: 'push', output: migrationResult.output }
+                );
+            }
+        } else {
+            throw new ValidationError(`Unsupported database type: ${dbType}. Must be 'postgresql' or 'mongodb'.`);
+        }
+
+        // Return success result
+        return {
+            success: true,
+            dbType,
+            stage,
+            command: migrationCommand,
+            message: 'Database migration completed successfully',
+        };
+    }
+
+    /**
+     * Validate execution parameters
+     * @private
+     */
+    _validateParams({ dbType, stage }) {
+        if (!dbType) {
+            throw new ValidationError('dbType is required');
+        }
+
+        if (typeof dbType !== 'string') {
+            throw new ValidationError('dbType must be a string');
+        }
+
+        if (!stage) {
+            throw new ValidationError('stage is required');
+        }
+
+        if (typeof stage !== 'string') {
+            throw new ValidationError('stage must be a string');
+        }
+    }
+}
+
+/**
+ * Custom error for migration failures
+ */
+class MigrationError extends Error {
+    constructor(message, context = {}) {
+        super(message);
+        this.name = 'MigrationError';
+        this.context = context;
+    }
+}
+
+/**
+ * Custom error for validation failures
+ */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+module.exports = {
+    RunDatabaseMigrationUseCase,
+    MigrationError,
+    ValidationError,
+};

package/database/use-cases/run-database-migration-use-case.test.js

@@ -0,0 +1,310 @@
+/**
+ * Tests for Run Database Migration Use Case
+ */
+
+const {
+    RunDatabaseMigrationUseCase,
+    MigrationError,
+    ValidationError,
+} = require('./run-database-migration-use-case');
+
+describe('RunDatabaseMigrationUseCase', () => {
+    let useCase;
+    let mockPrismaRunner;
+
+    beforeEach(() => {
+        // Mock prisma runner with all required methods
+        mockPrismaRunner = {
+            runPrismaGenerate: jest.fn(),
+            runPrismaMigrate: jest.fn(),
+            runPrismaDbPush: jest.fn(),
+            getMigrationCommand: jest.fn(),
+        };
+
+        useCase = new RunDatabaseMigrationUseCase({ prismaRunner: mockPrismaRunner });
+    });
+
+    describe('Constructor', () => {
+        it('should throw error if prismaRunner is not provided', () => {
+            expect(() => new RunDatabaseMigrationUseCase({})).toThrow('prismaRunner dependency is required');
+        });
+
+        it('should create instance with valid dependencies', () => {
+            expect(useCase).toBeInstanceOf(RunDatabaseMigrationUseCase);
+            expect(useCase.prismaRunner).toBe(mockPrismaRunner);
+        });
+    });
+
+    describe('Parameter Validation', () => {
+        it('should throw ValidationError if dbType is missing', async () => {
+            await expect(useCase.execute({ stage: 'production' })).rejects.toThrow(ValidationError);
+            await expect(useCase.execute({ stage: 'production' })).rejects.toThrow('dbType is required');
+        });
+
+        it('should throw ValidationError if dbType is not a string', async () => {
+            await expect(useCase.execute({ dbType: 123, stage: 'production' })).rejects.toThrow(ValidationError);
+            await expect(useCase.execute({ dbType: 123, stage: 'production' })).rejects.toThrow(
+                'dbType must be a string'
+            );
+        });
+
+        it('should throw ValidationError if stage is missing', async () => {
+            await expect(useCase.execute({ dbType: 'postgresql' })).rejects.toThrow(ValidationError);
+            await expect(useCase.execute({ dbType: 'postgresql' })).rejects.toThrow('stage is required');
+        });
+
+        it('should throw ValidationError if stage is not a string', async () => {
+            await expect(useCase.execute({ dbType: 'postgresql', stage: 123 })).rejects.toThrow(ValidationError);
+            await expect(useCase.execute({ dbType: 'postgresql', stage: 123 })).rejects.toThrow(
+                'stage must be a string'
+            );
+        });
+    });
+
+    describe('PostgreSQL Migrations', () => {
+        beforeEach(() => {
+            mockPrismaRunner.runPrismaGenerate.mockResolvedValue({ success: true });
+            mockPrismaRunner.runPrismaMigrate.mockResolvedValue({ success: true });
+        });
+
+        it('should successfully run PostgreSQL production migration', async () => {
+            mockPrismaRunner.getMigrationCommand.mockReturnValue('deploy');
+
+            const result = await useCase.execute({
+                dbType: 'postgresql',
+                stage: 'production',
+                verbose: true,
+            });
+
+            expect(result).toEqual({
+                success: true,
+                dbType: 'postgresql',
+                stage: 'production',
+                command: 'deploy',
+                message: 'Database migration completed successfully',
+            });
+
+            expect(mockPrismaRunner.runPrismaGenerate).toHaveBeenCalledWith('postgresql', true);
+            expect(mockPrismaRunner.getMigrationCommand).toHaveBeenCalledWith('production');
+            expect(mockPrismaRunner.runPrismaMigrate).toHaveBeenCalledWith('deploy', true);
+            expect(mockPrismaRunner.runPrismaDbPush).not.toHaveBeenCalled();
+        });
+
+        it('should successfully run PostgreSQL development migration', async () => {
+            mockPrismaRunner.getMigrationCommand.mockReturnValue('dev');
+
+            const result = await useCase.execute({
+                dbType: 'postgresql',
+                stage: 'dev',
+            });
+
+            expect(result.success).toBe(true);
+            expect(result.command).toBe('dev');
+            expect(mockPrismaRunner.getMigrationCommand).toHaveBeenCalledWith('dev');
+            expect(mockPrismaRunner.runPrismaMigrate).toHaveBeenCalledWith('dev', false);
+        });
+
+        it('should throw MigrationError if Prisma generate fails', async () => {
+            mockPrismaRunner.runPrismaGenerate.mockResolvedValue({
+                success: false,
+                error: 'Schema file not found',
+                output: 'Error output',
+            });
+
+            await expect(
+                useCase.execute({ dbType: 'postgresql', stage: 'production' })
+            ).rejects.toThrow(MigrationError);
+
+            await expect(
+                useCase.execute({ dbType: 'postgresql', stage: 'production' })
+            ).rejects.toThrow('Failed to generate Prisma client: Schema file not found');
+
+            expect(mockPrismaRunner.runPrismaMigrate).not.toHaveBeenCalled();
+        });
+
+        it('should throw MigrationError if PostgreSQL migration fails', async () => {
+            mockPrismaRunner.getMigrationCommand.mockReturnValue('deploy');
+            mockPrismaRunner.runPrismaMigrate.mockResolvedValue({
+                success: false,
+                error: 'Migration conflict detected',
+                output: 'Conflict output',
+            });
+
+            await expect(
+                useCase.execute({ dbType: 'postgresql', stage: 'production' })
+            ).rejects.toThrow(MigrationError);
+
+            await expect(
+                useCase.execute({ dbType: 'postgresql', stage: 'production' })
+            ).rejects.toThrow('PostgreSQL migration failed: Migration conflict detected');
+        });
+
+        it('should include context in MigrationError', async () => {
+            mockPrismaRunner.getMigrationCommand.mockReturnValue('deploy');
+            mockPrismaRunner.runPrismaMigrate.mockResolvedValue({
+                success: false,
+                error: 'Migration failed',
+                output: 'Error output',
+            });
+
+            try {
+                await useCase.execute({ dbType: 'postgresql', stage: 'production' });
+                fail('Should have thrown MigrationError');
+            } catch (error) {
+                expect(error).toBeInstanceOf(MigrationError);
+                expect(error.context).toEqual({
+                    dbType: 'postgresql',
+                    stage: 'production',
+                    command: 'deploy',
+                    step: 'migrate',
+                    output: 'Error output',
+                });
+            }
+        });
+    });
+
+    describe('MongoDB Migrations', () => {
+        beforeEach(() => {
+            mockPrismaRunner.runPrismaGenerate.mockResolvedValue({ success: true });
+            mockPrismaRunner.runPrismaDbPush.mockResolvedValue({ success: true });
+        });
+
+        it('should successfully run MongoDB migration', async () => {
+            const result = await useCase.execute({
+                dbType: 'mongodb',
+                stage: 'production',
+                verbose: true,
+            });
+
+            expect(result).toEqual({
+                success: true,
+                dbType: 'mongodb',
+                stage: 'production',
+                command: 'db push',
+                message: 'Database migration completed successfully',
+            });
+
+            expect(mockPrismaRunner.runPrismaGenerate).toHaveBeenCalledWith('mongodb', true);
+            expect(mockPrismaRunner.runPrismaDbPush).toHaveBeenCalledWith(true, true); // verbose=true, nonInteractive=true
+            expect(mockPrismaRunner.runPrismaMigrate).not.toHaveBeenCalled();
+        });
+
+        it('should use non-interactive mode for MongoDB', async () => {
+            await useCase.execute({
+                dbType: 'mongodb',
+                stage: 'production',
+            });
+
+            // Second parameter should be true for non-interactive
+            expect(mockPrismaRunner.runPrismaDbPush).toHaveBeenCalledWith(false, true);
+        });
+
+        it('should throw MigrationError if MongoDB push fails', async () => {
+            mockPrismaRunner.runPrismaDbPush.mockResolvedValue({
+                success: false,
+                error: 'Connection timeout',
+            });
+
+            await expect(useCase.execute({ dbType: 'mongodb', stage: 'production' })).rejects.toThrow(
+                MigrationError
+            );
+
+            await expect(useCase.execute({ dbType: 'mongodb', stage: 'production' })).rejects.toThrow(
+                'MongoDB push failed: Connection timeout'
+            );
+        });
+    });
+
+    describe('Unsupported Database Types', () => {
+        beforeEach(() => {
+            mockPrismaRunner.runPrismaGenerate.mockResolvedValue({ success: true });
+        });
+
+        it('should throw ValidationError for unsupported database type', async () => {
+            await expect(useCase.execute({ dbType: 'mysql', stage: 'production' })).rejects.toThrow(
+                ValidationError
+            );
+
+            await expect(useCase.execute({ dbType: 'mysql', stage: 'production' })).rejects.toThrow(
+                "Unsupported database type: mysql. Must be 'postgresql' or 'mongodb'."
+            );
+        });
+
+        it('should run Prisma generate before checking database type', async () => {
+            try {
+                await useCase.execute({ dbType: 'mysql', stage: 'production' });
+            } catch (error) {
+                // Expected error
+            }
+
+            expect(mockPrismaRunner.runPrismaGenerate).toHaveBeenCalledWith('mysql', false);
+        });
+    });
+
+    describe('Error Handling', () => {
+        it('should handle undefined error from Prisma generate', async () => {
+            mockPrismaRunner.runPrismaGenerate.mockResolvedValue({
+                success: false,
+                error: undefined,
+            });
+
+            await expect(useCase.execute({ dbType: 'postgresql', stage: 'production' })).rejects.toThrow(
+                'Failed to generate Prisma client: Unknown error'
+            );
+        });
+
+        it('should handle undefined error from PostgreSQL migration', async () => {
+            mockPrismaRunner.runPrismaGenerate.mockResolvedValue({ success: true });
+            mockPrismaRunner.getMigrationCommand.mockReturnValue('deploy');
+            mockPrismaRunner.runPrismaMigrate.mockResolvedValue({
+                success: false,
+                error: undefined,
+            });
+
+            await expect(useCase.execute({ dbType: 'postgresql', stage: 'production' })).rejects.toThrow(
+                'PostgreSQL migration failed: Unknown error'
+            );
+        });
+
+        it('should handle undefined error from MongoDB push', async () => {
+            mockPrismaRunner.runPrismaGenerate.mockResolvedValue({ success: true });
+            mockPrismaRunner.runPrismaDbPush.mockResolvedValue({
+                success: false,
+                error: undefined,
+            });
+
+            await expect(useCase.execute({ dbType: 'mongodb', stage: 'production' })).rejects.toThrow(
+                'MongoDB push failed: Unknown error'
+            );
+        });
+    });
+
+    describe('Verbose Mode', () => {
+        beforeEach(() => {
+            mockPrismaRunner.runPrismaGenerate.mockResolvedValue({ success: true });
+            mockPrismaRunner.runPrismaMigrate.mockResolvedValue({ success: true });
+            mockPrismaRunner.getMigrationCommand.mockReturnValue('deploy');
+        });
+
+        it('should pass verbose flag to all Prisma operations', async () => {
+            await useCase.execute({
+                dbType: 'postgresql',
+                stage: 'production',
+                verbose: true,
+            });
+
+            expect(mockPrismaRunner.runPrismaGenerate).toHaveBeenCalledWith('postgresql', true);
+            expect(mockPrismaRunner.runPrismaMigrate).toHaveBeenCalledWith('deploy', true);
+        });
+
+        it('should default verbose to false', async () => {
+            await useCase.execute({
+                dbType: 'postgresql',
+                stage: 'production',
+            });
+
+            expect(mockPrismaRunner.runPrismaGenerate).toHaveBeenCalledWith('postgresql', false);
+            expect(mockPrismaRunner.runPrismaMigrate).toHaveBeenCalledWith('deploy', false);
+        });
+    });
+});