core-services-sdk 1.3.23 → 1.3.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.23",
+  "version": "1.3.25",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",
@@ -51,4 +51,4 @@
     "url": "^0.11.4",
     "vitest": "^3.2.4"
   }
-}
+}

package/src/core/index.js

@@ -5,3 +5,5 @@ export * from './normalize-min-max.js'
 export * from './normalize-to-array.js'
 export * from './combine-unique-arrays.js'
 export * from './normalize-phone-number.js'
+export * from './normalize-array-operators.js'
+export * from './normalize-premitives-types-or-default.js'

package/src/core/normalize-array-operators.js

@@ -0,0 +1,24 @@
+export const normalizeOperators = (obj) => {
+  const arrayOps = ['in', 'nin', 'or', 'and']
+
+  function normalize(value) {
+    if (Array.isArray(value)) {
+      return value.map(normalize)
+    } else if (typeof value === 'object' && value !== null) {
+      // Handle objects with numeric keys (e.g. {0: {...}, 1: {...}})
+      const keys = Object.keys(value)
+      if (keys.every((k) => /^\d+$/.test(k))) {
+        return keys.sort().map((k) => normalize(value[k]))
+      }
+      for (const [k, v] of Object.entries(value)) {
+        value[k] = normalize(v)
+        if (arrayOps.includes(k)) {
+          value[k] = Array.isArray(value[k]) ? value[k] : [value[k]]
+        }
+      }
+    }
+    return value
+  }
+
+  return normalize(obj)
+}

package/src/core/normalize-premitives-types-or-default.js

