@hy_ong/zod-kit 0.1.1 → 0.1.2

package/dist/index.cjs

@@ -1291,35 +1291,31 @@ var validateIdType = (value, type) => {
   return pattern ? pattern.test(value) : false;
 };
 function id(required, options) {
-  const {
-    type = "auto",
-    minLength,
-    maxLength,
-    allowedTypes,
-    customRegex,
-    includes,
-    excludes,
-    startsWith,
-    endsWith,
-    caseSensitive = true,
-    transform,
-    defaultValue,
-    i18n
-  } = options ?? {};
+  const { type = "auto", minLength, maxLength, allowedTypes, customRegex, includes, excludes, startsWith, endsWith, caseSensitive = true, transform, defaultValue, i18n } = options ?? {};
   const isRequired = required ?? false;
-  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null);
+  const isNumericType = type === "numeric";
+  const actualDefaultValue = defaultValue !== void 0 ? defaultValue : isRequired ? isNumericType ? NaN : "" : null;
   const getMessage = (key, params) => {
     if (i18n) {
       const currentLocale2 = getLocale();
       const customMessages = i18n[currentLocale2];
       if (customMessages && customMessages[key]) {
         const template = customMessages[key];
-        return template.replace(/\$\{(\w+)}/g, (_, k) => params?.[k] ?? "");
+        return template.replace(/\$\{(\w+)}/g, (_match, k) => params?.[k] ?? "");
       }
     }
     return t(`common.id.${key}`, params);
   };
-  const preprocessFn = (val) => {
+  const preprocessNumericFn = (val) => {
+    if (val === "" || val === null || val === void 0) {
+      if (isRequired && defaultValue === void 0) {
+        return void 0;
+      }
+      return actualDefaultValue;
+    }
+    return Number(val);
+  };
+  const preprocessStringFn = (val) => {
     if (val === "" || val === null || val === void 0) {
       return actualDefaultValue;
     }
@@ -1329,7 +1325,30 @@ function id(required, options) {
     }
     return processed;
   };
-  const baseSchema = isRequired ? import_zod6.z.preprocess(preprocessFn, import_zod6.z.string()) : import_zod6.z.preprocess(preprocessFn, import_zod6.z.string().nullable());
+  if (isNumericType) {
+    const numericSchema = import_zod6.z.preprocess(preprocessNumericFn, import_zod6.z.any()).refine((val) => {
+      if (!isRequired && val === null) return true;
+      if (val === void 0 || isRequired && val === null) {
+        throw new import_zod6.z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }]);
+      }
+      if (typeof val !== "number" || isNaN(val)) {
+        throw new import_zod6.z.ZodError([{ code: "custom", message: getMessage("numeric"), path: [] }]);
+      }
+      const strVal = String(val);
+      if (!ID_PATTERNS.numeric.test(strVal)) {
+        throw new import_zod6.z.ZodError([{ code: "custom", message: getMessage("numeric"), path: [] }]);
+      }
+      if (minLength !== void 0 && strVal.length < minLength) {
+        throw new import_zod6.z.ZodError([{ code: "custom", message: getMessage("minLength", { minLength }), path: [] }]);
+      }
+      if (maxLength !== void 0 && strVal.length > maxLength) {
+        throw new import_zod6.z.ZodError([{ code: "custom", message: getMessage("maxLength", { maxLength }), path: [] }]);
+      }
+      return true;
+    });
+    return numericSchema;
+  }
+  const baseSchema = isRequired ? import_zod6.z.preprocess(preprocessStringFn, import_zod6.z.string()) : import_zod6.z.preprocess(preprocessStringFn, import_zod6.z.string().nullable());
   const schema = baseSchema.refine((val) => {
     if (val === null) return true;
     if (isRequired && (val === "" || val === "null" || val === "undefined")) {
@@ -1355,7 +1374,7 @@ function id(required, options) {
           const typeNames = allowedTypes.join(", ");
           throw new import_zod6.z.ZodError([{ code: "custom", message: getMessage("invalid") + ` (allowed types: ${typeNames})`, path: [] }]);
         }
-      } else if (type !== "auto") {
+      } else if (type && type !== "auto") {
         isValidId = validateIdType(val, type);
         if (!isValidId) {
           throw new import_zod6.z.ZodError([{ code: "custom", message: getMessage(type) || getMessage("invalid"), path: [] }]);
@@ -1366,7 +1385,7 @@ function id(required, options) {
           throw new import_zod6.z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }]);
         }
       }
