TypeScript Utility Types – Complete Guide from Beginner to Advanced (with Zod)

TypeScript utility types are predefined generic types that facilitate type transformations. They allow you to create new types from existing ones, for example by making certain properties optional or by extracting the return type of a function. This educational guide, in three levels (beginner, intermediate, advanced), presents all standard TypeScript utility types (such as Partial, Required, Readonly, Pick, Omit, Record, Exclude, Extract, NonNullable, Parameters, ReturnType, InstanceType, ThisType, etc.), with for each: an explanation of its usefulness, an example of use in TypeScript, then a comparison with an equivalent approach under Zod, a runtime validation schema library. We will also discuss the philosophical differences between TypeScript utility types (static type system) and Zod schemas (runtime validation).

Setting up the project with Bun

To try the code snippets, you can initialize a minimal TypeScript project using Bun (an ultra-fast JavaScript runner that also serves as a package manager). Make sure you have Bun installed, then in an empty folder run:

shell

Bun will create a default package.json and tsconfig.json. You can then run a TypeScript file with bun run file.ts (Bun transpiles TypeScript on the fly).

We're ready to explore utility types!

Beginner level: basic type system utilities

Partial<T> – Optional properties

TypeScript: The Partial<T> utility type constructs a type from an existing type T by making all its properties optional. In other words, each property of T becomes optional (adding a ?). This allows you to represent partial objects of this type. For example, if you have a User type with required fields, Partial<User> will allow you to create a version where these fields can be omitted:

typescript

Here, Partial<User> has the type { name?: string; age?: number }. This allows you, for example, to implement a partial update function without requiring all fields:

typescript

You call updateUser(existingUser, { age: 26 }) with a partial object – TypeScript statically guarantees that fieldsToUpdate contains only valid keys of User.

Equivalent with Zod: Zod offers an equivalent method to make an object schema partial. The .partial() method applied to a z.object schema makes all keys optional, similar to Partial in TypeScript. For example:

typescript

Here PartialUserSchema is a schema that validates objects containing possibly only a subset of keys (name and age become optional). You can check how it works:

typescript

Zod also allows you to make only certain properties optional by passing an object as a parameter (UserSchema.partial({ age: true }) only makes age optional). Note that .partial() only acts on the first level; Zod also provides .deepPartial() to recursively make nested fields optional.

Required<T> – Required properties

TypeScript: The Required<T> utility type is the opposite of Partial: it creates a type from T by making all its properties required (non-optional). It's useful for "solidifying" a type whose properties were optional. For example:

typescript

In this example, Required<Settings> is equivalent to { theme: string; fontSize: number } – any omission of a property becomes a compilation error.

Equivalent with Zod: For a Zod schema, the equivalent is the .required() method, which transforms an object schema by making all its properties required (unlike .partial() which makes them optional). This method is especially useful if you first defined a partial schema and want to get the strict version. For example:

typescript

Here StrictUserSchema requires that name and age be present. You can also target specific properties: BaseUserSchema.required({ age: true }) only makes age required (and leaves name optional).

Note that Required<T> acts at compile time (it no longer exists in the emitted JavaScript code), while schema.required() of Zod acts at runtime by validating the presence of keys during parsing.

Readonly<T> – Property immutability

TypeScript: The Readonly<T> utility transforms a type T by making its properties read-only (immutable). Any attempt to reassign these properties will be reported as an error at compilation. For example:

typescript

