DIGGLEにおけるBranded Typeを活用した型の強化

See More

はじめに

DIGGLEエンジニアのitoです。

最近は少しづつ暖かくなっているように感じていますが、時折寒い日が来るたびに三寒四温という言葉を思い返しています。

DIGGLEでは2023年1月からTypeScriptを導入してフロントエンドの開発をしています。

TypeScriptの型によって開発に多くの安心感をもたらしてくれますが、型を適用すれば終わりという話ではなく型の効果を高めるためのTipsが多く存在しており、よりよい開発環境を構築するために日々改善をしていく必要があります。

今回はそのようなTipsの一つであるBranded Typeを導入し、数値型の用途に応じたタグ付けによって意図しない演算を防ぐ方法について紹介します。

Branded Typeとは

Branded Type*1は独自で定義した型をより強固にできるTipsです。

型エイリアス

Branded Typeは型エイリアスとの相性がよいTipsになっているため、型エイリアスを軸に説明をさせていただきます。

型エイリアスとは、型に別名をつけることができる機能です。

typescriptbook.jp

TypeScriptの型はプリミティブ型とオブジェクトに分けることができ、それらの型単体の別名や組み合わせた型に名前をつけることができます。

typescriptbook.jp

type Positive = number // プリミティブ型の型エイリアス

type Cat = { name: string; species: string; } // オブジェクトの型エイリアス

型エイリアスは非常に便利なのですが、結局は同じ型であるために別の型として扱いたい場面では使えなかったりします。

例えば下記のような状況です。

type Positive = number // 正の数

let positiveNum: Positive = 1
positiveNum = -1
// 負の数を代入してもエラーにならない

type Unit = { id: string, name: string }
type Budget = { id: string, name: string, unitId: number }
type Row = { id: string, summary: string, budgetId: number }

async function getRows(budgetId: string) {
  const response = await api.get(`/budget/${budgetId}/rows`)
  return response.data
}
const rows = await getRows(unit.id)
// 異なるデータ構造のIDを渡してもエラーにならない

どちらの場合も型としてはnumberやstringを定められているだけのため、同様の型を持っているものであればどのようなデータであっても入ってしまいます。

オブジェクトにするとkeyを異なる組み合わせにすることである程度緩和することはできるものの、同じkeyの組み合わせを持っているオブジェクト同士はTypeScriptの構造的型付けの仕組みによって同一とみなされてしまうため常に通用するわけではありません。

typescriptbook.jp

クラスにすることで解決することではありますが、クラスから値を一つ取り出す場合などに同じ問題に直面することになります。

このような場合で、動作検証をする前の型チェックのタイミングでエラーを出してくれると開発の効率が上がります。

Branded Type

Branded Typeを活用することによって、前述の型エイリアスの例をより強固な型にすることができます。例えば、数値型に「正の数」や「ポイント座標」などのタグを付けることで、誤った代入や演算を防ぐことができます。

やり方は色々方法があるのですが、下記のサイトで紹介されている方法はシンプルでダミーのシンボル(__brand)を用意した後、 型にそのダミーシンボルを使った& { [__brand]: T }を加えるだけです*2。

egghead.io

declare const __brand: unique symbol
type Brand<B> = { [__brand]: B }
export type Branded<T, B> = T & Brand<B>

Branded Typeを踏まえて前述の例で紹介したコードを書き直すと下記のようになります。

type Positive = Branded<number, 'Positive'> // 正の数

let positiveNum: Positive = 1 as Positive
positiveNum = -1
// 型 'number' を型 'Brand<"Positive">' に割り当てることはできません。ts(2322)

type Unit = { id: Branded<number, 'UnitId'>; name: string }
type Budget = { id: Branded<number, 'BudgetId'>; name: string; unitId: number }
type Row = { id: Branded<number, 'RowId'>; summary: string; budgetId: number }

async function getRows(budgetId: Branded<number, 'BudgetId'>) {
  const response = await api.get(`/budget/${budgetId}/rows`)
  return response.data
}
const rows = await getRows(unit.id)
//   型 'Branded<number, "UnitId">' を型 'Brand<"BudgetId">' に割り当てることはできません。
//    プロパティ '[__brand]' の型に互換性がありません。
//      型 '"UnitId"' を型 '"BudgetId"' に割り当てることはできません。ts(2345)

無事にエラーが出て誤った代入を事前に検知できるようになりました。

positiveNum = -1の例もpositiveNum = -1 as Positiveとしてしまえば代入自体はできてしまいますが、-1 as Positiveと記述した時点で違和感を覚えることができると思います。

DIGGLEでのBranded Typeの活用方法

DIGGLEでは損益計算書(PL)を表現するにあたってCanvasタグによる描画を活用しています。

diggle.engineer

