@hy_ong/zod-kit 0.1.16 → 0.2.0

package/CLAUDE.md

@@ -0,0 +1,142 @@
+# CLAUDE.md — zod-kit
+
+## 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).
+
+- **Version:** 0.1.16
+- **License:** MIT
+- **NPM:** `@hy_ong/zod-kit`
+- **Peer dependency:** Zod ^4.3.6
+- **Production dependency:** dayjs ^1.11.19
+
+## Commands
+
+```bash
+# Run all tests (743 test cases across 17 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)
+npm run build
+# Equivalent to: tsup src/index.ts --format esm,cjs --dts
+
+# Lint
+npx eslint src/
+
+# 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.json             # English messages
+│       └── zh-TW.json          # Traditional Chinese messages
+└── validators/
+    ├── common/                 # 11 universal validators
+    │   ├── boolean.ts
+    │   ├── date.ts
+    │   ├── datetime.ts         # Uses dayjs for parsing
+    │   ├── email.ts
+    │   ├── file.ts
+    │   ├── id.ts               # UUID, nanoid, ObjectId
+    │   ├── number.ts
+    │   ├── password.ts
+    │   ├── text.ts
+    │   ├── time.ts
+    │   └── url.ts
+    └── taiwan/                 # 6 Taiwan-specific validators
+        ├── business-id.ts      # 統一編號 (checksum)
+        ├── fax.ts
+        ├── mobile.ts           # 09X-XXXX-XXXX
+        ├── national-id.ts      # 身分證/居留證 (checksum)
+        ├── 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
+```
+
+## 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
+
+- Locale state is global: `setLocale("en")` / `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)
+
+## 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"))` 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
+
+## 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)
+
+## 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`
+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`