@vida-global/core 2.3.4 → 2.3.6

package/lib/activeRecord/README.md

@@ -72,6 +72,14 @@ Wire up the migration CLI by adding scripts to `package.json`:
 
 Generate a migration with `npm run db:create_migration createUsers`. Pass `-- --databaseId metrics` to scope the migration to a non-default database. Run `npm run db:migrate` to apply migrations or `npm run db:rollback` to undo the most recent one.
 
+`db:migrate` and `db:rollback` take an optional `--envFile <path>`. Both open a database connection, and the CLI runs as a bare node process, so nothing has loaded the environment that `config/db/config.js` reads from. Point the flag at a `.env` file and it is loaded before the command runs:
+
+```
+npm run db:migrate -- --envFile .env.staging
+```
+
+A variable already set in the environment wins over the file, so an inline override on the command line still takes effect. Leave the flag off and nothing is loaded, which is what an application that gets its environment some other way wants. `db:create_migration` only writes a file, so it does not accept the flag.
+
 Migration files are named `<timestamp>_<description>.js`, with the database id appended before the extension when one is given — for example `1754500000000_createUsers.js` or `1754500000000_createUsers.metrics.js`. The leading timestamp is the version recorded in `migration_versions` and the order migrations run in, so files sort chronologically by name. Files that don't match this pattern are ignored.
 
 ```js

package/lib/activeRecord/db/migrator.js

@@ -143,9 +143,10 @@ class Migrator {
     get uuidIdColumn() {
         return {
           id: {
-            allowNull:  false,
-            primaryKey: true,
-            type:       this.DataTypes.UUID, }
+            allowNull:    false,
+            primaryKey:   true,
+            type:         this.DataTypes.UUID,
+            defaultValue: Sequelize.literal('gen_random_uuid()'), }
         };
     }
 
@@ -187,6 +188,20 @@ class Migrator {
     }
 
 
+    async tableExists(tableName) {
+        const tables = await this.#sequelizeQueryInterface.showAllTables(this.queryOptions);
+        return tables.some(table => (table?.tableName ?? table) == tableName);
+    }
+
+
+    // Escape hatch for DDL the typed methods cannot express — CHECK constraints, sequences shared
+    // between tables. Runs inside the migration transaction, so it rolls back with everything else.
+    // Prefer the typed methods; reach for this only when there is no other way.
+    async execute(sql, replacements) {
+        return await this.#connection._sequelize.query(sql, {...this.queryOptions, replacements});
+    }
+
+
     async addColumn(tableName, columnName, columnDetails) {
         await this.#sequelizeQueryInterface.addColumn(tableName, columnName, columnDetails, this.queryOptions);
     }

package/lib/server/openApi/apiDocGenerator.js

@@ -216,7 +216,7 @@ class ApiDocGenerator {
 
 
     get endpoint() {
-        return this.#action.path.replace(/:([^/]+)/g, '{$1}');
+        return this.#action.path.replace(/:([^/?]+)\??/g, '{$1}');
     }
 
 

package/lib/utils/envFile.js

@@ -0,0 +1,14 @@
+const dotenv = require('dotenv');
+const fs     = require('node:fs');
+
+
+function loadEnvFile(filePath) {
+    if (!filePath) return false;
+    if (!fs.existsSync(filePath)) throw new Error(`Environment file ${filePath} does not exist`);
+
+    dotenv.config({ path: filePath, quiet: true });
+    return true;
+}
+
+
+module.exports = { loadEnvFile };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "2.3.4",
+    "version": "2.3.6",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",
@@ -24,6 +24,7 @@
         "bullmq": "^5.0.0",
         "commander": "^13.1.0",
         "cookie-parser": "^1.4.7",
+        "dotenv": "^16.6.1",
         "express": "^4.21.2",
         "express-request-id": "1.4.1",
         "express-winston": "^4.0.0",

package/scripts/activeRecord/migrate.js

@@ -1,5 +1,13 @@
-const   migration = require('../../lib/activeRecord/db/migration');
-const { Command } = require('commander');
+const { loadEnvFile } = require('../../lib/utils/envFile');
+const   migration     = require('../../lib/activeRecord/db/migration');
+const { Command }     = require('commander');
+
+
+// Declared on the commands that touch the database rather than on the program, so it can be passed
+// after the command name, which is where npm puts it: `npm run db:migrate -- --envFile .env.staging`.
+function withEnvFileOption(command) {
+    return command.option('--envFile <path>', 'a .env file to load before the command runs');
+}
 
 
 const program = new Command();
@@ -7,6 +15,10 @@ program.name('Active Record Migration')
        .description('A CLI for generating and running Active Record migrations')
        .version('1.0.0');
 
+program.hook('preAction', (_program, command) => {
+    loadEnvFile(command.opts().envFile);
+});
+
 
 program.command('create_migration')
        .argument('<Description>', 'Description of your migration')
@@ -16,12 +28,13 @@ program.command('create_migration')
        });
 
 
-program.command('migrate')
+withEnvFileOption(program.command('migrate'))
        .action(async () => {
             await migration.runMigrations();
        });
 
-program.command('rollback')
+
+withEnvFileOption(program.command('rollback'))
        .action(async () => {
             await migration.rollbackMigration();
        });

package/test/activeRecord/db/migrator.test.js

@@ -161,13 +161,28 @@ describe('Migrator', () => {
             expect(columns.id).toEqual({ allowNull: false, autoIncrement: true, primaryKey: true, type: 'INTEGER' });
         });
 
-        it ('gives the table a uuid id that the database does not generate', async () => {
+        it ('gives the table a uuid id the database generates', async () => {
             const tableName = Helpers.randomString();
 
             await Helpers.migrator.createTable(tableName, {}, { id: 'uuid' });
 
             const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
-            expect(columns.id).toEqual({ allowNull: false, primaryKey: true, type: 'UUID' });
+            expect(columns.id).toEqual({
+                allowNull:    false,
+                primaryKey:   true,
+                type:         'UUID',
+                defaultValue: { literal: 'gen_random_uuid()' },
+            });
+        });
+
+
+        it ('does not give an auto-increment id a database default', async () => {
+            const tableName = Helpers.randomString();
+
+            await Helpers.migrator.createTable(tableName, {}, { id: 'bigint' });
+
+            const [, columns] = Helpers.mockQueryInterface.createTable.mock.calls[0];
+            expect(columns.id).not.toHaveProperty('defaultValue');
         });
 
         it ('refuses an id type it does not recognize', async () => {
@@ -297,6 +312,78 @@ describe('Migrator', () => {
     });
 
 
+    describe('Migrator#tableExists', () => {
+        it ('reports a table that is present', async () => {
+            const tableName = Helpers.randomString();
+            Helpers.mockQueryInterface.showAllTables.mockResolvedValue([Helpers.randomString(), tableName]);
+
+            await expect(Helpers.migrator.tableExists(tableName)).resolves.toBe(true);
+        });
+
+        it ('reports a table that is absent', async () => {
+            Helpers.mockQueryInterface.showAllTables.mockResolvedValue([Helpers.randomString()]);
+
+            await expect(Helpers.migrator.tableExists(Helpers.randomString())).resolves.toBe(false);
+        });
+
+        // Some dialects return objects rather than bare names.
+        it ('reads a name off an object entry', async () => {
+            const tableName = Helpers.randomString();
+            Helpers.mockQueryInterface.showAllTables.mockResolvedValue([{ tableName }]);
+
+            await expect(Helpers.migrator.tableExists(tableName)).resolves.toBe(true);
+        });
+
+        it ('runs inside the open transaction', async () => {
+            Helpers.mockQueryInterface.showAllTables.mockResolvedValue([]);
+
+            await Helpers.runInMigration(async function() {
+                await this.tableExists(Helpers.randomString());
+            });
+
+            expect(Helpers.mockQueryInterface.showAllTables).toHaveBeenCalledWith(Helpers.inTransaction);
+        });
+    });
+
+
+    describe('Migrator#execute', () => {
+        it ('runs the statement and returns its result', async () => {
+            const sql    = `CREATE SEQUENCE ${Helpers.randomString()}`;
+            const result = {};
+            Helpers.mockQuery.mockResolvedValue(result);
+
+            await expect(Helpers.migrator.execute(sql)).resolves.toBe(result);
+
+            expect(Helpers.mockQuery).toHaveBeenCalledWith(sql, {
+                ...Helpers.noTransaction,
+                replacements: undefined,
+            });
+        });
+
+        it ('passes replacements through for binding', async () => {
+            const sql          = 'SELECT :value';
+            const replacements = { value: Helpers.randomString() };
+            Helpers.mockQuery.mockResolvedValue(undefined);
+
+            await Helpers.migrator.execute(sql, replacements);
+
+            expect(Helpers.mockQuery).toHaveBeenCalledWith(sql, expect.objectContaining({ replacements }));
+        });
+
+        // Raw statements have to roll back with the rest of the migration.
+        it ('runs inside the open transaction', async () => {
+            const sql = `CREATE SEQUENCE ${Helpers.randomString()}`;
+            Helpers.mockQuery.mockResolvedValue(undefined);
+
+            await Helpers.runInMigration(async function() {
+                await this.execute(sql);
+            });
+
+            expect(Helpers.mockQuery).toHaveBeenCalledWith(sql, expect.objectContaining(Helpers.inTransaction));
+        });
+    });
+
+
     describe('Migrator#renameColumn', () => {
         it ('snake_cases renameColumn target', async () => {
             const tableName = Helpers.randomString();

package/test/activeRecord/helpers/migrator.js

@@ -16,6 +16,7 @@ const randomString       = TestHelpers.Faker.Text.randomString;
 const transaction        = { id: randomString() };
 const noTransaction      = { transaction: null };
 const inTransaction      = { transaction };
+const mockQuery          = jest.fn();
 const mockQueryInterface = {
     createTable: jest.fn(),
     dropTable: jest.fn(),
@@ -25,6 +26,7 @@ const mockQueryInterface = {
     removeIndex: jest.fn(),
     renameColumn: jest.fn(),
     changeColumn: jest.fn(),
+    showAllTables: jest.fn(),
 };
 
 
@@ -39,10 +41,12 @@ function randomColumnDetails() {
 jest.mock('sequelize', () => {
     class MockSequelize {
         static DataTypes = { BIGINT: 'BIGINT', DATE: 'DATE', INTEGER: 'INTEGER', UUID: 'UUID' };
+        static literal(sql) { return { literal: sql }; }
     }
     return { Sequelize: MockSequelize };
 });
 Sequelize.prototype.getQueryInterface = () => mockQueryInterface;
+Sequelize.prototype.query = (...args) => mockQuery(...args);
 
 
 jest.spyOn(ConnectionConfiguration, '_fetchAllConfigs').mockImplementation(() => ({
@@ -81,6 +85,7 @@ module.exports = {
   inTransaction,
   migrationModule,
   migrator,
+  mockQuery,
   mockQueryInterface,
   noTransaction,
   randomColumnDetails,

package/test/server/apiDocGenerator.test.js

@@ -70,6 +70,15 @@ describe('ApiDocGenerator', () => {
             expect(generator.endpoint).toEqual(formattedUrl);
         });
 
+        it ('removes the Express optional marker from a path parameter', () => {
+            const requiredName = Faker.Text.randomString();
+            const optionalName = Faker.Text.randomString();
+            const action = { path: `/things/:${requiredName}/:${optionalName}?` };
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.endpoint).toEqual(`/things/{${requiredName}}/{${optionalName}}`);
+        });
+
         it ('returns the path unchanged when there are no params', () => {
             const path      = `/${Faker.Text.randomString()}/${Faker.Text.randomString()}`;
             const action    = { path };
@@ -157,6 +166,25 @@ describe('ApiDocGenerator', () => {
             expect(generator.pathParams.id.required).toBe(true);
         });
 
+        it ('uses the validator definition for an optional Express path parameter', () => {
+            const parameterName = Faker.Text.randomString();
+            const description   = Faker.Text.randomString();
+            const action = { action: 'getRecord', method: 'GET', path: `/things/:${parameterName}?` };
+            ControllerClass.parametersForAction.mockReturnValue({
+                [parameterName]: { isString: true, optional: true, description },
+            });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.pathParams[parameterName]).toEqual({
+                name:        parameterName,
+                in:          'path',
+                required:    true,
+                description,
+                schema:      { type: 'string' },
+            });
+            expect(generator.pathParams[`${parameterName}?`]).toBeUndefined();
+        });
+
         it ('excludes parameters that are not in the path', () => {
             const action = { action: 'getRecord', method: 'GET', path: '/user/:id' };
             ControllerClass.parametersForAction.mockReturnValue({
@@ -214,6 +242,17 @@ describe('ApiDocGenerator', () => {
             expect(Object.keys(generator.queryParams)).toEqual(['detail']);
         });
 
+        it ('does not duplicate an optional Express path parameter as a query parameter', () => {
+            const parameterName = Faker.Text.randomString();
+            const action = { action: 'getRecord', method: 'GET', path: `/things/:${parameterName}?` };
+            ControllerClass.parametersForAction.mockReturnValue({
+                [parameterName]: { isString: true, optional: true },
+            });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.queryParams[parameterName]).toBeUndefined();
+        });
+
     });
 
 

package/test/utils/envFile.test.js

@@ -0,0 +1,46 @@
+const { loadEnvFile } = require('../../lib/utils/envFile');
+
+
+const fixturePath = `${__dirname}/helpers/envFile.fixture`;
+const fileKeys    = ['CORE_TEST_ENV_FILE_VALUE', 'CORE_TEST_ENV_FILE_PRESET'];
+
+
+beforeEach(() => {
+    fileKeys.forEach(key => delete process.env[key]);
+});
+
+
+afterEach(() => {
+    fileKeys.forEach(key => delete process.env[key]);
+});
+
+
+describe('utils/envFile', () => {
+    describe('loadEnvFile', () => {
+        it ('does nothing and reports false when given no path', () => {
+            expect(loadEnvFile(undefined)).toBe(false);
+            expect(process.env.CORE_TEST_ENV_FILE_VALUE).toBeUndefined();
+        });
+
+
+        it ('throws when the file does not exist', () => {
+            expect(() => loadEnvFile(`${fixturePath}.missing`))
+                .toThrow(`Environment file ${fixturePath}.missing does not exist`);
+        });
+
+
+        it ('loads the variables in the file into the environment', () => {
+            expect(loadEnvFile(fixturePath)).toBe(true);
+            expect(process.env.CORE_TEST_ENV_FILE_VALUE).toEqual('from_file');
+        });
+
+
+        it ('leaves a variable already set in the environment alone', () => {
+            process.env.CORE_TEST_ENV_FILE_PRESET = 'from_environment';
+
+            loadEnvFile(fixturePath);
+
+            expect(process.env.CORE_TEST_ENV_FILE_PRESET).toEqual('from_environment');
+        });
+    });
+});

package/test/utils/helpers/envFile.fixture

@@ -0,0 +1,2 @@
+CORE_TEST_ENV_FILE_VALUE=from_file
+CORE_TEST_ENV_FILE_PRESET=from_file