core-services-sdk 1.1.1 → 1.2.2

package/.vscode/launch.json

@@ -15,6 +15,20 @@
       "smartStep": true,
       "skipFiles": ["<node_internals>/**"],
       "console": "integratedTerminal"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug Vitest Current File",
+      "autoAttachChildProcesses": true,
+      "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
+      "args": [
+        "run",
+        "${relativeFile}" // ← no `--test`
+      ],
+      "smartStep": true,
+      "skipFiles": ["<node_internals>/**"],
+      "console": "integratedTerminal"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.1.1",
+  "version": "1.2.2",
   "main": "src/index.js",
   "type": "module",
   "scripts": {
@@ -21,6 +21,7 @@
   "dependencies": {
     "amqplib": "^0.10.8",
     "http-status": "^2.1.0",
+    "mongodb": "^6.17.0",
     "node-fetch": "^3.3.2",
     "uuid": "^11.1.0",
     "xml2js": "^0.6.2"

package/src/fastify/error-codes.js

@@ -0,0 +1,7 @@
+import httpStatus from 'http-status'
+
+export const GENERAL_ERROR = {
+  httpStatusCode: httpStatus.INTERNAL_SERVER_ERROR,
+  httpStatusText: httpStatus[httpStatus.INTERNAL_SERVER_ERROR],
+  code: `GENERAL.${httpStatus[httpStatus.INTERNAL_SERVER_ERROR]}`,
+}

package/src/fastify/error-handlers/with-error-handling.js

@@ -0,0 +1,90 @@
+import httpStatus from 'http-status'
+
+import { HttpError } from '../../http/HttpError.js'
+import { GENERAL_ERROR } from '../error-codes.js'
+
+/**
+ * Generic error-handling wrapper that logs and throws a safe error.
+ * @param {object} log - Logger with an .error method.
+ * @param {HttpError} defaultError - Error to throw if original error is not an HttpError.
+ * @returns {(funcToInvoke: () => Promise<any>) => Promise<any>}
+ */
+export const withErrorHandling =
+  (log, defaultError) => async (funcToInvoke) => {
+    try {
+      return await funcToInvoke()
+    } catch (error) {
+      log.error(`[withErrorHandling] - Error: ${error?.stack || error}`)
+
+      if (!error) {
+        throw defaultError
+      }
+
+      if (HttpError.isInstanceOf(error)) {
+        throw error
+      }
+
+      const httpError = HttpError.FromError(error)
+
+      throw httpError
+    }
+  }
+
+/**
+ * Executes function with error handling and replies on failure.
+ *
+ * @param {object} params
+ * @param {Reply} params.reply - Fastify reply object
+ * @param {Logger} params.log - Logger object
+ * @param {HttpError} [params.defaultError] - Fallback error
+ */
+export const withErrorHandlingReply =
+  ({ reply, log, defaultError = new HttpError(GENERAL_ERROR) }) =>
+  async (funcToInvoke) => {
+    try {
+      return await withErrorHandling(log, defaultError)(funcToInvoke)
+    } catch (error) {
+      const { code, httpStatusText, httpStatusCode } = error
+      reply.status(httpStatusCode).send({ code, httpStatusText })
+    }
+  }
+
+/**
+ * Executes function with error handling and replies on failure.
+ *
+ * @param {object} params
+ * @param {Reply} params.reply - Fastify reply object
+ * @param {Logger} params.log - Logger object
+ * @param {HttpError} [params.defaultError] - Fallback error
+ */
+export const replyOnErrorOnly =
+  ({ reply, log, defaultError = new HttpError(GENERAL_ERROR) }) =>
+  async (funcToInvoke) => {
+    try {
+      return await withErrorHandling(log, defaultError)(funcToInvoke)
+    } catch (error) {
+      log.error(`[replyOnErrorOnly] - Error: ${error?.stack || error}`)
+      const isHttp = HttpError.isInstanceOf(error)
+      const errorMerged = isHttp
+        ? error
+        : new HttpError({
+            ...defaultError,
+            message: error?.message || defaultError.message,
+            code: error?.code || defaultError.code,
+          })
+
+      if (!isHttp && error?.stack) {
+        errorMerged.stack = error.stack
+      }
+
+      const exposed =
+        errorMerged.message ?? errorMerged.code ?? GENERAL_ERROR.httpStatusText
+
+      const status =
+        errorMerged.httpStatusCode && errorMerged.httpStatusCode in httpStatus
+          ? errorMerged.httpStatusCode
+          : httpStatus.INTERNAL_SERVER_ERROR
+
+      reply.status(status).send({ error: exposed })
+    }
+  }

package/src/fastify/error-handlers/with-error-handling.types.js

@@ -0,0 +1,10 @@
+/**
+ * @typedef {object} Reply
+ * @property {(code: number) => Reply} status - Sets the HTTP status code
+ * @property {(payload: any) => void} send - Sends the response
+ */
+
+/**
+ * @typedef {object} Logger
+ * @property {(message: string, ...args: any[]) => void} error - Logs an error message
+ */

package/src/fastify/index.js

@@ -0,0 +1,2 @@
+export { GENERAL_ERROR } from './error-codes.js'
+export * from './error-handlers/with-error-handling.js'

package/src/http/HttpError.js

@@ -1,47 +1,74 @@
-import * as httpStatus from 'http-status'
+import httpStatus from 'http-status'
 
-const DEFAULT_ERROR = {
-  httpStatusCode: httpStatus.INTERNAL_SERVER_ERROR,
-  code: 'UNKNOWN',
-  httpStatusText: httpStatus[httpStatus.INTERNAL_SERVER_ERROR],
-}
-
-/**
- *
- */
 export class HttpError extends Error {
-  /** @type {number} */
-  httpStatusCode
-  /** @type {string} */
+  /** @type {string|undefined} */
   code
-  /** @type {string} */
+
+  /** @type {number|undefined} */
+  httpStatusCode
+
+  /** @type {string|undefined} */
   httpStatusText
 
-  /** @type {Array} */
-  details
-  constructor({
-    httpStatusCode,
-    code,
-    httpStatusText,
-    details = [],
-  } = DEFAULT_ERROR) {
-    super(`${code || httpStatus[httpStatusCode]}`)
-    this.httpStatusCode = httpStatusCode
+  /**
+   * @param {object} [error]
+   * @param {string} [error.code]
+   * @param {string} [error.message]
+   * @param {number} [error.httpStatusCode]
+   * @param {string} [error.httpStatusText]
+   */
+  constructor(error = {}) {
+    const { code, message, httpStatusCode, httpStatusText } = error
+
+    super(
+      message ||
+        (httpStatusCode && httpStatus[httpStatusCode]) ||
+        code ||
+        'Unknown error',
+    )
+
     this.code = code
-    this.httpStatusText = httpStatusText
-    this.details = details
+    this.httpStatusCode = httpStatusCode
+    this.httpStatusText =
+      httpStatusText || (httpStatusCode && httpStatus[httpStatusCode])
 
     if (typeof Error.captureStackTrace === 'function') {
       Error.captureStackTrace(this, this.constructor)
     }
   }
 
-  /**
-   *
-   * @param {object} instance
-   * @returns {boolean}
-   */
   static isInstanceOf(instance) {
     return instance instanceof HttpError
   }
+
+  static [Symbol.hasInstance](instance) {
+    return (
+      instance &&
+      typeof instance === 'object' &&
+      'message' in instance &&
+      'httpStatusCode' in instance &&
+      'httpStatusText' in instance
+    )
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      httpStatusCode: this.httpStatusCode,
+      httpStatusText: this.httpStatusText,
+    }
+  }
+
+  static FromError(error) {
+    const httpError = new HttpError({
+      code: error.code || 'UNHANDLED_ERROR',
+      message: error.message || 'An unexpected error occurred',
+      httpStatusCode: httpStatus.INTERNAL_SERVER_ERROR,
+      httpStatusText: httpStatus[httpStatus.INTERNAL_SERVER_ERROR],
+    })
+
+    httpError.stack = error.stack
+    return httpError
+  }
 }

package/src/index.js

@@ -1,3 +1,6 @@
+export * from './fastify'
+export * from './mongodb/index.js'
+export * from './mongodb/connect.js'
 export * from './rabbit-mq/index.js'
 export * as http from './http/http.js'
 export * from './http/responseType.js'

package/src/mongodb/connect.js

@@ -0,0 +1,23 @@
+import { MongoClient, ServerApiVersion } from 'mongodb'
+
+/**
+ * Connects to MongoDB.
+ *
+ * @param {Object} options
+ * @param {string} options.uri - MongoDB connection URI.
+ * @param {object} [options.serverApi] - Optional serverApi configuration.
+ * @returns {Promise<import('mongodb').MongoClient>}
+ */
+
+export const mongoConnect = async ({ uri, serverApi }) => {
+  const client = await MongoClient.connect(uri, {
+    serverApi: {
+      version: ServerApiVersion.v1,
+      strict: true,
+      deprecationErrors: true,
+      ...serverApi,
+    },
+  })
+
+  return client
+}

package/src/mongodb/index.js

@@ -0,0 +1,71 @@
+// @ts-nocheck
+import { mongoConnect } from './connect.js'
+
+/**
+ * Initializes MongoDB collections and provides a transaction wrapper and read-only client accessor.
+ *
+ * @param {Object} options
+ * @param {{ uri: string, options: { dbName: string } }} options.config - MongoDB connection config
+ * @param {Record<string, string>} options.collectionNames - Map of collection keys to MongoDB collection names
+ *
+ * @returns {Promise<
+ *   Record<string, import('mongodb').Collection> & {
+ *     withTransaction: (action: ({ session: import('mongodb').ClientSession }) => Promise<void>) => Promise<void>,
+ *     readonly client: import('mongodb').MongoClient
+ *   }
+ * >}
+ *
+ * @example
+ * const { users, logs, withTransaction, client } = await initializeMongoDb({
+ *   config: {
+ *     uri: 'mongodb://localhost:27017',
+ *     options: { dbName: 'mydb' },
+ *   },
+ *   collectionNames: {
+ *     users: 'users',
+ *     logs: 'system_logs',
+ *   },
+ * });
+ *
+ * await withTransaction(async ({ session }) => {
+ *   await users.insertOne({ name: 'Alice' }, { session });
+ *   await logs.insertOne({ event: 'UserCreated', user: 'Alice' }, { session });
+ * });
+ *
+ * await client.close(); // Close connection manually
+ */
+export const initializeMongoDb = async ({ config, collectionNames = {} }) => {
+  const client = await mongoConnect(config)
+  const db = client.db(config.options.dbName)
+
+  const collectionRefs = Object.entries(collectionNames).reduce(
+    (collections, [key, collectionName]) => ({
+      ...collections,
+      [key]: db.collection(collectionName),
+    }),
+    {},
+  )
+
+  const withTransaction = async (action) => {
+    const session = client.startSession()
+    try {
+      session.startTransaction()
+      await action({ session })
+      await session.commitTransaction()
+    } catch (error) {
+      await session.abortTransaction()
+      throw error
+    } finally {
+      await session.endSession()
+    }
+  }
+
+  return {
+    ...collectionRefs,
+    withTransaction,
+    /** @type {import('mongodb').MongoClient} */
+    get client() {
+      return client
+    },
+  }
+}

package/src/rabbit-mq/index.js

@@ -10,7 +10,7 @@ import { v4 as uuidv4 } from 'uuid'
 /**
  * Connects to RabbitMQ server.
  * @param {{ host: string }} options
- * @returns {Promise<amqp.Connection>}
+ * @returns {Promise<import('amqplib').Connection>}
  */
 export const connectQueueService = async ({ host }) => {
   try {
@@ -57,10 +57,10 @@ const parseMessage = (msgInfo) => {
  * @returns {Promise<void>}
  */
 export const subscribeToQueue = async ({
-  channel,
+  log,
   queue,
+  channel,
   onReceive,
-  log,
   nackOnError = false,
 }) => {
   try {

package/tests/HttpError.test.js

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest'
+import { HttpError } from '../src/http/HttpError.js'
+import httpStatus from 'http-status'
+
+describe('HttpError', () => {
+  it('creates an error with all fields explicitly set', () => {
+    const err = new HttpError({
+      code: 'SOME_ERROR',
+      message: 'Something went wrong',
+      httpStatusCode: httpStatus.BAD_REQUEST,
+      httpStatusText: httpStatus[httpStatus.BAD_REQUEST],
+    })
+
+    expect(err).toBeInstanceOf(HttpError)
+    expect(err.message).toBe('Something went wrong')
+    expect(err.code).toBe('SOME_ERROR')
+    expect(err.httpStatusCode).toBe(httpStatus.BAD_REQUEST)
+    expect(err.httpStatusText).toBe(httpStatus[httpStatus.BAD_REQUEST])
+  })
+
+  it('falls back to code if message and httpStatusCode are missing', () => {
+    const err = new HttpError({ code: 'MY_CODE' })
+    expect(err.message).toBe('MY_CODE')
+    expect(err.code).toBe('MY_CODE')
+  })
+
+  it('falls back to status text if only httpStatusCode is provided', () => {
+    const err = new HttpError({ httpStatusCode: httpStatus.NOT_FOUND })
+    expect(err.message).toBe(httpStatus[httpStatus.NOT_FOUND])
+    expect(err.httpStatusText).toBe(httpStatus[httpStatus.NOT_FOUND])
+    expect(err.httpStatusCode).toBe(httpStatus.NOT_FOUND)
+  })
+
+  it('falls back to "Unknown error" if nothing is provided', () => {
+    const err = new HttpError()
+    expect(err.message).toBe('Unknown error')
+    expect(err.code).toBeUndefined()
+    expect(err.httpStatusCode).toBeUndefined()
+    expect(err.httpStatusText).toBeUndefined()
+  })
+
+  it('uses httpStatusText if not explicitly set but httpStatusCode is present', () => {
+    const err = new HttpError({ httpStatusCode: httpStatus.UNAUTHORIZED })
+    expect(err.httpStatusText).toBe(httpStatus[httpStatus.UNAUTHORIZED])
+  })
+
+  it('supports static isInstanceOf check', () => {
+    const err = new HttpError()
+    expect(HttpError.isInstanceOf(err)).toBe(true)
+    expect(HttpError.isInstanceOf(new Error())).toBe(false)
+  })
+
+  it('supports Symbol.hasInstance (dynamic instanceof)', () => {
+    const fake = {
+      code: 'FAKE',
+      message: 'Fake error',
+      httpStatusCode: httpStatus.UNAUTHORIZED,
+      httpStatusText: httpStatus[httpStatus.UNAUTHORIZED],
+    }
+
+    expect(fake instanceof HttpError).toBe(true)
+  })
+
+  it('serializes correctly via toJSON', () => {
+    const err = new HttpError({
+      code: 'TOO_FAST',
+      message: 'You are too fast',
+      httpStatusCode: httpStatus.TOO_MANY_REQUESTS,
+      httpStatusText: httpStatus[httpStatus.TOO_MANY_REQUESTS],
+    })
+
+    const json = JSON.stringify(err)
+    expect(JSON.parse(json)).toEqual({
+      code: 'TOO_FAST',
+      message: 'You are too fast',
+      httpStatusCode: httpStatus.TOO_MANY_REQUESTS,
+      httpStatusText: httpStatus[httpStatus.TOO_MANY_REQUESTS],
+    })
+  })
+})

package/tests/core-util.js

@@ -0,0 +1,24 @@
+import { exec } from 'child_process'
+/**
+ * Starts a MongoDB Docker container on the specified port.
+ * @param {string} command - Command to run, like: 'docker run -d --name mongo-test -p 2730:27017 mongo'.
+ * @returns {Promise<void>}
+ */
+export const runInTerminal = async (command) => {
+  return new Promise((resolve, reject) => {
+    exec(command, (error, stdout, stderr) => {
+      if (error) {
+        console.error('Error starting command:', error.message)
+        return reject(error)
+      }
+      if (stderr) {
+        console.warn('stderr:', stderr)
+      }
+      console.log('Command started:', stdout.trim())
+      resolve()
+    })
+  })
+}
+
+export const sleep = async (milliseconds) =>
+  new Promise((res) => setTimeout(res, milliseconds))

package/tests/mongodb.test.js

@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { runInTerminal, sleep } from './core-util.js'
+import { initializeMongoDb } from '../src/mongodb/index.js'
+
+const port = 2730
+const dbName = 'testdb'
+const host = 'localhost'
+const mongoUri = `mongodb://${host}:${port}/?replicaSet=rs0`
+const dockerStopCommand = `docker stop ${dbName} && docker rm ${dbName}`
+const dockerCreateCommant = `docker run -d --name ${dbName} -p ${port}:27017 mongo --replSet rs0`
+const dockerReplicaSetCommand = `docker exec -i ${dbName} mongosh --eval "rs.initiate()"`
+
+describe('MongoDB Init & Transaction SDK', () => {
+  let collections
+
+  beforeAll(async () => {
+    try {
+      await runInTerminal(dockerStopCommand)
+    } catch (error) {
+      console.log('No existing container to stop.')
+    }
+
+    await runInTerminal(dockerCreateCommant)
+    await sleep(5000)
+    await runInTerminal(dockerReplicaSetCommand)
+
+    collections = await initializeMongoDb({
+      config: {
+        uri: mongoUri,
+        options: { dbName },
+      },
+      collectionNames: {
+        users: 'users',
+        logs: 'logs',
+      },
+    })
+
+    await collections.users.deleteMany({})
+    await collections.logs.deleteMany({})
+  }, 60000)
+
+  afterAll(async () => {
+    if (collections?.client) {
+      await collections.client.db(dbName).dropDatabase()
+      await collections.client.close()
+    }
+  }, 20000)
+
+  it.skip('should insert into multiple collections within a transaction', async () => {
+    if (!collections) throw new Error('collections not initialized')
+
+    await collections.withTransaction(async ({ session }) => {
+      const userInsert = collections.users.insertOne(
+        { name: 'Alice' },
+        { session },
+      )
+      const logInsert = collections.logs.insertOne(
+        { action: 'UserCreated', user: 'Alice' },
+        { session },
+      )
+      await Promise.all([userInsert, logInsert])
+    })
+
+    const insertedUser = await collections.users.findOne({ name: 'Alice' })
+    const insertedLog = await collections.logs.findOne({ user: 'Alice' })
+
+    expect(insertedUser).not.toBeNull()
+    expect(insertedLog).not.toBeNull()
+  }, 20000)
+}, 60000)

package/tests/with-error-handling.test.js

@@ -0,0 +1,124 @@
+import httpStatus from 'http-status'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+import { HttpError } from '../src/http/HttpError.js'
+import { GENERAL_ERROR } from '../src/fastify/error-codes.js'
+import {
+  replyOnErrorOnly,
+  withErrorHandling,
+  withErrorHandlingReply,
+} from '../src/fastify/error-handlers/with-error-handling.js'
+
+describe('withErrorHandling', () => {
+  const log = { error: vi.fn() }
+
+  it('should return result on success', async () => {
+    const fn = vi.fn().mockResolvedValue('ok')
+    const result = await withErrorHandling(
+      log,
+      new HttpError(GENERAL_ERROR),
+    )(fn)
+    expect(result).toBe('ok')
+  })
+
+  it('should rethrow HttpError', async () => {
+    const err = new HttpError({
+      message: 'Bad',
+      httpStatusCode: httpStatus.BAD_REQUEST,
+    })
+    const fn = vi.fn().mockRejectedValue(err)
+
+    await expect(
+      withErrorHandling(log, new HttpError(GENERAL_ERROR))(fn),
+    ).rejects.toThrow(err)
+  })
+
+  it('should wrap non-HttpError with HttpError', async () => {
+    const fn = vi.fn().mockRejectedValue(new Error('oops'))
+
+    await expect(
+      withErrorHandling(log, new HttpError(GENERAL_ERROR))(fn),
+    ).rejects.toBeInstanceOf(HttpError)
+  })
+})
+
+describe('withErrorHandlingReply', () => {
+  const reply = {
+    status: vi.fn().mockReturnThis(),
+    send: vi.fn(),
+  }
+
+  const log = { error: vi.fn() }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should return result on success', async () => {
+    const fn = vi.fn().mockResolvedValue('good')
+    const result = await withErrorHandlingReply({ reply, log })(fn)
+    expect(result).toBe('good')
+  })
+
+  it('should send reply on HttpError', async () => {
+    const err = new HttpError({
+      message: 'not found',
+      code: 'NOT_FOUND',
+      httpStatusCode: httpStatus.NOT_FOUND,
+      httpStatusText: httpStatus[httpStatus.NOT_FOUND],
+    })
+
+    const fn = vi.fn().mockRejectedValue(err)
+    await withErrorHandlingReply({ reply, log })(fn)
+
+    expect(reply.status).toHaveBeenCalledWith(httpStatus.NOT_FOUND)
+    expect(reply.send).toHaveBeenCalledWith({
+      code: 'NOT_FOUND',
+      httpStatusText: 'Not Found',
+    })
+  })
+})
+
+describe('replyOnErrorOnly', () => {
+  const reply = {
+    status: vi.fn().mockReturnThis(),
+    send: vi.fn(),
+  }
+
+  const log = { error: vi.fn() }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('should return result on success', async () => {
+    const fn = vi.fn().mockResolvedValue('yay')
+    const result = await replyOnErrorOnly({ reply, log })(fn)
+    expect(result).toBe('yay')
+  })
+
+  it('should send reply with default error when error is not HttpError', async () => {
+    const fn = vi.fn().mockRejectedValue(new Error('bad'))
+    await replyOnErrorOnly({ reply, log })(fn)
+
+    expect(reply.status).toHaveBeenCalledWith(httpStatus.INTERNAL_SERVER_ERROR)
+    expect(reply.send).toHaveBeenCalledWith(
+      expect.objectContaining({ error: 'bad' }),
+    )
+  })
+
+  it('should send reply with HttpError if thrown', async () => {
+    const err = new HttpError({
+      message: 'forbidden',
+      code: 'NO_ACCESS',
+      httpStatusCode: httpStatus.FORBIDDEN,
+      httpStatusText: httpStatus[httpStatus.FORBIDDEN],
+    })
+
+    const fn = vi.fn().mockRejectedValue(err)
+    await replyOnErrorOnly({ reply, log })(fn)
+
+    expect(reply.status).toHaveBeenCalledWith(httpStatus.FORBIDDEN)
+    expect(reply.send).toHaveBeenCalledWith({ error: 'forbidden' })
+  })
+})

package/vitest.config.js

@@ -0,0 +1,6 @@
+export default {
+  test: {
+    testTimeout: 30000,
+    hookTimeout: 30000,
+  },
+}

package/src/rabbit-mq/use-how-to.js

@@ -1,22 +0,0 @@
-import { initializeQueue, rabbitUriFromEnv } from './rabbit.js'
-
-const log = {
-  info: console.log,
-  error: console.error,
-}
-
-const start = async () => {
-  const host = rabbitUriFromEnv(process.env)
-  const rabbit = await initializeQueue({ host, log })
-
-  await rabbit.subscribe({
-    queue: 'testQueue',
-    onReceive: async (data) => {
-      console.log('Received:', data)
-    },
-  })
-
-  await rabbit.publish('testQueue', { hello: 'world' })
-}
-
-start()