@hy_ong/zod-kit 0.0.1

package/.prettierrc.json

@@ -0,0 +1,9 @@
+{
+  "semi": false,
+  "singleQuote": false,
+  "printWidth": 200,
+  "tabWidth": 2,
+  "jsxSingleQuote": false,
+  "trailingComma": "es5",
+  "plugins": []
+}

package/README.md

@@ -0,0 +1,183 @@
+# Zod Kit
+
+A TypeScript library that provides common validation schemas built on top of [Zod](https://github.com/colinhacks/zod) with internationalization support.
+
+## Features
+
+- 🔍 Pre-built validation schemas for common data types
+- 🌐 Internationalization support (English and Traditional Chinese)
+- 📝 TypeScript-first with full type safety
+- ⚡ Built on top of Zod for robust validation
+- 🎯 Configurable validation options
+
+## Installation
+
+```bash
+npm install zod-kit 
+```
+
+## Quick Start
+
+```typescript
+import { email, password, text, number } from 'zod-kit'
+
+// Email validation
+const emailSchema = email({ label: 'Email' })
+emailSchema.parse('user@example.com') // ✅
+
+// Password validation with requirements
+const passwordSchema = password({
+  label: 'Password',
+  min: 8,
+  uppercase: true,
+  lowercase: true,
+  digits: true,
+  special: true
+})
+
+// Text validation
+const nameSchema = text({
+  label: 'Name',
+  min: 2,
+  max: 50
+})
+```
+
+## Available Schemas
+
+### Email
+
+```typescript
+email({
+  label: string,           // Field label for error messages
+  required? : boolean,      // Default: true
+  domain? : string,         // Restrict to specific domain
+  min? : number,           // Minimum length
+  max? : number,           // Maximum length
+  includes? : string       // Must include substring
+})
+```
+
+### Password
+
+```typescript
+password({
+  label: string,          // Field label for error messages
+  required? : boolean,     // Default: true
+  min? : number,          // Minimum length
+  max? : number,          // Maximum length
+  uppercase? : boolean,   // Require uppercase letters
+  lowercase? : boolean,   // Require lowercase letters
+  digits? : boolean,      // Require digits
+  special? : boolean      // Require special characters
+})
+```
+
+### Text
+
+```typescript
+text({
+  label: string,          // Field label for error messages
+  required? : boolean,     // Default: true
+  min? : number,          // Minimum length
+  max? : number,          // Maximum length
+  includes? : string,     // Must include substring
+  regex? : RegExp         // Custom regex pattern
+})
+```
+
+### Number
+
+```typescript
+number({
+  label: string,          // Field label for error messages
+  required? : boolean,     // Default: true
+  min? : number,          // Minimum value
+  max? : number,          // Maximum value
+  positive? : boolean,    // Must be positive
+  negative? : boolean,    // Must be negative
+  finite? : boolean       // Must be finite
+})
+```
+
+### Integer
+
+```typescript
+integer({
+  label: string,          // Field label for error messages
+  required? : boolean,     // Default: true
+  min? : number,          // Minimum value
+  max? : number,          // Maximum value
+  positive? : boolean,    // Must be positive
+  negative? : boolean     // Must be negative
+})
+```
+
+### URL
+
+```typescript
+url({
+  label: string,          // Field label for error messages
+  required? : boolean,     // Default: true
+  protocol? : string[]     // Allowed protocols (e.g., ['https'])
+})
+```
+
+### Boolean
+
+```typescript
+boolean({
+  label: string,          // Field label for error messages
+  required? : boolean      // Default: true
+})
+```
+
+## Internationalization
+
+Set the locale for error messages:
+
+```typescript
+import { setLocale } from 'zod-kit'
+
+// Set to English (default is Traditional Chinese)
+setLocale('en')
+
+// Set to Traditional Chinese
+setLocale('zh-TW')
+```
+
+## Optional Fields
+
+All schemas support optional validation by setting `required: false`:
+
+```typescript
+const optionalEmail = email({
+  label: 'Email',
+  required: false
+})
+
+optionalEmail.parse(null) // ✅ null
+optionalEmail.parse('') // ✅ null
+optionalEmail.parse('user@example.com') // ✅ 'user@example.com'
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build the package
+npm run build
+```
+
+## License
+
+ISC
+
+## Author
+
+Ong Hoe Yuan

package/eslint.config.mjs

@@ -0,0 +1,10 @@
+// @ts-check
+
+import eslint from "@eslint/js"
+import tseslint from "typescript-eslint"
+
+export default tseslint.config(eslint.configs.recommended, tseslint.configs.recommended, {
+  rules: {
+    "@typescript-eslint/no-explicit-any": "off",
+  },
+})

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hy_ong/zod-kit",
+  "version": "0.0.1",
+  "description": "Zod Kit",
+  "keywords": [
+    "zod",
+    "kit",
+    "zod-kit"
+  ],
+  "homepage": "https://github.com/hy-ong/zod-kit#readme",
+  "bugs": {
+    "url": "https://github.com/hy-ong/zod-kit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hy-ong/zod-kit.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "ISC",
+  "author": "Ong Hoe Yuan",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "dayjs": "^1.11.13",
+    "zod": "^4.0.14"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.32.0",
+    "eslint": "^9.32.0",
+    "prettier": "^3.6.2",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.38.0",
+    "vitest": "^3.2.4"
+  }
+}