@@ -0,0 +1,215 @@
+/**
+ * Normalize Utilities
+ *
+ * Small helpers to guarantee stable, predictable values from user/config inputs.
+ * When an incoming value is missing, malformed, or in a different-but-supported
+ * representation (e.g., number/boolean as string), these utilities either accept
+ * it (after safe normalization) or return a default you control.
+ *
+ * Design highlights:
+ * - Keep call sites compact and intention-revealing.
+ * - Be strict for strings (no implicit type coercion).
+ * - Be permissive for number/boolean when the input is a string in an accepted form.
+ * - Fast, side-effect free, no deep cloning — values are returned by reference when valid.
+ */
+
+/**
+ * Generic predicate-based normalization.
+ *
+ * Purpose:
+ *  Ensure a value conforms to a caller-provided predicate; otherwise return a provided default.
+ *  Useful when you need a single reusable pattern for custom shapes or policies
+ *  (e.g., "must be a non-empty array of strings", "must be a plain object", etc.).
+ *
+ * Behavior:
+ *  - Calls `isValid(value)`.
+ *  - If the predicate returns true → returns `value` (as-is).
+ *  - Otherwise → returns `defaultValue` (as-is).
+ *
+ * Performance & Safety:
+ *  - O(1) aside from your predicate cost.
+ *  - No cloning or sanitization is performed.
+ *  - Ensure `isValid` is pure and fast; avoid throwing inside it.
+ *
+ * @template T
+ * @param {any} value
+ *   Candidate input to validate.
+ * @param {(v:any)=>boolean} isValid
+ *   Validation predicate. Return true iff the input is acceptable.
+ * @param {T} defaultValue
+ *   Fallback to return when `value` fails validation.
+ * @returns {T}
+ *   The original `value` when valid; otherwise `defaultValue`.
+ *
+ * @example
+ * // Ensure a finite number
+ * normalizeOrDefault(5, v => typeof v === 'number' && Number.isFinite(v), 0) // → 5
+ * normalizeOrDefault('x', v => typeof v === 'number', 0)                     // → 0
+ *
+ * @example
+ * // Ensure an object (non-null, non-array)
+ * const cfg = normalizeOrDefault(
+ *   maybeCfg,
+ *   v => v && typeof v === 'object' && !Array.isArray(v),
+ *   {}
+ * )
+ */
+export function normalizeOrDefault(value, isValid, defaultValue) {
+  return isValid(value) ? value : defaultValue
+}
+
+/**
+ * Normalize a value to a non-empty, trimmed string; otherwise return a default (also trimmed).
+ *
+ * Purpose:
+ *  Guarantee that downstream code receives a usable, non-empty string
+ *  without performing implicit type coercion.
+ *
+ * Acceptance Criteria:
+ *  - Accept only actual strings whose `trim()` length is > 0.
+ *  - Return `value.trim()` when valid.
+ *  - Otherwise return `defaultValue.trim()`.
+ *
+ * Why strict for strings?
+ *  - Silent coercion from non-strings to string can hide bugs.
+ *  - If you need to stringify other types, do it explicitly at the call site.
+ *
+ * Edge Cases:
+ *  - If `defaultValue` is empty or whitespace-only, the function returns an empty string.
+ *    Prefer providing a meaningful, non-empty default for clarity.
+ *
+ * @param {any} value
+ *   Candidate to normalize (must be a string to be accepted).
+ * @param {string} defaultValue
+ *   Fallback used when `value` is not a non-empty string. Will be `trim()`ed.
+ * @returns {string}
+ *   A trimmed non-empty string when `value` is valid; otherwise `defaultValue.trim()`.
+ *
+ * @example
+ * normalizeStringOrDefault('  user-roles-management:edit  ', 'fallback')
+ * // → 'user-roles-management:edit'
+ *
+ * @example
+ * normalizeStringOrDefault('', 'user-roles-management:edit')
+ * // → 'user-roles-management:edit'
+ *
+ * @example
+ * normalizeStringOrDefault(42, 'user-roles-management:edit')
+ * // → 'user-roles-management:edit'
+ */
+export function normalizeStringOrDefault(value, defaultValue) {
+  const def = typeof defaultValue === 'string' ? defaultValue.trim() : ''
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (trimmed.length > 0) {
+      return trimmed
+    }
+  }
+  return def
+}
+
+/**
+ * Normalize a value to a valid number (with safe string coercion); otherwise return a default.
+ *
+ * Purpose:
+ *  Accept numeric inputs that may arrive as strings (e.g., from env vars or config files)
+ *  while keeping semantics explicit and predictable.
+ *
+ * Acceptance Criteria:
+ *  - Accepts finite numbers (`typeof value === 'number' && Number.isFinite(value)`).
+ *  - Accepts strings that become a finite number via `Number(trimmed)`.
+ *    Examples: "42", "  3.14 ", "1e3", "-7", "0x10" (JS Number semantics).
+ *  - Rejects non-numeric strings (e.g., "", "   ", "abc") and non-number types.
+ *  - Returns `defaultValue` when not acceptable.
+ *
+ * Parsing Semantics:
+ *  - Uses `Number(s)` which requires the whole trimmed string to be numeric.
+ *  - Honors JavaScript numeric literal rules (including hex and scientific notation).
+ *  - If you want base-10 only or looser parsing, do it explicitly before calling.
+ *
+ * @param {any} value
+ *   Candidate to normalize (number or numeric string).
+ * @param {number} defaultValue
+ *   Fallback used when `value` is neither a finite number nor a numeric string.
+ * @returns {number}
+ *   A finite number derived from `value`, or `defaultValue`.
+ *
+ * @example
+ * normalizeNumberOrDefault(42, 0)       // → 42
+ * normalizeNumberOrDefault(' 3.14 ', 0) // → 3.14
+ * normalizeNumberOrDefault('1e3', 0)    // → 1000
+ * normalizeNumberOrDefault('-7', 0)     // → -7
+ *
+ * @example
+ * normalizeNumberOrDefault('abc', 7)    // → 7
+ * normalizeNumberOrDefault(NaN, 7)      // → 7
+ * normalizeNumberOrDefault({}, 7)       // → 7
+ */
+export function normalizeNumberOrDefault(value, defaultValue) {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value
+  }
+  if (typeof value === 'string') {
+    const s = value.trim()
+    if (s.length > 0) {
+      const n = Number(s)
+      if (Number.isFinite(n)) {
+        return n
+      }
+    }
+  }
+  return defaultValue
+}
+
+/**
+ * Normalize a value to a boolean (with "true"/"false" string support); otherwise return a default.
+ *
+ * Purpose:
+ *  Stabilize feature flags and binary config values that might be provided as either booleans
+ *  or as canonical strings.
+ *
+ * Acceptance Criteria:
+ *  - Accepts actual booleans (`true` / `false`) → returned as-is.
+ *  - Accepts strings equal to "true" or "false" (case-insensitive, trimmed).
+ *    "true"  → true
+ *    "false" → false
+ *  - Rejects other strings ("yes", "1", "0", etc.) and other types → returns `defaultValue`.
+ *
+ * Rationale:
+ *  - Limiting string forms to the canonical words avoids accidental truthiness/falseyness.
+ *  - If you need to accept "1"/"0" or other variants, coerce at the call site so intent is explicit.
+ *
+ * @param {any} value
+ *   Candidate to normalize (boolean or "true"/"false" string).
+ * @param {boolean} defaultValue
+ *   Fallback used when `value` is neither a boolean nor an accepted string form.
+ * @returns {boolean}
+ *   A boolean derived from `value`, or `defaultValue`.
+ *
+ * @example
+ * normalizeBooleanOrDefault(true,  false) // → true
+ * normalizeBooleanOrDefault(false, true)  // → false
+ *
+ * @example
+ * normalizeBooleanOrDefault('true',  false) // → true
+ * normalizeBooleanOrDefault(' FALSE ', true) // → false
+ *
+ * @example
+ * normalizeBooleanOrDefault('yes',  false) // → false  (rejected → default)
+ * normalizeBooleanOrDefault(1,      true)  // → true   (rejected → default)
+ */
+export function normalizeBooleanOrDefault(value, defaultValue) {
+  if (typeof value === 'boolean') {
+    return value
+  }
+  if (typeof value === 'string') {
+    const s = value.trim().toLowerCase()
+    if (s === 'true') {
+      return true
+    }
+    if (s === 'false') {
+      return false
+    }
+  }
+  return defaultValue
+}

package/src/mongodb/dsl-to-mongo.js

