Воплощённые типы

Всем привет!

Хочу представить вам подход к определению типов, позволяющий сделать ваш код чище и понятнее. Я называю это «Воплощённые типы» («Embodied types»).

Воплощённый тип — тип, для которого определена переменная с одинаковым именем и в которой содержится объект с утилитами для этого типа.

Начнём с практического примера. Он искусственный, но так будет короче и понятнее.

Допустим, в ответе от сервера в поле decision мы получаем значение типа string или null.

В зависимости от некоторых условий, это будет либо произвольный текст, либо значение, имеющее только три формы: ‘foo’, ‘bar’ и null.
«Истинные» значения: ‘foo’ и null.

Типизировать это можно вот так:

// types.ts  export type StrBool = 'foo' | 'bar' | null; export type Response = { decision: string | null }; // Можно написать и decision: string | StrBool, // но typescript все равно сведет это к типу string | null

Значение из поля decision может использоваться много где в проекте, но нас интересуют несколько предполагаемых функций:

// run.ts  export function runFoo(): void {   /* ... */ }  export function runBar(): void {   /* ... */ }  export function runNull(): void {   /* ... */ }  // utils.ts  export function log(value: boolean) {   /* ... */ }

Исходный код в репозитории, шаг 0.

Если значение decision является типом StrBool, то в зависимости от того, какое значение в поле decision, мы должны запустить одну из функций run*, а также вызвать log, передав в него decision, преобразованный в boolean.

Начнём с очевидного и прямолинейного варианта:

// index.ts import { handle } from './handle';  /* ...получаем decision */  if (decision === 'foo' || decision === 'bar' || decision === null) {   handle(decision); }  // handle.ts import { StrBool } from './types'; import { runFoo, runBar, runNull } from './run'; import { log } from './utils';  export function handle(decision: StrBool): void {   if (decision === 'foo') {     runFoo();   } else if (decision === 'bar') {     runBar();   } else {     runNull();   }   log(decision === 'foo' || decision === null); }

Исходный код в репозитории, шаг 1.

Выглядит не очень, вам не кажется?

Помочь нам может type guard. Напишем его для типа StrBool:

// utils.ts  import { StrBool } from './types';  export function isStrBool(value: unknown): value is StrBool {   return value === 'foo' || value === 'bar' || value === null; }  export function log(value: boolean) {   /* ... */ }

Решение принимает вид:

// index.ts import { handle } from './handle'; import { isStrBool } from './utils';  /* ...получаем decision */  if (isStrBool(decision)) {   handle(decision); }

Исходный код в репозитории, шаг 2.

Уже чуть лучше, но что если однажды бэк вместо ‘foo’ станет присылать ‘fooo’? Будем по всему коду исправлять сравнения? Литералы стоит поместить в константы, а ещё лучше написать функции, выполняющие сравнение и заодно являющиеся type guard-ами. Так и сделаем:

// utils.ts import { StrBool } from './types';  const STR_BOOL_FOO: StrBool = 'foo'; const STR_BOOL_BAR: StrBool = 'bar';  export function isStrBool(value: unknown): value is StrBool {   return isStrBoolFoo(value) || isStrBoolBar(value) || isStrBoolNull(value); }  export function isStrBoolFoo(value: unknown): value is StrBool {   return value === STR_BOOL_FOO; }  export function isStrBoolBar(value: unknown): value is StrBool {   return value === STR_BOOL_BAR; }  export function isStrBoolNull(value: unknown): value is StrBool {   return value === null; }  export function log(value: boolean) {   /* ... */ }

// handle.ts import { StrBool } from './types'; import { runFoo, runBar, runNull } from './run'; import { isStrBoolBar, isStrBoolFoo, isStrBoolNull, log } from './utils';  export function handle(decision: StrBool): void {   if (isStrBoolFoo(decision)) {     runFoo();   } else if (isStrBoolBar(decision)) {     runBar();   } else {     runNull();   }   log(isStrBoolFoo(decision) || isStrBoolNull(decision)); }

Исходный код в репозитории, шаг 3.

Теперь со стороны будет несколько проще понять, что происходит у нас в коде, а также мы облегчили себе будущие доработки выносом литералов в константы и сравнений в утилиты. Хотя и несколько многословно получилось.

Но появилась иная проблема. Узнает ли другой/новый разработчик в вашей команде об этих константах и утилитах? Будет ли их использовать? Насколько вам самим будет легко вспомнить их названия через некоторое время?

Именно эти проблемы я предлагаю решить с использованием воплощённых типов.

Взгляните-ка на этот код:

// StrBool.ts  // 1 export type StrBool = 'foo' | 'bar' | null;  // 2 export const StrBool = {   // 2.1   Foo: 'foo',   Bar: 'bar',   Null: null,   // 2.1   is,   isFoo,   isBar,   isNull,   intoBoolean, };  // 3 function is(value: unknown): value is StrBool {   return isFoo(value) || isBar(value) || isNull(value); }  // 4 function isFoo(value: unknown): value is StrBool {   return value === StrBool.Foo; }  function isBar(value: unknown): value is StrBool {   return value === StrBool.Bar; }  function isNull(value: unknown): value is StrBool {   return value === StrBool.Null; }  // 5 function intoBoolean(value: StrBool): boolean {   return isFoo(value) || isNull(value); }

1. type StrBool — определение типа, являющегося объединением трёх литералов.

2. const StrBool — объект, являющийся «воплощением» типа StrBool. Состоит из:

   2.1) литералов, составляющих тип StrBool;
   2.2) функций-утилит для типа StrBool.

3. Функция is является type guard-ом для типа StrBool.

4. Функции isFoo, isBar, isNull являются type guard-ами для типа StrBool, кроме того позволяют одновременно с выведением типа значения выполнить проверку его соответствия одному из литералов.

5. Функция intoBoolean выполняет приведение значения типа StrBool к типу boolean.

Теперь наше решение может выглядеть так:

// index.ts import { StrBool } from './StrBool'; import { handle } from './handle';  const decision = '' as string | null;  if (StrBool.is(decision)) {   handle(decision); }  // handle.ts import { StrBool } from './StrBool'; import { runFoo, runBar, runNull } from './run'; import { log } from './utils';  export function handle(decision: StrBool): void {   if (StrBool.isFoo(decision)) {     runFoo();   } else if (StrBool.isBar(decision)) {     runBar();   } else {     runNull();   }   log(StrBool.intoBoolean(decision)); }

Исходный код в репозитории, шаг 4.

Таким образом, мы заменили разрозненный ворох функций и констант, существующих в отрыве от связанного с ними типа, на один объект с тем же именем что и у типа. Это — воплощённый тип.

По моему мнению, воплощённые типы позволяют улучшить читаемость кода, быстрее отлавливать ошибки и качественнее структурировать проект.

Кроме того, такой подход открывает ещё больше возможностей. Утилиты можно неограниченно добавлять в объект, связанный с типом, не засоряя импорты. Можно внутри проекта выработать контракт о том, для каких разновидностей типов, какой набор утилит и с какими именами является стандартом (переменной, содержащей объект, можно присвоить любой тип) и так далее.

На этом всё, рад буду почитать ваше мнение о таком подходе в комментариях.

Также пишите в комментариях, если вам будет интересно почитать статью про реализацию воплощённого типа — дженерика. Будут некоторые нюансы, и каррированные type guard-ы.