core-services-sdk 1.3.51 → 1.3.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.51",
+  "version": "1.3.52",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",
@@ -33,9 +33,11 @@
     "fastify": "^5.4.0",
     "google-libphonenumber": "^3.2.42",
     "http-status": "^2.1.0",
+    "knex": "^3.1.0",
     "mongodb": "^6.18.0",
     "nodemailer": "^7.0.5",
     "p-retry": "^7.0.0",
+    "pg": "^8.16.3",
     "pino": "^9.7.0",
     "ulid": "^3.0.1",
     "uuid": "^11.1.0",

package/src/index.js

@@ -10,3 +10,4 @@ export * from './rabbit-mq/index.js'
 export * from './templates/index.js'
 export * from './util/index.js'
 export * from './instant-messages/index.js'
+export * from './postgresql/index.js'

package/src/postgresql/connect-to-pg.js

@@ -0,0 +1,23 @@
+import knex from 'knex'
+
+/**
+ * Creates and returns a Knex database connection instance.
+ *
+ * This function initializes a Knex client configured for PostgreSQL
+ * using the provided connection configuration.
+ *
+ * @param {object|string} connection
+ *   Knex connection configuration.
+ *   Can be a connection object or a connection string.
+ *
+ * @returns {import('knex').Knex}
+ *   A configured Knex database instance.
+ */
+export const connectToPg = (connection) => {
+  const db = knex({
+    connection,
+    client: 'pg',
+  })
+
+  return db
+}

package/src/postgresql/index.js

@@ -0,0 +1,3 @@
+export * from './connect-to-pg.js'
+export * from './validate-schema.js'
+export * from './start-stop-postgres-docker.js'

package/src/postgresql/start-stop-postgres-docker.js

