core-services-sdk 1.3.3 → 1.3.5

package/src/http/http.js

@@ -10,10 +10,22 @@ const JSON_HEADER = {
   'Content-Type': 'application/json',
 }
 
+/**
+ * Checks if the HTTP status is considered successful (2xx).
+ *
+ * @param {Response} res - The fetch response object.
+ * @returns {boolean} `true` if status code is between 200-299.
+ */
 const isOkStatus = ({ status }) =>
-  // Range of response OK
   status >= httpStatus.OK && status < httpStatus.MULTIPLE_CHOICES
 
+/**
+ * Verifies response status and throws a structured HttpError if not OK.
+ *
+ * @param {Response} res - The fetch response object.
+ * @throws {HttpError} When the response status is not OK.
+ * @returns {Response} The response if status is OK.
+ */
 const checkStatus = async (res) => {
   if (!isOkStatus(res)) {
     const text = await res.text()
@@ -30,63 +42,95 @@ const checkStatus = async (res) => {
   return res
 }
 
+/**
+ * Reads the raw text from a fetch response.
+ *
+ * @param {Response} response - The fetch response.
+ * @returns {Promise<string>} The text body.
+ */
 const getTextResponse = async (response) => {
-  const text = await response.text()
-  return text
+  return await response.text()
 }
 
+/**
+ * Attempts to parse a JSON string.
+ *
+ * @param {string} responseText - A raw JSON string.
+ * @returns {Object} Parsed JSON object.
+ * @throws {SyntaxError} If the string is not valid JSON.
+ */
 const tryConvertJsonResponse = (responseText) => {
   try {
-    const obj = JSON.parse(responseText)
-    return obj
+    return JSON.parse(responseText)
   } catch (error) {
     error.responseText = responseText
     throw error
   }
 }
 
+/**
+ * Attempts to extract a JSON object from a fetch response.
+ *
+ * @param {Response} response - The fetch response.
+ * @returns {Promise<Object|string>} Parsed object or raw string on failure.
+ */
 const tryGetJsonResponse = async (response) => {
   let jsonText
   try {
-    jsonText = getTextResponse(response)
-    const obj = tryConvertJsonResponse(jsonText)
-    return obj
+    jsonText = await getTextResponse(response)
+    return tryConvertJsonResponse(jsonText)
   } catch (error) {
-    if (!jsonText) {
-      throw error
-    }
+    if (!jsonText) throw error
     return jsonText
   }
 }
 
+/**
+ * Attempts to extract an XML object from a fetch response.
+ *
+ * @param {Response} response - The fetch response.
+ * @returns {Promise<Object|string>} Parsed XML object or raw string.
+ */
 const tryGetXmlResponse = async (response) => {
   let xmlText
   try {
     xmlText = await getTextResponse(response)
-    const xml = await parseStringPromise(xmlText)
-    return xml
+    return await parseStringPromise(xmlText)
   } catch (error) {
-    if (!xmlText) {
-      throw error
-    }
+    if (!xmlText) throw error
     return xmlText
   }
 }
 
+/**
+ * Extracts and parses the fetch response body based on expected type.
+ *
+ * @param {Response} response - The fetch response.
+ * @param {string} responseType - The expected response type ('json', 'xml', 'text').
+ * @returns {Promise<any>} The parsed response payload.
+ */
 const getResponsePayload = async (response, responseType) => {
   switch (responseType) {
     case ResponseType.json:
       return tryGetJsonResponse(response)
-
     case ResponseType.xml:
       return tryGetXmlResponse(response)
-
     default:
     case ResponseType.text:
       return getTextResponse(response)
   }
 }
 
+/**
+ * Sends an HTTP GET request.
+ *
+ * @param {Object} params
+ * @param {string} params.url - The target URL.
+ * @param {Object} [params.headers] - Optional custom headers.
+ * @param {string} [params.credentials='include'] - Credential mode.
+ * @param {string} [params.expectedType='json'] - Response type.
+ * @returns {Promise<any>} Parsed response data.
+ */
 export const get = async ({
   url,
   headers = {},
@@ -95,18 +139,24 @@ export const get = async ({
 }) => {
   const response = await fetch(url, {
     method: HTTP_METHODS.GET,
-    headers: {
-      ...JSON_HEADER,
-      ...headers,
-    },
+    headers: { ...JSON_HEADER, ...headers },
     ...(credentials ? { credentials } : {}),
   })
-
   await checkStatus(response)
-  const data = await getResponsePayload(response, expectedType)
-  return data
+  return await getResponsePayload(response, expectedType)
 }
 
+/**
+ * Sends an HTTP POST request.
+ *
+ * @param {Object} params
+ * @param {string} params.url - The target URL.
+ * @param {Object} params.body - Body data to send.
+ * @param {Object} [params.headers] - Optional custom headers.
+ * @param {string} [params.credentials='include'] - Credential mode.
+ * @param {string} [params.expectedType='json'] - Response type.
+ * @returns {Promise<any>} Parsed response data.
+ */
 export const post = async ({
   url,
   body,
@@ -116,18 +166,20 @@ export const post = async ({
 }) => {
   const response = await fetch(url, {
     method: HTTP_METHODS.POST,
-    headers: {
-      ...JSON_HEADER,
-      ...headers,
-    },
+    headers: { ...JSON_HEADER, ...headers },
     body: JSON.stringify(body),
     ...(credentials ? { credentials } : {}),
   })
   await checkStatus(response)
-  const data = await getResponsePayload(response, expectedType)
-  return data
+  return await getResponsePayload(response, expectedType)
 }
 
+/**
+ * Sends an HTTP PUT request.
+ *
+ * @param {Object} params - Same as `post`.
+ * @returns {Promise<any>} Parsed response data.
+ */
 export const put = async ({
   url,
   body,
@@ -137,19 +189,20 @@ export const put = async ({
 }) => {
   const response = await fetch(url, {
     method: HTTP_METHODS.PUT,
-    headers: {
-      ...JSON_HEADER,
-      ...headers,
-    },
+    headers: { ...JSON_HEADER, ...headers },
     body: JSON.stringify(body),
     ...(credentials ? { credentials } : {}),
   })
-
   await checkStatus(response)
-  const data = await getResponsePayload(response, expectedType)
-  return data
+  return await getResponsePayload(response, expectedType)
 }
 
+/**
+ * Sends an HTTP PATCH request.
+ *
+ * @param {Object} params - Same as `post`.
+ * @returns {Promise<any>} Parsed response data.
+ */
 export const patch = async ({
   url,
   body,
@@ -159,19 +212,20 @@ export const patch = async ({
 }) => {
   const response = await fetch(url, {
     method: HTTP_METHODS.PATCH,
-    headers: {
-      ...JSON_HEADER,
-      ...headers,
-    },
+    headers: { ...JSON_HEADER, ...headers },
     body: JSON.stringify(body),
     ...(credentials ? { credentials } : {}),
   })
-
   await checkStatus(response)
-  const data = await getResponsePayload(response, expectedType)
-  return data
+  return await getResponsePayload(response, expectedType)
 }
 
+/**
+ * Sends an HTTP DELETE request.
+ *
+ * @param {Object} params - Same as `post`, but body is optional.
+ * @returns {Promise<any>} Parsed response data.
+ */
 export const deleteApi = async ({
   url,
   body,
@@ -181,19 +235,24 @@ export const deleteApi = async ({
 }) => {
   const response = await fetch(url, {
     method: HTTP_METHODS.DELETE,
-    headers: {
-      ...JSON_HEADER,
-      ...headers,
-    },
+    headers: { ...JSON_HEADER, ...headers },
     ...(body ? { body: JSON.stringify(body) } : {}),
     ...(credentials ? { credentials } : {}),
   })
-
   await checkStatus(response)
-  const data = await getResponsePayload(response, expectedType)
-  return data
+  return await getResponsePayload(response, expectedType)
 }
 
+/**
+ * Consolidated HTTP client with method shortcuts.
+ *
+ * @namespace http
+ * @property {Function} get - HTTP GET method.
+ * @property {Function} post - HTTP POST method.
+ * @property {Function} put - HTTP PUT method.
+ * @property {Function} patch - HTTP PATCH method.
+ * @property {Function} deleteApi - HTTP DELETE method.
+ */
 export const http = {
   get,
   put,

package/src/ids/generators.js

@@ -0,0 +1,73 @@
+import { v4 as uuidv4 } from 'uuid'
+import { ID_PREFIXES } from './prefixes.js'
+
+/**
+ * Generates a new UUID v4 string.
+ *
+ * @returns {string} A new UUID (version 4).
+ *
+ * @example
+ * generateId() // '550e8400-e29b-41d4-a716-446655440000'
+ */
+export const generateId = () => {
+  return uuidv4()
+}
+
+/**
+ * Generates a unique ID with the given prefix.
+ *
+ * @param {string} prefix - A prefix string to prepend to the UUID.
+ * @returns {string} A unique ID in the format `${prefix}_${uuid}`.
+ *
+ * @example
+ * generatePrefixedId('usr') // 'usr_550e8400-e29b-41d4-a716-446655440000'
+ */
+export const generatePrefixedId = (prefix) => {
+  return `${prefix}_${generateId()}`
+}
+
+/**
+ * Generates a user ID with a `usr_` prefix.
+ *
+ * @returns {string} A user ID.
+ */
+export const generateUserId = () => generatePrefixedId(ID_PREFIXES.USER)
+
+/**
+ * Generates a tenant ID with a `tnt_` prefix.
+ *
+ * @returns {string} A tenant ID.
+ */
+export const generateTenantId = () => generatePrefixedId(ID_PREFIXES.TENANT)
+
+/**
+ * Generates a permission ID with a `prm_` prefix.
+ *
+ * @returns {string} A permission ID.
+ */
+export const generatePermissionId = () =>
+  generatePrefixedId(ID_PREFIXES.PERMISSION)
+
+/**
+ * Generates a correlation ID with a `crln_` prefix.
+ *
+ * @returns {string} A correlation ID.
+ */
+export const generateCorrelationId = () =>
+  generatePrefixedId(ID_PREFIXES.CORRELATION)
+
+/**
+ * Generates a verification ID with a `vrf_` prefix.
+ *
+ * @returns {string} A verification ID.
+ */
+export const generateVerificationId = () =>
+  generatePrefixedId(ID_PREFIXES.VERIFICATION)
+
+/**
+ * Generates a role permissions ID with a `role_` prefix.
+ *
+ * @returns {string} A role permissions ID.
+ */
+export const generateRolePermissionsId = () =>
+  generatePrefixedId(ID_PREFIXES.ROLE_PERMISSIONS)

package/src/ids/prefixes.js

@@ -0,0 +1,28 @@
+/**
+ * Mapping of entity types to their unique ID prefixes.
+ *
+ * These prefixes are prepended to UUIDs to create consistent and identifiable IDs across the system.
+ * For example: 'usr_550e8400-e29b-41d4-a716-446655440000'
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const ID_PREFIXES = Object.freeze({
+  /** User entity ID prefix */
+  USER: 'usr',
+
+  /** Tenant entity ID prefix */
+  TENANT: 'tnt',
+
+  /** Permission entity ID prefix */
+  PERMISSION: 'prm',
+
+  /** Correlation ID prefix (e.g., for tracing requests) */
+  CORRELATION: 'crln',
+
+  /** Verification entity ID prefix (e.g., email/phone code) */
+  VERIFICATION: 'vrf',
+
+  /** Role-permissions mapping ID prefix */
+  ROLE_PERMISSIONS: 'role',
+})

package/src/index.js

@@ -1,10 +1,17 @@
 export * from './fastify/index.js'
 export * from './mongodb/index.js'
-export * from './mongodb/connect.js'
+export * from './crypto/crypto.js'
 export * from './rabbit-mq/index.js'
+export * from './logger/get-logger.js'
+export * from './core/regex-utils.js'
 export * as http from './http/http.js'
 export * from './http/responseType.js'
+export * from './crypto/encryption.js'
+export * from './core/otp-generators.js'
+export * from './core/sanitize-objects.js'
+export * from './core/normalize-to-array.js'
 export { initMailer } from './mailer/index.js'
+export * from './core/combine-unique-arrays.js'
 export { HttpError } from './http/HttpError.js'
 export { Mailer } from './mailer/mailer.service.js'
 export { TransportFactory } from './mailer/transport.factory.js'

package/src/logger/get-logger.js

@@ -0,0 +1,64 @@
+import pino from 'pino'
+
+const requiredMethods = ['info', 'warn', 'error', 'debug']
+
+const dummyLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+}
+
+/**
+ * @param {any} logger
+ * @returns {boolean}
+ */
+const isValidLogger = (logger) =>
+  typeof logger === 'object' &&
+  requiredMethods.every((method) => typeof logger[method] === 'function')
+
+/**
+ * Creates or returns a logger instance based on user-provided options.
+ *
+ * Supported usages:
+ * - `undefined` → pino with level 'info'
+ * - `true` → pino with level 'info'
+ * - `{ logger: true, level?: string }` → pino with given level
+ * - `{ logger: LoggerObject }` → use provided logger
+ * - fallback → dummy logger
+ *
+ * @param {true | Object | undefined} option
+ * @returns {import('pino').Logger | typeof dummyLogger}
+ */
+export const getLogger = (option) => {
+  // No option provided or just true: use pino default
+  if (option === undefined || option === true) {
+    const logger = pino({ level: 'info' })
+    logger.info(
+      '[getLogger] No logger config provided. Using default Pino logger (level: info).',
+    )
+    return logger
+  }
+
+  // Option object provided
+  if (typeof option === 'object') {
+    const { logger, level } = option
+
+    // User asked for internal pino with level
+    if (logger === true) {
+      const pinoLogger = pino({ level: level || 'info' })
+      pinoLogger.info(
+        `[getLogger] Using internal Pino logger (level: ${level || 'info'}).`,
+      )
+      return pinoLogger
+    }
+
+    // User supplied a custom logger
+    if (isValidLogger(logger)) {
+      return logger
+    }
+  }
+
+  // Invalid or no-op fallback
+  return dummyLogger
+}

package/src/logger/index.js

@@ -0,0 +1 @@
+export * from './get-logger.js'

package/src/mongodb/index.js

@@ -1,73 +1,3 @@
-// @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()
-    let actionResponse
-    try {
-      session.startTransaction()
-      actionResponse = await action({ session })
-      await session.commitTransaction()
-    } catch (error) {
-      await session.abortTransaction()
-      throw error
-    } finally {
-      await session.endSession()
-      return actionResponse
-    }
-  }
-
-  return {
-    ...collectionRefs,
-    withTransaction,
-    /** @type {import('mongodb').MongoClient} */
-    get client() {
-      return client
-    },
-  }
-}
+export * from './connect.js'
+export * from './initialize-mongodb.js'
+export * from './validate-mongo-uri.js'

package/src/mongodb/initialize-mongodb.js

@@ -0,0 +1,73 @@
+// @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()
+    let actionResponse
+    try {
+      session.startTransaction()
+      actionResponse = await action({ session })
+      await session.commitTransaction()
+    } catch (error) {
+      await session.abortTransaction()
+      throw error
+    } finally {
+      await session.endSession()
+      return actionResponse
+    }
+  }
+
+  return {
+    ...collectionRefs,
+    withTransaction,
+    /** @type {import('mongodb').MongoClient} */
+    get client() {
+      return client
+    },
+  }
+}

package/src/mongodb/validate-mongo-uri.js

@@ -0,0 +1,32 @@
+/**
+ * Validates whether a given string is a properly formatted MongoDB URI.
+ *
+ * Supports both standard (`mongodb://`) and SRV (`mongodb+srv://`) protocols.
+ *
+ * @param {string} uri - The URI string to validate.
+ * @returns {boolean} `true` if the URI is a valid MongoDB connection string, otherwise `false`.
+ *
+ * @example
+ * isValidMongoUri('mongodb://localhost:27017/mydb') // true
+ * isValidMongoUri('mongodb+srv://cluster.example.com/test') // true
+ * isValidMongoUri('http://localhost') // false
+ * isValidMongoUri('') // false
+ */
+export function isValidMongoUri(uri) {
+  if (typeof uri !== 'string' || !uri.trim()) {
+    return false
+  }
+
+  try {
+    const parsed = new URL(uri)
+
+    const isValidProtocol =
+      parsed.protocol === 'mongodb:' || parsed.protocol === 'mongodb+srv:'
+
+    const hasHostname = Boolean(parsed.hostname)
+
+    return isValidProtocol && hasHostname
+  } catch (e) {
+    return false
+  }
+}

package/tests/core/combine-unique-arrays.unit.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest'
+
+import { combineUniqueArrays } from '../../src/core/combine-unique-arrays.js'
+
+describe('combineUniqueArrays', () => {
+  it('should combine arrays and remove duplicates (numbers)', () => {
+    const result = combineUniqueArrays([1, 2], [2, 3], [3, 4])
+    expect(result).toEqual([1, 2, 3, 4])
+  })
+
+  it('should combine arrays and remove duplicates (strings)', () => {
+    const result = combineUniqueArrays(['a', 'b'], ['b', 'c'])
+    expect(result).toEqual(['a', 'b', 'c'])
+  })
+
+  it('should return empty array when no input is provided', () => {
+    const result = combineUniqueArrays()
+    expect(result).toEqual([])
+  })
+
+  it('should handle single array', () => {
+    const result = combineUniqueArrays([1, 2, 2, 3])
+    expect(result).toEqual([1, 2, 3])
+  })
+
+  it('should preserve order of first appearance', () => {
+    const result = combineUniqueArrays(['b', 'a'], ['a', 'c'])
+    expect(result).toEqual(['b', 'a', 'c'])
+  })
+
+  it('should handle mixed types', () => {
+    const result = combineUniqueArrays(['1', 1, true, 'true'], [true, '1'])
+    expect(result).toEqual(['1', 1, true, 'true'])
+  })
+})