@hy_ong/zod-kit 0.1.16 → 0.2.1

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

@@ -0,0 +1,184 @@
+# CLAUDE.md — zod-kit
+
+## Project Overview
+
+`@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.2.0
+- **License:** MIT
+- **NPM:** `@hy_ong/zod-kit`
+- **Peer dependency:** Zod ^4.3.6
+- **Production dependency:** dayjs ^1.11.19
+
+## Commands
+
+```bash
+# Run all tests (1050 test cases across 25 files)
+npm test
+
+# Run tests once (no watch mode)
+npm test -- --run
+
+# Run specific test file
+npx vitest run tests/common/email.test.ts
+
+# Build (ESM + CJS + .d.ts, 26 entry points with code splitting)
+npm run build
+# 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
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts                    # Re-exports all validators + config
+├── config.ts                   # Locale state (setLocale, getLocale)
+├── i18n/
+│   ├── index.ts                # Translation function t(key, params)
+│   └── locales/
+│       ├── 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/                 # 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/                 # 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/                     # 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
+
+Every validator follows this consistent pattern:
+
+```typescript
+function validatorName<IsRequired extends boolean = false>(
+  required?: IsRequired,
+  options?: Omit<ValidatorOptions<IsRequired>, "required">
+): ValidatorSchema<IsRequired>
+```
+
+- First param: `required` boolean (defaults to `false`)
+- Second param: options object (varies per validator)
+- Returns: `ZodType` — required returns non-nullable, optional returns nullable
+
+### Validation Pipeline
+
+All validators use a two-step approach:
+1. `z.preprocess()` — input transformation (trim, coerce, normalize)
+2. `.superRefine()` — complex business logic and custom error messages
+
+### i18n System
+
+- 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
+
+### Taiwan Validators
+
+Taiwan validators implement domain-specific algorithms:
+- **National ID / Business ID**: Checksum verification with weighted sums
+- **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
+
+- **Formatter:** Prettier — no semicolons, double quotes, 200 char line width, 2-space indent
+- **Linter:** ESLint 9 + typescript-eslint (recommended rules, `no-explicit-any` disabled)
+- **TypeScript:** Strict mode, ESNext target, declaration files generated
+- **Module:** ES Module (`"type": "module"` in package.json)
+- **Tests:** Vitest with globals enabled, node environment
+
+## Conventions
+
+- 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-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
+- CI runs on GitHub Actions (Node 18/20/22): lint, type-check, test, build
+
+## Build Output
+
+`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 all 10 locale files in `src/i18n/locales/`
+3. Export from `src/index.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-36NWHESN.js