Branded Typeは、Canvasタグによるテーブルを構築すると区別したくなる下記の二つの情報を適切に区別することに役立ちました。

• Canvasタグ内に描画する際の座標(Point)
• テーブル内のセルの位置(Index)

PointとIndexについて

Pointを設定する部分にIndexを指定してしまったり、その逆が起こってしまうとCanvasの描画が崩壊してしまいます。

開発している際にローカル環境で発生したバグには下記のようなものがあり、それぞれの取り間違いを型エラーで検知できなければ改善やリファクタリングで再発するリスクがあります。

• テーブルの固定行や列を指定するセルの位置(Index)に、誤ってPointの値を突っ込んでしまう
  • 固定行や列に大きな値が設定され、Canvasタグ一面に固定行や列が表示されてしまう
• 罫線の描画でセルの位置(Index)を罫線描画開始位置のPointに変換する必要があるのにIndexのまま突っ込んでしまう
  • 罫線が正しく描画されずテーブルの描画が崩れる

デグレが発生しないようにスナップショットテストを仕込むなどしていましたが、それでももしかしたらとCanvasテーブルを改善しようとするたびに気を張らなければいけませんでした。

Branded Type化によって取り間違いを事前にエラーで検知できるようになり、気を張らずに思い切った改善をしやすい環境ができました。

Canvasタグでの実際の活用方法

DIGGLEでは下記の記事を参考にさせていただき、Branded Typeを用意しています。

zenn.dev

declare const __brand: unique symbol

type Brand<T, TrueKeys extends string, FalseKeys extends string = never> = T & {
  [__brand]: {
    readonly [key in FalseKeys | TrueKeys]: key extends TrueKeys ? true : false
  }
}

ここのままでもかなり有用なのですが、Point/Indexで活用しようとすると四則演算で型の情報が吹き飛ぶ問題が発生します。

type Point = Brand<number, 'Point'>

const pointA = 100 as Point
const pointB = 200 as Point
const pointC: Point = pointA + pointB // Point型ではなくnumber型になるためエラーが発生する

asで四則演算のたびに無理やりキャストすることはできるのですが、四則演算の中で型を混在することもできてしまいます。

type Point = Brand<number, 'Point'>
type Index = Brand<number, 'Index'>

const pointA = 100 as Point
const pointB = 200 as Point
const pointC: Point = (pointA + pointB) as Point // Point型になる

const indexA = 1 as Index
const num: Point = (pointA + indexA) as Point // 特にエラーにならない

Canvasでのテーブル描画では煩雑な四則演算が行われるため、型の取り間違いでエラーを起こす危険性も高く、できれば安全に対応したい部分でした。

そこでnumber型にだけBrandedNumberという型/値を用意して、値のほうに型の問題を解消する四則演算を仕込むことにしました。

export type BrandedNumber<
  TrueKeys extends string,
  FalseKeys extends string = never,
> = Brand<number, TrueKeys, FalseKeys>
export const BrandedNumber =
  <Z extends z.Schema>(schema: Z) =>
  <T extends number>() => {
    const brandedNumber = (num: number): T => {
      const result = schema.safeParse(num)
      if (result.success) return result.data as T
      console.error(result.error)
      throw new Error(`Validation error, ${schema.description}`, result.error)
    }

    brandedNumber.add = (...args: T[]): T =>
      args.reduce((acc: number, cur: number) => acc + cur, 0) as T
    brandedNumber.subtract = (first: T, ...rest: T[]): T => {
      if (first === undefined) throw new Error('First argument is required')
      return rest.reduce((acc: number, cur: number) => acc - cur, first) as T
    }
    brandedNumber.multiply = (a: T, b: number): T => (a * b) as T
    brandedNumber.divide = (a: T, b: number): T => {
      if (b === 0) throw new Error('Division by zero')
      return (a / b) as T
    }

    brandedNumber.z = schema as Z

    return brandedNumber
  }

BrandedNumberを利用すると下記のように安全に四則演算をできるようになります。

export type Point = BrandedNumber<'Point', 'Index' | BrandedNumberType.NaN>

const schema = z.coerce.number().default(-1).describe('Point')
export const Point = BrandedNumber(schema)<Point>()

const add = Point.add(Point(1), Point(2))
const sub = Point.subtract(Point(1), Point(2))
const mul = Point.multiply(Point(1), 5)
const div = Point.divide(Point(1), 5)

ついでになるべくasを使わなくて済むようにPoint(1)の形で対象の型の値を作れるような関数を仕込みました。

仕込んだ関数ではzodのparseを仕込めるようにしています(zodを仕込めるようにすることでPosition(-1)と値を作成した際にエラーを出せるようになりました)。

export type BrandedNumber<
  TrueKeys extends string,
  FalseKeys extends string = never,
