Я продолжаю серию публикаций адаптированного и дополненного
перевода
"Карманной книги по TypeScript
".
Другие части:
Функции это основные строительные блоки любого приложения, будь
то функции, импортируемые из другого модуля, или методы класса. В
TS
существует несколько способов описания того, как
фукнции вызываются.
Простейшим способом описания типа функции является выражение.
Такие типы похожи на стрелочные функции:
function greeter(fn: (a: string) => void) { fn('Hello, World')}function printToConsole(s: string) { console.log(s)}greeter(printToConsole)
Выражение (a: string) => void
означает "функция
с одним параметром a
типа string
, которая
ничего не возвращает". Как и в случае с определением функции, если
тип параметра не указан, он будет иметь значение
any
.
Обратите внимание: название параметра является
обязательным. Тип функции (string) => void
означает
"функция с параметром string
типа
any
"!
Разумеется, для типа функции можно использовать синоним:
type GreetFn = (a: string) => voidfunction greeter(fn: GreetFn) { // ...}
Сигнатуры вызова (call
signatures)
В JS
функции, кроме того, что являются вызываемыми
(callable), могут иметь свойства. Однако, тип-выражение не
позволяет определять свойства функции. Для описания вызываемой
сущности (entity), обладающей некоторыми свойствами, можно
использовать сигнатуру вызова (call signature) в объектном
типе:
type DescFn = { description: string (someArg: number): boolean}function doSomething(fn: DescFn) { console.log(`Значением, возвращаемым ${fn.description} является ${fn(6)}`)}
Обратите внимание: данный синтаксис немного отличается
от типа-выражения функции между параметрами и возвращаемым
значением используется :
вместо
=>
.
Сигнатуры
конструктора (construct signatures)
Как известно, функции могут вызываться с ключевым словом
new
. TS
считает такие функции
конструкторами, поскольку они, как правило, используются для
создания объектов. Для определения типов таких функций используется
сигнатура конструктора:
type SomeConstructor = { new (s: string): SomeObject}function fn(ctor: SomeConstructor) { return new ctor('Hello!')}
Некоторые объекты, такие, например, как объект
Date
, могут вызываться как с, так и без
new
. Сигнатуры вызова и конструктора можно
использовать совместно:
interface CallOrConstruct { new (s: string): Date (n?: number): number}
Общие функции или функции-дженерики (generic functions)
Часто тип данных, возвращаемых функцией, зависит от типа
передаваемого функции аргумента или же два типа возвращаемых
функцией значений зависят друг от друга. Рассмотрим функцию,
возвращающую первый элемент массива:
function firstElement(arr: any[]) { return arr[0]}
Функция делают свою работу, но, к сожалению, типом возвращаемого
значения является any
. Было бы лучше, если бы функция
возвращала тип элемента массива.
В TS
общие типы или дженерики (generics)
используются для описания связи между двумя значениями. Это
делается с помощью определения параметра Type
в
сигнатуре функции:
function firstElement<Type>(arr: Type[]): Type { return arr[0]}
Добавив параметр Type
и использовав его в двух
местах, мы создали связь между входящими данными функции (массивом)
и ее выходными данными (возвращаемым значением). Теперь при вызове
функции возвращается более конкретный тип:
// `s` имеет тип `string`const s = firstElement(['a', 'b', 'c'])// `n` имеет тип `number`const n = firstElement([1, 2, 3])
Предположение типа
(inference)
Мы можем использовать несколько параметров типа. Например,
самописная версия функции map
может выглядеть так:
function map<Input, Output>(arr: Input[], func: (arg: Input) => Output): Output[] { return arr.map(func)}// Типом `n` является `string`,// а типом `parsed` - `number[]`const parsed = map(['1', '2', '3'], (n) => parseInt(n))
Обратите внимание, что в приведенном примере
TS
может сделать вывод относительно типа
Input
на основе переданного string[]
, а
относительно типа Output
на основе возвращаемого
number
.
Ограничения (constraints)
Ограничение, как следует из названия, используется для
ограничения типов, принимаемых параметром типа.
Реализуем функцию, возвращающую самое длинное из двух значений.
Для этого нам потребуется свойство length
, которое
будет числом. Мы ограничим параметр типа типом number
с помощью ключевого слова extends
:
function longest<Type extends { length: number }>(a: Type, b: Type) { if (a.length >= b.length) { return a } else { return b }}// Типом `longerArr` является `number[]`const longerArr = longest([1, 2], [1, 2, 3])// Типом `longerStr` является `string`const longerStr = longest('alice', 'bob')// Ошибка! У чисел нет свойства `length`const notOK = longest(10, 100)// Argument of type 'number' is not assignable to parameter of type '{ length: number }'.// Аргумент типа 'number' не может быть присвоен параметру типа '{ length: number; }'
Мы позволяем TS
предполагать тип значения,
возвращаемого из функции longest
.
Поскольку мы свели Type
к { length: number
}
, то получили доступ к свойству length
параметров a
и b
. Без ограничения типа у
нас бы не было такого доступа, потому что значения этих свойств
могли бы иметь другой тип без длины.
Типы longerArr
и longerStr
были
выведены на основе аргументов. Запомните, дженерики
определяют связь между двумя и более значениями одного типа!
Наконец, как мы и ожидали, вызов longest(10, 100)
отклоняется, поскольку тип number
не имеет свойства
length
.
Работа с
ограниченными значениями
Вот пример распространенной ошибки, возникающей при работе с
ограничениями дженериков:
function minLength<Type extends { length: number }>( obj: Type, min: number): Type { if (obj.length >= min) { return obj } else { return { length: min } }}// Type '{ length: number; }' is not assignable to type 'Type'. '{ length: number; }' is assignable to the constraint of type 'Type', but 'Type' could be instantiated with a different subtype of constraint '{ length: number; }'.// Тип '{ length: number; }' не может быть присвоен типу 'Type'. '{ length: number; }' может присваиваться ограничению типа 'Type', но 'Type' может быть инстанцирован с другим подтипом ограничения '{ length: number; }'
На первый взгляд может показаться, что все в порядке
Type
сведен к { length: number }
, и
функция возвращает либо Type
, либо значение,
совпадающее с ограничением. Проблема состоит в том, что функция
может вернуть объект, идентичный тому, который ей передается, а не
просто объект, совпадающий с ограничением. Если бы во время
компиляции не возникло ошибки, мы могли бы написать что-то вроде
этого:
// `arr` получает значение `{ length: 6 }`const arr = minLength([1, 2, 3], 6)// и ломает приложение, поскольку массивы// имеют метод `slice`, но не возвращаемый объект!console.log(arr.slice(0))
Определение типа
аргументов
Обычно, TS
делает правильные выводы относительно
типов аргументов в вызове дженерика, но так бывает не всегда.
Допустим, мы реализовали такую функцию для объединения двух
массивов:
function combine<Type>(arr1: Type[], arr2: Type[]): Type[] { return arr1.concat(arr2)}
При обычном вызове данной функции с несовпадающими по типу
массивами возникает ошибка:
const arr = combine([1, 2, 3], ['привет'])// Type 'string' is not assignable to type 'number'.
Однако, мы можем вручную определить Type
, и тогда
все будет в порядке:
const arr = combine<string | number>([1, 2, 3], ['привет'])
Руководство по написанию хороших функций-дженериков
Используйте
параметры типа без ограничений
Рассмотрим две похожие функции:
function firstElement1<Type>(arr: Type[]) { return arr[0]}function firstElement2<Type extends any[]>(arr: Type) { return arr[0]}// a: number (хорошо)const a = fisrtElement1([1, 2, 3])// b: any (плохо)const b = fisrtElement2([1, 2, 3])
Предполагаемым типом значения, возвращаемого функцией
firstElement1
является Type
, а значения,
возвращаемого функцией firstElement2
any
.
Это объясняется тем, что TS
разрешает (resolve)
выражение arr[0]
с помощью ограничения типа вместо
того, чтобы ждать разрешения элемента после вызова функции.
Правило: по-возможности, используйте параметры типа без
ограничений.
Используйте минимальное количество параметров типа
Вот еще одна парочка похожих функций:
function filter1<Type>(arr: Type[], func: (arg: Type) => boolean): Type[] { return arr.filter(func)}function filter2<Type, Func extends (arg: Type) => boolean>( arr: Type[], func: Func): Type[] { return arr.filter(func)}
Во втором случае мы создаем параметр типа Func
,
который не связывает значения. Это означает, что при вызове функции
придется определять дополнительный аргумент типа без веских на то
причин. Это не есть хорошо.
Правило: всегда используйте минимальное количество
параметров типа.
Параметры типа
должны указываться дважды
Иногда мы забываем, что функция не обязательно должна быть
дженериком:
function greet<Str extends string>(s: Str) { console.log(`Привет, ${s}!`)}greet('народ')
Вот упрощенная версия данной функции:
function greet(s: string) { console.log(`Привет, ${s}!`)}
Запомните, параметры типа предназначены для связывания типов
нескольких значений.
Правило: если параметр типа появляется в сигнатуре
функции только один раз, то, скорее всего, он вам не нужен.
Опциональные
параметры (optional parameters)
Функции в JS
могут принимать произвольное
количество аргументов. Например, метод toFixed
принимает опциональное количество цифр после запятой:
function fn(n: number) { console.log(n.toFixed()) // 0 аргументов console.log(n.toFixed(3)) // 1 аргумент}
Мы можем смоделировать это в TS
, пометив параметр
как опциональный с помощью ?
:
function f(x?: number) { // ...}f() // OKf(10) // OK
Несмотря на то, что тип параметра определен как
number
, параметр x
на самом деле имеет
тип number | undefined
, поскольку неопределенные
параметры в JS
получают значение
undefined
.
Мы также можем указать "дефолтный" параметр (параметр по
умолчанию):
function f(x = 10) { // ...}
Теперь в теле функции f
параметр x
будет иметь тип number
, поскольку любой аргумент со
значением undefined
будет заменен на 10
.
Обратите внимание: явная передача undefined
означает "отсутствующий" аргумент.
declare function f(x?: number): void// OKf()f(10)f(undefined)
Опциональные параметры в функциях обратного вызова
При написании функций, вызывающих "колбеки", легко допустить
такую ошибку:
function myForEach(arr: any[], callback: (arg: any, index?: number) => void) { for (let i = 0; i < arr.length; i++) { callback(arr[i], i) }}
Указав index?
, мы хотим, чтобы оба этих вызова были
легальными:
myForEach([1, 2, 3], (a) => console.log(a))myForEach([1, 2, 3], (a, i) => console.log(a, i))
В действительности, это означает, что колбек может быть
вызван с одним аргументом. Другими словами, определение
функции говорит, что ее реализация может выглядеть так:
function myForEach(arr: any[], callback: (arg: any, index?: number) => void) { for (let i = 0; i < arr.length; i++) { callback(arr[i]) }}
Поэтому попытка вызова такой функции приводит к ошибке:
myForEach([1, 2, 3], (a, i) => { console.log(i.toFixed()) // Object is possibly 'undefined'. // Возможным значением объекта является 'undefined'})
В JS
при вызове функции с большим (ударение на
первый слог) количеством аргументов, чем указано в определении
фукнции, дополнительные параметры просто игнорируются.
TS
ведет себя аналогичным образом. Функции с меньшим
количеством параметров (одного типа) могут заменять функции с
большим количеством параметров.
Правило: при написании типа функции для колбека, не
указывайте опциональные параметры до тех пор, пока не будете
вызывать функцию без передачи этих параметров.
Перегрузка функции
(function overload)
Некоторые функции могут вызываться с разным количеством
аргументов. Например, мы можем написать функцию, возвращающую
Date
, которая принимает время в мс (timestamp, один
аргумент) или день/месяц/год (три аргумента).
В TS
такую функцию можно реализовать с помощью
сигнатур перегрузки (overload signatures). Для этого перед телом
функции указывается несколько ее сигнатур:
function makeDate(timestamp: number): Datefunction makeDate(d: number, m: number, y: number): Datefunction makeDate(dOrTimestamp: number, m?: number, y?: number): Date { if (m !== undefined && y !== undefined) { return new Date(y, m, dOrTimestamp) } else { return new Date(dOrTimestamp) }}const d1 = makeDate(12345678)const d2 = makeDate(5, 5, 5)const d3 = makeDate(1, 3)// No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments.// Нет перегрузки, принимающей 2 аргумента, но существуют перегрузки, ожидающие получения 1 или 3 аргумента
В приведенном примере мы реализовали две перегрузки: одну,
принимающую один аргумент, и вторую, принимающую три аргумента.
Первые две сигнатуры называются сигнатурами перегрузки.
Затем мы реализовали функцию с совместимой сигнатурой
(compatible signature). Функции имеют сигнатуру реализации
(implementation signature), но эта сигнатура не может вызываться
напрямую. Несмотря на то, что мы написали функцию с двумя
опциональными параметрами после обязательного, она не может
вызываться с двумя параметрами!
Сигнатуры
перегрузки и сигнатура реализации
Предположим, что у нас имеется такой код:
function fn(x: string): voidfunction fn() { // ...}// Мы ожидаем, что функция может вызываться без аргументовfn()// Expected 1 arguments, but got 0.// Ожидалось получение 1 аргумента, а получено 0
Почему в данном случае возникает ошибка? Дело в том, что
сигнатура реализации не видна снаружи (за пределами тела функции).
Поэтому при написании перегруженной функции всегда нужно указывать
две или более сигнатуры перегрузки перед сигнатурой реализации.
Кроме того, сигнатура реализации должна быть совместима с
сигнатурами перегрузки. Например, при вызове следующих функций
возникают ошибки, поскольку сигнатура реализации не совпадает с
сигнатурами перегрузки:
function fn(x: boolean): void// Неправильный тип аргументаfunction fn(x: string): void// This overload signature is not compatible with its implementation signature.// Данная сигнатура перегрузки не совместима с сигнатурой ее реализацииfunction(x: boolean) {}
function fn(x: string): string// Неправильный тип возвращаемого значенияfunction(x: number): boolean// This overload signature is not compatible with its implementation signature.function fn(x: string | number) { return 'упс'}
Правила
реализации хороших перегрузок функции
Рассмотрим функцию, возвращающую длину строки или массива:
function len(s: string): numberfunction len(arr: any[]): numberfunction len(x: any) { return x.length}
На первый взгляд кажется, что все в порядке. Мы можем вызывать
функцию со строками или массивами. Однако, мы не можем вызывать ее
со значением, которое может быть либо строкой, либо массивом,
поскольку TS
ассоциирует вызов функции с одной из ее
перегрузок:
len('') // OKlen([0]) // OKlen(Math.random() > 0.5 ? 'привет' : [0])/*No overload matches this call. Overload 1 of 2, '(s: string): number', gave the following error. Argument of type 'number[] | "привет"' is not assignable to parameter of type 'string'. Type 'number[]' is not assignable to type 'string'. Overload 2 of 2, '(arr: any[]): number', gave the following error. Argument of type 'number[] | "привет"' is not assignable to parameter of type 'any[]'. Type 'string' is not assignable to type 'any[]'.*//*Ни одна из перегрузок не совпадает с вызовом. Перегрузка 1 из 2, '(s: string): number', возвращает следующую ошибку. Аргумент типа 'number[] | "привет"' не может быть присвоен параметру типа 'string'. Тип 'number[]' не может быть присвоен типу 'string'. Перегрузка 2 из 2, '(arr: any[]): number', возвращает следующую ошибку. Аргумент типа 'number[] | "привет"' не может быть присвоен типу 'any[]'. Тип 'string' не может быть присвоен типу 'any[]'.*/
Поскольку обе перегрузки имеют одинаковое количество аргументов
и один и тот же тип возвращаемого значения, мы можем реализовать
такую "неперегруженную" версию данной функции:
function len(x: any[] | string) { return x.length}
Так намного лучше! Теперь мы можем вызывать функцию с любым
значением и, кроме того, нам не нужно предварительно определять
правильную сигнатуру реализации функцию.
Правило: по-возможности используйте объединения вместо
перегрузок функции.
Определение this
в функциях
Рассмотрим пример:
const user = { id: 123, admin: false, becomeAdmin: function() { this.admin = true }}
TS
"понимает", что значением this
функции user.becomeAdmin
является внешний объект
user
. В большинстве случаев этого достаточно, но порой
нам требуется больше контроля над тем, что представляет собой
this
. Спецификация JS
определяет, что мы
не можем использовать this
в качестве названия
параметра. TS
использует это синтаксическое
пространство (syntax space), позволяя определять тип
this
в теле функции:
const db = getDB()const admins = db.filterUsers(function() { return this.admin})
Обратите внимание: в данном случае мы не можем
использовать стрелочную функцию.
const db = getDB()const admins = db.filterUsers(() => this.admin)// The containing arrow function captures the global value of 'this'. Element implicitly has an 'any' type because type 'typeof globalThis' has no index signature.// Стрелочная функция перехватывает глобальное значение 'this'. Неявным типом элемента является 'any', поскольку тип 'typeof globalThis' не имеет сигнатуры индекса
Другие типы, о которых
следует знать
void
void
представляет значение, возвращаемое функцией,
которая ничего не возвращает. Если в теле функции отсутствует
оператор return
или после этого оператора не указано
возвращаемого значения, предполагаемым типом возвращаемого такой
функцией значения будет void
:
// Предполагаемым типом является `void`function noop() { return}
В JS
функция, которая ничего не возвращает,
"неявно" возвращает undefined
. Однако, в
TS
void
и undefined
это
разные вещи.
Обратите внимание: void
это не тоже самое,
что undefined
.
object
Специальный тип object
представляет значение,
которое не является примитивом (string, number, boolean,
symbol, null, undefined
). object
отличается от
типа пустого объекта ({}
), а также от глобального типа
Object
. Скорее всего, вам никогда не потребуется
использовать Object
.
Правило: object
это не
Object
. Всегда используйте object
!
Обратите внимание: в JS
функции это
объекты: они имеют свойства, Object.prototype
в
цепочке прототипов, являются instanceof Object
, мы
можем вызывать на них Object.keys
и т.д. По этой
причине в TS
типом функций является
object
.
unknown
Тип unknown
представляет любое значение. Он похож
на тип any
, но является более безопасным, поскольку не
позволяет ничего делать с неизвестным значением:
function f1(a: any) { a.b() // OK}function f2(a: unknown) { a.b() // Object is of type 'unknown'. // Типом объекта является 'unknown'}
Это бывает полезным для описания типа функции, поскольку таким
способом мы можем описать функцию, принимающую любое значение без
использования типа any
в теле функции. Другими
словами, мы можем описать функцию, возвращающую значение
неизвестного типа:
function safeParse(s: string): unknown { return JSON.parse(s)}const obj = safeParse(someRandomString)
never
Некоторые функции никогда не возвращают значений:
function fail(msg: string): never { throw new Error(msg)}
Тип never
представляет значение, которого не
существует. Чаще всего, это означает, что функция выбрасывает
исключение или останавливает выполнение программы.
never
также появляется, когда TS
определяет, что в объединении больше ничего не осталось:
function fn(x: string | number) { if (typeof x === 'string') { // ... } else if (typeof x === 'number') { // ... } else { x // типом `x` является `never`! }}
Function
Глобальный тип Function
описывает такие свойства
как bind
, call
, apply
и
другие, характерные для функций в JS
. Он также имеет
специальное свойство, позволяющее вызывать значения типа
Function
такие вызовы возвращают any
:
function doSomething(f: Function) { f(1, 2, 3)}
Такой вызов функции называется нетипизированным и его лучше
избегать из-за небезопасного возвращаемого типа
any
.
Если имеется необходимость принимать произвольную функцию без ее
последующего вызова, лучше предпочесть более безопасный тип
() => void
.
Оставшиеся параметры и
аргументы
Оставшиеся
параметры (rest parameters)
Кроме использования опциональных параметров или перегрузок для
создания функций, принимающих разное или фиксированное количество
аргументов, мы можем определять функции, принимающие произвольное
количество аргументов с помощью синтаксиса
оставшихся параметров.
Оставшиеся параметры указываются после других параметров с
помощью ...
:
function multiply(n: number, ...m: number[]) { return m.map((x) => n * x)}// `a` получает значение [10, 20, 30, 40]const a = multiply(10, 1, 2, 3, 4)
В TS
неявным типом таких параметров является
any[]
, а не any
. Любая аннотация типа для
них должна иметь вид Array<T>
или
T[]
, или являться кортежем.
Оставшиеся аргументы
(rest arguments)
Синтаксис
распространения (синонимы: расширение, распаковка) (spread
syntax) позволяет передавать произвольное количество элементов
массива. Например, метод массива push
принимает любое
количество аргументов:
const arr1 = [1, 2, 3]const arr2 = [4, 5, 6]arr1.push(...arr2)
Обратите внимание: TS
не считает массивы
иммутабельными. Это может привести к неожиданному поведению:
// Предполагаемым типом `args` является `number[]` - массив с 0 или более чисел// а не конкретно с 2 числамиconst args = [8, 5]const angle = Math.atan2(...args)// Expected 2 arguments, but got 0 or more.// Ожидалось получение 2 аргументов, а получено 0 или более
Самым простым решением данной проблемы является использование
const
:
// Предполагаемым типом является кортеж, состоящий из 2 элементовconst args = [8, 5] as const// OKconst angle = Math.atan2(...args)
Деструктуризация параметров (parameter destructuring)
Деструктуризация параметров используется для распаковки
объекта, переданного в качестве аргумента, в одну или более
локальную переменную в теле функции. В JS
это выглядит
так:
function sum({ a, b, c }) { console.log(a + b + c)}sum({ a: 10, b: 3, c: 9 })
Аннотация типа для объекта указывается после
деструктуризации:
function sum({ a, b, c }: { a: number, b: number, c: number }) { console.log(a + b + c)}
Для краткости можно использовать именованный тип:
type ABC = { a: number, b: number, c: number }function sum({ a, b, c }: ABC) { console.log(a + b + c)}
Возможность
присвоения функций переменным
Использование void
в качестве типа возвращаемого
функцией значения может приводить к необычному, но вполне
ожидаемому поведению.
Контекстуальная типизация (contextual typing), основанная на
void
, не запрещает функции что-либо возвращать.
Другими словами, функция, типом возвращаемого значения которой
является void
type vf = () => void
,
может возвращать любое значение, но это значение будет
игнорироваться.
Все приведенные ниже реализации типа () => void
являются валидными:
type voidFn = () => voidconst f1: voidFn = () => { return true}const f2: voidFn = () => trueconst f3: voidFn = function() { return true}
Когда возвращаемое любой из этих функций значение присваивается
переменной, она будет хранить тип void
:
const v1 = f1()const v2 = f2()const v3 = f3()
Поэтому следующий код является валидным, несмотря на то, что
Array.prototype.push
возвращает число, а
Array.prototype.forEach
ожидает получить функцию с
типом возвращаемого значения void
:
const src = [1, 2, 3]const dst = [0]src.forEach((el) => dist.push(el))
Существует один специальный случай, о котором следует помнить:
когда литеральное определение функции имеет тип возвращаемого
значения void
, функция не должна ничего
возвращать:
function f2(): void { // Ошибка return true}const f3 = function(): void { // Ошибка return true}
Облачные серверы от Маклауд
быстрые и безопасные.
Зарегистрируйтесь по ссылке выше или кликнув на баннер и
получите 10% скидку на первый месяц аренды сервера любой
конфигурации!