colinhacks/zod — drift 9.2/10

9.2/10

Severe drift

The documentation is generally comprehensive and well-aligned with the code API surface. The vast majority of exported functions and types are properly documented with examples and behavior descriptions. However, there are several notable gaps where prominently exported code APIs lack corresponding documentation or have significant discrepancies in function signatures and parameter details.

2 high2 medium3 low

Open issue with all findings ↗

Files analyzed

267

API symbols

Doc pages

36.5s

Analyzed in

API coverage — Poorly documented

23 of 267 exported symbols mentioned in docs

4 deprecated APIs detected in code

$ZodCUIDParamspackages/zod/src/v4/core/api.ts
$ZodCheckCUIDParamspackages/zod/src/v4/core/api.ts
_cuidpackages/zod/src/v4/core/api.ts
_nativeEnumpackages/zod/src/v4/core/api.ts

12 source files inspected · claude-haiku-4-5-20251001 · Jun 3, 2026

7 mismatches found

Missing documentation for @deprecated message parameter

packages/zod/src/v4/core/api.ts

high

In the code

export export type Params< T extends schemas.$ZodType | checks.$ZodCheck, IssueTypes extends errors.$ZodIssueBase, OmitKeys extends keyof T["_zod"]["def"] = never, > = util.Flatten< Partial< util.EmptyToNever< Omit<T["_zod"]["def"], OmitKeys> & ([IssueTypes] extends [never] ? {} // unknown : { error?: string | errors.$ZodErrorMap<IssueTypes> | undefined; /** @deprecated This parameter is deprecated. Use `error` instead. */ message?: string | undefined; // supported in Zod 3 }) > > >;  // L8

In the docs

(not documented)

The code explicitly marks the `message` parameter as deprecated in favor of `error` in the Params type definition, with a comment that it's supported for Zod 3 compatibility. However, the documentation provides no guidance on this deprecation or migration path for users upgrading from Zod 3.

Suggested fix

Add a migration guide or deprecation notice in the API reference explaining that the `message` parameter has been replaced by `error`, and provide examples of the new usage pattern.

Missing documentation for .prefault() method

packages/zod/src/v4/core/api.ts

high

In the code

(not documented in provided code surface - implied by context)

In the docs

z.string().transform(val => val.length).prefault("tuna");
schema.parse(undefined); // => 4

The documentation mentions and demonstrates .prefault() method with examples, but this method is not present in the provided API surface code. This suggests either the code surface is incomplete or the docs reference a feature that may not be fully exported/available.

Suggested fix

Verify that .prefault() is actually exported from the public API. If it is, add it to the code surface. If it's not fully implemented, update the documentation to remove this section or mark it as experimental.

Missing documentation for z.stringFormat() API

packages/zod/src/v4/core/api.ts

medium

In the code

export function _stringFormat<Format extends string>(Class: typeof schemas.$ZodCustomStringFormat, format: Format, fnOrRegex: ((arg: string) => util.MaybeAsync<unknown>) | RegExp, _params: string | $ZodStringFormatParams = {}): schemas.$ZodCustomStringFormat<Format>  // L1802

In the docs

(not documented)

The z.stringFormat() function is exported and functional in the code but is completely undocumented in the API reference. This is a user-facing API for defining custom string formats that developers might need to use directly.

Suggested fix

Add a new section under 'String formats' documenting z.stringFormat() with examples showing both regex and function-based validation approaches, similar to how custom formats are mentioned but not fully detailed.

Missing documentation for z.stringbool() API

packages/zod/src/v4/core/api.ts

medium

In the code

export function _stringbool(Classes: { Codec?: typeof schemas.$ZodCodec; Boolean?: typeof schemas.$ZodBoolean; String?: typeof schemas.$ZodString; }, _params?: string | $ZodStringBoolParams): schemas.$ZodCodec<schemas.$ZodString, schemas.$ZodBoolean>  // L1738

In the docs

const strbool = z.stringbool();

While z.stringbool() is documented in the 'Stringbools' section with usage examples, the documentation does not match the actual function signature. The code shows it returns a z.ZodCodec (bidirectional transform), but the docs present it as a simple schema that parses to boolean. The underlying mechanism is misrepresented.

Suggested fix

Update the Stringbools section to clarify that z.stringbool() returns a codec that performs bidirectional transformations, and note that it's a convenience wrapper around z.codec() for converting string boolean values to actual booleans.

Missing documentation for numeric string formats (e164, ipv4, ipv6, mac, etc.)

packages/zod/src/v4/core/api.ts

low

In the code

export function _e164<T extends schemas.$ZodE164>(Class: util.SchemaClass<T>, params?: string | $ZodE164Params | $ZodCheckE164Params): T  // L471
export function _ipv4<T extends schemas.$ZodIPv4>(Class: util.SchemaClass<T>, params?: string | $ZodIPv4Params | $ZodCheckIPv4Params): T  // L352
export function _ipv6<T extends schemas.$ZodIPv6>(Class: util.SchemaClass<T>, params?: string | $ZodIPv6Params | $ZodCheckIPv6Params): T  // L369
export function _mac<T extends schemas.$ZodMAC>(Class: util.SchemaClass<T>, params?: string | $ZodMACParams | $ZodCheckMACParams): T  // L386

In the docs

z.e164();          // E.164 phone numbers
z.ipv4();
z.ipv6();
z.mac();

The documentation mentions these formatters (e164, ipv4, ipv6, mac) exist but provides minimal detail compared to other string formats like email or UUID. For ipv4/ipv6, there's no mention of version parameters that exist in the code signature. For mac, the delimiter parameter is documented but the params signature allows more customization.

Suggested fix

Expand the documentation for IP addresses and phone numbers sections to include parameter examples (e.g., ipv4({ version: 'v4' })), and clarify optional parameters that can be passed.

Missing parameter documentation for z.email() pattern option

packages/zod/src/v4/core/api.ts

low

In the code

export export type $ZodEmailParams = StringFormatParams<schemas.$ZodEmail, "when">;  // L93

In the docs

z.email({ pattern: /your regex here/ });

The code shows that z.email() accepts parameters beyond just `pattern`, including a `when` parameter for conditional validation (from StringFormatParams). The documentation only mentions the pattern parameter but doesn't document the full parameter interface.

Suggested fix

Update the email section to document all available parameters including error customization and when conditions, consistent with how other format validators are documented.

Incomplete documentation for z.hash() encoding options

packages/zod/src/v4/core/api.ts

low

In the code

export function _hash<T extends schemas.$ZodString>(Class: util.SchemaClass<T>, params?: string | $ZodStringFormatParams): T  // (implied from pattern)

In the docs

z.hash("sha256", { enc: "hex" });       // default
z.hash("sha256", { enc: "base64" });    // base64 encoding
z.hash("sha256", { enc: "base64url" }); // base64url encoding (no padding)

The documentation shows z.hash() accepting an `enc` parameter for encoding specification, but this is not directly reflected in the visible function signature. The documentation implies more configuration options than may be actually exposed.

Suggested fix

Verify that z.hash() actually supports the `enc` parameter with the documented values. If it does, ensure the type signature is properly exposed in the API surface documentation.

Re-analyze →Check a different repo