@@ -0,0 +1,158 @@
+import { execSync } from 'node:child_process'
+
+/**
+ * Starts a PostgreSQL Docker container for testing purposes.
+ *
+ * If a container with the same name already exists, it will be stopped and removed first.
+ * The function blocks until PostgreSQL is ready to accept connections.
+ *
+ * @param {object} options
+ * @param {number} [options.port=5433]
+ *   Host port to bind PostgreSQL to.
+ *
+ * @param {string} [options.containerName='postgres-test']
+ *   Docker container name.
+ *
+ * @param {string} [options.user='testuser']
+ *   Database user name.
+ *
+ * @param {string} [options.pass='testpass']
+ *   Database user password.
+ *
+ * @param {string} [options.db='testdb']
+ *   Database name.
+ *
+ * @returns {void}
+ *
+ * @throws {Error}
+ *   Throws if PostgreSQL does not become ready within the expected time.
+ */
+
+export function startPostgres({
+  port = 5433,
+  containerName = 'postgres-test',
+  user = 'testuser',
+  pass = 'testpass',
+  db = 'testdb',
+}) {
+  console.log(`[PgTest] Starting PostgreSQL on port ${port}...`)
+
+  stopPostgres(containerName)
+
+  execSync(
+    `docker run -d \
+      --name ${containerName} \
+      -e POSTGRES_USER=${user} \
+      -e POSTGRES_PASSWORD=${pass} \
+      -e POSTGRES_DB=${db} \
+      -p ${port}:5432 \
+      postgres:16`,
+    { stdio: 'inherit' },
+  )
+
+  waitForPostgres(containerName, user, db)
+}
+
+/**
+ * Stops and removes a PostgreSQL Docker container used for testing.
+ *
+ * If the container does not exist, the function exits silently.
+ *
+ * @param {string} [containerName='postgres-test']
+ *   Docker container name.
+ *
+ * @returns {void}
+ */
+
+export function stopPostgres(containerName = 'postgres-test') {
+  console.log(`[PgTest] Stopping PostgreSQL...`)
+  try {
+    execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' })
+  } catch {}
+}
+
+/**
+ * Checks whether PostgreSQL inside the Docker container
+ * is ready to accept connections.
+ *
+ * @param {string} containerName
+ *   Docker container name.
+ *
+ * @param {string} user
+ *   Database user name.
+ *
+ * @param {string} db
+ *   Database name.
+ *
+ * @returns {boolean}
+ *   Returns true if PostgreSQL is ready, otherwise false.
+ */
+
+export function isPostgresReady(containerName, user, db) {
+  try {
+    execSync(
+      `docker exec ${containerName} psql -U ${user} -d ${db} -c "SELECT 1"`,
+      { stdio: 'ignore' },
+    )
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Waits until PostgreSQL inside the Docker container
+ * is ready to accept connections.
+ *
+ * Retries for a fixed number of attempts before failing.
+ *
+ * @param {string} containerName
+ *   Docker container name.
+ *
+ * @param {string} user
+ *   Database user name.
+ *
+ * @param {string} db
+ *   Database name.
+ *
+ * @returns {void}
+ *
+ * @throws {Error}
+ *   Throws if PostgreSQL does not become ready within the timeout.
+ */
+
+export function waitForPostgres(containerName, user, db) {
+  console.log(`[PgTest] Waiting for PostgreSQL to be ready...`)
+
+  const maxRetries = 20
+  let retries = 0
+  let ready = false
+
+  while (!ready && retries < maxRetries) {
+    ready = isPostgresReady(containerName, user, db)
+    if (!ready) {
+      retries++
+      execSync(`sleep 1`)
+    }
+  }
+
+  if (!ready) {
+    throw new Error(
+      `[PgTest] PostgreSQL failed to start within ${maxRetries} seconds`,
+    )
+  }
+
+  console.log(`[PgTest] PostgreSQL is ready.`)
+}
+
+/**
+ * Build a PostgreSQL connection URI
+ * @param {object} opts
+ * @param {string} opts.user
+ * @param {string} opts.pass
+ * @param {number} opts.port
+ * @param {string} opts.db
+ */
+export function buildPostgresUri({ user, pass, port, db }) {
+  return `postgres://${user}:${pass}@localhost:${port}/${db}`
+}

package/src/postgresql/validate-schema.js

@@ -0,0 +1,39 @@
+import { connectToPg } from './connect-to-pg.js'
+
+/**
+ * Validates that the specified database tables exist.
+ *
+ * Checks all provided table names and collects any missing tables.
+ * Throws a single error listing all missing tables after validation completes.
+ *
+ * @param {string|object} connection
+ *   Database connection configuration.
+ *   Can be a database connection URI or a Knex connection object.
+ *
+ * @param {string[]} tables
+ *   List of required table names to validate.
+ *
+ * @returns {Promise<void>}
+ *
+ * @throws {Error}
+ *   Throws an error if one or more required tables are missing.
+ */
+export async function validateSchema(connection, tables) {
+  const db = connectToPg(connection)
+
+  const missingTables = []
+
+  for (const table of tables) {
+    const exists = await db.schema.hasTable(table)
+    if (!exists) {
+      missingTables.push(table)
+    }
+  }
+
+  if (missingTables.length > 0) {
+    throw new Error(
+      `Missing the following tables: ${missingTables.join(', ')}. ` +
+        `Did you run migrations?`,
+    )
+  }
+}

package/tests/postgresql/validate-schema.integration.test.js

@@ -0,0 +1,54 @@
+import { describe, it, beforeAll, afterAll, expect } from 'vitest'
+
+import {
+  startPostgres,
+  stopPostgres,
+  buildPostgresUri,
+} from '../../src/postgresql/start-stop-postgres-docker.js'
+import { connectToPg } from '../../src/postgresql/connect-to-pg.js'
+import { validateSchema } from '../../src/postgresql/validate-schema.js'
+
+const PG_OPTIONS = {
+  port: 5433,
+  containerName: 'postgres-validate-schema-test',
+  user: 'testuser',
+  pass: 'testpass',
+  db: 'testdb',
+}
+
+const DATABASE_URI = buildPostgresUri(PG_OPTIONS)
+
+describe('validateSchema', () => {
+  beforeAll(async () => {
+    startPostgres(PG_OPTIONS)
+
+    const db = connectToPg(DATABASE_URI)
+
+    // create one table only
+    await db.schema.createTable('files', (table) => {
+      table.string('id').primary()
+    })
+
+    await db.destroy()
+  })
+
+  afterAll(() => {
+    stopPostgres(PG_OPTIONS.containerName)
+  })
+
+  it('does not throw when all required tables exist', async () => {
+    await expect(validateSchema(DATABASE_URI, ['files'])).resolves.not.toThrow()
+  })
+
+  it('throws a single error listing missing tables', async () => {
+    await expect(
+      validateSchema(DATABASE_URI, ['files', 'documents', 'attachments']),
+    ).rejects.toThrow('Missing the following tables: documents, attachments')
+  })
+
+  it('throws when all tables are missing', async () => {
+    await expect(
+      validateSchema(DATABASE_URI, ['missing_a', 'missing_b']),
+    ).rejects.toThrow('Missing the following tables: missing_a, missing_b')
+  })
+})