@hy_ong/zod-kit 0.2.2 → 0.2.4

package/src/validators/common/one-of.ts

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview OneOf validator for Zod Kit
+ *
+ * Provides single-select validation that restricts input to a predefined set of allowed values,
+ * with support for case-insensitive matching, default values, and transformation.
+ *
+ * @author Ong Hoe Yuan
+ * @version 0.2.2
+ */
+
+import { z, ZodType } from "zod"
+import { t } from "../../i18n"
+import { getLocale, type Locale } from "../../config"
+
+/**
+ * Type definition for oneOf validation error messages
+ *
+ * @interface OneOfMessages
+ * @property {string} [required] - Message when field is required but empty
+ * @property {string} [invalid] - Message when value is not in the allowed list
+ */
+export type OneOfMessages = {
+  required?: string
+  invalid?: string
+}
+
+/**
+ * Configuration options for oneOf validation
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @template T - The type of allowed values
+ *
+ * @interface OneOfOptions
+ * @property {T[]} values - Array of allowed values
+ * @property {T | null} [defaultValue] - Default value when input is empty
+ * @property {boolean} [caseSensitive=true] - Whether string matching is case-sensitive
+ * @property {Function} [transform] - Custom transformation function applied after validation
+ * @property {Record<Locale, OneOfMessages>} [i18n] - Custom error messages for different locales
+ */
+export type OneOfOptions<IsRequired extends boolean = true, V extends readonly (string | number)[] = readonly (string | number)[]> = {
+  values: V
+  defaultValue?: IsRequired extends true ? V[number] : V[number] | null
+  caseSensitive?: boolean
+  transform?: (value: V[number]) => V[number]
+  i18n?: Partial<Record<Locale, Partial<OneOfMessages>>>
+}
+
+/**
+ * Type alias for oneOf validation schema based on required flag
+ *
+ * @template IsRequired - Whether the field is required
+ * @template T - The type of allowed values
+ */
+export type OneOfSchema<IsRequired extends boolean, V extends readonly (string | number)[]> = IsRequired extends true ? ZodType<V[number]> : ZodType<V[number] | null>
+
+/**
+ * Creates a Zod schema for single-select validation that restricts values to a predefined set
+ *
+ * @template IsRequired - Whether the field is required (affects return type)
+ * @template T - The type of allowed values (string | number)
+ * @param {IsRequired} [required=false] - Whether the field is required
+ * @param {OneOfOptions<IsRequired, T>} options - Configuration options (values is required)
+ * @returns {OneOfSchema<IsRequired, T>} Zod schema for oneOf validation
+ *
+ * @example
+ * ```typescript
+ * // Basic single-select validation (optional by default)
+ * const roleSchema = oneOf(false, { values: ["admin", "editor", "viewer"] })
+ * roleSchema.parse("admin") // ✓ "admin"
+ * roleSchema.parse(null)    // ✓ null
+ *
+ * // Required
+ * const statusSchema = oneOf(true, { values: ["active", "inactive", "pending"] })
+ * statusSchema.parse("active") // ✓ "active"
+ * statusSchema.parse(null)     // ✗ Required
+ * statusSchema.parse("banned") // ✗ Invalid
+ *
+ * // Numeric values
+ * const prioritySchema = oneOf(true, { values: [1, 2, 3, 4, 5] })
+ * prioritySchema.parse(3)  // ✓ 3
+ * prioritySchema.parse(10) // ✗ Invalid
+ *
+ * // Case-insensitive matching
+ * const colorSchema = oneOf(true, {
+ *   values: ["red", "green", "blue"],
+ *   caseSensitive: false
+ * })
+ * colorSchema.parse("RED")   // ✓ "red" (normalized to match original)
+ * colorSchema.parse("Green") // ✓ "green"
+ *
+ * // With default value
+ * const tierSchema = oneOf(false, {
+ *   values: ["free", "pro", "enterprise"],
+ *   defaultValue: "free"
+ * })
+ * tierSchema.parse(null) // ✓ "free"
+ *
+ * // With transform
+ * const sizeSchema = oneOf(true, {
+ *   values: ["s", "m", "l", "xl"],
+ *   transform: (val) => val.toUpperCase() as any
+ * })
+ * sizeSchema.parse("m") // ✓ "M"
+ * ```
+ */
+export function oneOf<IsRequired extends boolean = false, const V extends readonly (string | number)[] = readonly (string | number)[]>(
+  required?: IsRequired,
+  options?: Omit<OneOfOptions<IsRequired, V>, "required">,
+): OneOfSchema<IsRequired, V> {
+  const { values = [] as unknown as V, defaultValue = null, caseSensitive = true, transform, i18n } = options ?? {}
+
+  const isRequired = required ?? (false as IsRequired)
+
+  const getMessage = (key: keyof OneOfMessages, params?: Record<string, any>) => {
+    if (i18n) {
+      const currentLocale = getLocale()
+      const customMessages = i18n[currentLocale]
+      if (customMessages && customMessages[key]) {
+        const template = customMessages[key]!
+        return template.replace(/\$\{(\w+)}/g, (_, k) => params?.[k] ?? "")
+      }
+    }
+    return t(`common.oneOf.${key}`, params)
+  }
+
+  const preprocessFn = (val: unknown) => {
+    if (val === "" || val === null || val === undefined) {
+      return defaultValue
+    }
+
+    // Coerce number strings to numbers when values contains numbers
+    const hasNumbers = values.some((v) => typeof v === "number")
+    if (hasNumbers && typeof val === "string" && !isNaN(Number(val)) && val.trim() !== "") {
+      const numVal = Number(val)
+      if ((values as readonly number[]).includes(numVal)) return numVal
+    }
+
+    // Case-insensitive normalization for string values
+    if (!caseSensitive && typeof val === "string") {
+      const match = values.find((v) => typeof v === "string" && v.toLowerCase() === val.toLowerCase())
+      if (match !== undefined) return match
+      return val
+    }
+
+    return val
+  }
+
+  const baseSchema = z.preprocess(preprocessFn, z.any())
+
+  const schema = baseSchema
+    .superRefine((val, ctx) => {
+      if (val === null) {
+        if (isRequired) {
+          ctx.addIssue({ code: "custom", message: getMessage("required") })
+        }
+        return
+      }
+
+      if (!(values as readonly (string | number)[]).includes(val as V[number])) {
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("invalid", { values: values.join(", ") }),
+        })
+      }
+    })
+    .transform((val) => {
+      if (val === null || !transform) return val
+      return transform(val as V[number])
+    })
+
+  return schema as unknown as OneOfSchema<IsRequired, V>
+}