@@ -0,0 +1,99 @@
+/**
+ * Convert a normalized query object into a MongoDB query object.
+ *
+ * Supported operators: eq, in, nin, gt, gte, lt, lte, and, or.
+ *
+ * Example input:
+ * {
+ *   userId: { in: ['123','456'] },
+ *   status: { eq: 'active' },
+ *   age: { gte: 18 },
+ *   or: [
+ *     { role: { eq: 'admin' } },
+ *     { status: { eq: 'active' } }
+ *   ]
+ * }
+ *
+ * Example output:
+ * {
+ *   userId: { $in: ['123','456'] },
+ *   status: { $eq: 'active' },
+ *   age: { $gte: 18 },
+ *   $or: [
+ *     { role: { $eq: 'admin' } },
+ *     { status: { $eq: 'active' } }
+ *   ]
+ * }
+ *
+ * @param {Record<string, any>} query - The normalized query object
+ * @returns {Record<string, any>} - A MongoDB query object
+ */
+/**
+ * Map DSL logical keywords to Mongo operators.
+ */
+const LOGICAL_OPS = new Map([
+  ['or', '$or'],
+  ['and', '$and'],
+  ['nor', '$nor'],
+  ['not', '$not'],
+])
+
+/**
+ * Convert a condition object (e.g. { gt: 18, lt: 65 }) into Mongo condition.
+ * Recursively applies to nested objects.
+ */
+function convertCondition(condition) {
+  if (
+    condition === null ||
+    typeof condition !== 'object' ||
+    Array.isArray(condition)
+  ) {
+    return condition // primitive or array stays as is
+  }
+
+  return Object.fromEntries(
+    Object.entries(condition).map(([op, value]) => {
+      if (op.startsWith('$')) {
+        return [op, value] // already Mongo operator
+      }
+      const mongoOp = `$${op}`
+      return [mongoOp, convertCondition(value)]
+    }),
+  )
+}
+
+/**
+ * Convert a normalized query object into a MongoDB query object.
+ *
+ * @param {Record<string, any>} query - normalized DSL query
+ * @returns {Record<string, any>} - MongoDB query object
+ */
+export function toMongo(query = {}) {
+  return Object.fromEntries(
+    Object.entries(query).map(([field, condition]) => {
+      // logical operator
+      if (LOGICAL_OPS.has(field)) {
+        const mongoOp = LOGICAL_OPS.get(field)
+        if (Array.isArray(condition)) {
+          return [mongoOp, condition.map(toMongo)]
+        }
+        if (condition && typeof condition === 'object') {
+          return [mongoOp, toMongo(condition)]
+        }
+        return [mongoOp, condition]
+      }
+
+      // operator object
+      if (
+        condition !== null &&
+        typeof condition === 'object' &&
+        !Array.isArray(condition)
+      ) {
+        return [field, convertCondition(condition)]
+      }
+
+      // plain value or null → $eq
+      return [field, { $eq: condition }]
+    }),
+  )
+}

package/src/mongodb/index.js

@@ -1,3 +1,4 @@
 export * from './connect.js'
+export * from './dsl-to-mongo.js'
 export * from './initialize-mongodb.js'
 export * from './validate-mongo-uri.js'

package/tests/core/normalize-array-operators.integration.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+
+import { buildServer } from '../resources/server.js'
+
+describe('Integration: Fastify + normalizeOperators', () => {
+  let app
+
+  beforeAll(async () => {
+    app = buildServer()
+    await app.listen({ port: 0 })
+  })
+
+  afterAll(async () => {
+    await app.close()
+  })
+
+  it('GET with userId[in]=123,456 should normalize to array', async () => {
+    const res = await app.inject('/users?userId[in]=123,456&status[eq]=active')
+    const body = res.json()
+
+    expect(body.dsl).toEqual({
+      userId: { in: ['123', '456'] },
+      status: { eq: 'active' },
+    })
+  })
+
+  it('GET with userId[in]=123 should wrap in array', async () => {
+    const res = await app.inject('/users?userId[in]=123')
+    const body = res.json()
+
+    expect(body.dsl).toEqual({ userId: { in: ['123'] } })
+  })
+
+  it('GET with OR query should normalize to array', async () => {
+    const res = await app.inject(
+      '/users?or[0][status][eq]=active&or[1][role][eq]=admin',
+    )
+    const body = res.json()
+
+    expect(body.dsl).toEqual({
+      or: [{ status: { eq: 'active' } }, { role: { eq: 'admin' } }],
+    })
+  })
+
+  it('POST with where body should normalize', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/users/search',
+      payload: {
+        where: {
+          userId: { in: '123' },
+          age: { gte: 18 },
+        },
+      },
+    })
+
+    const body = res.json()
+
+    expect(body.dsl).toEqual({
+      userId: { in: ['123'] },
+      age: { gte: 18 },
+    })
+  })
+})

