@hy_ong/zod-kit 0.2.0 → 0.2.2

package/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npx eslint src/
+      - run: npx tsc --noEmit
+      - run: npm test -- --run
+      - run: npm run build

package/CLAUDE.md

@@ -2,9 +2,9 @@
 
 ## Project Overview
 
-`@hy_ong/zod-kit` is a TypeScript library providing pre-built Zod validation schemas with full i18n support (English, Traditional Chinese). It includes common validators (email, password, text, number, etc.) and Taiwan-specific validators (National ID, Business ID, mobile, tel, fax, postal code).
+`@hy_ong/zod-kit` is a TypeScript library providing pre-built Zod validation schemas with full i18n support (10 locales). It includes common validators (email, password, text, number, credit card, IP, color, coordinate, etc.) and Taiwan-specific validators (National ID, Business ID, mobile, tel, fax, postal code, invoice, license plate, bank account, passport).
 
-- **Version:** 0.1.16
+- **Version:** 0.2.0
 - **License:** MIT
 - **NPM:** `@hy_ong/zod-kit`
 - **Peer dependency:** Zod ^4.3.6
@@ -13,7 +13,7 @@
 ## Commands
 
 ```bash
-# Run all tests (743 test cases across 17 files)
+# Run all tests (1050 test cases across 25 files)
 npm test
 
 # Run tests once (no watch mode)
@@ -22,13 +22,16 @@ npm test -- --run
 # Run specific test file
 npx vitest run tests/common/email.test.ts
 
-# Build (ESM + CJS + .d.ts)
+# Build (ESM + CJS + .d.ts, 26 entry points with code splitting)
 npm run build
-# Equivalent to: tsup src/index.ts --format esm,cjs --dts
+# Uses tsup.config.ts for multi-entry build
 
 # Lint
 npx eslint src/
 
+# Type check
+npx tsc --noEmit
+
 # Publish (runs tests + build automatically via prepublishOnly)
 npm publish --access public
 ```
@@ -42,34 +45,65 @@ src/
 ├── i18n/
 │   ├── index.ts                # Translation function t(key, params)
 │   └── locales/
-│       ├── en.json             # English messages
-│       └── zh-TW.json          # Traditional Chinese messages
+│       ├── en-US.json          # English (US)
+│       ├── en-GB.json          # English (UK)
+│       ├── zh-TW.json          # Traditional Chinese
+│       ├── zh-CN.json          # Simplified Chinese
+│       ├── ja-JP.json          # Japanese
+│       ├── ko-KR.json          # Korean
+│       ├── ms-MY.json          # Malay
+│       ├── id-ID.json          # Indonesian
+│       ├── th-TH.json          # Thai
+│       └── vi-VN.json          # Vietnamese
 └── validators/
-    ├── common/                 # 11 universal validators
+    ├── common/                 # 15 universal validators
     │   ├── boolean.ts
+    │   ├── color.ts            # Hex, RGB, HSL with alpha support
+    │   ├── coordinate.ts       # Latitude, longitude, coordinate pairs
+    │   ├── credit-card.ts      # Luhn algorithm, card type detection
     │   ├── date.ts
     │   ├── datetime.ts         # Uses dayjs for parsing
     │   ├── email.ts
     │   ├── file.ts
     │   ├── id.ts               # UUID, nanoid, ObjectId
+    │   ├── ip.ts               # IPv4, IPv6, CIDR support
     │   ├── number.ts
     │   ├── password.ts
     │   ├── text.ts
     │   ├── time.ts
     │   └── url.ts
-    └── taiwan/                 # 6 Taiwan-specific validators
+    └── taiwan/                 # 10 Taiwan-specific validators
+        ├── bank-account.ts     # 銀行帳號 (bank code + account number)
         ├── business-id.ts      # 統一編號 (checksum)
         ├── fax.ts
+        ├── invoice.ts          # 統一發票 (2 letters + 8 digits)
+        ├── license-plate.ts    # 車牌號碼 (new + legacy formats)
         ├── mobile.ts           # 09X-XXXX-XXXX
         ├── national-id.ts      # 身分證/居留證 (checksum)
+        ├── passport.ts         # 護照號碼 (9 digits, type prefix)
         ├── postal-code.ts      # 3/5/6-digit with official data
         └── tel.ts              # Landline + toll-free (0800/0809)
 
 tests/                          # Mirrors src/validators/ structure