package/tests/common/many-of.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import { manyOf, setLocale, Locale } from "../../src"
+
+const locales = [
+  {
+    locale: "en-US",
+    messages: {
+      required: "Required",
+      invalid: "Must be from: react, vue, angular, svelte",
+      minSelect: "Must select at least 2 item(s)",
+      maxSelect: "Must select at most 3 item(s)",
+      duplicate: "Duplicate values are not allowed",
+    },
+  },
+  {
+    locale: "zh-TW",
+    messages: {
+      required: "必填",
+      invalid: "必須為以下值之一：react, vue, angular, svelte",
+      minSelect: "至少需選擇 2 項",
+      maxSelect: "最多只能選擇 3 項",
+      duplicate: "不允許重複的值",
+    },
+  },
+] as const
+
+const frameworks = ["react", "vue", "angular", "svelte"] as const
+
+describe.each(locales)("manyOf(true) locale: $locale", ({ locale, messages }) => {
+  beforeEach(() => setLocale(locale as Locale))
+
+  describe("basic functionality", () => {
+    it("should accept valid arrays", () => {
+      const schema = manyOf(true, { values: [...frameworks] })
+      expect(schema.parse(["react"])).toEqual(["react"])
+      expect(schema.parse(["react", "vue"])).toEqual(["react", "vue"])
+      expect(schema.parse(["react", "vue", "angular", "svelte"])).toEqual(["react", "vue", "angular", "svelte"])
+    })
+
+    it("should reject invalid values in array", () => {
+      const schema = manyOf(true, { values: [...frameworks] })
+      expect(() => schema.parse(["react", "jquery"])).toThrow(messages.invalid)
+    })
+
+    it("should fail with empty when required", () => {
+      const schema = manyOf(true, { values: [...frameworks] })
+      expect(() => schema.parse(null)).toThrow(messages.required)
+      expect(() => schema.parse(undefined)).toThrow(messages.required)
+      expect(() => schema.parse("")).toThrow(messages.required)
+    })
+
+    it("should pass with null when not required", () => {
+      const schema = manyOf(false, { values: [...frameworks] })
+      expect(schema.parse(null)).toBe(null)
+      expect(schema.parse(undefined)).toBe(null)
+      expect(schema.parse("")).toBe(null)
+    })
+
+    it("should wrap single value in array", () => {
+      const schema = manyOf(true, { values: [...frameworks] })
+      expect(schema.parse("react")).toEqual(["react"])
+    })
+  })
+
+  describe("min/max selection", () => {
+    it("should enforce minimum selections", () => {
+      const schema = manyOf(true, { values: [...frameworks], min: 2 })
+      expect(() => schema.parse(["react"])).toThrow(messages.minSelect)
+      expect(schema.parse(["react", "vue"])).toEqual(["react", "vue"])
+    })
+
+    it("should enforce maximum selections", () => {
+      const schema = manyOf(true, { values: [...frameworks], max: 3 })
+      expect(() => schema.parse(["react", "vue", "angular", "svelte"])).toThrow(messages.maxSelect)
+      expect(schema.parse(["react", "vue", "angular"])).toEqual(["react", "vue", "angular"])
+    })
+
+    it("should enforce both min and max", () => {
+      const schema = manyOf(true, { values: [...frameworks], min: 2, max: 3 })
+      expect(() => schema.parse(["react"])).toThrow(messages.minSelect)
+      expect(() => schema.parse(["react", "vue", "angular", "svelte"])).toThrow(messages.maxSelect)
+      expect(schema.parse(["react", "vue"])).toEqual(["react", "vue"])
+      expect(schema.parse(["react", "vue", "angular"])).toEqual(["react", "vue", "angular"])
+    })
+  })
+
+  describe("duplicate handling", () => {
+    it("should reject duplicates by default", () => {
+      const schema = manyOf(true, { values: [...frameworks] })
+      expect(() => schema.parse(["react", "react"])).toThrow(messages.duplicate)
+    })
+
+    it("should allow duplicates when configured", () => {
+      const schema = manyOf(true, { values: [...frameworks], allowDuplicates: true })
+      expect(schema.parse(["react", "react"])).toEqual(["react", "react"])
+    })
+  })
+
+  describe("numeric values", () => {
+    it("should accept valid numeric arrays", () => {
+      const schema = manyOf(true, { values: [1, 2, 3, 4, 5] })
+      expect(schema.parse([1, 3, 5])).toEqual([1, 3, 5])
+    })
+
+    it("should reject invalid numeric values", () => {
+      const schema = manyOf(true, { values: [1, 2, 3] })
+      expect(() => schema.parse([1, 10])).toThrow()
+    })
+
+    it("should coerce number strings", () => {
+      const schema = manyOf(true, { values: [1, 2, 3] })
+      expect(schema.parse(["1", "2"])).toEqual([1, 2])
+    })
+  })
+
+  describe("case sensitivity", () => {
+    it("should be case sensitive by default", () => {
+      const schema = manyOf(true, { values: [...frameworks] })
+      expect(() => schema.parse(["React"])).toThrow()
+    })
+
+    it("should match case-insensitively when configured", () => {
+      const schema = manyOf(true, { values: [...frameworks], caseSensitive: false })
+      expect(schema.parse(["REACT", "Vue"])).toEqual(["react", "vue"])
+    })
+  })
+
+  describe("default value", () => {
+    it("should use default value when input is empty", () => {
+      const schema = manyOf(false, { values: [...frameworks], defaultValue: ["react"] })
+      expect(schema.parse(null)).toEqual(["react"])
+      expect(schema.parse(undefined)).toEqual(["react"])
+      expect(schema.parse("")).toEqual(["react"])
+    })
+
+    it("should use provided value over default", () => {
+      const schema = manyOf(false, { values: [...frameworks], defaultValue: ["react"] })
+      expect(schema.parse(["vue", "angular"])).toEqual(["vue", "angular"])
+    })
+  })
+
+  describe("transform", () => {
+    it("should apply transform to valid arrays", () => {
+      const schema = manyOf(true, {
+        values: [...frameworks],
+        transform: (vals) => vals.map((v) => v.toUpperCase()) as any,
+      })
+      expect(schema.parse(["react", "vue"])).toEqual(["REACT", "VUE"])
+    })
+  })
+
+  describe("custom i18n", () => {
+    it("should use custom messages when provided", () => {
+      const schema = manyOf(true, {
+        values: [...frameworks],
+        i18n: {
+          "en-US": { required: "Pick frameworks!", duplicate: "No repeats!" },
+          "zh-TW": { required: "請選擇框架！", duplicate: "不能重複！" },
+        },
+      })
+
+      if (locale === "en-US") {
+        expect(() => schema.parse(null)).toThrow("Pick frameworks!")
+        expect(() => schema.parse(["react", "react"])).toThrow("No repeats!")
+      } else {
+        expect(() => schema.parse(null)).toThrow("請選擇框架！")
+        expect(() => schema.parse(["react", "react"])).toThrow("不能重複！")
+      }
+    })
+  })
+
+  describe("complex scenarios", () => {
+    it("should work with all options combined", () => {
+      const schema = manyOf(true, {
+        values: [...frameworks],
+        min: 1,
+        max: 3,
+        caseSensitive: false,
+      })
+
+      expect(schema.parse(["REACT", "Vue"])).toEqual(["react", "vue"])
+      expect(() => schema.parse([])).toThrow() // min 1
+      expect(() => schema.parse(["react", "vue", "angular", "svelte"])).toThrow() // max 3
+      expect(() => schema.parse(["jquery"])).toThrow() // invalid
+    })
+
+    it("should handle empty array when required with no min", () => {
+      const schema = manyOf(true, { values: [...frameworks] })
+      // Empty array is a valid array, just has 0 items — not null
+      expect(schema.parse([])).toEqual([])
+    })
+
+    it("should handle empty array with min constraint", () => {
+      const schema = manyOf(true, { values: [...frameworks], min: 1 })
+      expect(() => schema.parse([])).toThrow()
+    })
+  })
+})