package/tests/core/normalize-array-operators.unit.test.js

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest'
+
+import { normalizeOperators } from '../../src/core/normalize-array-operators.js'
+
+describe('normalizeOperators', () => {
+  it('should wrap single value in `in` into an array', () => {
+    const input = { userId: { in: '123' } }
+    const output = normalizeOperators(input)
+    expect(output).toEqual({ userId: { in: ['123'] } })
+  })
+
+  it('should keep array value in `in` as is', () => {
+    const input = { userId: { in: ['123', '456'] } }
+    const output = normalizeOperators(input)
+    expect(output).toEqual({ userId: { in: ['123', '456'] } })
+  })
+
+  it('should wrap single value in `nin` into an array', () => {
+    const input = { userId: { nin: '789' } }
+    const output = normalizeOperators(input)
+    expect(output).toEqual({ userId: { nin: ['789'] } })
+  })
+
+  it('should normalize object with numeric keys into array (or)', () => {
+    const input = {
+      or: { 0: { status: { eq: 'active' } }, 1: { role: { eq: 'admin' } } },
+    }
+    const output = normalizeOperators(input)
+    expect(output).toEqual({
+      or: [{ status: { eq: 'active' } }, { role: { eq: 'admin' } }],
+    })
+  })
+
+  it('should wrap single object in `or` into array', () => {
+    const input = { or: { status: { eq: 'active' } } }
+    const output = normalizeOperators(input)
+    expect(output).toEqual({
+      or: [{ status: { eq: 'active' } }],
+    })
+  })
+
+  it('should handle nested in + or together', () => {
+    const input = {
+      or: {
+        0: { userId: { in: '123' } },
+        1: { userId: { in: ['456', '789'] } },
+      },
+    }
+    const output = normalizeOperators(input)
+    expect(output).toEqual({
+      or: [{ userId: { in: ['123'] } }, { userId: { in: ['456', '789'] } }],
+    })
+  })
+
+  it('should handle `and` with mixed single and multiple values', () => {
+    const input = {
+      and: {
+        0: { status: { eq: 'active' } },
+        1: { userId: { in: '123' } },
+      },
+    }
+    const output = normalizeOperators(input)
+    expect(output).toEqual({
+      and: [{ status: { eq: 'active' } }, { userId: { in: ['123'] } }],
+    })
+  })
+
+  it('should do nothing for fields without array operators', () => {
+    const input = { age: { gte: 18 } }
+    const output = normalizeOperators(input)
+    expect(output).toEqual({ age: { gte: 18 } })
+  })
+
+  it('should work with deeply nested structures', () => {
+    const input = {
+      or: {
+        0: {
+          and: {
+            0: { userId: { in: '123' } },
+            1: { status: { eq: 'active' } },
+          },
+        },
+        1: { role: { nin: 'guest' } },
+      },
+    }
+
+    const output = normalizeOperators(input)
+
+    expect(output).toEqual({
+      or: [
+        {
+          and: [{ userId: { in: ['123'] } }, { status: { eq: 'active' } }],
+        },
+        { role: { nin: ['guest'] } },
+      ],
+    })
+  })
+})

package/tests/core/normalize-premitives-types-or-default.unit.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  normalizeOrDefault,
+  normalizeStringOrDefault,
+  normalizeNumberOrDefault,
+  normalizeBooleanOrDefault,
+} from '../../src/core/normalize-premitives-types-or-default.js'
+
+describe('normalizeOrDefault (generic)', () => {
+  it('returns value if predicate is true', () => {
+    const out = normalizeOrDefault(5, (v) => typeof v === 'number', 0)
+    expect(out).toBe(5)
+  })
+  it('returns default if predicate is false', () => {
+    const out = normalizeOrDefault('x', (v) => typeof v === 'number', 0)
+    expect(out).toBe(0)
+  })
+})
+
+describe('normalizeStringOrDefault (strict, no coercion)', () => {
+  it('keeps a non-empty trimmed string', () => {
+    expect(normalizeStringOrDefault('  hello  ', 'fallback')).toBe('hello')
+  })
+  it('returns default for empty / whitespace-only', () => {
+    expect(normalizeStringOrDefault('', 'fallback')).toBe('fallback')
+    expect(normalizeStringOrDefault('   ', 'fallback')).toBe('fallback')
+  })
+  it('returns default for non-strings', () => {
+    expect(normalizeStringOrDefault(123, 'fallback')).toBe('fallback')
+    expect(normalizeStringOrDefault(null, 'fallback')).toBe('fallback')
+  })
+  it('trims default defensively', () => {
+    expect(normalizeStringOrDefault('', '  fallback  ')).toBe('fallback')
+  })
+})
+
+describe('normalizeNumberOrDefault (coercive for strings)', () => {
+  it('keeps valid number', () => {
+    expect(normalizeNumberOrDefault(42, 0)).toBe(42)
+  })
+  it('coerces valid numeric string', () => {
+    expect(normalizeNumberOrDefault('42', 0)).toBe(42)
+    expect(normalizeNumberOrDefault('  3.14 ', 0)).toBe(3.14)
+    expect(normalizeNumberOrDefault('1e3', 0)).toBe(1000)
+    expect(normalizeNumberOrDefault('-7', 0)).toBe(-7)
+  })
+  it('returns default for invalid number inputs', () => {
+    expect(normalizeNumberOrDefault(NaN, 7)).toBe(7)
+    expect(normalizeNumberOrDefault('   ', 7)).toBe(7)
+    expect(normalizeNumberOrDefault('abc', 7)).toBe(7)
+    expect(normalizeNumberOrDefault({}, 7)).toBe(7)
+  })
+})
+
+describe('normalizeBooleanOrDefault (coercive for "true"/"false" strings)', () => {
+  it('keeps actual booleans', () => {
+    expect(normalizeBooleanOrDefault(true, false)).toBe(true)
+    expect(normalizeBooleanOrDefault(false, true)).toBe(false)
+  })
+  it('coerces "true"/"false" strings (case-insensitive)', () => {
+    expect(normalizeBooleanOrDefault('true', false)).toBe(true)
+    expect(normalizeBooleanOrDefault('FALSE', true)).toBe(false)
+    expect(normalizeBooleanOrDefault('  TrUe  ', false)).toBe(true)
+  })
+  it('returns default for other strings / types', () => {
+    expect(normalizeBooleanOrDefault('yes', false)).toBe(false)
+    expect(normalizeBooleanOrDefault('0', true)).toBe(true)
+    expect(normalizeBooleanOrDefault(1, false)).toBe(false)
+    expect(normalizeBooleanOrDefault(null, true)).toBe(true)
+  })
+})

