Typed lookup maps
Validate configuration or lookup data represented as a native Map with controlled key and value types.
Zod · Module
z.map
z.map() creates a Zod schema for JavaScript Maps by defining separate schemas for keys and values. It infers the corresponding TypeScript Map type and supports entry-count and readonly constraints.
How it works
z.map() builds a schema for JavaScript Map instances by taking one schema for keys and another for values. Parsing checks each entry against those schemas and infers the corresponding TypeScript Map type; the resulting map can also be constrained by entry count or made readonly.
Syntax
z.map(keySchema, valueSchema)Parameters
| Name | Type | Description |
|---|---|---|
keySchema | ZodType | Schema applied to every key in the Map. |
valueSchema | ZodType | Schema applied to every value in the Map. |
Returns
A Zod map schema that validates Map entries and infers a corresponding Map type.
Key points
- Call z.map() with the key schema first and the value schema second; this example accepts string keys and number values.
- Type inference turns the schema into Map<string, number> for TypeScript consumers.
- The inferred type can annotate a native JavaScript Map before validation.
- Use parse() to validate a Map and obtain the parsed value when validation succeeds.
- nonempty() requires the Map to contain at least one entry.
- min(5) sets a lower bound of five entries.
Common mistakes
- The map schema also accepts collection-size constraints such as nonempty(), min(), max(), and size().
Example: Validate a string-to-number Map
import { z } from "zod";
const StringNumberMap = z.map(z.string(), z.number());
const result = StringNumberMap.parse(
new Map([
["one", 1],
["two", 2],
]),
);
console.log(result.get("one")); // 1Creates a schema for a Map with string keys and numeric values, then validates a matching Map.
When to use it
Cardinality validation
Enforce minimum, maximum, exact, or nonzero entry counts on a Map.
Immutable map output
Expose validated map data through a readonly collection type.
Interview questions
QWhat does z.map() validate and infer?
z.map(keySchema, valueSchema) defines the validation rules for Map keys and values. For example, z.map(z.string(), z.number()) infers Map<string, number> and validates each map entry.
Follow-up: How would you require at least five entries? Use .min(5) on the map schema; .size(5) would require exactly five.
QWhat is the argument order for z.map()?
Pass a key schema first and a value schema second, such as z.map(z.string(), z.number()). Parsing a Map checks that its keys are strings and its values are numbers.
Follow-up: How can the output type be read-only? Add .readonly(), which produces a ReadonlyMap type.
QHow can a z.map() schema constrain collection size?
Map schemas support .nonempty(), .min(), .max(), and .size() to constrain the number of entries. These methods respectively require at least one, set a lower bound, set an upper bound, or require an exact count.
Follow-up: What constraint would reject both four and six entries when five are required? Use .size(5).
Related
z.setz.recordz.infernonemptyminmaxsizereadonly