-    } else if (val !== null && hasContentValidations && type !== "auto" && !customRegex) {
+    } else if (val !== null && hasContentValidations && type && type !== "auto" && !customRegex) {
       if (allowedTypes && allowedTypes.length > 0) {
         const isValidType = allowedTypes.some((allowedType) => validateIdType(val, allowedType));
         if (!isValidType) {

package/dist/index.d.cts

@@ -978,10 +978,11 @@ type IdType = "numeric" | "uuid" | "objectId" | "nanoid" | "snowflake" | "cuid"
  * Configuration options for ID validation
  *
  * @template IsRequired - Whether the field is required (affects return type)
+ * @template Type - The ID type being validated
  *
  * @interface IdOptions
  * @property {IsRequired} [required=true] - Whether the field is required
- * @property {IdType} [type="auto"] - Expected ID type or auto-detection
+ * @property {Type} [type="auto"] - Expected ID type or auto-detection
  * @property {number} [minLength] - Minimum length of ID
  * @property {number} [maxLength] - Maximum length of ID
  * @property {IdType[]} [allowedTypes] - Multiple allowed ID types (overrides type)
@@ -992,11 +993,11 @@ type IdType = "numeric" | "uuid" | "objectId" | "nanoid" | "snowflake" | "cuid"
  * @property {string} [endsWith] - String that ID must end with
  * @property {boolean} [caseSensitive=true] - Whether validation is case-sensitive
  * @property {Function} [transform] - Custom transformation function for ID
- * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {any} [defaultValue] - Default value when input is empty (string for string types, number for numeric)
  * @property {Record<Locale, IdMessages>} [i18n] - Custom error messages for different locales
  */
-type IdOptions<IsRequired extends boolean = true> = {
-    type?: IdType;
+type IdOptions<Type extends IdType | undefined = undefined> = {
+    type?: Type;
     minLength?: number;
     maxLength?: number;
     allowedTypes?: IdType[];
@@ -1007,17 +1008,20 @@ type IdOptions<IsRequired extends boolean = true> = {
     endsWith?: string;
     caseSensitive?: boolean;
     transform?: (value: string) => string;
-    defaultValue?: IsRequired extends true ? string : string | null;
+    defaultValue?: any;
     i18n?: Record<Locale, IdMessages>;
 };
 /**
- * Type alias for ID validation schema based on required flag
+ * Type alias for ID validation schema based on required flag and ID type
  *
  * @template IsRequired - Whether the field is required
+ * @template IdType - The ID type being validated
  * @typedef IdSchema
- * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ * @description Returns appropriate Zod type based on required flag and ID type:
+ * - numeric type: ZodNumber or ZodNullable<ZodNumber>
+ * - other types: ZodString or ZodNullable<ZodString>
  */
-type IdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+type IdSchema<IsRequired extends boolean, Type extends IdType | undefined = undefined> = Type extends "numeric" ? IsRequired extends true ? ZodNumber : ZodNullable<ZodNumber> : IsRequired extends true ? ZodString : ZodNullable<ZodString>;
 /**
  * Regular expression patterns for different ID formats
  *
@@ -1079,9 +1083,9 @@ declare const validateIdType: (value: string, type: IdType) => boolean;
  * Creates a Zod schema for ID validation with comprehensive format support
  *
  * @template IsRequired - Whether the field is required (affects return type)
+ * @template Type - The ID type being validated (affects return type for numeric)
  * @param {IsRequired} [required=false] - Whether the field is required
- * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
- * @returns {IdSchema<IsRequired>} Zod schema for ID validation
+ * @returns {IdSchema<IsRequired, Type>} Zod schema for ID validation
  *
  * @description
  * Creates a comprehensive ID validator with support for multiple ID formats,
@@ -1149,7 +1153,16 @@ declare const validateIdType: (value: string, type: IdType) => boolean;
  * @see {@link detectIdType} for auto-detection logic
  * @see {@link validateIdType} for type-specific validation
  */
-declare function id<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<IdOptions<IsRequired>, 'required'>): IdSchema<IsRequired>;
+declare function id<IsRequired extends boolean = false>(required?: IsRequired): IdSchema<IsRequired, undefined>;
+declare function id<IsRequired extends boolean = false>(required: IsRequired, options: Omit<IdOptions<"numeric">, "required"> & {
+    type: "numeric";
+}): IdSchema<IsRequired, "numeric">;
+declare function id<IsRequired extends boolean = false, Type extends Exclude<IdType, "numeric"> = Exclude<IdType, "numeric">>(required: IsRequired, options: Omit<IdOptions<Type>, "required"> & {
+    type: Type;
+}): IdSchema<IsRequired, Type>;
+declare function id<IsRequired extends boolean = false>(required: IsRequired, options: Omit<IdOptions, "required"> & {
+    type?: never;
+}): IdSchema<IsRequired, undefined>;
 
 /**
  * @fileoverview Number validator for Zod Kit

package/dist/index.d.ts

@@ -978,10 +978,11 @@ type IdType = "numeric" | "uuid" | "objectId" | "nanoid" | "snowflake" | "cuid"
  * Configuration options for ID validation
  *
  * @template IsRequired - Whether the field is required (affects return type)
+ * @template Type - The ID type being validated
  *
  * @interface IdOptions
  * @property {IsRequired} [required=true] - Whether the field is required
- * @property {IdType} [type="auto"] - Expected ID type or auto-detection
+ * @property {Type} [type="auto"] - Expected ID type or auto-detection
  * @property {number} [minLength] - Minimum length of ID
  * @property {number} [maxLength] - Maximum length of ID
  * @property {IdType[]} [allowedTypes] - Multiple allowed ID types (overrides type)
@@ -992,11 +993,11 @@ type IdType = "numeric" | "uuid" | "objectId" | "nanoid" | "snowflake" | "cuid"
  * @property {string} [endsWith] - String that ID must end with
  * @property {boolean} [caseSensitive=true] - Whether validation is case-sensitive
  * @property {Function} [transform] - Custom transformation function for ID
- * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {any} [defaultValue] - Default value when input is empty (string for string types, number for numeric)
  * @property {Record<Locale, IdMessages>} [i18n] - Custom error messages for different locales
  */
-type IdOptions<IsRequired extends boolean = true> = {
-    type?: IdType;
+type IdOptions<Type extends IdType | undefined = undefined> = {
+    type?: Type;
     minLength?: number;
     maxLength?: number;
     allowedTypes?: IdType[];
@@ -1007,17 +1008,20 @@ type IdOptions<IsRequired extends boolean = true> = {
     endsWith?: string;
     caseSensitive?: boolean;
     transform?: (value: string) => string;
-    defaultValue?: IsRequired extends true ? string : string | null;
+    defaultValue?: any;
     i18n?: Record<Locale, IdMessages>;
 };
 /**
- * Type alias for ID validation schema based on required flag
+ * Type alias for ID validation schema based on required flag and ID type
  *
  * @template IsRequired - Whether the field is required
+ * @template IdType - The ID type being validated
  * @typedef IdSchema
- * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ * @description Returns appropriate Zod type based on required flag and ID type:
+ * - numeric type: ZodNumber or ZodNullable<ZodNumber>
+ * - other types: ZodString or ZodNullable<ZodString>
  */
-type IdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>;
+type IdSchema<IsRequired extends boolean, Type extends IdType | undefined = undefined> = Type extends "numeric" ? IsRequired extends true ? ZodNumber : ZodNullable<ZodNumber> : IsRequired extends true ? ZodString : ZodNullable<ZodString>;
 /**
  * Regular expression patterns for different ID formats
  *
@@ -1079,9 +1083,9 @@ declare const validateIdType: (value: string, type: IdType) => boolean;
  * Creates a Zod schema for ID validation with comprehensive format support
  *
  * @template IsRequired - Whether the field is required (affects return type)
+ * @template Type - The ID type being validated (affects return type for numeric)
  * @param {IsRequired} [required=false] - Whether the field is required
- * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
- * @returns {IdSchema<IsRequired>} Zod schema for ID validation
+ * @returns {IdSchema<IsRequired, Type>} Zod schema for ID validation
  *
  * @description
  * Creates a comprehensive ID validator with support for multiple ID formats,
@@ -1149,7 +1153,16 @@ declare const validateIdType: (value: string, type: IdType) => boolean;
  * @see {@link detectIdType} for auto-detection logic
  * @see {@link validateIdType} for type-specific validation
  */
-declare function id<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<IdOptions<IsRequired>, 'required'>): IdSchema<IsRequired>;
+declare function id<IsRequired extends boolean = false>(required?: IsRequired): IdSchema<IsRequired, undefined>;
+declare function id<IsRequired extends boolean = false>(required: IsRequired, options: Omit<IdOptions<"numeric">, "required"> & {
+    type: "numeric";
+}): IdSchema<IsRequired, "numeric">;
+declare function id<IsRequired extends boolean = false, Type extends Exclude<IdType, "numeric"> = Exclude<IdType, "numeric">>(required: IsRequired, options: Omit<IdOptions<Type>, "required"> & {
+    type: Type;
+}): IdSchema<IsRequired, Type>;
+declare function id<IsRequired extends boolean = false>(required: IsRequired, options: Omit<IdOptions, "required"> & {
+    type?: never;
+}): IdSchema<IsRequired, undefined>;
 
 /**
  * @fileoverview Number validator for Zod Kit

package/dist/index.js

@@ -1213,35 +1213,31 @@ var validateIdType = (value, type) => {
   return pattern ? pattern.test(value) : false;
 };
 function id(required, options) {
-  const {
-    type = "auto",
-    minLength,
-    maxLength,
-    allowedTypes,
-    customRegex,
-    includes,
-    excludes,
-    startsWith,
-    endsWith,
-    caseSensitive = true,
-    transform,
-    defaultValue,
-    i18n
-  } = options ?? {};
+  const { type = "auto", minLength, maxLength, allowedTypes, customRegex, includes, excludes, startsWith, endsWith, caseSensitive = true, transform, defaultValue, i18n } = options ?? {};
   const isRequired = required ?? false;
-  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null);
+  const isNumericType = type === "numeric";
+  const actualDefaultValue = defaultValue !== void 0 ? defaultValue : isRequired ? isNumericType ? NaN : "" : null;
   const getMessage = (key, params) => {
     if (i18n) {
       const currentLocale2 = getLocale();
       const customMessages = i18n[currentLocale2];
       if (customMessages && customMessages[key]) {
         const template = customMessages[key];
-        return template.replace(/\$\{(\w+)}/g, (_, k) => params?.[k] ?? "");
+        return template.replace(/\$\{(\w+)}/g, (_match, k) => params?.[k] ?? "");
       }
     }
     return t(`common.id.${key}`, params);
   };
-  const preprocessFn = (val) => {
+  const preprocessNumericFn = (val) => {
+    if (val === "" || val === null || val === void 0) {
+      if (isRequired && defaultValue === void 0) {
+        return void 0;
+      }
+      return actualDefaultValue;
+    }
+    return Number(val);
+  };
+  const preprocessStringFn = (val) => {
     if (val === "" || val === null || val === void 0) {
       return actualDefaultValue;
     }
@@ -1251,7 +1247,30 @@ function id(required, options) {
     }
     return processed;
   };
-  const baseSchema = isRequired ? z6.preprocess(preprocessFn, z6.string()) : z6.preprocess(preprocessFn, z6.string().nullable());
+  if (isNumericType) {
+    const numericSchema = z6.preprocess(preprocessNumericFn, z6.any()).refine((val) => {
+      if (!isRequired && val === null) return true;
+      if (val === void 0 || isRequired && val === null) {
+        throw new z6.ZodError([{ code: "custom", message: getMessage("required"), path: [] }]);
+      }
+      if (typeof val !== "number" || isNaN(val)) {
+        throw new z6.ZodError([{ code: "custom", message: getMessage("numeric"), path: [] }]);
+      }
+      const strVal = String(val);
+      if (!ID_PATTERNS.numeric.test(strVal)) {
+        throw new z6.ZodError([{ code: "custom", message: getMessage("numeric"), path: [] }]);
+      }
+      if (minLength !== void 0 && strVal.length < minLength) {
+        throw new z6.ZodError([{ code: "custom", message: getMessage("minLength", { minLength }), path: [] }]);
+      }
+      if (maxLength !== void 0 && strVal.length > maxLength) {
+        throw new z6.ZodError([{ code: "custom", message: getMessage("maxLength", { maxLength }), path: [] }]);
+      }
+      return true;
+    });
+    return numericSchema;
+  }
+  const baseSchema = isRequired ? z6.preprocess(preprocessStringFn, z6.string()) : z6.preprocess(preprocessStringFn, z6.string().nullable());
   const schema = baseSchema.refine((val) => {
     if (val === null) return true;
     if (isRequired && (val === "" || val === "null" || val === "undefined")) {
@@ -1277,7 +1296,7 @@ function id(required, options) {
           const typeNames = allowedTypes.join(", ");
           throw new z6.ZodError([{ code: "custom", message: getMessage("invalid") + ` (allowed types: ${typeNames})`, path: [] }]);
         }
-      } else if (type !== "auto") {
+      } else if (type && type !== "auto") {
         isValidId = validateIdType(val, type);
         if (!isValidId) {
           throw new z6.ZodError([{ code: "custom", message: getMessage(type) || getMessage("invalid"), path: [] }]);
@@ -1288,7 +1307,7 @@ function id(required, options) {
           throw new z6.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }]);
         }
       }
-    } else if (val !== null && hasContentValidations && type !== "auto" && !customRegex) {
+    } else if (val !== null && hasContentValidations && type && type !== "auto" && !customRegex) {
       if (allowedTypes && allowedTypes.length > 0) {
         const isValidType = allowedTypes.some((allowedType) => validateIdType(val, allowedType));
         if (!isValidType) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hy_ong/zod-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A comprehensive TypeScript library providing pre-built Zod validation schemas with full internationalization support for common data types and Taiwan-specific formats",
   "keywords": [
     "zod",

package/src/validators/common/id.ts

@@ -8,7 +8,7 @@
  * @version 0.0.5
  */
 
-import { z, ZodNullable, ZodString } from "zod"
+import { z, ZodNullable, ZodString, ZodNumber } from "zod"
 import { t } from "../../i18n"
 import { getLocale, type Locale } from "../../config"
 
@@ -85,10 +85,11 @@ export type IdType =
  * Configuration options for ID validation
  *
  * @template IsRequired - Whether the field is required (affects return type)
+ * @template Type - The ID type being validated
  *
  * @interface IdOptions
  * @property {IsRequired} [required=true] - Whether the field is required
- * @property {IdType} [type="auto"] - Expected ID type or auto-detection
+ * @property {Type} [type="auto"] - Expected ID type or auto-detection
  * @property {number} [minLength] - Minimum length of ID
  * @property {number} [maxLength] - Maximum length of ID
  * @property {IdType[]} [allowedTypes] - Multiple allowed ID types (overrides type)
@@ -99,11 +100,11 @@ export type IdType =
  * @property {string} [endsWith] - String that ID must end with
  * @property {boolean} [caseSensitive=true] - Whether validation is case-sensitive
  * @property {Function} [transform] - Custom transformation function for ID
- * @property {string | null} [defaultValue] - Default value when input is empty
+ * @property {any} [defaultValue] - Default value when input is empty (string for string types, number for numeric)
  * @property {Record<Locale, IdMessages>} [i18n] - Custom error messages for different locales
  */
-export type IdOptions<IsRequired extends boolean = true> = {
-  type?: IdType
+export type IdOptions<Type extends IdType | undefined = undefined> = {
+  type?: Type
   minLength?: number
   maxLength?: number
   allowedTypes?: IdType[]
@@ -114,18 +115,27 @@ export type IdOptions<IsRequired extends boolean = true> = {
   endsWith?: string
   caseSensitive?: boolean
   transform?: (value: string) => string
-  defaultValue?: IsRequired extends true ? string : string | null
+  defaultValue?: any // Simplified to avoid complex conditional types
   i18n?: Record<Locale, IdMessages>
 }
 
 /**
- * Type alias for ID validation schema based on required flag
+ * Type alias for ID validation schema based on required flag and ID type
  *
  * @template IsRequired - Whether the field is required
+ * @template IdType - The ID type being validated
  * @typedef IdSchema
- * @description Returns ZodString if required, ZodNullable<ZodString> if optional
+ * @description Returns appropriate Zod type based on required flag and ID type:
+ * - numeric type: ZodNumber or ZodNullable<ZodNumber>
+ * - other types: ZodString or ZodNullable<ZodString>
  */
-export type IdSchema<IsRequired extends boolean> = IsRequired extends true ? ZodString : ZodNullable<ZodString>
+export type IdSchema<IsRequired extends boolean, Type extends IdType | undefined = undefined> = Type extends "numeric"
+  ? IsRequired extends true
+    ? ZodNumber
+    : ZodNullable<ZodNumber>
+  : IsRequired extends true
+    ? ZodString
+    : ZodNullable<ZodString>
 
 /**
  * Regular expression patterns for different ID formats
@@ -216,9 +226,9 @@ const validateIdType = (value: string, type: IdType): boolean => {
  * Creates a Zod schema for ID validation with comprehensive format support
  *
  * @template IsRequired - Whether the field is required (affects return type)
+ * @template Type - The ID type being validated (affects return type for numeric)
  * @param {IsRequired} [required=false] - Whether the field is required
- * @param {Omit<ValidatorOptions<IsRequired>, 'required'>} [options] - Configuration options for validation
- * @returns {IdSchema<IsRequired>} Zod schema for ID validation
+ * @returns {IdSchema<IsRequired, Type>} Zod schema for ID validation
  *
  * @description
  * Creates a comprehensive ID validator with support for multiple ID formats,
@@ -286,27 +296,31 @@ const validateIdType = (value: string, type: IdType): boolean => {
  * @see {@link detectIdType} for auto-detection logic
  * @see {@link validateIdType} for type-specific validation
  */
-export function id<IsRequired extends boolean = false>(required?: IsRequired, options?: Omit<IdOptions<IsRequired>, 'required'>): IdSchema<IsRequired> {
-  const {
-    type = "auto",
-    minLength,
-    maxLength,
-    allowedTypes,
-    customRegex,
-    includes,
-    excludes,
-    startsWith,
-    endsWith,
-    caseSensitive = true,
-    transform,
-    defaultValue,
-    i18n,
-  } = options ?? {}
-
-  const isRequired = required ?? false as IsRequired
-
-  // Set appropriate default value based on required flag
-  const actualDefaultValue = defaultValue ?? (isRequired ? "" : null)
+// Overload: no options provided
+export function id<IsRequired extends boolean = false>(required?: IsRequired): IdSchema<IsRequired, undefined>
+
+// Overload: options with numeric type
+export function id<IsRequired extends boolean = false>(required: IsRequired, options: Omit<IdOptions<"numeric">, "required"> & { type: "numeric" }): IdSchema<IsRequired, "numeric">
+
+// Overload: options with other specific type
+export function id<IsRequired extends boolean = false, Type extends Exclude<IdType, "numeric"> = Exclude<IdType, "numeric">>(
+  required: IsRequired,
+  options: Omit<IdOptions<Type>, "required"> & { type: Type }
+): IdSchema<IsRequired, Type>
+
+// Overload: options without type specified
+export function id<IsRequired extends boolean = false>(required: IsRequired, options: Omit<IdOptions, "required"> & { type?: never }): IdSchema<IsRequired, undefined>
+
+// Implementation
+export function id<IsRequired extends boolean = false, Type extends IdType | undefined = undefined>(required?: IsRequired, options?: any): any {
+  const { type = "auto" as Type, minLength, maxLength, allowedTypes, customRegex, includes, excludes, startsWith, endsWith, caseSensitive = true, transform, defaultValue, i18n } = options ?? {}
+
+  const isRequired = (required ?? false) as IsRequired
+  const isNumericType = type === "numeric"
+
+  // Set appropriate default value based on required flag and type
+  // For required fields, we don't set a default unless explicitly provided
+  const actualDefaultValue = defaultValue !== undefined ? defaultValue : isRequired ? (isNumericType ? NaN : "") : null
 
   // Helper function to get custom message or fallback to default i18n
   const getMessage = (key: keyof IdMessages, params?: Record<string, any>) => {
@@ -315,14 +329,30 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
       const customMessages = i18n[currentLocale]
       if (customMessages && customMessages[key]) {
         const template = customMessages[key]!
-        return template.replace(/\$\{(\w+)}/g, (_, k) => params?.[k] ?? "")
+        return template.replace(/\$\{(\w+)}/g, (_match: string, k: string) => params?.[k] ?? "")
       }
     }
     return t(`common.id.${key}`, params)
   }
 
-  // Preprocessing function
-  const preprocessFn = (val: unknown) => {
+  // Preprocessing function for numeric type
+  const preprocessNumericFn = (val: unknown) => {
+    // Handle empty/null values
+    if (val === "" || val === null || val === undefined) {
+      // If required and no default, return a special marker that will fail validation
+      if (isRequired && defaultValue === undefined) {
+        // Return undefined to trigger required error in refine
+        return undefined as any
+      }
+      return actualDefaultValue
+    }
+
+    // Try to convert to number and return (even if NaN) so it can be validated by the schema
+    return Number(val)
+  }
+
+  // Preprocessing function for string type
+  const preprocessStringFn = (val: unknown) => {
     if (val === "" || val === null || val === undefined) {
       return actualDefaultValue
     }
@@ -336,7 +366,44 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
     return processed
   }
 
-  const baseSchema = isRequired ? z.preprocess(preprocessFn, z.string()) : z.preprocess(preprocessFn, z.string().nullable())
+  // Create base schema based on type
+  if (isNumericType) {
+    // Use z.any() to avoid Zod's built-in type checking, then validate manually
+    const numericSchema = z.preprocess(preprocessNumericFn, z.any()).refine((val) => {
+      // Allow null for optional fields
+      if (!isRequired && val === null) return true
+
+      // Required check for undefined/null/empty (empty string when required)
+      if (val === undefined || (isRequired && val === null)) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("required"), path: [] }])
+      }
+
+      // Numeric validation - check if it's an actual number (not NaN)
+      if (typeof val !== "number" || isNaN(val)) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("numeric"), path: [] }])
+      }
+
+      // Length checks on string representation
+      const strVal = String(val)
+      if (!ID_PATTERNS.numeric.test(strVal)) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("numeric"), path: [] }])
+      }
+
+      if (minLength !== undefined && strVal.length < minLength) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("minLength", { minLength }), path: [] }])
+      }
+      if (maxLength !== undefined && strVal.length > maxLength) {
+        throw new z.ZodError([{ code: "custom", message: getMessage("maxLength", { maxLength }), path: [] }])
+      }
+
+      return true
+    })
+
+    return numericSchema as unknown as IdSchema<IsRequired, Type>
+  }
+
+  // String-based ID validation
+  const baseSchema = isRequired ? z.preprocess(preprocessStringFn, z.string()) : z.preprocess(preprocessStringFn, z.string().nullable())
 
   const schema = baseSchema
     .refine((val) => {
@@ -372,12 +439,12 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
 
         if (allowedTypes && allowedTypes.length > 0) {
           // Check if ID matches any of the allowed types
-          isValidId = allowedTypes.some((allowedType) => validateIdType(val, allowedType))
+          isValidId = allowedTypes.some((allowedType: IdType) => validateIdType(val, allowedType))
           if (!isValidId) {
             const typeNames = allowedTypes.join(", ")
             throw new z.ZodError([{ code: "custom", message: getMessage("invalid") + ` (allowed types: ${typeNames})`, path: [] }])
           }
-        } else if (type !== "auto") {
+        } else if (type && type !== "auto") {
           // Validate specific type
           isValidId = validateIdType(val, type)
           if (!isValidId) {
@@ -390,10 +457,10 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
             throw new z.ZodError([{ code: "custom", message: getMessage("invalid"), path: [] }])
           }
         }
-      } else if (val !== null && hasContentValidations && type !== "auto" && !customRegex) {
+      } else if (val !== null && hasContentValidations && type && type !== "auto" && !customRegex) {
         // Still validate specific types even with content validations (but not auto)
         if (allowedTypes && allowedTypes.length > 0) {
-          const isValidType = allowedTypes.some((allowedType) => validateIdType(val, allowedType))
+          const isValidType = allowedTypes.some((allowedType: IdType) => validateIdType(val, allowedType))
           if (!isValidType) {
             const typeNames = allowedTypes.join(", ")
             throw new z.ZodError([{ code: "custom", message: getMessage("invalid") + ` (allowed types: ${typeNames})`, path: [] }])
@@ -444,7 +511,7 @@ export function id<IsRequired extends boolean = false>(required?: IsRequired, op
       return val // preserve the original case for UUID/ObjectId or when case-sensitive
     })
 
-  return schema as unknown as IdSchema<IsRequired>
+  return schema as unknown as IdSchema<IsRequired, Type>
 }
 
 /**

package/tests/common/id.test.ts

@@ -135,8 +135,8 @@ describe.each(locales)("id(true) locale: $locale", ({ locale, messages }) => {
     })
 
     it("should apply transform function", () => {
-      const schema = id(true, { type: "numeric", transform: (val) => val.toUpperCase() })
-      expect(schema.parse("123")).toBe("123")
+      const schema = id(true, { type: "uuid", transform: (val) => val.toUpperCase() })
+      expect(schema.parse("550e8400-e29b-41d4-a716-446655440000")).toBe("550E8400-E29B-41D4-A716-446655440000")
     })
   })
 
@@ -162,7 +162,9 @@ describe.each(locales)("id(true) locale: $locale", ({ locale, messages }) => {
       it("should accept valid numeric IDs", () => {
         const schema = id(true, { type: "numeric" })
         validIds.numeric.forEach((validId) => {
-          expect(schema.parse(validId)).toBe(validId)
+          const result = schema.parse(validId)
+          expect(typeof result).toBe("number")
+          expect(result).toBe(Number(validId))
         })
       })
 
@@ -461,7 +463,8 @@ describe.each(locales)("id(true) locale: $locale", ({ locale, messages }) => {
       expect(schema.parse("")).toBe(null)
       expect(() => schema.parse("ab")).toThrow() // not numeric
       expect(() => schema.parse("12")).toThrow() // too short
-      expect(schema.parse("12345")).toBe("12345")
+      expect(schema.parse("12345")).toBe(12345) // Returns number for numeric type
+      expect(typeof schema.parse("12345")).toBe("number")
     })
 
     it("should handle multiple allowed types with constraints", () => {
@@ -499,4 +502,59 @@ describe.each(locales)("id(true) locale: $locale", ({ locale, messages }) => {
       expect(ID_PATTERNS.objectId.test("507f1f77bcf86cd799439011")).toBe(true)
     })
   })
+
+  describe("numeric type returns number", () => {
+    it("should return number type when type is numeric and required is true", () => {
+      const schema = id(true, { type: "numeric" })
+      const result = schema.parse("123")
+      expect(result).toBe(123)
+      expect(typeof result).toBe("number")
+    })
+
+    it("should return number | null when type is numeric and required is false", () => {
+      const schema = id(false, { type: "numeric" })
+      const result = schema.parse("456")
+      expect(result).toBe(456)
+      expect(typeof result).toBe("number")
+
+      const nullResult = schema.parse(null)
+      expect(nullResult).toBe(null)
+
+      const emptyResult = schema.parse("")
+      expect(emptyResult).toBe(null)
+    })
+
+    it("should use numeric default value for numeric type", () => {
+      const schema = id(true, { type: "numeric", defaultValue: 999 })
+      const result = schema.parse("")
+      expect(result).toBe(999)
+      expect(typeof result).toBe("number")
+    })
+
+    it("should validate numeric ID constraints", () => {
+      const schema = id(true, { type: "numeric", minLength: 3, maxLength: 5 })
+
+      expect(schema.parse("123")).toBe(123)
+      expect(schema.parse("12345")).toBe(12345)
+
+      // Too short
+      expect(() => schema.parse("12")).toThrow()
+
+      // Too long
+      expect(() => schema.parse("123456")).toThrow()
+
+      // Not numeric
+      expect(() => schema.parse("abc")).toThrow()
+    })
+
+    it("should convert string numbers to number type", () => {
+      const schema = id(true, { type: "numeric" })
+
+      expect(schema.parse("0")).toBe(0)
+      expect(schema.parse("999999")).toBe(999999)
+      expect(schema.parse(123)).toBe(123)
+
+      expect(typeof schema.parse("123")).toBe("number")
+    })
+  })
 })