zod-error-map 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# zod-error-map
+
+Type-safe, customizable error message mapping for Zod validation.
+
+## Installation
+
+```bash
+npm install zod-error-map
+```
+
+## Usage
+
+### Basic Usage (Zod v4)
+
+```js
+import { z } from 'zod'
+import { setZodErrorMap } from 'zod-error-map'
+
+setZodErrorMap(z)
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+})
+
+schema.parse({ email: 'invalid', password: '123' })
+// Error: The 'email' must be a valid email address
+```
+
+### Custom Configuration
+
+```js
+import { z } from 'zod'
+import { setZodErrorMap, ErrorCode } from 'zod-error-map'
+
+setZodErrorMap(z, {
+  defaultError: 'Validation failed',
+  formatMessages: {
+    email: (label) => `Please enter a valid email for ${label.quoted}`,
+  },
+  builders: {
+    [ErrorCode.TOO_SMALL]: (issue, label) =>
+      `${label.bare} needs at least ${issue.minimum} characters`,
+  },
+})
+```
+
+### Using the Error Mapper Directly
+
+```js
+import { createErrorMapper } from 'zod-error-map'
+
+const mapper = createErrorMapper({
+  defaultError: 'Invalid input',
+})
+
+const message = mapper.format({
+  code: 'invalid_type',
+  path: ['email'],
+  input: undefined,
+  expected: 'string',
+})
+// "The email is required"
+```
+
+### Zod v3 Compatibility
+
+```js
+import { z } from 'zod'
+import { createZodErrorMap } from 'zod-error-map'
+
+z.setErrorMap(createZodErrorMap())
+```
+
+## API
+
+### `setZodErrorMap(z, config?)`
+
+Sets the global Zod error map using `z.config()` (Zod v4).
+
+### `createZodErrorMap(config?)`
+
+Creates a Zod error map compatible with `z.setErrorMap()` (Zod v3).
+
+### `createErrorMapper(config?)`
+
+Creates an error mapper instance with custom configuration.
+
+### Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `defaultError` | `string` | Default error message when no builder matches |
+| `builders` | `Record<string, MessageBuilder>` | Custom message builders by error code |
+| `formatMessages` | `Record<string, (label) => string>` | Custom messages for format validation errors |
+
+### Error Codes
+
+- `ErrorCode.INVALID_TYPE` - Type mismatch or missing required field
+- `ErrorCode.TOO_SMALL` - Value below minimum length/value
+- `ErrorCode.TOO_BIG` - Value above maximum length/value
+- `ErrorCode.INVALID_FORMAT` - Invalid format (email, uuid, url, etc.)
+- `ErrorCode.CUSTOM` - Custom validation errors
+
+### Format Types
+
+`FormatType.EMAIL`, `FormatType.UUID`, `FormatType.URL`, `FormatType.REGEX`, `FormatType.CUID`, `FormatType.CUID2`, `FormatType.ULID`, `FormatType.IP`, `FormatType.DATE`, `FormatType.DATETIME`, `FormatType.TIME`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "zod-error-map",
+  "version": "0.1.0",
+  "description": "Type-safe, customizable error message mapping for Zod validation",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "!src/**/*.test.js"
+  ],
+  "scripts": {
+    "test": "node --test 'tests/**/*.test.js'",
+    "typecheck": "tsc"
+  },
+  "keywords": [
+    "zod",
+    "validation",
+    "error",
+    "error-map",
+    "error-messages",
+    "typescript"
+  ],
+  "author": "Manoel Lopes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manoel-lopes/zod-error-map.git"
+  },
+  "bugs": {
+    "url": "https://github.com/manoel-lopes/zod-error-map/issues"
+  },
+  "homepage": "https://github.com/manoel-lopes/zod-error-map#readme",
+  "peerDependencies": {
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "zod": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/error-codes.js

@@ -0,0 +1,32 @@
+/**
+ * Zod error codes
+ * @readonly
+ * @enum {string}
+ */
+export const ErrorCode = /** @type {const} */ ({
+  INVALID_TYPE: 'invalid_type',
+  TOO_SMALL: 'too_small',
+  TOO_BIG: 'too_big',
+  INVALID_FORMAT: 'invalid_format',
+  CUSTOM: 'custom',
+})
+
+/**
+ * Format types for invalid_format errors
+ * @readonly
+ * @enum {string}
+ */
+export const FormatType = /** @type {const} */ ({
+  EMAIL: 'email',
+  UUID: 'uuid',
+  URL: 'url',
+  REGEX: 'regex',
+  CUID: 'cuid',
+  CUID2: 'cuid2',
+  ULID: 'ulid',
+  IP: 'ip',
+  EMOJI: 'emoji',
+  DATE: 'date',
+  DATETIME: 'datetime',
+  TIME: 'time',
+})

package/src/error-mapper.js

@@ -0,0 +1,87 @@
+import { createDefaultBuilders } from './message-builders.js'
+
+/**
+ * @typedef {import('./types.js').RawIssue} RawIssue
+ * @typedef {import('./types.js').Label} Label
+ * @typedef {import('./types.js').MessageBuilder} MessageBuilder
+ * @typedef {import('./types.js').ErrorMapConfig} ErrorMapConfig
+ */
+
+const DEFAULT_ERROR = 'Invalid input'
+
+/**
+ * Checks if the issue is a valid RawIssue
+ * @param {unknown} issue
+ * @returns {issue is RawIssue}
+ */
+function isRawIssue(issue) {
+  return (
+    typeof issue === 'object' &&
+    issue !== null &&
+    'code' in issue
+  )
+}
+
+/**
+ * Gets the label from the issue path
+ * @param {RawIssue} issue
+ * @returns {Label}
+ */
+function getLabel(issue) {
+  const path = issue.path ?? []
+  const field = path[path.length - 1]
+  if (typeof field === 'string') {
+    return { bare: field, quoted: `'${field}'` }
+  }
+  return { bare: 'value', quoted: 'value' }
+}
+
+/**
+ * Creates a Zod error mapper with customizable message builders
+ * @param {ErrorMapConfig} [config]
+ * @returns {{ format: (issue: unknown) => string, createErrorMap: () => (issue: unknown) => string }}
+ */
+export function createErrorMapper(config = {}) {
+  const defaultError = config.defaultError ?? DEFAULT_ERROR
+  const defaultBuilders = createDefaultBuilders(defaultError, config.formatMessages)
+  const builders = { ...defaultBuilders, ...config.builders }
+
+  /**
+   * Builds the error message for a Zod issue
+   * @param {RawIssue} issue
+   * @returns {string}
+   */
+  function buildMessage(issue) {
+    const label = getLabel(issue)
+    const builder = builders[issue.code]
+    if (builder) {
+      return builder(issue, label)
+    }
+    return issue.message || defaultError
+  }
+
+  /**
+   * Formats a Zod issue into a human-readable message
+   * @param {unknown} issue
+   * @returns {string}
+   */
+  function format(issue) {
+    if (!isRawIssue(issue)) return defaultError
+    return buildMessage(issue)
+  }
+
+  /**
+   * Creates an error map function for Zod
+   * @returns {(issue: unknown) => string}
+   */
+  function createErrorMap() {
+    return format
+  }
+
+  return { format, createErrorMap }
+}
+
+/**
+ * Default error mapper instance
+ */
+export const defaultErrorMapper = createErrorMapper()

package/src/index.d.ts

@@ -0,0 +1,77 @@
+import type { z } from 'zod'
+
+export interface Label {
+  bare: string
+  quoted: string
+}
+
+export interface RawIssue {
+  code: string
+  path: Array<string | number>
+  input?: unknown
+  expected?: string
+  minimum?: number
+  maximum?: number
+  format?: string
+  message?: string
+}
+
+export type MessageBuilder = (issue: RawIssue, label: Label) => string
+
+export type FormatMessageBuilder = (label: Label) => string
+
+export interface ErrorMapConfig {
+  defaultError?: string
+  builders?: Record<string, MessageBuilder>
+  formatMessages?: Record<string, FormatMessageBuilder>
+}
+
+export interface ErrorMapper {
+  format: (issue: unknown) => string
+  createErrorMap: () => (issue: unknown) => string
+}
+
+export declare const ErrorCode: {
+  readonly INVALID_TYPE: 'invalid_type'
+  readonly TOO_SMALL: 'too_small'
+  readonly TOO_BIG: 'too_big'
+  readonly INVALID_FORMAT: 'invalid_format'
+  readonly CUSTOM: 'custom'
+}
+
+export declare const FormatType: {
+  readonly EMAIL: 'email'
+  readonly UUID: 'uuid'
+  readonly URL: 'url'
+  readonly REGEX: 'regex'
+  readonly CUID: 'cuid'
+  readonly CUID2: 'cuid2'
+  readonly ULID: 'ulid'
+  readonly IP: 'ip'
+  readonly EMOJI: 'emoji'
+  readonly DATE: 'date'
+  readonly DATETIME: 'datetime'
+  readonly TIME: 'time'
+}
+
+export declare function createErrorMapper(config?: ErrorMapConfig): ErrorMapper
+export declare const defaultErrorMapper: ErrorMapper
+
+export declare function getInputDescription(input: unknown): string
+export declare const defaultFormatMessages: Record<string, (label: Label) => string>
+export declare function buildInvalidTypeMessage(issue: RawIssue, label: Label): string
+export declare function buildTooSmallMessage(issue: RawIssue, label: Label): string
+export declare function buildTooBigMessage(issue: RawIssue, label: Label): string
+export declare function createFormatMessageBuilder(
+  formatMessages?: Record<string, (label: Label) => string>
+): MessageBuilder
+export declare function createCustomMessageBuilder(defaultError: string): MessageBuilder
+export declare function createDefaultBuilders(
+  defaultError: string,
+  formatMessages?: Record<string, (label: Label) => string>
+): Record<string, MessageBuilder>
+
+export declare function setZodErrorMap(z: typeof import('zod').z, config?: ErrorMapConfig): void
+export declare function createZodErrorMap(
+  config?: ErrorMapConfig
+): (issue: unknown, ctx: unknown) => { message: string }

package/src/index.js

@@ -0,0 +1,22 @@
+export { ErrorCode, FormatType } from './error-codes.js'
+
+export {
+  createErrorMapper,
+  defaultErrorMapper,
+} from './error-mapper.js'
+
+export {
+  getInputDescription,
+  defaultFormatMessages,
+  buildInvalidTypeMessage,
+  buildTooSmallMessage,
+  buildTooBigMessage,
+  createFormatMessageBuilder,
+  createCustomMessageBuilder,
+  createDefaultBuilders,
+} from './message-builders.js'
+
+export {
+  setZodErrorMap,
+  createZodErrorMap,
+} from './zod-integration.js'

package/src/message-builders.js

@@ -0,0 +1,108 @@
+import { ErrorCode, FormatType } from './error-codes.js'
+
+/**
+ * @typedef {import('./types.js').RawIssue} RawIssue
+ * @typedef {import('./types.js').Label} Label
+ * @typedef {import('./types.js').MessageBuilder} MessageBuilder
+ */
+
+/**
+ * Gets a human-readable description of the input type
+ * @param {unknown} input
+ * @returns {string}
+ */
+export function getInputDescription(input) {
+  if (input === undefined) return 'undefined'
+  if (input === null) return 'null'
+  if (Array.isArray(input)) return 'array'
+  return typeof input
+}
+
+/**
+ * Default format error messages
+ * @type {Record<string, (label: Label) => string>}
+ */
+export const defaultFormatMessages = {
+  [FormatType.EMAIL]: (label) => `The ${label.quoted} must be a valid email address`,
+  [FormatType.UUID]: (label) => `The ${label.quoted} must be a valid UUID`,
+  [FormatType.URL]: (label) => `The ${label.quoted} must be a valid URL`,
+  [FormatType.REGEX]: (label) => `The ${label.quoted} has an invalid format`,
+  [FormatType.CUID]: (label) => `The ${label.quoted} must be a valid CUID`,
+  [FormatType.CUID2]: (label) => `The ${label.quoted} must be a valid CUID2`,
+  [FormatType.ULID]: (label) => `The ${label.quoted} must be a valid ULID`,
+  [FormatType.IP]: (label) => `The ${label.quoted} must be a valid IP address`,
+  [FormatType.DATE]: (label) => `The ${label.quoted} must be a valid date`,
+  [FormatType.DATETIME]: (label) => `The ${label.quoted} must be a valid datetime`,
+  [FormatType.TIME]: (label) => `The ${label.quoted} must be a valid time`,
+}
+
+/**
+ * Builds error message for invalid_type errors
+ * @type {MessageBuilder}
+ */
+export function buildInvalidTypeMessage(issue, label) {
+  const received = getInputDescription(issue.input)
+  if (received === 'undefined') {
+    return `The ${label.bare} is required`
+  }
+  return `Expected ${issue.expected} for ${label.quoted}, received ${received}`
+}
+
+/**
+ * Builds error message for too_small errors
+ * @type {MessageBuilder}
+ */
+export function buildTooSmallMessage(issue, label) {
+  const min = Number(issue.minimum) || 0
+  return `The ${label.quoted} must contain at least ${min} characters`
+}
+
+/**
+ * Builds error message for too_big errors
+ * @type {MessageBuilder}
+ */
+export function buildTooBigMessage(issue, label) {
+  const max = Number(issue.maximum) || 0
+  return `The ${label.quoted} must contain at most ${max} characters`
+}
+
+/**
+ * Creates a format message builder with custom format messages
+ * @param {Record<string, (label: Label) => string>} [formatMessages]
+ * @returns {MessageBuilder}
+ */
+export function createFormatMessageBuilder(formatMessages = defaultFormatMessages) {
+  return (issue, label) => {
+    const format = issue.format || ''
+    const messageBuilder = formatMessages[format]
+    if (messageBuilder) {
+      return messageBuilder(label)
+    }
+    return `The ${label.quoted} has an invalid format`
+  }
+}
+
+/**
+ * Builds error message for custom errors
+ * @param {string} defaultError
+ * @returns {MessageBuilder}
+ */
+export function createCustomMessageBuilder(defaultError) {
+  return (issue, _label) => issue.message || defaultError
+}
+
+/**
+ * Creates the default message builders map
+ * @param {string} defaultError
+ * @param {Record<string, (label: Label) => string>} [formatMessages]
+ * @returns {Record<string, MessageBuilder>}
+ */
+export function createDefaultBuilders(defaultError, formatMessages) {
+  return {
+    [ErrorCode.INVALID_TYPE]: buildInvalidTypeMessage,
+    [ErrorCode.TOO_SMALL]: buildTooSmallMessage,
+    [ErrorCode.TOO_BIG]: buildTooBigMessage,
+    [ErrorCode.INVALID_FORMAT]: createFormatMessageBuilder(formatMessages),
+    [ErrorCode.CUSTOM]: createCustomMessageBuilder(defaultError),
+  }
+}

package/src/types.js

@@ -0,0 +1,37 @@
+/**
+ * @typedef {object} Label
+ * @property {string} bare - The field name without quotes
+ * @property {string} quoted - The field name with quotes
+ */
+
+/**
+ * @typedef {object} RawIssue
+ * @property {string} code - The error code from Zod
+ * @property {Array<string | number>} path - The path to the field
+ * @property {unknown} [input] - The input value that caused the error
+ * @property {string} [expected] - The expected type
+ * @property {number} [minimum] - Minimum value/length constraint
+ * @property {number} [maximum] - Maximum value/length constraint
+ * @property {string} [format] - Format type (email, uuid, url, etc.)
+ * @property {string} [message] - Custom error message
+ */
+
+/**
+ * @callback MessageBuilder
+ * @param {RawIssue} issue - The raw Zod issue
+ * @param {Label} label - The field label
+ * @returns {string} The formatted error message
+ */
+
+/**
+ * @typedef {(label: Label) => string} FormatMessageBuilder
+ */
+
+/**
+ * @typedef {object} ErrorMapConfig
+ * @property {string} [defaultError] - Default error message
+ * @property {Record<string, MessageBuilder>} [builders] - Custom message builders by error code
+ * @property {Record<string, FormatMessageBuilder>} [formatMessages] - Custom messages for format errors
+ */
+
+export {}

package/src/zod-integration.js

@@ -0,0 +1,31 @@
+/**
+ * @typedef {import('./types.js').ErrorMapConfig} ErrorMapConfig
+ */
+
+import { createErrorMapper } from './error-mapper.js'
+
+/**
+ * Sets the global Zod error map using z.config()
+ * @param {import('zod')} z - The Zod instance
+ * @param {ErrorMapConfig} [config] - Optional configuration
+ * @returns {void}
+ */
+export function setZodErrorMap(z, config) {
+  const mapper = createErrorMapper(config)
+  z.config({
+    customError: (issue) => mapper.format(issue),
+  })
+}
+
+/**
+ * Creates a Zod error map function compatible with z.setErrorMap() (Zod v3)
+ * @param {ErrorMapConfig} [config] - Optional configuration
+ * @returns {(issue: unknown, ctx: unknown) => { message: string }}
+ */
+export function createZodErrorMap(config) {
+  const mapper = createErrorMapper(config)
+  return (issue, _ctx) => {
+    const message = mapper.format(issue)
+    return { message }
+  }
+}