package/tests/mongodb/dsl-to-mongo.integration.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+
+import { buildServer } from '../resources/server-to-mongo.js'
+
+describe('Integration E2E: Fastify + normalizeOperators + toMongo', () => {
+  let app
+
+  beforeAll(async () => {
+    app = buildServer()
+    await app.listen({ port: 0 })
+  })
+
+  afterAll(async () => {
+    await app.close()
+  })
+
+  it('GET with simple comparison and AND logic', async () => {
+    const res = await app.inject(
+      '/search?and[0][age][gte]=18&and[1][age][lt]=65&status[eq]=active',
+    )
+    const body = res.json()
+
+    expect(body.dsl).toEqual({
+      and: [{ age: { gte: '18' } }, { age: { lt: '65' } }],
+      status: { eq: 'active' },
+    })
+
+    expect(body.mongo).toEqual({
+      $and: [{ age: { $gte: '18' } }, { age: { $lt: '65' } }],
+      status: { $eq: 'active' },
+    })
+  })
+
+  it('GET with OR and IN', async () => {
+    const res = await app.inject(
+      '/search?or[0][role][eq]=admin&or[1][role][eq]=user&userId[in]=123,456',
+    )
+    const body = res.json()
+
+    expect(body.dsl).toEqual({
+      or: [{ role: { eq: 'admin' } }, { role: { eq: 'user' } }],
+      userId: { in: ['123', '456'] },
+    })
+
+    expect(body.mongo).toEqual({
+      $or: [{ role: { $eq: 'admin' } }, { role: { $eq: 'user' } }],
+      userId: { $in: ['123', '456'] },
+    })
+  })
+
+  it('POST with nested AND/OR, gt/lt, exists', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/search',
+      payload: {
+        where: {
+          and: [
+            { age: { gt: 18, lt: 65 } },
+            {
+              or: [{ status: { eq: 'active' } }, { status: { eq: 'pending' } }],
+            },
+          ],
+          deletedAt: { exists: false },
+        },
+      },
+    })
+
+    const body = res.json()
+
+    expect(body.dsl).toEqual({
+      and: [
+        { age: { gt: 18, lt: 65 } },
+        { or: [{ status: { eq: 'active' } }, { status: { eq: 'pending' } }] },
+      ],
+      deletedAt: { exists: false },
+    })
+
+    expect(body.mongo).toEqual({
+      $and: [
+        { age: { $gt: 18, $lt: 65 } },
+        {
+          $or: [{ status: { $eq: 'active' } }, { status: { $eq: 'pending' } }],
+        },
+      ],
+      deletedAt: { $exists: false },
+    })
+  })
+})

package/tests/mongodb/dsl-to-mongo.unit.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest'
+
+import { toMongo } from '../../src/mongodb/dsl-to-mongo.js'
+
+describe('toMongo', () => {
+  it('should convert plain values to $eq', () => {
+    const input = { status: 'active', role: 'admin' }
+    const output = toMongo(input)
+    expect(output).toEqual({
+      status: { $eq: 'active' },
+      role: { $eq: 'admin' },
+    })
+  })
+
+  it('should convert eq operator to $eq', () => {
+    const input = { status: { eq: 'active' } }
+    const output = toMongo(input)
+    expect(output).toEqual({ status: { $eq: 'active' } })
+  })
+
+  it('should convert in operator to $in', () => {
+    const input = { userId: { in: ['123', '456'] } }
+    const output = toMongo(input)
+    expect(output).toEqual({ userId: { $in: ['123', '456'] } })
+  })
+
+  it('should convert nin operator to $nin', () => {
+    const input = { userId: { nin: ['123'] } }
+    const output = toMongo(input)
+    expect(output).toEqual({ userId: { $nin: ['123'] } })
+  })
+
+  it('should convert comparison operators correctly', () => {
+    const input = {
+      age: { gt: 18, lte: 65 },
+    }
+    const output = toMongo(input)
+    expect(output).toEqual({
+      age: { $gt: 18, $lte: 65 },
+    })
+  })
+
+  it('should handle $or with multiple conditions', () => {
+    const input = {
+      or: [{ status: { eq: 'active' } }, { role: { eq: 'admin' } }],
+    }
+    const output = toMongo(input)
+    expect(output).toEqual({
+      $or: [{ status: { $eq: 'active' } }, { role: { $eq: 'admin' } }],
+    })
+  })
+
+  it('should handle $and with multiple conditions', () => {
+    const input = {
+      and: [{ status: { eq: 'active' } }, { age: { gte: 18 } }],
+    }
+    const output = toMongo(input)
+    expect(output).toEqual({
+      $and: [{ status: { $eq: 'active' } }, { age: { $gte: 18 } }],
+    })
+  })
+
+  it('should handle nested logical operators', () => {
+    const input = {
+      or: [
+        { status: { eq: 'active' } },
+        {
+          and: [{ age: { gte: 18 } }, { age: { lte: 65 } }],
+        },
+      ],
+    }
+    const output = toMongo(input)
+    expect(output).toEqual({
+      $or: [
+        { status: { $eq: 'active' } },
+        {
+          $and: [{ age: { $gte: 18 } }, { age: { $lte: 65 } }],
+        },
+      ],
+    })
+  })
+
+  it('should handle multiple fields mixed with operators', () => {
+    const input = {
+      userId: { in: ['123', '456'] },
+      status: 'active',
+      or: [{ role: { eq: 'admin' } }, { age: { gt: 30 } }],
+    }
+    const output = toMongo(input)
+    expect(output).toEqual({
+      userId: { $in: ['123', '456'] },
+      status: { $eq: 'active' },
+      $or: [{ role: { $eq: 'admin' } }, { age: { $gt: 30 } }],
+    })
+  })
+
+  it('should return empty object if input is empty', () => {
+    expect(toMongo({})).toEqual({})
+  })
+
+  it('should handle null values as $eq null', () => {
+    const input = { deletedAt: null }
+    const output = toMongo(input)
+    expect(output).toEqual({ deletedAt: { $eq: null } })
+  })
+})