package/src/common/boolean.ts

@@ -0,0 +1,37 @@
+import { z, ZodBoolean, ZodNullable, ZodType } from "zod"
+import { t } from "../i18n"
+
+export type BooleanOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  label: string
+  defaultValue?: IsRequired extends true ? boolean : boolean | null
+  shouldBe?: boolean
+}
+
+export type BooleanSchema<IsRequired extends boolean> = IsRequired extends true ? ZodBoolean : ZodNullable<ZodBoolean>
+
+export function boolean<IsRequired extends boolean = true>(options?: BooleanOptions<IsRequired>): BooleanSchema<IsRequired> {
+  const { required = true, label, defaultValue = null, shouldBe } = options ?? {}
+
+  let result: ZodType = z.preprocess(
+    (val) => {
+      if (val === "" || val === undefined || val === null) return defaultValue
+      if (val === "true" || val === 1 || val === "1") return true
+      if (val === "false" || val === 0 || val === "0") return false
+      return val
+    },
+    z.union([z.literal(true), z.literal(false), z.literal(null)])
+  )
+
+  if (required && defaultValue === null) {
+    result = result.refine((val) => val !== null, { message: t("common.boolean.required", { label }) })
+  }
+
+  if (shouldBe === true) {
+    result = result.refine((val) => val === true, { message: t("common.boolean.shouldBe.true", { label }) })
+  } else if (shouldBe === false) {
+    result = result.refine((val) => val === false, { message: t("common.boolean.shouldBe.false", { label }) })
+  }
+
+  return result as IsRequired extends true ? ZodBoolean : ZodNullable<ZodBoolean>
+}

package/src/common/date.ts