Here, todo is of type Readonly<Todo> so its fields cannot be modified after initialization. This often corresponds to the use of Object.freeze in JavaScript, but TypeScript only handles this at the type level (it doesn't actually prevent mutation at runtime, it only warns at compile time).

Equivalent with Zod: Zod offers an interesting feature for immutability. The .readonly() method applied to a schema returns a new schema that, when parsing, calls Object.freeze() on the result, and whose static type is marked Readonly<...>. In other words, Zod can freeze the validated object and ensure that it corresponds to a readonly type. For example:

typescript

Here, FrozenUserSchema freezes the object output from parse. If you try to modify frozenUser, an exception will be thrown at runtime because the object is immutable. Thus, Zod goes further than TypeScript: where Readonly<T> is purely static (properties could be modified in JS if you bypass typing), the Zod .readonly() schema ensures real immutability at runtime in addition to providing the corresponding Readonly<...> type.

Pick<T, Keys> – Selection of a subset of properties

TypeScript: Pick<T, Keys> constructs a new type from T by keeping only certain properties specified by Keys (typically a union of string literals representing property names). It's useful for creating a more restricted type from an existing type. For example:

typescript

Here, TodoPreview only keeps title and completed from FullTodo. Any unlisted property (description for ex.) is excluded from the resulting type.

Equivalent with Zod: Zod object schemas also have a .pick() method that creates a new schema containing only the indicated keys, in a similar way:

typescript

You pass an object with the keys to keep set to true. TodoPreviewSchema will only validate objects with title and completed (other properties of FullTodo will be ignored by the parser by default). For example, TodoPreviewSchema.parse({ title: "Clean", completed: false, description: "..." }) will return { title: "...", completed: false } having removed description (because by default Zod ignores unspecified keys, behavior that can be adjusted with .strict() or .passthrough() as needed).

Similarly, Zod provides .omit() for the opposite effect.

Omit<T, Keys> – Exclusion of properties

TypeScript: Omit<T, Keys> creates a new type starting from T and removing certain properties (Keys). It's the complement of Pick (in fact Omit<T, K> is often implemented as Pick<T, Exclude<keyof T, K>>). Example:

typescript

Here TaskMeta only contains id and title. The properties done and dueDate have been excluded.

Equivalent with Zod: Zod's .omit() method produces an object schema without the indicated keys. Example:

typescript

TaskMetaSchema will validate objects containing only id and title. Any omitted key (done, dueDate) will be ignored if present in the input. Thus, Pick and Omit allow you to project a Zod schema onto a subset of fields just as their TypeScript equivalents do at the type level.

Record<Keys, Type> – Dictionary of typed keys

TypeScript: Record<Keys, Type> constructs an object type whose keys are of type Keys (typically a union of string literals or a more general string/number type) and values are of type Type. This allows you to describe, for example, an object indexed by identifiers. A classic example:

typescript

Here, Record<CatName, CatInfo> ensures that the cats object has exactly the keys "miffy", "boris", "mordred", each associated with a CatInfo. Record is very useful for typing objects used as dictionaries or maps.

Equivalent with Zod: Zod offers the z.record(keySchema, valueSchema) schema to validate objects of this kind. You can use it with a key schema (for example z.string() or a literal schema) and a value schema. Example:

typescript

Here, AgeMapSchema validates any key as long as it's a string (by default, Zod z.record without a first argument assumes string). If you have a finite set of keys, it's often better to use z.object({ ... }) with explicitly named keys or z.enum([...]) to constrain the keys. In fact, Zod allows a stricter key schema: you could define const CatNameSchema = z.enum(["miffy","boris","mordred"]) then do z.record(CatNameSchema, CatInfoSchema) – however, be aware that at runtime JavaScript object keys are always strings. Even a numeric key will be converted to a string at runtime (e.g., a key 1 becomes "1" in a JS object). Zod takes this into account and does not allow you to define a pure numeric key schema without transforming it to a string.

In summary, Record<Keys, Type> (TypeScript) and z.record(keySchema, valueSchema) (Zod) both allow you to type dictionaries. The former acts at the type system level, the latter at runtime to validate the object's structure.

Intermediate level: manipulating unions and optional types

Exclude<UnionType, ExcludedMembers> – Removal of members from a union

TypeScript: Exclude<U, E> creates a type by removing from the union U all members that are assignable to type E. In other words, you exclude certain types from a union. For example:

typescript

Here, Exclude<Role, "admin"> removes the literal "admin" from the union, leaving only "user" | "guest". Another example: Exclude<string | number | boolean, string> would give number | boolean (removing everything assignable to string). It's useful for refining a union type by eliminating undesirable cases.

Equivalent with Zod: To restrict the possibilities of a union at runtime, you typically define a schema that doesn't include the cases to exclude. For example, if you have a RoleSchema = z.enum(["admin","user","guest"]), you can create a subset by not including "admin". Zod provides for enumerations the `.exclude([…]) method that generates a new enumeration schema without the specified values. For example:

typescript

This NonAdminSchema corresponds exactly to the Exclude<Role, "admin"> type but also ensures validation at runtime. Under the hood, RoleSchema.exclude(["admin"]) simply removes "admin" from the list of allowed literals. Similarly, Zod offers .extract([...]) to perform the complementary operation.

Extract<Type, Union> – Extraction of members from a union

TypeScript: Extract<T, U> creates a type by keeping from T only members assignable to U. It's roughly the opposite of Exclude. For example:

typescript

Another example: Extract<"a" | "b" | "c", "a" | "f"> will give "a" (because only "a" is common to both). This utility type is therefore used to filter a union to extract only a certain subtype.

Equivalent with Zod: As with Exclude, Zod allows you to obtain at runtime a schema corresponding to a subset of an enumeration via .extract([...]). Let's take the example of roles again: to extract only, say, the limited roles "user" and "guest" from a complete RoleSchema:

typescript

Here LimitedRolesSchema corresponds to the type Extract<Role, "user" | "guest">. In practice, you could get the same result by directly defining z.enum(["user","guest"]), but .extract is convenient for deriving a schema from an existing enum. Note that .exclude and .extract of Zod apply to enumeration schemas (z.enum or z.nativeEnum), and not to arbitrary unions of complex types. For the latter, you generally manually construct the desired new union schema.

NonNullable<T> – Exclusion of null and undefined

TypeScript: NonNullable<T> constructs a type by excluding null and undefined from T. It's common in TypeScript to have union types including these "nullish" values and to want a type that is purged of them. For example:

typescript

Here, DefinitelyString only contains string (neither null nor undefined). This utility type is often used in combination with presence conditions (if (value != null) { ... }) to help the compiler refine types.

Equivalent with Zod: With Zod, by default schemas don't accept undefined or null unless you specify it. In other words, a z.string() schema will only accept a string, not undefined. To allow these values, you explicitly use z.string().optional() (which allows undefined) or z.string().nullable() (which allows null) or even .nullish() (which allows either). Thus, obtaining the equivalent of a NonNullable type simply means not including null/undefined in the schema. However, if you start from a more permissive schema and want to make it stricter, you can use a combination of techniques: for example, the .unwrap() method allows you to extract the underlying schema from an optional or nullable schema.

typescript

Here, OptionalName.unwrap() returns the original z.string() schema. This allows you to "remove" the optional or nullable character introduced previously. Another approach would be to use a custom refinement to reject null/undefined, but that would be redundant given the behavior of Zod schemas.

Advanced level: function and class types

Parameters<Type> – Function parameter types

TypeScript: Parameters<T> extracts the parameter types of a function type T as a tuple. This is useful for working with function signatures, especially when you want to create a function that wraps another function. For example:

typescript

Here, Parameters<typeof greet> extracts the tuple [string, number] representing the parameters of greet. This allows safeGreet to accept exactly the same parameters as greet.

Equivalent with Zod: Zod provides z.function() to define function schemas, with methods to specify parameter types and return type. While there's no direct equivalent to Parameters<T>, you can define a function schema and extract its parameter types using TypeScript's own Parameters utility on the inferred type:

typescript

Here, GreetSchema defines a function schema that takes a string and a number and returns a string. The .implement() method creates a wrapper function that validates inputs and outputs according to the schema. We can extract the parameter types using Parameters<GreetFn>. This approach combines runtime validation with static typing.

ReturnType<Type> – Function return type

TypeScript: ReturnType<T> extracts the return type of a function type T. This is useful when you want to work with the result of a function without having to explicitly redefine its type. For example:

typescript

Here, ReturnType<typeof createUser> extracts the object type returned by createUser. This allows us to define the User type without duplicating the structure.

Equivalent with Zod: As with Parameters, there's no direct Zod equivalent to ReturnType, but you can combine Zod's function schema with TypeScript's ReturnType utility:

typescript

Here, we define a function schema with CreateUserSchema, then extract its return type in two ways: using TypeScript's ReturnType on the inferred function type, or using Zod's .returnType() method which returns the schema for the return value. Both approaches give us the User type.

InstanceType<Type> – Class instance type

TypeScript: InstanceType<T> extracts the instance type of a constructor function type T. This is useful when you have a class reference and want to work with instances of that class. For example:

typescript

Here, InstanceType<typeof Point> gives us the type of a Point instance, which includes its properties and methods.

Equivalent with Zod: Zod doesn't have a direct equivalent for class instance types, as it focuses on data validation rather than class behavior. However, you can define a schema for the shape of class instances:

typescript

This approach defines a schema that matches the shape of a Point instance, but it doesn't capture the full class relationship. For more complex class validation, you might need to combine Zod with class-validator or similar libraries.

Philosophical Differences Between TypeScript Utility Types and Zod Schemas

TypeScript utility types and Zod schemas both serve to ensure data reliability, but at different levels: one at compile time, the other at runtime.

• TypeScript: static safety (compile-time) – Utility types (and the type system in general) operate during development. TypeScript analyzes the code and prevents type inconsistencies before the code even runs. For example, Partial<T> ensures that a function won't forget to handle cases where properties are missing, ReturnType<Fn> gives the expected shape of function returns, etc. However, these checks no longer exist once the application is running: TypeScript erases types during transpilation to JavaScript. Nothing prevents bad data from circulating at runtime (coming from JSON, user forms, external APIs...). The type system alone cannot protect against unexpected values at runtime.
• Zod: dynamic validation (runtime) – Zod schemas intervene at runtime to fill this gap. By defining a schema for your data, you create a runtime guard that verifies received data matches the expected format. For example, a PartialUserSchema will actually verify that the received object contains only valid keys and their values are of the correct type, whereas Partial<User> is just a compile-time assurance. Thus, Zod and TypeScript are complementary: TypeScript ensures the internal consistency of your code (what you manipulate corresponds to the announced types), while Zod ensures external data conforms to your types.

We can summarize it this way:

• TypeScript is a compile-time guard that catches errors early in the development cycle and helps you avoid many common mistakes before even running the code.
• Zod is a runtime guard that ensures no non-compliant data "passes through the door" of your application (user input, API response, config content, etc.).

In terms of philosophy, utility types express transformations or constraints at the type system level (they help the developer, having no direct impact on the emitted code), while Zod provides contracts at the runtime level (they allow concrete implementation of data validations and transformations at execution). Both approaches address different but related needs: maintaining code robustness. Moreover, Zod is designed to integrate harmoniously with TypeScript: it automatically infers static types from your schemas, avoiding definition duplication. This means you can often define a Zod schema (for validation) and use z.infer to derive the corresponding static TypeScript type, instead of defining a TypeScript interface and a separate schema – thus having a single source of truth for your data types.

In conclusion, knowing TypeScript utility types allows you to leverage the type system to write safe and expressive code, while mastering Zod gives you the tools to enforce these type contracts at runtime. Used together, they significantly strengthen the reliability of your TypeScript applications: TypeScript protects you from programming errors, and Zod protects your application from unexpected data from the outside world. Create your types, validate your data, and code with peace of mind 🎉!

1bun init
2bun add zod             # adds Zod as a dependency

1interface User {
2  name: string;
3  age: number;
4}
5
6const partialUser: Partial<User> = { name: "Alice" };
7// 'partialUser' can contain only the name, the 'age' property is optional
8partialUser.age = 30;  // OK to add later because age: number | undefined

1function updateUser(user: User, fieldsToUpdate: Partial<User>): User {
2  return { ...user, ...fieldsToUpdate };
3}

1import { z } from "zod";
2
3const UserSchema = z.object({
4  name: z.string(),
5  age: z.number()
6});
7const PartialUserSchema = UserSchema.partial();
8type PartialUser = z.infer<typeof PartialUserSchema>; 
9// PartialUser is of type { name?: string; age?: number }

1PartialUserSchema.parse({ name: "Alice" });      // OK (missing age allowed)
2PartialUserSchema.parse({ });                    // OK (can be empty)
3PartialUserSchema.parse({ age: " thirty " });    // Error: age is not a number

1interface Settings {
2  theme?: string;
3  fontSize?: number;
4}
5const s1: Settings = { theme: "dark" };              // OK, fontSize missing
6const s2: Required<Settings> = { theme: "dark" };    // Error – fontSize is required
7// TypeScript: Property 'fontSize' is missing in type ... but required in type 'Required<Settings>'

1const BaseUserSchema = z.object({
2  name: z.string().optional(),
3  age: z.number().optional()
4});
5// BaseUserSchema: { name?: string; age?: number }
6const StrictUserSchema = BaseUserSchema.required();
7// StrictUserSchema: { name: string; age: number }

1interface Todo { title: string; done: boolean; }
2const todo: Readonly<Todo> = { title: "Init project", done: false };
3todo.done = true;  
4// Error TS: Cannot assign to 'done' because it is a read-only property.

1const FrozenUserSchema = z.object({ name: z.string() }).readonly();
2type FrozenUser = z.infer<typeof FrozenUserSchema>; 
3// FrozenUser: Readonly<{ name: string }>
4const frozenUser = FrozenUserSchema.parse({ name: "Bob" });
5frozenUser.name;        // "Bob"
6frozenUser.name = "Eve"; // Runtime error: the object is frozen (TypeError in strict mode)

1interface FullTodo {
2  title: string;
3  description: string;
4  completed: boolean;
5}
6type TodoPreview = Pick<FullTodo, "title" | "completed">;
7// TodoPreview: { title: string; completed: boolean }
8const t: TodoPreview = { title: "Clean", completed: false }; // OK

1const FullTodoSchema = z.object({
2  title: z.string(),
3  description: z.string(),
4  completed: z.boolean()
5});
6const TodoPreviewSchema = FullTodoSchema.pick({ title: true, completed: true });
7type TodoPreview = z.infer<typeof TodoPreviewSchema>; 
8// { title: string; completed: boolean }

1interface Task {
2  id: string;
3  title: string;
4  done: boolean;
5  dueDate: string;
6}
7type TaskMeta = Omit<Task, "done" | "dueDate">;
8// TaskMeta: { id: string; title: string }

1const TaskSchema = z.object({
2  id: z.string(),
3  title: z.string(),
4  done: z.boolean(),
5  dueDate: z.string()
6});
7const TaskMetaSchema = TaskSchema.omit({ done: true, dueDate: true });
8type TaskMeta = z.infer<typeof TaskMetaSchema>; 
9// { id: string; title: string }

1type CatName = "miffy" | "boris" | "mordred";
2interface CatInfo { age: number; breed: string; }
3type Cats = Record<CatName, CatInfo>;
4/* Equivalent to:
5type Cats = {
6  miffy: CatInfo;
7  boris: CatInfo;
8  mordred: CatInfo;
9}
10*/
11const cats: Cats = {
12  miffy: { age: 10, breed: "Persian" },
13  boris: { age: 5, breed: "Maine Coon" },
14  mordred: { age: 16, breed: "British Shorthair" }
15};

1// We want an object whose keys are names (string) and values are ages (number)
2const AgeMapSchema = z.record(z.string(), z.number());
3type AgeMap = z.infer<typeof AgeMapSchema>; 
4// AgeMap: Record<string, number>
5AgeMapSchema.parse({ "Alice": 30, "Bob": 25});    // OK
6AgeMapSchema.parse({ "Alice": 30, "Bob": "25" });  // Error: "25" is not a number

1type Role = "admin" | "user" | "guest";
2type NonAdmin = Exclude<Role, "admin">;  
3// NonAdmin: "user" | "guest"

1const RoleSchema = z.enum(["admin", "user", "guest"]);
2const NonAdminSchema = RoleSchema.exclude(["admin"]);
3type NonAdmin = z.infer<typeof NonAdminSchema>; 
4// NonAdmin: "user" | "guest"
5NonAdminSchema.parse("user");   // OK
6NonAdminSchema.parse("admin");  // Error: "admin" is excluded

1type Mixed = string | number | boolean;
2type NumbersOnly = Extract<Mixed, number | boolean>; 
3// NumbersOnly: number | boolean (we only keep what's assignable to number | boolean)

1const LimitedRolesSchema = RoleSchema.extract(["user", "guest"]);
2type LimitedRoles = z.infer<typeof LimitedRolesSchema>; 
3// LimitedRoles: "user" | "guest"
4LimitedRolesSchema.parse("guest");  // OK
5LimitedRolesSchema.parse("admin");  // Error, "admin" is not extracted

1type MaybeString = string | null | undefined;
2type DefinitelyString = NonNullable<MaybeString>;  
3// DefinitelyString: string

1const OptionalName = z.string().optional();          // type: string | undefined
2const Name = OptionalName.unwrap();                 // retrieves underlying z.string() (type: string)
3Name.parse("Alice");   // "Alice"
4Name.parse(undefined); // Error: undefined not accepted

1function greet(name: string, age: number): string {
2  return `Hello ${name}, you are ${age} years old`;
3}
4type GreetParams = Parameters<typeof greet>; 
5// GreetParams: [name: string, age: number]
6
7// We can use this type to create a function that calls greet
8function safeGreet(...args: GreetParams): string {
9  try {
10    return greet(...args);
11  } catch (e) {
12    return "Greeting failed";
13  }
14}

1const GreetSchema = z.function()
2  .args(z.string(), z.number()) // defines parameters: string, number
3  .returns(z.string());         // defines return type: string
4
5type GreetFn = z.infer<typeof GreetSchema>; // type: (name: string, age: number) => string
6type GreetParams = Parameters<GreetFn>;     // type: [string, number]
7
8// We can use this schema to validate a function
9const greet = GreetSchema.implement((name, age) => {
10  return `Hello ${name}, you are ${age} years old`;
11});
12// greet is now a validated function that will throw if called with wrong types

1function createUser(name: string) {
2  return { id: Date.now(), name, createdAt: new Date() };
3}
4type User = ReturnType<typeof createUser>; 
5// User: { id: number; name: string; createdAt: Date }
6
7// We can now use this type elsewhere
8function processUser(user: User) {
9  console.log(`Processing user ${user.name} created at ${user.createdAt}`);
10}

1const CreateUserSchema = z.function()
2  .args(z.string())
3  .returns(
4    z.object({
5      id: z.number(),
6      name: z.string(),
7      createdAt: z.date()
8    })
9  );
10
11type CreateUserFn = z.infer<typeof CreateUserSchema>; 
12// type: (name: string) => { id: number; name: string; createdAt: Date }
13type User = ReturnType<CreateUserFn>; 
14// type: { id: number; name: string; createdAt: Date }
15
16// We can also directly extract the return schema
17const UserSchema = CreateUserSchema.returnType();
18// UserSchema is the object schema for the return value
19type User2 = z.infer<typeof UserSchema>; // Same as User

1class Point {
2  x: number;
3  y: number;
4  
5  constructor(x: number, y: number) {
6    this.x = x;
7    this.y = y;
8  }
9  
10  distanceFromOrigin(): number {
11    return Math.sqrt(this.x * this.x + this.y * this.y);
12  }
13}
14
15type PointInstance = InstanceType<typeof Point>; 
16// PointInstance: Point (the instance type, with x, y, and distanceFromOrigin)
17
18// We can use this type without having an actual instance
19function processPoint(p: PointInstance) {
20  console.log(`Point at (${p.x}, ${p.y}) is ${p.distanceFromOrigin()} from origin`);
21}

1const PointSchema = z.object({
2  x: z.number(),
3  y: z.number(),
4  distanceFromOrigin: z.function()
5    .args()
6    .returns(z.number())
7});
8
9type PointLike = z.infer<typeof PointSchema>; 
10// type: { x: number; y: number; distanceFromOrigin: () => number }
11
12// We can validate if an object conforms to the Point interface
13function isPoint(obj: unknown): obj is PointLike {
14  return PointSchema.safeParse(obj).success;
15}