-├── common/                     # 11 test files
-└── taiwan/                     # 6 test files
+├── common/                     # 15 test files
+└── taiwan/                     # 10 test files
+```
+
+## Per-Module Imports
+
+Users can import individual validators for tree-shaking:
+
+```typescript
+// Full import
+import { email, twNationalId } from "@hy_ong/zod-kit"
+
+// Per-module import (tree-shakeable)
+import { email } from "@hy_ong/zod-kit/common/email"
+import { twNationalId } from "@hy_ong/zod-kit/taiwan/national-id"
 ```
 
+All 26 sub-modules are configured in `tsup.config.ts` (entry points) and `package.json` (exports map).
+
 ## Architecture & Patterns
 
 ### Validator Function Signature
@@ -95,7 +129,8 @@ All validators use a two-step approach:
 
 ### i18n System
 
-- Locale state is global: `setLocale("en")` / `setLocale("zh-TW")`
+- 10 locales: en-US, en-GB, zh-TW, zh-CN, ja-JP, ko-KR, ms-MY, id-ID, th-TH, vi-VN
+- Locale state is global: `setLocale("en-US")` / `setLocale("zh-TW")`
 - Translation keys are dot-separated: `common.email.invalid`
 - Parameter substitution: `${paramName}` in message templates
 - Each validator supports custom `i18n` overrides in options
@@ -107,6 +142,10 @@ Taiwan validators implement domain-specific algorithms:
 - **Postal Code**: Validates against official Chunghwa Post data (28KB+ of mappings)
 - **Tel/Fax**: Area code + digit length rules per region
 - **Mobile**: Operator prefix validation (090-099)
+- **Invoice**: 2-letter prefix + 8-digit format, auto-strip hyphens, auto-uppercase
+- **License Plate**: New (2012+) and legacy formats for car/motorcycle
+- **Bank Account**: Bank code validation against official list + account number length
+- **Passport**: 9-digit format with type prefix (0=diplomatic, 1=official, 2=ordinary, 3=travel)
 
 ## Code Style
 
@@ -120,23 +159,26 @@ Taiwan validators implement domain-specific algorithms:
 
 - Commit messages use **Conventional Commits**: `feat(scope):`, `fix(scope):`, `chore:`, `docs:`
 - Every validator exports both a factory function and relevant type definitions
-- Test files use `beforeEach(() => setLocale("en"))` for consistent locale
+- Test files use `beforeEach(() => setLocale("en-US"))` for consistent locale
 - Test structure: `describe("validatorName(required) features")` → nested `describe` per feature → `it` cases
 - Source files are organized by domain: `common/` for universal, `taiwan/` for locale-specific
-- No CI/CD pipelines — tests and builds are run manually or via `prepublishOnly` hook
+- CI runs on GitHub Actions (Node 18/20/22): lint, type-check, test, build
 
 ## Build Output
 
-`dist/` contains four files:
-- `index.js` — ESM bundle
-- `index.cjs` — CommonJS bundle
-- `index.d.ts` — TypeScript declarations (ESM)
-- `index.d.cts` — TypeScript declarations (CJS)
+`dist/` contains per-module outputs with code splitting:
+- `{module}.js` — ESM bundle
+- `{module}.cjs` — CommonJS bundle
+- `{module}.d.ts` — TypeScript declarations (ESM)
+- `{module}.d.cts` — TypeScript declarations (CJS)
+- `chunk-*.js` / `chunk-*.cjs` — Shared code chunks
 
 ## Adding a New Validator
 
 1. Create `src/validators/{domain}/{name}.ts` following the generic pattern above
-2. Add i18n keys to both `src/i18n/locales/en.json` and `zh-TW.json`
+2. Add i18n keys to all 10 locale files in `src/i18n/locales/`
 3. Export from `src/index.ts`
-4. Create `tests/{domain}/{name}.test.ts` with comprehensive coverage
-5. Test with `npx vitest run tests/{domain}/{name}.test.ts`
+4. Add entry point to `tsup.config.ts`
+5. Add exports map entry to `package.json`
+6. Create `tests/{domain}/{name}.test.ts` with comprehensive coverage
+7. Test with `npx vitest run tests/{domain}/{name}.test.ts`

package/dist/chunk-2SWEVDFZ.js

@@ -0,0 +1,134 @@
+import {
+  getLocale,
+  t
+} from "./chunk-6AAP4LPF.js";
+
+// src/validators/common/color.ts
+import { z } from "zod";
+var HEX_RGB = /^#[0-9a-f]{3}$/i;
+var HEX_RRGGBB = /^#[0-9a-f]{6}$/i;
+var HEX_RRGGBBAA = /^#[0-9a-f]{8}$/i;
+function isValidByte(n) {
+  return Number.isInteger(n) && n >= 0 && n <= 255;
+}
+function isValidAlpha(n) {
+  return n >= 0 && n <= 1;
+}
+function isValidHue(n) {
+  return n >= 0 && n <= 360;
+}
+function isValidPercentage(n) {
+  return n >= 0 && n <= 100;
+}
+function validateHex(value, allowAlpha) {
+  if (HEX_RGB.test(value) || HEX_RRGGBB.test(value)) return true;
+  if (allowAlpha && HEX_RRGGBBAA.test(value)) return true;
+  return false;
+}
+function validateRgb(value, allowAlpha) {
+  const rgbaMatch = value.match(/^rgba?\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*(?:,\s*(-?\d+(?:\.\d+)?))?\s*\)$/);
+  if (!rgbaMatch) return false;
+  const r = Number(rgbaMatch[1]);
+  const g = Number(rgbaMatch[2]);
+  const b = Number(rgbaMatch[3]);
+  const a = rgbaMatch[4] !== void 0 ? Number(rgbaMatch[4]) : void 0;
+  if (!isValidByte(r) || !isValidByte(g) || !isValidByte(b)) return false;
+  if (a !== void 0) {
+    if (!allowAlpha) return false;
+    if (!isValidAlpha(a)) return false;
+  }
+  if (value.startsWith("rgba(") && a === void 0) return false;
+  if (value.startsWith("rgb(") && a !== void 0) return false;
+  return true;
+}
+function validateHsl(value, allowAlpha) {
+  const hslaMatch = value.match(/^hsla?\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)%\s*,\s*(-?\d+(?:\.\d+)?)%\s*(?:,\s*(-?\d+(?:\.\d+)?))?\s*\)$/);
+  if (!hslaMatch) return false;
+  const h = Number(hslaMatch[1]);
+  const s = Number(hslaMatch[2]);
+  const l = Number(hslaMatch[3]);
+  const a = hslaMatch[4] !== void 0 ? Number(hslaMatch[4]) : void 0;
+  if (!isValidHue(h) || !isValidPercentage(s) || !isValidPercentage(l)) return false;
+  if (a !== void 0) {
+    if (!allowAlpha) return false;
+    if (!isValidAlpha(a)) return false;
+  }
+  if (value.startsWith("hsla(") && a === void 0) return false;
+  if (value.startsWith("hsl(") && a !== void 0) return false;
+  return true;
+}
+function validateColor(value, formats, allowAlpha) {
+  const hasAny = formats.includes("any");
+  if (hasAny) {
+    if (validateHex(value, allowAlpha)) return { valid: true };
+    if (validateRgb(value, allowAlpha)) return { valid: true };
+    if (validateHsl(value, allowAlpha)) return { valid: true };
+    return { valid: false };
+  }
+  for (const format of formats) {
+    if (format === "hex" && validateHex(value, allowAlpha)) return { valid: true };
+    if (format === "rgb" && validateRgb(value, allowAlpha)) return { valid: true };
+    if (format === "hsl" && validateHsl(value, allowAlpha)) return { valid: true };
+  }
+  if (formats.length === 1) {
+    return { valid: false, failedFormat: formats[0] };
+  }
+  return { valid: false };
+}
+function color(required, options) {
+  const { format = "any", allowAlpha = true, transform, defaultValue, i18n } = options ?? {};
+  const isRequired = required ?? false;
+  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null);
+  const formats = Array.isArray(format) ? format : [format];
+  const getMessage = (key, params) => {
+    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.color.${key}`, params);
+  };
+  const preprocessFn = (val) => {
+    if (val === "" || val === null || val === void 0) {
+      return actualDefaultValue;
+    }
+    let processed = String(val).trim();
+    if (processed === "" && !required) {
+      return null;
+    }
+    if (transform) {
+      processed = transform(processed);
+    }
+    return processed;
+  };
+  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable());
+  const schema = baseSchema.superRefine((val, ctx) => {
+    if (val === null) return;
+    if (isRequired && (val === "" || val === "null" || val === "undefined")) {
+      ctx.addIssue({ code: "custom", message: getMessage("required") });
+      return;
+    }
+    if (!isRequired && val === "") return;
+    const result = validateColor(val, formats, allowAlpha);
+    if (!result.valid) {
+      const formatMessageMap = {
+        hex: "notHex",
+        rgb: "notRgb",
+        hsl: "notHsl",
+        any: "invalid"
+      };
+      const messageKey = result.failedFormat ? formatMessageMap[result.failedFormat] : "invalid";
+      ctx.addIssue({ code: "custom", message: getMessage(messageKey) });
+      return;
+    }
+  });
+  return schema;
+}
+
+export {
+  validateColor,
+  color
+};