@@ -0,0 +1,44 @@
+import { z, ZodNullable, ZodString } from "zod"
+import { t } from "../i18n"
+import dayjs from "dayjs"
+import customParseFormat from "dayjs/plugin/customParseFormat"
+import isSameOrAfter from "dayjs/plugin/isSameOrAfter"
+import isSameOrBefore from "dayjs/plugin/isSameOrBefore"
+
+dayjs.extend(isSameOrAfter)
+dayjs.extend(isSameOrBefore)
+dayjs.extend(customParseFormat)
+
+export type DateOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  label: string
+  min?: number
+  max?: number
+  format?: string
+  includes?: string
+  defaultValue?: IsRequired extends true ? string : string | null
+}
+
+export type DateSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+
+export function date<IsRequired extends boolean = true>(options?: DateOptions<IsRequired>): DateSchema<IsRequired> {
+  const { required = true, label, min, max, format = "YYYY-MM-DD", includes, defaultValue = null } = options ?? {}
+
+  const baseSchema = required
+    ? z.preprocess((val) => (val === "" || val === null || val === undefined ? defaultValue : val), z.coerce.string().trim())
+    : z.preprocess((val) => (val === "" || val === null || val === undefined ? defaultValue : val), z.coerce.string().trim().nullable())
+
+  const schema = baseSchema
+    .refine(
+      (val) => {
+        if (!val) return !required
+        return dayjs(val, format, true).isValid()
+      },
+      { message: t("common.date.format", { label, format }) }
+    )
+    .refine((val) => val === null || min === undefined || dayjs(val, format).isSameOrAfter(dayjs(min, format)), { message: t("common.date.min", { label, min }) })
+    .refine((val) => val === null || max === undefined || dayjs(val, format).isSameOrBefore(dayjs(max, format)), { message: t("common.date.max", { label, max }) })
+    .refine((val) => val === null || includes === undefined || val.includes(includes), { message: t("common.date.includes", { label, includes }) })
+
+  return schema as unknown as DateSchema<IsRequired>
+}

package/src/common/email.ts

@@ -0,0 +1,45 @@
+import { z, ZodNullable, ZodString } from "zod"
+import { t } from "../i18n"
+import { TextSchema } from "./text"
+
+export type EmailOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  label: string
+  domain?: string
+  min?: number
+  max?: number
+  includes?: string
+}
+
+export type EmailSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+
+export function email<IsRequired extends boolean = true>(options?: EmailOptions<IsRequired>): EmailSchema<IsRequired> {
+  const { required = true, label, domain, min, max, includes } = options ?? {}
+
+  const baseSchema = required
+    ? z.preprocess(
+        (val) => (val === "" || val === null || val === undefined ? null : val),
+        z.email({
+          error: (issue) => {
+            if (issue.code === "invalid_type") return t("common.email.required", { label })
+            else if (issue.code === "invalid_format") return t("common.email.invalid", { label })
+            return t("common.email.invalid", { label })
+          },
+        })
+      )
+    : z.preprocess((val) => (val === "" || val === null || val === undefined ? null : val), z.email({ message: t("common.email.invalid", { label }) }).nullable())
+
+  const schema = baseSchema
+    .refine((val) => (required ? val !== "" && val !== "null" && val !== "undefined" : true), { message: t("common.text.required", { label }) })
+    .refine((val) => val === null || min === undefined || val.length >= min, { message: t("common.text.min", { label, min }) })
+    .refine((val) => val === null || max === undefined || val.length <= max, { message: t("common.text.max", { label, max }) })
+    .refine((val) => val === null || includes === undefined || val.includes(includes), { message: t("common.text.includes", { label, includes }) })
+    .refine(
+      (val) => {
+        if (val === null || domain === undefined) return true
+        return val.split("@")[1]?.toLowerCase() === domain.toLowerCase()
+      },
+      { message: t("common.email.domain", { label, domain }) }
+    )
+  return schema as unknown as TextSchema<IsRequired>
+}

package/src/common/integer.ts