@@ -0,0 +1,124 @@
+import {
+  getLocale,
+  t
+} from "./chunk-ZBOQCXD4.js";
+
+// src/validators/common/date.ts
+import { z } from "zod";
+import dayjs from "dayjs";
+import customParseFormat from "dayjs/plugin/customParseFormat";
+import isSameOrAfter from "dayjs/plugin/isSameOrAfter";
+import isSameOrBefore from "dayjs/plugin/isSameOrBefore";
+import isToday from "dayjs/plugin/isToday";
+import weekday from "dayjs/plugin/weekday";
+dayjs.extend(isSameOrAfter);
+dayjs.extend(isSameOrBefore);
+dayjs.extend(customParseFormat);
+dayjs.extend(isToday);
+dayjs.extend(weekday);
+function date(required, options) {
+  const {
+    min,
+    max,
+    format = "YYYY-MM-DD",
+    includes,
+    excludes,
+    mustBePast,
+    mustBeFuture,
+    mustBeToday,
+    mustNotBeToday,
+    weekdaysOnly,
+    weekendsOnly,
+    transform,
+    defaultValue = null,
+    i18n
+  } = options ?? {};
+  const isRequired = required ?? false;
+  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null);
+  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.date.${key}`, params);
+  };
+  const preprocessFn = (val) => {
+    if (val === "" || val === null || val === void 0) {
+      return actualDefaultValue;
+    }
+    let processed = String(val).trim();
+    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 (val !== null && !dayjs(val, format, true).isValid()) {
+      ctx.addIssue({ code: "custom", message: getMessage("format", { format }) });
+      return;
+    }
+    const dateObj = dayjs(val, format);
+    if (val !== null && min !== void 0 && !dateObj.isSameOrAfter(dayjs(min, format))) {
+      ctx.addIssue({ code: "custom", message: getMessage("min", { min }) });
+      return;
+    }
+    if (val !== null && max !== void 0 && !dateObj.isSameOrBefore(dayjs(max, format))) {
+      ctx.addIssue({ code: "custom", message: getMessage("max", { max }) });
+      return;
+    }
+    if (val !== null && includes !== void 0 && !val.includes(includes)) {
+      ctx.addIssue({ code: "custom", message: getMessage("includes", { includes }) });
+      return;
+    }
+    if (val !== null && excludes !== void 0) {
+      const excludeList = Array.isArray(excludes) ? excludes : [excludes];
+      for (const exclude of excludeList) {
+        if (val.includes(exclude)) {
+          ctx.addIssue({ code: "custom", message: getMessage("excludes", { excludes: exclude }) });
+          return;
+        }
+      }
+    }
+    const today = dayjs().startOf("day");
+    const targetDate = dateObj.startOf("day");
+    if (val !== null && mustBePast && !targetDate.isBefore(today)) {
+      ctx.addIssue({ code: "custom", message: getMessage("past") });
+      return;
+    }
+    if (val !== null && mustBeFuture && !targetDate.isAfter(today)) {
+      ctx.addIssue({ code: "custom", message: getMessage("future") });
+      return;
+    }
+    if (val !== null && mustBeToday && !targetDate.isSame(today)) {
+      ctx.addIssue({ code: "custom", message: getMessage("today") });
+      return;
+    }
+    if (val !== null && mustNotBeToday && targetDate.isSame(today)) {
+      ctx.addIssue({ code: "custom", message: getMessage("notToday") });
+      return;
+    }
+    if (val !== null && weekdaysOnly && (dateObj.day() === 0 || dateObj.day() === 6)) {
+      ctx.addIssue({ code: "custom", message: getMessage("weekday") });
+      return;
+    }
+    if (val !== null && weekendsOnly && dateObj.day() !== 0 && dateObj.day() !== 6) {
+      ctx.addIssue({ code: "custom", message: getMessage("weekend") });
+      return;
+    }
+  });
+  return schema;
+}
+
+export {
+  date
+};

package/dist/chunk-4LYZAO3P.js

@@ -0,0 +1,165 @@
+import {
+  getLocale,
+  t
+} from "./chunk-ZBOQCXD4.js";
+
+// src/validators/common/number.ts
+import { z } from "zod";
+function number(required, options) {
+  const { min, max, defaultValue, type = "both", positive, negative, nonNegative, nonPositive, multipleOf, precision, finite = true, transform, parseCommas = false, 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.number.${key}`, params);
+  };
+  const actualDefaultValue = defaultValue ?? null;
+  const schema = z.preprocess(
+    (val) => {
+      if (val === "" || val === void 0 || val === null) {
+        return actualDefaultValue;
+      }
+      if (typeof val === "string") {
+        let processedVal = val.trim();
+        if (parseCommas) {
+          processedVal = processedVal.replace(/,/g, "");
+        }
+        const parsed = Number(processedVal);
+        if (isNaN(parsed)) {
+          return parsed;
+        }
+        if (transform) {
+          return transform(parsed);
+        }
+        return parsed;
+      }
+      if (typeof val === "number") {
+        if (transform && Number.isFinite(val)) {
+          return transform(val);
+        }
+        return val;
+      }
+      return val;
+    },
+    z.union([z.number(), z.null(), z.nan(), z.custom((val) => val === Infinity || val === -Infinity)])
+  ).superRefine((val, ctx) => {
+    if (isRequired && val === null) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("required")
+      });
+      return;
+    }
+    if (val === null) return;
+    if (isNaN(val)) {
+      if (type === "integer") {
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("integer")
+        });
+      } else if (type === "float") {
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("float")
+        });
+      } else {
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("invalid")
+        });
+      }
+      return;
+    }
+    if (finite && !Number.isFinite(val)) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("finite")
+      });
+      return;
+    }
+    if (type === "integer" && !Number.isInteger(val)) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("integer")
+      });
+      return;
+    }
+    if (type === "float" && Number.isInteger(val)) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("float")
+      });
+      return;
+    }
+    if (positive && val <= 0) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("positive")
+      });
+      return;
+    }
+    if (negative && val >= 0) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("negative")
+      });
+      return;
+    }
+    if (nonNegative && val < 0) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("nonNegative")
+      });
+      return;
+    }
+    if (nonPositive && val > 0) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("nonPositive")
+      });
+      return;
+    }
+    if (min !== void 0 && val < min) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("min", { min })
+      });
+      return;
+    }
+    if (max !== void 0 && val > max) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("max", { max })
+      });
+      return;
+    }
+    if (multipleOf !== void 0 && val % multipleOf !== 0) {
+      ctx.addIssue({
+        code: "custom",
+        message: getMessage("multipleOf", { multipleOf })
+      });
+      return;
+    }
+    if (precision !== void 0) {
+      const decimalPlaces = (val.toString().split(".")[1] || "").length;
+      if (decimalPlaces > precision) {
+        ctx.addIssue({
+          code: "custom",
+          message: getMessage("precision", { precision })
+        });
+        return;
+      }
+    }
+  });
+  return schema;
+}
+
+export {
+  number
+};