package/dist/chunk-32JI34CV.cjs

@@ -0,0 +1,146 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+var _chunkUCOXAZJFcjs = require('./chunk-UCOXAZJF.cjs');
+
+// src/validators/common/ip.ts
+var _zod = require('zod');
+function validateIPv4(value) {
+  const parts = value.split(".");
+  if (parts.length !== 4) return false;
+  for (const part of parts) {
+    if (part === "") return false;
+    if (part.length > 1 && part.startsWith("0")) return false;
+    const num = Number(part);
+    if (!Number.isInteger(num) || num < 0 || num > 255) return false;
+  }
+  return true;
+}
+function validateIPv6(value) {
+  const lastColon = value.lastIndexOf(":");
+  if (lastColon !== -1) {
+    const afterLastColon = value.substring(lastColon + 1);
+    if (afterLastColon.includes(".")) {
+      if (!validateIPv4(afterLastColon)) return false;
+      const ipv6Prefix = value.substring(0, lastColon);
+      return validateIPv6Groups(ipv6Prefix, 6);
+    }
+  }
+  return validateIPv6Groups(value, 8);
+}
+function validateIPv6Groups(value, maxGroups) {
+  if (value.includes("::")) {
+    const doubleColonCount = value.split("::").length - 1;
+    if (doubleColonCount > 1) return false;
+    const [left, right] = value.split("::");
+    const leftGroups = left === "" ? [] : left.split(":");
+    const rightGroups = right === "" ? [] : right.split(":");
+    if (leftGroups.length + rightGroups.length >= maxGroups) return false;
+    for (const group of [...leftGroups, ...rightGroups]) {
+      if (!isValidHexGroup(group)) return false;
+    }
+    return true;
+  }
+  const groups = value.split(":");
+  if (groups.length !== maxGroups) return false;
+  for (const group of groups) {
+    if (!isValidHexGroup(group)) return false;
+  }
+  return true;
+}
+function isValidHexGroup(group) {
+  if (group.length === 0 || group.length > 4) return false;
+  return /^[0-9a-fA-F]{1,4}$/.test(group);
+}
+function ip(required, options) {
+  const { version = "any", allowCIDR = false, whitelist, transform, defaultValue, i18n } = _nullishCoalesce(options, () => ( {}));
+  const isRequired = _nullishCoalesce(required, () => ( false));
+  const actualDefaultValue = _nullishCoalesce(defaultValue, () => ( (isRequired ? "" : null)));
+  const getMessage = (key, params) => {
+    if (i18n) {
+      const currentLocale = _chunkUCOXAZJFcjs.getLocale.call(void 0, );
+      const customMessages = i18n[currentLocale];
+      if (customMessages && customMessages[key]) {
+        const template = customMessages[key];
+        return template.replace(/\$\{(\w+)}/g, (_, k) => _nullishCoalesce(_optionalChain([params, 'optionalAccess', _2 => _2[k]]), () => ( "")));
+      }
+    }
+    return _chunkUCOXAZJFcjs.t.call(void 0, `common.ip.${key}`, params);
+  };
+  const preprocessFn = (val) => {
+    if (val === "" || val === null || val === void 0) {
+      return actualDefaultValue;
+    }
+    let processed = String(val).trim();
+    if (processed === "" && !required) {
+      return null;
+    }
+    if (transform) {
+      processed = transform(processed);
+    }
+    return processed;
+  };
+  const baseSchema = isRequired ? _zod.z.preprocess(preprocessFn, _zod.z.string()) : _zod.z.preprocess(preprocessFn, _zod.z.string().nullable());
+  const schema = baseSchema.superRefine((val, ctx) => {
+    if (val === null) return;
+    if (isRequired && (val === "" || val === "null" || val === "undefined")) {
+      ctx.addIssue({ code: "custom", message: getMessage("required") });
+      return;
+    }
+    if (!isRequired && val === "") return;
+    let ipPart = val;
+    let cidrPrefix = null;
+    const slashIndex = val.indexOf("/");
+    if (slashIndex !== -1) {
+      if (!allowCIDR) {
+        ctx.addIssue({ code: "custom", message: getMessage("invalid") });
+        return;
+      }
+      ipPart = val.substring(0, slashIndex);
+      cidrPrefix = val.substring(slashIndex + 1);
+    }
+    const isV4 = validateIPv4(ipPart);
+    const isV6 = validateIPv6(ipPart);
+    if (version === "v4") {
+      if (!isV4) {
+        ctx.addIssue({ code: "custom", message: getMessage("notIPv4") });
+        return;
+      }
+    } else if (version === "v6") {
+      if (!isV6) {
+        ctx.addIssue({ code: "custom", message: getMessage("notIPv6") });
+        return;
+      }
+    } else {
+      if (!isV4 && !isV6) {
+        ctx.addIssue({ code: "custom", message: getMessage("invalid") });
+        return;
+      }
+    }
+    if (cidrPrefix !== null) {
+      if (!/^\d+$/.test(cidrPrefix)) {
+        ctx.addIssue({ code: "custom", message: getMessage("invalid") });
+        return;
+      }
+      const prefixNum = Number(cidrPrefix);
+      const maxPrefix = isV4 ? 32 : 128;
+      if (prefixNum < 0 || prefixNum > maxPrefix) {
+        ctx.addIssue({ code: "custom", message: getMessage("invalid") });
+        return;
+      }
+    }
+    if (whitelist && whitelist.length > 0) {
+      if (!whitelist.includes(val)) {
+        ctx.addIssue({ code: "custom", message: getMessage("notInWhitelist") });
+        return;
+      }
+    }
+  });
+  return schema;
+}
+
+
+
+
+
+exports.validateIPv4 = validateIPv4; exports.validateIPv6 = validateIPv6; exports.ip = ip;