@@ -0,0 +1,47 @@
+import { z, ZodNullable, ZodNumber } from "zod"
+import { t } from "../i18n"
+
+export type IntegerOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  label: string
+  min?: number
+  max?: number
+  defaultValue?: IsRequired extends true ? number : number | null
+}
+
+export type IntegerSchema<IsRequired extends boolean> = IsRequired extends true ? ZodNumber : ZodNullable<ZodNumber>
+
+export function integer<IsRequired extends boolean = true>(options?: IntegerOptions<IsRequired>): IntegerSchema<IsRequired> {
+  const { required = true, label, min, max, defaultValue } = options ?? {}
+
+  const schema = z
+    .preprocess(
+      (val) => {
+        if (val === "" || val === undefined || val === null) return defaultValue ?? null
+        return typeof val === "string" ? Number(val) : val
+      },
+      z.union([
+        z.number({
+          error: (issue) => {
+            if (issue.code === "invalid_type") return t("common.integer.integer", { label })
+            return t("common.integer.required", { label })
+          },
+        }),
+        z.null(),
+      ])
+    )
+    .refine((val) => !required || val !== null, {
+      message: t("common.integer.required", { label }),
+    })
+    .refine((val) => val === null || Number.isInteger(val), {
+      message: t("common.integer.integer", { label }),
+    })
+    .refine((val) => val === null || min === undefined || val >= min, {
+      message: t("common.integer.min", { label, min }),
+    })
+    .refine((val) => val === null || max === undefined || val <= max, {
+      message: t("common.integer.max", { label, max }),
+    })
+
+  return schema as unknown as IntegerSchema<IsRequired>
+}

package/src/common/number.ts

@@ -0,0 +1,38 @@
+import { z, ZodNullable, ZodNumber } from "zod"
+import { t } from "../i18n"
+
+export type NumberOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  label: string
+  min?: number
+  max?: number
+  defaultValue?: IsRequired extends true ? number : number | null
+}
+
+export type NumberSchema<IsRequired extends boolean> = IsRequired extends true ? ZodNumber : ZodNullable<ZodNumber>
+
+export function number<IsRequired extends boolean = true>(options?: NumberOptions<IsRequired>): NumberSchema<IsRequired> {
+  const { required = true, label, min, max, defaultValue } = options ?? {}
+
+  const schema = z
+    .preprocess(
+      (val) => {
+        if (val === "" || val === undefined || val === null) return defaultValue ?? null
+        return typeof val === "string" ? Number(val) : val
+      },
+      z.union([
+        z.number({
+          error: (issue) => {
+            if (issue.code === "invalid_type") return t("common.number.integer", { label })
+            return t("common.number.required", { label })
+          },
+        }),
+        z.null(),
+      ])
+    )
+    .refine((val) => !required || val !== null, { message: t("common.number.required", { label }) })
+    .refine((val) => val === null || min === undefined || val >= min, { message: t("common.number.min", { label, min }) })
+    .refine((val) => val === null || max === undefined || val <= max, { message: t("common.number.max", { label, max }) })
+
+  return schema as unknown as NumberSchema<IsRequired>
+}

package/src/common/password.ts

@@ -0,0 +1,34 @@
+import { z, ZodNullable, ZodString } from "zod"
+import { t } from "../i18n"
+
+export type PasswordOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  label: string
+  min?: number
+  max?: number
+  uppercase?: boolean
+  lowercase?: boolean
+  digits?: boolean
+  special?: boolean
+}
+
+export type PasswordSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+
+export function password<IsRequired extends boolean = true>(options?: PasswordOptions<IsRequired>): PasswordSchema<IsRequired> {
+  const { required = true, label, min, max, uppercase, lowercase, digits, special } = options ?? {}
+
+  const baseSchema = required
+    ? z.preprocess((val) => (val === "" || val === null || val === undefined ? null : val), z.coerce.string().trim())
+    : z.preprocess((val) => (val === "" || val === null || val === undefined ? null : val), z.coerce.string().trim().nullable())
+
+  const schema = baseSchema
+    .refine((val) => (required ? val !== "" && val !== "null" && val !== "undefined" : true), { message: t("common.password.required", { label }) })
+    .refine((val) => val === null || min === undefined || val.length >= min, { message: t("common.password.min", { label, min }) })
+    .refine((val) => val === null || max === undefined || val.length <= max, { message: t("common.password.max", { label, max }) })
+    .refine((val) => val === null || !uppercase || /[A-Z]/.test(val), { message: t("common.password.uppercase", { label }) })
+    .refine((val) => val === null || !lowercase || /[a-z]/.test(val), { message: t("common.password.lowercase", { label }) })
+    .refine((val) => val === null || !special || /[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]+/.test(val), { message: t("common.password.special", { label }) })
+    .refine((val) => val === null || !digits || /[0-9]/.test(val), { message: t("common.password.digits", { label }) })
+
+  return schema as unknown as PasswordSchema<IsRequired>
+}

