【TypeScript】オプショナルプロパティ（?）の使い方｜省略可能なプロパティと undefined の扱いを解説

interface User {
  name: string;   // 必須
  age?: number;   // 省略してよい
}

// age を書かなくても OK
const alice: User = { name: 'Alice' };

// もちろん書いてもよい
const bob: User = { name: 'Bob', age: 30 };

// name は必須なので、これはエラー
// Property 'name' is missing in type '{ age: number; }' but required in type 'User'.
const carol: User = { age: 20 };

interface Config {
  readonly id?: string;   // readonly → 名前 → ? の順
  readonly retry?: number;
}

const config: Config = {};        // 省略できる
// config.id = 'abc';             // Cannot assign to 'id' because it is a read-only property.

interface User {
  name: string;
  age?: number;
}

const user: User = { name: 'Alice' };

const age = user.age;          // age: number | undefined

// error TS18048: 'user.age' is possibly 'undefined'.
console.log(user.age.toFixed(0));

// error TS2322: Type 'number | undefined' is not assignable to type 'number'.
const n: number = user.age;

function describe(user: User): string {
  if (user.age !== undefined) {
    // ここでは user.age: number
    return `${user.name}（${user.age.toFixed(0)}歳）`;
  }
  return `${user.name}（年齢不明）`;
}

interface Profile {
  bio?: string;
  address?: {
    city?: string;
  };
}

interface User {
  name: string;
  age?: number;
  profile?: Profile;
  greet?(): void;
}

const user: User = { name: 'Alice' };

// ?. で途中が無ければ undefined になる
const city = user.profile?.address?.city;   // city: string | undefined

// ?? で既定値を与えれば string になる
const label: string = user.profile?.address?.city ?? '未設定';

// 数値も同様（0 は 0 のまま残る）
const age: number = user.age ?? 0;

// オプショナルメソッドは ?.() で「あれば呼ぶ」
user.greet?.();

interface FetchOptions {
  url: string;
  method?: 'GET' | 'POST';
  timeout?: number;
  retry?: number;
}

function request(options: FetchOptions) {
  // 分割代入で受け取りつつ既定値を与える
  const { url, method = 'GET', timeout = 5000, retry = 0 } = options;

  // ここから先はすべて undefined を含まない型
  // method: 'GET' | 'POST' / timeout: number / retry: number
  console.log(url, method, timeout, retry);
}

request({ url: '/api/posts' });                       // GET 5000 0
request({ url: '/api/posts', timeout: undefined });   // これも 5000 になる

interface A {
  age?: number;             // 省略できる
}

interface B {
  age: number | undefined;  // 必ず書く必要がある
}

const a: A = {};            // OK

// error TS2741: Property 'age' is missing in type '{}' but required in type 'B'.
const b: B = {};

const b2: B = { age: undefined };   // こう書けば OK

function greet(name: string, title?: string): string {
  // title: string | undefined
  return title ? `${title} ${name}` : name;
}

greet('Alice');              // 省略できる
greet('Alice', 'Dr.');
greet('Alice', undefined);   // 明示的な undefined も渡せる

// error TS1016: A required parameter cannot follow an optional parameter.
function bad(title?: string, name: string) {}

// error TS1015: Parameter cannot have question mark and initializer.
function bad2(title?: string = 'Dr.') {}

// デフォルト値を付けると、省略可能かつ中では undefined を含まない型になる
function good(name: string, title: string = 'Dr.'): string {
  // title: string（undefined にならない）
  return `${title} ${name}`;
}

// lib.es5.d.ts の定義
// type Partial<T> = { [P in keyof T]?: T[P] };

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

// { name?: string; email?: string; age?: number }
type UserPatch = Partial<User>;

// 更新したい項目だけ渡せる関数
function updateUser(id: number, patch: UserPatch) {
  // ...
}

updateUser(1, { age: 31 });
updateUser(1, {});   // 何も渡さなくても型としては通る

// 逆向きの変換もある（? を外して必須にする）
type StrictUser = Required<UserPatch>;   // { name: string; email: string; age: number }

type Settings = {
  theme: { color: string; size: number };
};

// theme は省略できるが、書くなら color と size は必須
// error TS2741: Property 'color' is missing in type '{ size: number; }'...
const patch: Partial<Settings> = { theme: { size: 14 } };

const ok: Partial<Settings> = {};   // これは OK

{
  "compilerOptions": {
    "strict": true,
    "exactOptionalPropertyTypes": true
  }
}

interface User {
  name: string;
  age?: number;
}

const a: User = { name: 'Alice' };   // 省略は OK

// error TS2375: Type '{ name: string; age: undefined; }' is not assignable to type 'User'
// with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of
// the target's properties.
const b: User = { name: 'Bob', age: undefined };

interface User2 {
  name: string;
  age?: number | undefined;   // 明示的な undefined も許す
}

const c: User2 = { name: 'Carol', age: undefined };   // OK

// 読み取ったときの型は undefined を含んだまま（省略されている可能性があるため）
const age = a.age;   // age: number | undefined

// オプショナルプロパティなので delete できる
delete a.age;

const omitted = { name: 'Alice' };
const explicit = { name: 'Bob', age: undefined };

console.log('age' in omitted);          // false
console.log('age' in explicit);         // true

console.log(Object.keys(omitted));      // [ 'name' ]
console.log(Object.keys(explicit));     // [ 'name', 'age' ]

console.log(JSON.stringify(omitted));   // {"name":"Alice"}
console.log(JSON.stringify(explicit));  // {"name":"Bob"}  ← undefined は消える

// プロパティを読むだけならどちらも undefined
console.log(omitted.age === undefined, explicit.age === undefined);   // true true

const defaults = { age: 20 };

// プロパティが無いので既定値が残る
console.log({ ...defaults, ...{ name: 'Alice' } });
// { age: 20, name: 'Alice' }

// 明示的な undefined が既定値を上書きしてしまう
console.log({ ...defaults, ...{ name: 'Bob', age: undefined } });
// { age: undefined, name: 'Bob' }

// 分割代入のデフォルト値なら undefined でも既定値が使われる
const { age = 20 } = { age: undefined };
console.log(age);   // 20

interface User {
  name: string;
  age?: number;
}

function f(user: User) {
  if ('age' in user) {
    // error TS2322: Type 'number | undefined' is not assignable to type 'number'.
    const n: number = user.age;
  }

  if (user.age !== undefined) {
    const n: number = user.age;   // OK
  }
}

interface User {
  name: string;
  age?: number;
}

const user: User = { name: 'Alice' };

// strictNullChecks が無効だと、どちらもエラーにならない
const n: number = user.age;
console.log(user.age.toFixed(0));   // 実行時に TypeError になる

function ng(user: User, items: number[]) {
  if (user.age !== undefined) {
    // コールバックの中では絞り込みが解除される
    // error TS2322: Type 'number | undefined' is not assignable to type 'number'.
    items.forEach(() => {
      const n: number = user.age;
    });
  }
}

function ok(user: User, items: number[]) {
  const age = user.age;          // 先に const で受ける
  if (age !== undefined) {
    items.forEach(() => {
      const n: number = age;     // OK
    });
  }
}