package/tests/mongodb/dsl-to-mongo2.unit.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest'
+
+import { toMongo } from '../../src/mongodb/dsl-to-mongo.js'
+
+describe('toMongo - extended operators', () => {
+  it('should support all comparison operators', () => {
+    const input = {
+      age: { eq: 30, ne: 40, gt: 10, gte: 20, lt: 100, lte: 90 },
+      userId: { in: ['u1', 'u2'], nin: ['u3'] },
+    }
+    const output = toMongo(input)
+
+    expect(output).toEqual({
+      age: { $eq: 30, $ne: 40, $gt: 10, $gte: 20, $lt: 100, $lte: 90 },
+      userId: { $in: ['u1', 'u2'], $nin: ['u3'] },
+    })
+  })
+
+  it('should support logical operators', () => {
+    const input = {
+      and: [{ age: { gt: 18 } }, { status: { eq: 'active' } }],
+      or: [{ role: { eq: 'admin' } }, { role: { eq: 'user' } }],
+      nor: [{ country: { eq: 'US' } }],
+    }
+    const output = toMongo(input)
+
+    expect(output).toEqual({
+      $and: [{ age: { $gt: 18 } }, { status: { $eq: 'active' } }],
+      $or: [{ role: { $eq: 'admin' } }, { role: { $eq: 'user' } }],
+      $nor: [{ country: { $eq: 'US' } }],
+    })
+  })
+
+  it('should support element operators', () => {
+    const input = {
+      deletedAt: { exists: false },
+      status: { type: 'string' },
+    }
+    const output = toMongo(input)
+
+    expect(output).toEqual({
+      deletedAt: { $exists: false },
+      status: { $type: 'string' },
+    })
+  })
+
+  it('should support evaluation operators', () => {
+    const input = {
+      name: { regex: '^haim', options: 'i' },
+      score: { mod: [4, 0] },
+      description: { text: 'fast search' },
+    }
+    const output = toMongo(input)
+
+    expect(output).toEqual({
+      name: { $regex: '^haim', $options: 'i' },
+      score: { $mod: [4, 0] },
+      description: { $text: 'fast search' },
+    })
+  })
+
+  it('should support array operators', () => {
+    const input = {
+      tags: { all: ['tech', 'ai'], size: 3 },
+      scores: { elemMatch: { gt: 90 } },
+    }
+    const output = toMongo(input)
+
+    expect(output).toEqual({
+      tags: { $all: ['tech', 'ai'], $size: 3 },
+      scores: { $elemMatch: { $gt: 90 } },
+    })
+  })
+
+  it('should not transform unknown operators (false positive check)', () => {
+    const input = {
+      age: { weirdOp: 123 },
+    }
+    const output = toMongo(input)
+
+    expect(output).toEqual({
+      age: { $weirdOp: 123 },
+    })
+  })
+
+  it('should not wrap already Mongo operators with $$ (false positive)', () => {
+    const input = {
+      age: { $gte: 18 },
+    }
+    const output = toMongo(input)
+
+    expect(output).toEqual({
+      age: { $gte: 18 },
+    })
+  })
+
+  it('should handle nested structures with mix of operators', () => {
+    const input = {
+      or: [
+        { and: [{ age: { gte: 18 } }, { age: { lte: 65 } }] },
+        { status: { ne: 'banned' } },
+      ],
+      tags: { all: ['mongo', 'node'] },
+    }
+    const output = toMongo(input)
+
+    expect(output).toEqual({
+      $or: [
+        { $and: [{ age: { $gte: 18 } }, { age: { $lte: 65 } }] },
+        { status: { $ne: 'banned' } },
+      ],
+      tags: { $all: ['mongo', 'node'] },
+    })
+  })
+})

