TypeScript Partial ve Required: Örnekler ve Deep Partial

Partial<T>, T tipinin her özelliğini isteğe bağlı yapan yerleşik bir utility type'tır. Bir güncelleme ya da patch için doğal tiptir: çağıran taraf yalnızca değişen alanları gönderir.

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> tipi { id?: number; name?: string; email?: string } olur. Derleyici geçirdiğiniz alanları yine kontrol eder: { nmae: "x" } ya da { name: 42 } bir hatadır; Partial tipini gevşek bir object ya da any parametresinden daha iyi yapan da budur.

Partial Nasıl Tanımlanır

Partial, TypeScript'in standart kütüphanesinde tek satırlık bir mapped type'tır:

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

T tipinin her P anahtarı için aynı tipte isteğe bağlı bir özellik bildirir. keyof T üzerinde eşleme yaptığı için, readonly olan özelliklerde readonly korunur. Sıradan bir tip olduğu için çalışma zamanında hiçbir etkisi yoktur: changes olarak geçirilen nesne her durumda aynı nesnedir.

Bir Partial'dan Okumak T | undefined Verir

Bir Partial<T> tipinin her özelliği eksik olabilir, bu yüzden birini okumak özellik tipini ve undefined değerini verir. Derleyici eksik durumu ele almanızı ister:

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 }, bir Partial<Options> değerini eksiksiz bir Options değerine geri çevirmenin olağan yoludur: önce varsayılanları yayın, verilen değerlerin onları ezmesine izin verin.

Açık undefined Tuzağı

İsteğe bağlı bir özellik eksik olabilir, ama undefined değeriyle var da olabilir. Nesne spread'i bu undefined değerini gerçek değerin üzerine kopyalar ve sonuç tipi bunu göstermez:

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' }

Bu sorun, boş alanların undefined hâline geldiği bir formdan ya da query string'den bir patch oluşturulduğunda ortaya çıkar. exactOptionalPropertyTypes derleyici seçeneği (strict kapsamında değildir), name?: string | undefined yazmadığınız sürece name?: string için { name: undefined } ifadesini bir derleme hatası yapar ve sorunu kaynağında önler.

Partial Sığdır

Partial yalnızca en üst düzey özellikleri isteğe bağlı yapar. İç içe bir nesneyi geçirirseniz, o nesne eksiksiz olmalıdır:

// 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; }'.

editor özelliği isteğe bağlıdır, ama var olduğunda tipi değişmeden { fontSize: number; tabSize: number } olur. Ayar nesneleri, API patch'leri ve test fixture'ları için genellikle her düzeyde isteğe bağlı özellikler istersiniz. Bunun için özyinelemeli bir tip gerekir.

DeepPartial: Özyinelemeli Bir Partial

TypeScript'te yerleşik bir derin sürüm yoktur, ama birkaç satırdan ibarettir. Fonksiyonlar ve diziler olduğu gibi bırakılır, çünkü dizi elemanlarını isteğe bağlı yapmak [undefined] değerine izin verirdi:

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: [] }

Tip özyinelemelidir; birleştirme değildir. applySettings, editor özelliğini elle birleştirir, çünkü nesne spread'i de sığdır. lodash gibi kütüphanelerde generic bir derin birleştirme fonksiyonu (merge) vardır ve onun tiplenmesi yukarıdaki tipten daha zordur.

Required: Partial'ın Tersi

Required<T>, her özellikten ? işaretini kaldırır. -? değiştiricisiyle tanımlanmıştır; bu değiştirici her özelliğin tipinden undefined değerini de çıkarır:

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 };

Desen Partial ile aynıdır, yalnızca tersine çevrilmiştir: bir API'nin kullanıcıları gevşek bir yapılandırma geçirir, içerideki kod ise her değerin var olduğunun bilindiği bir Required sürümüyle çalışır. Spread'de yukarıdaki güncelleme fonksiyonundaki açık aynen vardır: açıkça port: undefined geçiren bir çağıran, varsayılanı undefined ile ezer ve exactOptionalPropertyTypes açık değilse derleyici bunu kabul eder. Required da Partial gibi sığdır.

Yalnızca Bazı Özellikleri İsteğe Bağlı ya da Zorunlu Yapmak

Partial ve Required her özelliğe uygulanır. Yalnızca birkaçını değiştirmek için tipi Pick ve Omit ile bölün ve yeniden birleştirin:

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