package/dist/chunk-42C5OHRK.js

@@ -0,0 +1,71 @@
+import {
+  getLocale,
+  t
+} from "./chunk-6AAP4LPF.js";
+
+// src/validators/common/boolean.ts
+import { z } from "zod";
+function boolean(required, options) {
+  const {
+    defaultValue = null,
+    shouldBe,
+    truthyValues = [true, "true", 1, "1", "yes", "on"],
+    falsyValues = [false, "false", 0, "0", "no", "off"],
+    strict = false,
+    transform,
+    i18n
+  } = options ?? {};
+  const isRequired = required ?? false;
+  const getMessage = (key, params) => {
+    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.boolean.${key}`, params);
+  };
+  let result = z.preprocess(
+    (val) => {
+      if (val === "" || val === void 0 || val === null) return defaultValue;
+      if (strict && typeof val !== "boolean" && val !== null) {
+        return val;
+      }
+      if (truthyValues.includes(val)) {
+        let processed = true;
+        if (transform) processed = transform(processed);
+        return processed;
+      }
+      if (falsyValues.includes(val)) {
+        let processed = false;
+        if (transform) processed = transform(processed);
+        return processed;
+      }
+      return val;
+    },
+    z.union([z.literal(true), z.literal(false), z.literal(null)])
+  );
+  if (isRequired && defaultValue === null) {
+    result = result.refine((val) => val !== null, { message: getMessage("required") });
+  }
+  if (shouldBe === true) {
+    result = result.refine((val) => val === true, { message: getMessage("shouldBeTrue") });
+  } else if (shouldBe === false) {
+    result = result.refine((val) => val === false, { message: getMessage("shouldBeFalse") });
+  }
+  if (strict) {
+    result = result.refine(
+      (val) => {
+        return val === null || typeof val === "boolean";
+      },
+      { message: getMessage("invalid") }
+    );
+  }
+  return result;
+}
+
+export {
+  boolean
+};