package/src/common/text.ts

@@ -0,0 +1,35 @@
+import { z, ZodNullable, ZodString } from "zod"
+import { t } from "../i18n"
+
+export type TextOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  label: string
+  min?: number
+  max?: number
+  startsWith?: string
+  endsWith?: string
+  includes?: string
+  regex?: RegExp
+  defaultValue?: IsRequired extends true ? string : string | null
+}
+
+export type TextSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+
+export function text<IsRequired extends boolean = true>(options?: TextOptions<IsRequired>): TextSchema<IsRequired> {
+  const { required = true, label, min, max, startsWith, endsWith, includes, regex, defaultValue = null } = options ?? {}
+
+  const baseSchema = required
+    ? z.preprocess((val) => (val === "" || val === null || val === undefined ? defaultValue : val), z.coerce.string().trim())
+    : z.preprocess((val) => (val === "" || val === null || val === undefined ? defaultValue : val), z.coerce.string().trim().nullable())
+
+  const schema = baseSchema
+    .refine((val) => (required ? val !== "" && val !== "null" && val !== "undefined" : true), { message: t("common.text.required", { label }) })
+    .refine((val) => val === null || min === undefined || val.length >= min, { message: t("common.text.min", { label, min }) })
+    .refine((val) => val === null || max === undefined || val.length <= max, { message: t("common.text.max", { label, max }) })
+    .refine((val) => val === null || startsWith === undefined || val.startsWith(startsWith), { message: t("common.text.startsWith", { label, startsWith }) })
+    .refine((val) => val === null || endsWith === undefined || val.endsWith(endsWith), { message: t("common.text.endsWith", { label, endsWith }) })
+    .refine((val) => val === null || includes === undefined || val.includes(includes), { message: t("common.text.includes", { label, includes }) })
+    .refine((val) => val === null || regex === undefined || regex.test(val), { message: t("common.text.invalid", { label, regex }) })
+
+  return schema as unknown as TextSchema<IsRequired>
+}

package/src/common/url.ts

@@ -0,0 +1,38 @@
+import { z, ZodNullable, ZodString } from "zod"
+import { t } from "../i18n"
+import { TextSchema } from "./text"
+
+export type UrlOptions<IsRequired extends boolean = true> = {
+  required?: IsRequired
+  label: string
+  min?: number
+  max?: number
+  includes?: string
+}
+
+export type UrlSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+
+export function url<IsRequired extends boolean = true>(options?: UrlOptions<IsRequired>): UrlSchema<IsRequired> {
+  const { required = true, label, min, max, includes } = options ?? {}
+
+  const baseSchema = required
+    ? z.preprocess(
+        (val) => (val === "" || val === null || val === undefined ? null : val),
+        z.url({
+          error: (issue) => {
+            if (issue.code === "invalid_type") return t("common.url.required", { label })
+            else if (issue.code === "invalid_format") return t("common.url.invalid", { label })
+            return t("common.url.invalid", { label })
+          },
+        })
+      )
+    : z.preprocess((val) => (val === "" || val === null || val === undefined ? null : val), z.url({ message: t("common.url.invalid", { label }) }).nullable())
+
+  const schema = baseSchema
+    .refine((val) => (required ? val !== "" && val !== "null" && val !== "undefined" : true), { message: t("common.text.required", { label }) })
+    .refine((val) => val === null || min === undefined || val.length >= min, { message: t("common.text.min", { label, min }) })
+    .refine((val) => val === null || max === undefined || val.length <= max, { message: t("common.text.max", { label, max }) })
+    .refine((val) => val === null || includes === undefined || val.includes(includes), { message: t("common.text.includes", { label, includes }) })
+
+  return schema as unknown as TextSchema<IsRequired>
+}