package/tests/resources/server-to-mongo.js

@@ -0,0 +1,27 @@
+import qs from 'qs'
+import Fastify from 'fastify'
+
+import { toMongo } from '../../src/mongodb/dsl-to-mongo.js'
+import { normalizeOperators } from '../../src/core/normalize-array-operators.js'
+
+export function buildServer() {
+  const app = Fastify({
+    querystringParser: (str) => qs.parse(str, { comma: true, depth: 10 }),
+  })
+
+  // GET /search?...
+  app.get('/search', async (req) => {
+    const dsl = normalizeOperators(req.query)
+    const mongo = toMongo(dsl)
+    return { dsl, mongo }
+  })
+
+  // POST /search with body { where: {...} }
+  app.post('/search', async (req) => {
+    const dsl = normalizeOperators(req.body?.where || {})
+    const mongo = toMongo(dsl)
+    return { dsl, mongo }
+  })
+
+  return app
+}

package/tests/resources/server.js

@@ -0,0 +1,23 @@
+import Fastify from 'fastify'
+import qs from 'qs'
+import { normalizeOperators } from '../../src/core/normalize-array-operators.js'
+
+export function buildServer() {
+  const app = Fastify({
+    querystringParser: (str) => qs.parse(str, { comma: true, depth: 10 }),
+  })
+
+  // GET /users
+  app.get('/users', async (req) => {
+    const dsl = normalizeOperators(req.query)
+    return { dsl }
+  })
+
+  // POST /users/search
+  app.post('/users/search', async (req) => {
+    const dsl = normalizeOperators(req.body?.where || {})
+    return { dsl }
+  })
+
+  return app
+}

package/types/core/index.d.ts

@@ -5,3 +5,5 @@ export * from "./normalize-min-max.js";
 export * from "./normalize-to-array.js";
 export * from "./combine-unique-arrays.js";
 export * from "./normalize-phone-number.js";
+export * from "./normalize-array-operators.js";
+export * from "./normalize-premitives-types-or-default.js";

package/types/core/normalize-array-operators.d.ts

@@ -0,0 +1 @@
+export function normalizeOperators(obj: any): any;

