TypeScript Partial and Required: Examples and Deep Partial

Partial<T> is a built-in utility type that makes every property of T optional. It is the natural type for an update or patch: the caller sends only the fields that changed.

interface User {
  id: number;
  name: string;
  email: string;
}

function updateUser(user: User, changes: Partial<User>): User {
  return { ...user, ...changes };
}

const ada: User = { id: 1, name: "Ada", email: "ada@example.com" };

const renamed = updateUser(ada, { name: "Ada Lovelace" });
const moved = updateUser(ada, { email: "ada@analytical.org" });

console.log(renamed); // { id: 1, name: 'Ada Lovelace', email: 'ada@example.com' }
console.log(moved.email); // ada@analytical.org

Partial<User> is { id?: number; name?: string; email?: string }. The compiler still checks the fields you do pass: { nmae: "x" } or { name: 42 } is an error, which is what makes Partial better than a loose object or any parameter.

How Partial Is Defined

Partial is a one-line mapped type in TypeScript's standard library:

type Partial<T> = {
  [P in keyof T]?: T[P];
};

For each key P of T, it declares an optional property with the same type. Because it maps over keyof T, it keeps readonly on properties that had it. Being an ordinary type, it has no runtime effect: the object passed as changes is the same object either way.

Reading from a Partial Gives T | undefined

Every property of a Partial<T> may be missing, so reading one gives the property type plus undefined. The compiler makes you handle the missing case:

interface Options {
  retries: number;
  timeoutMs: number;
  verbose: boolean;
}

const defaults: Options = { retries: 3, timeoutMs: 5000, verbose: false };

function connect(opts: Partial<Options> = {}) {
  const retries = opts.retries ?? defaults.retries; // number
  // opts.timeoutMs * 2 would be error TS18048: 'opts.timeoutMs' is possibly 'undefined'.
  const full: Options = { ...defaults, ...opts };
  console.log(retries, full);
}

connect({ verbose: true });
// 3 { retries: 3, timeoutMs: 5000, verbose: true }
connect();
// 3 { retries: 3, timeoutMs: 5000, verbose: false }

{ ...defaults, ...opts } is the usual way to turn a Partial<Options> back into a complete Options: spread the defaults first and let the given values override them.

The Explicit undefined Pitfall

An optional property may be missing, but it may also be present with the value undefined. Object spread copies that undefined over the real value, and the result type does not show it:

interface User {
  name: string;
  email: string;
}

function update(user: User, changes: Partial<User>): User {
  return { ...user, ...changes };
}

const u = update({ name: "Ada", email: "ada@example.com" }, { name: undefined });
console.log(u);             // { name: undefined, email: 'ada@example.com' }
console.log(typeof u.name); // undefined, although the type says string

// Fix: drop undefined values before merging
function updateSafe(user: User, changes: Partial<User>): User {
  const defined = Object.fromEntries(
    Object.entries(changes).filter(([, v]) => v !== undefined),
  ) as Partial<User>;
  return { ...user, ...defined };
}
console.log(updateSafe({ name: "Ada", email: "ada@example.com" }, { name: undefined }));
// { name: 'Ada', email: 'ada@example.com' }

This bites when a patch is built from a form or a query string where empty fields become undefined. The exactOptionalPropertyTypes compiler option (not part of strict) makes { name: undefined } a compile error for name?: string unless you write name?: string | undefined, which prevents it at the source.

Partial Is Shallow

Partial only makes the top-level properties optional. A nested object, if you pass it, must be complete:

// This does not compile: Partial only reaches the first level
interface Settings {
  theme: string;
  editor: { fontSize: number; tabSize: number };
}

const patch: Partial<Settings> = {
  editor: { fontSize: 16 },
};
console.log(patch);

index.ts(8,3): error TS2741: Property 'tabSize' is missing in type '{ fontSize: number; }' but required in type '{ fontSize: number; tabSize: number; }'.

The editor property is optional, but once present it has type { fontSize: number; tabSize: number }, unchanged. For settings objects, API patches and test fixtures you often want optional properties at every level. That needs a recursive type.

DeepPartial: A Recursive Partial

TypeScript has no built-in deep version, but it is a few lines. Functions and arrays are left as they are, because making array elements optional would allow [undefined]:

type DeepPartial<T> =
  T extends (...args: any[]) => unknown ? T :
  T extends readonly unknown[] ? T :
  T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } :
  T;

interface Settings {
  theme: string;
  editor: { fontSize: number; tabSize: number };
  recent: string[];
}

const defaults: Settings = {
  theme: "dark",
  editor: { fontSize: 14, tabSize: 2 },
  recent: [],
};

function applySettings(base: Settings, patch: DeepPartial<Settings>): Settings {
  return { ...base, ...patch, editor: { ...base.editor, ...patch.editor } };
}

const patch: DeepPartial<Settings> = { editor: { fontSize: 16 } }; // OK now
console.log(applySettings(defaults, patch));
// { theme: 'dark', editor: { fontSize: 16, tabSize: 2 }, recent: [] }

The type is recursive; the merge is not. applySettings merges editor by hand because object spread is shallow too. A generic deep merge function exists in libraries such as lodash (merge), and its typing is harder than the type above.

Required: The Opposite of Partial

Required<T> removes the ? from every property. It is defined with the -? modifier, which also removes undefined from each property's type:

interface ServerConfig {
  host: string;
  port?: number;
  tls?: boolean;
}

type ResolvedConfig = Required<ServerConfig>; // { host: string; port: number; tls: boolean }

function resolve(config: ServerConfig): ResolvedConfig {
  return { port: 80, tls: false, ...config };
}

const cfg = resolve({ host: "example.com", tls: true });
console.log(cfg.port + 1, cfg.tls); // 81 true
// @ts-expect-error: Property 'tls' is missing in type '{ host: string; port: number; }'
const incomplete: ResolvedConfig = { host: "a", port: 1 };

The pattern is the same as with Partial, reversed: users of an API pass a loose config, and the code inside works with a Required version where every value is known to exist. The spread has the same hole as the update function above: a caller who passes port: undefined explicitly overwrites the default with undefined, and the compiler accepts it unless exactOptionalPropertyTypes is on. Required is shallow in the same way Partial is.

Making Only Some Properties Optional or Required

Partial and Required apply to every property. To change just a few, split the type with Pick and Omit and put it back together:

type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;

interface Post {
  id: number;
  title: string;
  body?: string;
}

type NewPost = PartialBy<Post, "id">;      // id optional, title required, body optional
type Published = RequiredBy<Post, "body">; // body now required