package/src/config.ts

@@ -0,0 +1,9 @@
+export type Locale = "zh-TW" | "en"
+
+let currentLocale: Locale = "zh-TW"
+
+export const setLocale = (locale: Locale) => {
+  currentLocale = locale
+}
+
+export const getLocale = (): Locale => currentLocale

package/src/i18n/index.ts

@@ -0,0 +1,22 @@
+import zhTW from "./locales/zh-TW.json"
+import en from "./locales/en.json"
+import { getLocale } from "../config"
+
+const dicts = {
+  "zh-TW": zhTW,
+  en,
+} satisfies Record<string, unknown>
+
+export const t = (key: string, params: Record<string, any> = {}): string => {
+  const locale = getLocale()
+  const dict = dicts[locale] || {}
+
+  const template = getNestedValue(dict, key) ?? key
+
+  return template.replace(/\$\{(\w+)}/g, (_, k) => params[k] ?? "")
+}
+
+function getNestedValue(obj: Record<string, any>, path: string): string | undefined {
+  const result = path.split(".").reduce((acc: any, part: string) => (acc && typeof acc === "object" ? acc[part] : undefined), obj)
+  return typeof result === "string" ? result : undefined
+}

package/src/i18n/locales/en.json

@@ -0,0 +1,68 @@
+{
+  "common": {
+    "boolean": {
+      "required": "${label} is required",
+      "shouldBe": {
+        "true": "${label} must be True",
+        "false": "${label} must be False"
+      }
+    },
+    "email": {
+      "required": "${label} is required",
+      "min": "${label} must be at least ${min} characters",
+      "max": "${label} must be at most ${max} characters",
+      "includes": "${label} must include ${includes}",
+      "invalid": "${label} is invalid format",
+      "domain": "${label} must be under the domain @${domain}"
+    },
+    "url": {
+      "required": "${label} is required",
+      "min": "${label} must be at least ${min} characters",
+      "max": "${label} must be at most ${max} characters",
+      "includes": "${label} must include ${includes}",
+      "invalid": "${label} is invalid format"
+    },
+    "password": {
+      "required": "${label} is required",
+      "min": "${label} must be at least ${min} characters",
+      "max": "${label} must be at most ${max} characters",
+      "uppercase": "${label} must include at least one uppercase letter",
+      "lowercase": "${label} must include at least one lowercase letter",
+      "digits": "${label} must include at least one digit",
+      "special": "${label} must include at least one special character"
+    },
+    "number": {
+      "required": "${label} is required",
+      "min": "${label} must be at least ${min}",
+      "max": "${label} must be at most ${max}"
+    },
+    "integer": {
+      "required": "${label} is required",
+      "min": "${label} must be at least ${min}",
+      "max": "${label} must be at most ${max}",
+      "integer": "${label} must be an integer"
+    },
+    "float": {
+      "required": "${label} is required",
+      "min": "${label} must be at least ${min}",
+      "max": "${label} must be at most ${max}",
+      "float": "${label} must be an float"
+    },
+    "text": {
+      "required": "${label} is required",
+      "min": "${label} must be at least ${min} characters",
+      "max": "${label} must be at most ${max} characters",
+      "startsWith": "${label} must start with ${startsWith}",
+      "endsWith": "${label} must end with ${endsWith}",
+      "includes": "${label} must include ${includes}",
+      "invalid": "${label} is invalid format"
+    },
+    "date": {
+      "required": "${label} is required",
+      "min": "${label} must be at least ${min} characters",
+      "max": "${label} must be at most ${max} characters",
+      "includes": "${label} must include ${includes}",
+      "format": "${label} must be in ${format} format"
+    }
+  }
+}