package/types/core/normalize-premitives-types-or-default.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Normalize Utilities
+ *
+ * Small helpers to guarantee stable, predictable values from user/config inputs.
+ * When an incoming value is missing, malformed, or in a different-but-supported
+ * representation (e.g., number/boolean as string), these utilities either accept
+ * it (after safe normalization) or return a default you control.
+ *
+ * Design highlights:
+ * - Keep call sites compact and intention-revealing.
+ * - Be strict for strings (no implicit type coercion).
+ * - Be permissive for number/boolean when the input is a string in an accepted form.
+ * - Fast, side-effect free, no deep cloning — values are returned by reference when valid.
+ */
+/**
+ * Generic predicate-based normalization.
+ *
+ * Purpose:
+ *  Ensure a value conforms to a caller-provided predicate; otherwise return a provided default.
+ *  Useful when you need a single reusable pattern for custom shapes or policies
+ *  (e.g., "must be a non-empty array of strings", "must be a plain object", etc.).
+ *
+ * Behavior:
+ *  - Calls `isValid(value)`.
+ *  - If the predicate returns true → returns `value` (as-is).
+ *  - Otherwise → returns `defaultValue` (as-is).
+ *
+ * Performance & Safety:
+ *  - O(1) aside from your predicate cost.
+ *  - No cloning or sanitization is performed.
+ *  - Ensure `isValid` is pure and fast; avoid throwing inside it.
+ *
+ * @template T
+ * @param {any} value
+ *   Candidate input to validate.
+ * @param {(v:any)=>boolean} isValid
+ *   Validation predicate. Return true iff the input is acceptable.
+ * @param {T} defaultValue
+ *   Fallback to return when `value` fails validation.
+ * @returns {T}
+ *   The original `value` when valid; otherwise `defaultValue`.
+ *
+ * @example
+ * // Ensure a finite number
+ * normalizeOrDefault(5, v => typeof v === 'number' && Number.isFinite(v), 0) // → 5
+ * normalizeOrDefault('x', v => typeof v === 'number', 0)                     // → 0
+ *
+ * @example
+ * // Ensure an object (non-null, non-array)
+ * const cfg = normalizeOrDefault(
+ *   maybeCfg,
+ *   v => v && typeof v === 'object' && !Array.isArray(v),
+ *   {}
+ * )
+ */
+export function normalizeOrDefault<T>(value: any, isValid: (v: any) => boolean, defaultValue: T): T;
+/**
+ * Normalize a value to a non-empty, trimmed string; otherwise return a default (also trimmed).
+ *
+ * Purpose:
+ *  Guarantee that downstream code receives a usable, non-empty string
+ *  without performing implicit type coercion.
+ *
+ * Acceptance Criteria:
+ *  - Accept only actual strings whose `trim()` length is > 0.
+ *  - Return `value.trim()` when valid.
+ *  - Otherwise return `defaultValue.trim()`.
+ *
+ * Why strict for strings?
+ *  - Silent coercion from non-strings to string can hide bugs.
+ *  - If you need to stringify other types, do it explicitly at the call site.
+ *
+ * Edge Cases:
+ *  - If `defaultValue` is empty or whitespace-only, the function returns an empty string.
+ *    Prefer providing a meaningful, non-empty default for clarity.
+ *
+ * @param {any} value
+ *   Candidate to normalize (must be a string to be accepted).
+ * @param {string} defaultValue
+ *   Fallback used when `value` is not a non-empty string. Will be `trim()`ed.
+ * @returns {string}
+ *   A trimmed non-empty string when `value` is valid; otherwise `defaultValue.trim()`.
+ *
+ * @example
+ * normalizeStringOrDefault('  user-roles-management:edit  ', 'fallback')
+ * // → 'user-roles-management:edit'
+ *
+ * @example
+ * normalizeStringOrDefault('', 'user-roles-management:edit')
+ * // → 'user-roles-management:edit'
+ *
+ * @example
+ * normalizeStringOrDefault(42, 'user-roles-management:edit')
+ * // → 'user-roles-management:edit'
+ */
+export function normalizeStringOrDefault(value: any, defaultValue: string): string;
+/**
+ * Normalize a value to a valid number (with safe string coercion); otherwise return a default.
+ *
+ * Purpose:
+ *  Accept numeric inputs that may arrive as strings (e.g., from env vars or config files)
+ *  while keeping semantics explicit and predictable.
+ *
+ * Acceptance Criteria:
+ *  - Accepts finite numbers (`typeof value === 'number' && Number.isFinite(value)`).
+ *  - Accepts strings that become a finite number via `Number(trimmed)`.
+ *    Examples: "42", "  3.14 ", "1e3", "-7", "0x10" (JS Number semantics).
+ *  - Rejects non-numeric strings (e.g., "", "   ", "abc") and non-number types.
+ *  - Returns `defaultValue` when not acceptable.
+ *
+ * Parsing Semantics:
+ *  - Uses `Number(s)` which requires the whole trimmed string to be numeric.
+ *  - Honors JavaScript numeric literal rules (including hex and scientific notation).
+ *  - If you want base-10 only or looser parsing, do it explicitly before calling.
+ *
+ * @param {any} value
+ *   Candidate to normalize (number or numeric string).
+ * @param {number} defaultValue
+ *   Fallback used when `value` is neither a finite number nor a numeric string.
+ * @returns {number}
+ *   A finite number derived from `value`, or `defaultValue`.
+ *
+ * @example
+ * normalizeNumberOrDefault(42, 0)       // → 42
+ * normalizeNumberOrDefault(' 3.14 ', 0) // → 3.14
+ * normalizeNumberOrDefault('1e3', 0)    // → 1000
+ * normalizeNumberOrDefault('-7', 0)     // → -7
+ *
+ * @example
+ * normalizeNumberOrDefault('abc', 7)    // → 7
+ * normalizeNumberOrDefault(NaN, 7)      // → 7
+ * normalizeNumberOrDefault({}, 7)       // → 7
+ */
+export function normalizeNumberOrDefault(value: any, defaultValue: number): number;
+/**
+ * Normalize a value to a boolean (with "true"/"false" string support); otherwise return a default.
+ *
+ * Purpose:
+ *  Stabilize feature flags and binary config values that might be provided as either booleans
+ *  or as canonical strings.
+ *
+ * Acceptance Criteria:
+ *  - Accepts actual booleans (`true` / `false`) → returned as-is.
+ *  - Accepts strings equal to "true" or "false" (case-insensitive, trimmed).
+ *    "true"  → true
+ *    "false" → false
+ *  - Rejects other strings ("yes", "1", "0", etc.) and other types → returns `defaultValue`.
+ *
+ * Rationale:
+ *  - Limiting string forms to the canonical words avoids accidental truthiness/falseyness.
+ *  - If you need to accept "1"/"0" or other variants, coerce at the call site so intent is explicit.
+ *
+ * @param {any} value
+ *   Candidate to normalize (boolean or "true"/"false" string).
+ * @param {boolean} defaultValue
+ *   Fallback used when `value` is neither a boolean nor an accepted string form.
+ * @returns {boolean}
+ *   A boolean derived from `value`, or `defaultValue`.
+ *
+ * @example
+ * normalizeBooleanOrDefault(true,  false) // → true
+ * normalizeBooleanOrDefault(false, true)  // → false
+ *
+ * @example
+ * normalizeBooleanOrDefault('true',  false) // → true
+ * normalizeBooleanOrDefault(' FALSE ', true) // → false
+ *
+ * @example
+ * normalizeBooleanOrDefault('yes',  false) // → false  (rejected → default)
+ * normalizeBooleanOrDefault(1,      true)  // → true   (rejected → default)
+ */
+export function normalizeBooleanOrDefault(value: any, defaultValue: boolean): boolean;

package/types/mongodb/dsl-to-mongo.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert a normalized query object into a MongoDB query object.
+ *
+ * @param {Record<string, any>} query - normalized DSL query
+ * @returns {Record<string, any>} - MongoDB query object
+ */
+export function toMongo(query?: Record<string, any>): Record<string, any>;

package/types/mongodb/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./connect.js";
+export * from "./dsl-to-mongo.js";
 export * from "./initialize-mongodb.js";
 export * from "./validate-mongo-uri.js";