> = Brand<number, TrueKeys, FalseKeys>
/// NOTE: 部分的型推論が効かないため、カリー化することによってschemaのほうに型推論が効くようにしている
///       このため、BrandedNumber(schema)<T>()のように利用する
export const BrandedNumber =
  <Z extends z.Schema>(schema: Z) =>
  <T extends number>() => {
    const brandedNumber = (num: number): T => {
      const result = schema.safeParse(num)
      if (result.success) return result.data as T
      console.error(result.error)
      throw new Error(`Validation error, ${schema.description}`, result.error)
    }

   ...

    return brandedNumber
  }

わざわざカリー化させているconst brandedNumber = (num: number): Tの部分は本当は下記のようにしたかったです。

export type BrandedNumber<
  TrueKeys extends string,
  FalseKeys extends string = never,
> = Brand<number, TrueKeys, FalseKeys>
export const BrandedNumber =
  <T extends number, Z extends z.Schema>(schema: Z) => {
    const brandedNumber = (num: number): T => {
      const result = schema.safeParse(num)
      if (result.success) return result.data as T
      console.error(result.error)
      throw new Error(`Validation error, ${schema.description}`, result.error)
    }

   ...

    return brandedNumber
  }

ですが、コメント部分に記載している通りTを指定してしまうと引数にzodのschemaを渡してもZの型推論がされなくなってしまったため、カリー化することで推論を効かせて利用できるようにしています。

交差型の扱いについて

参考にさせていただいた下記の記事では、

zenn.dev

Branded Type のオブジェクト型のvalueにunknownではなくtrue/falseを持たせる

という工夫で同じkeyでそれぞれtrue/falseを指定すると全体がnever型になるようにしていました。

type PositiveNumber = number & { Positive: true };

type NegativeNumber = number & { Positive: false };

type PositiveNegativeNumber = PositiveNumber & NegativeNumber; // never

true/falseで分けられる多数の要素で構成すればPositive/Negativeといった2値の関係のもの以外でも表現することができるためとても便利なやり方なのですが、 今回の対応ではダミーシンボルである__brandをかましてしまっているため、neverになっているkeyがneverになるだけで同じような振る舞いになりません。

type PositiveNumber = number & { [__brand]: { Positive: true } }
type NegativeNumber = number & { [__brand]: { Positive: false } }

type PositiveNegativeNumber = PositiveNumber & NegativeNumber // number & { [__brand]: never }

この場合のPositiveNegativeNumberã‚‚__brandキーにnever型が入ってはいるのですが、ベースにしている型が同じであれば同一キーでtrue/falseを指定している型の交差型をとったもの同士の代入はできてしまうという中途半端な状態になってしまいます。

型を見た際にnever型であればすぐに間違いに気がつけますが、number & { [__brand]: never }という型になっている場合は意図しているものか誤りなのか分かりづらい状況になってしまいます。

type TrueType = number & { [__brand]: { HogeHoge: true } }
type FalseType = number & { [__brand]: { HogeHoge: false } }

type HogeHogeNumber = TrueType & FalseType
const testNum: HogeHogeNumber = 1 as PositiveNegativeNumber
// HogeHogeNumberもnumber & { [__brand]: never }になるため、PositiveNegativeNumberを入れてもエラーにならない

そこで交差型を作るAndBrand型を用意しました。

export type AndBrand<T, U> = T extends { [__brand]: infer TO }
  ? U extends { [__brand]: infer UO }
    ? TO & UO extends never
      ? never
      : T & U
    : never
  : never

こちらを使うと下記のようになり問題が解消されます。

type TrueType = number & { [__brand]: { HogeHoge: true } }
type FalseType = number & { [__brand]: { HogeHoge: false } }

type HogeHogeNumber = AndBrand<TrueType, FalseType> // never型になることで間違いに気が付きやすくなる

まとめ

Branded Type化によって型を強固にして今後のレポート改善において自信を持って手を加えていけるような体制を整えました。

今回の対応中にも、型を誤って指定している部分を見つけるなど早速効果を発揮してくれました。

今後もこのBranded Type化を広く進めていくことによってよりよいフロントエンド環境を整えていこうと思っています。

終わりに

DIGGLEではともにプロダクトを開発してくれるエンジニアを大募集中です。

少しでも興味があれば、ぜひ下記採用サイトからエントリーください。
カジュアル面談も実施しているので、気軽なお気持ちでご応募いただければと思います！

herp.careers

*1:他の呼び方として幽霊型(Phantom Type)やBranded Primitiveという呼び方もされているようです

*2:ダミーシンボルを含んだオブジェクトを交差型で付与することで、オブジェクトのキーの型チェックで引っかかるようにするものです そのため、ダミーシンボルを含んだオブジェクトが同じ構造になっている場合は同じBranded Typeとして認識されます https://michalzalecki.com/nominal-typing-in-typescript/#approach-4-intersection-types-and-brands