package/tests/common/one-of.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import { oneOf, setLocale, Locale } from "../../src"
+
+const locales = [
+  {
+    locale: "en-US",
+    messages: {
+      required: "Required",
+      invalid: "Must be one of: admin, editor, viewer",
+    },
+  },
+  {
+    locale: "zh-TW",
+    messages: {
+      required: "必填",
+      invalid: "必須為以下其中一個值：admin, editor, viewer",
+    },
+  },
+] as const
+
+const stringValues = ["admin", "editor", "viewer"] as const
+const numericValues = [1, 2, 3, 4, 5] as const
+
+describe.each(locales)("oneOf(true) locale: $locale", ({ locale, messages }) => {
+  beforeEach(() => setLocale(locale as Locale))
+
+  describe("basic functionality", () => {
+    it("should accept valid values", () => {
+      const schema = oneOf(true, { values: [...stringValues] })
+      expect(schema.parse("admin")).toBe("admin")
+      expect(schema.parse("editor")).toBe("editor")
+      expect(schema.parse("viewer")).toBe("viewer")
+    })
+
+    it("should reject invalid values", () => {
+      const schema = oneOf(true, { values: [...stringValues] })
+      expect(() => schema.parse("hacker")).toThrow(messages.invalid)
+      expect(() => schema.parse("superadmin")).toThrow(messages.invalid)
+    })
+
+    it("should fail with empty when required", () => {
+      const schema = oneOf(true, { values: [...stringValues] })
+      expect(() => schema.parse("")).toThrow(messages.required)
+      expect(() => schema.parse(null)).toThrow(messages.required)
+      expect(() => schema.parse(undefined)).toThrow(messages.required)
+    })
+
+    it("should pass with null when not required", () => {
+      const schema = oneOf(false, { values: [...stringValues] })
+      expect(schema.parse("")).toBe(null)
+      expect(schema.parse(null)).toBe(null)
+      expect(schema.parse(undefined)).toBe(null)
+    })
+  })
+
+  describe("numeric values", () => {
+    it("should accept valid numeric values", () => {
+      const schema = oneOf(true, { values: [...numericValues] })
+      expect(schema.parse(1)).toBe(1)
+      expect(schema.parse(3)).toBe(3)
+      expect(schema.parse(5)).toBe(5)
+    })
+
+    it("should reject invalid numeric values", () => {
+      const schema = oneOf(true, { values: [...numericValues] })
+      expect(() => schema.parse(10)).toThrow()
+      expect(() => schema.parse(0)).toThrow()
+    })
+
+    it("should coerce number strings to numbers", () => {
+      const schema = oneOf(true, { values: [...numericValues] })
+      expect(schema.parse("3")).toBe(3)
+      expect(schema.parse("5")).toBe(5)
+    })
+  })
+
+  describe("case sensitivity", () => {
+    it("should be case sensitive by default", () => {
+      const schema = oneOf(true, { values: [...stringValues] })
+      expect(() => schema.parse("Admin")).toThrow()
+      expect(() => schema.parse("EDITOR")).toThrow()
+    })
+
+    it("should match case-insensitively when configured", () => {
+      const schema = oneOf(true, { values: [...stringValues], caseSensitive: false })
+      expect(schema.parse("Admin")).toBe("admin")
+      expect(schema.parse("EDITOR")).toBe("editor")
+      expect(schema.parse("VIEWER")).toBe("viewer")
+    })
+  })
+
+  describe("default value", () => {
+    it("should use default value when input is empty", () => {
+      const schema = oneOf(false, { values: [...stringValues], defaultValue: "viewer" })
+      expect(schema.parse("")).toBe("viewer")
+      expect(schema.parse(null)).toBe("viewer")
+      expect(schema.parse(undefined)).toBe("viewer")
+    })
+
+    it("should use provided value over default", () => {
+      const schema = oneOf(false, { values: [...stringValues], defaultValue: "viewer" })
+      expect(schema.parse("admin")).toBe("admin")
+    })
+  })
+
+  describe("transform", () => {
+    it("should apply transform to valid values", () => {
+      const schema = oneOf(true, {
+        values: [...stringValues],
+        transform: (val) => val.toUpperCase() as any,
+      })
+      expect(schema.parse("admin")).toBe("ADMIN")
+      expect(schema.parse("editor")).toBe("EDITOR")
+    })
+  })
+
+  describe("custom i18n", () => {
+    it("should use custom messages when provided", () => {
+      const schema = oneOf(true, {
+        values: [...stringValues],
+        i18n: {
+          "en-US": { required: "Pick a role!", invalid: "Bad role!" },
+          "zh-TW": { required: "請選擇角色！", invalid: "無效角色！" },
+        },
+      })
+
+      if (locale === "en-US") {
+        expect(() => schema.parse("")).toThrow("Pick a role!")
+        expect(() => schema.parse("hacker")).toThrow("Bad role!")
+      } else {
+        expect(() => schema.parse("")).toThrow("請選擇角色！")
+        expect(() => schema.parse("hacker")).toThrow("無效角色！")
+      }
+    })
+  })
+})

package/tsup.config.ts

@@ -9,7 +9,9 @@ export default defineConfig({
     "common/email": "src/validators/common/email.ts",
     "common/file": "src/validators/common/file.ts",
     "common/id": "src/validators/common/id.ts",
+    "common/many-of": "src/validators/common/many-of.ts",
     "common/number": "src/validators/common/number.ts",
+    "common/one-of": "src/validators/common/one-of.ts",
     "common/password": "src/validators/common/password.ts",
     "common/text": "src/validators/common/text.ts",
     "common/time": "src/validators/common/time.ts",