Docs
⌘ K

9 минуты

Руководство по миграции AssemblyScript

Up until now, Subgraphs have been using one of the first versions of AssemblyScript⁠ (v0.6). Finally we’ve added support for the newest one available⁠ (v0.19.10)! 🎉

That will enable Subgraph developers to use newer features of the AS language and standard library.

Это руководство применимо для всех, кто использует graph-cli/graph-ts версии ниже 0.22.0. Если у Вас уже есть версия выше (или равная) этой, значит, Вы уже использовали версию 0.19.10 AssemblyScript 🙂

Note: As of 0.24.0, graph-node can support both versions, depending on the apiVersion specified in the Subgraph manifest.

Особенности

Новый функционал

  • Теперь TypedArray можно создавать из ArrayBuffer, используя новый статический метод wrap⁠ (v0.8.1⁠)
  • Новые функции стандартной библиотеки: String#toUpperCase, String#toLowerCase, String#localeCompareи TypedArray#set (v0.9.0⁠)
  • Добавлена поддержка x instanceof GenericClass (v0.9.2⁠)
  • Добавлен StaticArray<T>, более эффективный вариант массива (v0.9.3⁠)
  • Добавлен Array<T>#flat (v0.10.0⁠)
  • Реализован аргумент radix в Number#toString (v0.10.1⁠)
  • Добавлена поддержка разделителей в литералах с плавающей точкой (v0.13.7⁠)
  • Добавлена поддержка функций первого класса (v0.14.0⁠)
  • Добавлены встроенные функции: i32/i64/f32/f64.add/sub/mul (v0.14.13⁠)
  • Реализован Array/TypedArray/String#at (v0.18.2⁠)
  • Добавлена поддержка строк с шаблонными литералами (v0.18.17⁠)
  • Добавлены encodeURI(Component) и decodeURI(Component) (v0.18.27⁠)
  • Добавлены toString, toDateString и toTimeString в Date (v0.18.29⁠)
  • Добавлен toUTCString для Date (v0.18.30⁠)
  • Добавлен встроенный тип nonnull/NonNullable (v0.19.2⁠)

Оптимизации

  • Функции Math, такие как exp, exp2, log, log2 иpow, были заменены на более быстрые варианты (v0.9.0⁠)
  • Немного оптимизирована функция Math.mod (v0.17.1⁠)
  • Кэшировано больше обращений к полям в стандартных Map и Set (v0.17.8⁠)
  • Проведена оптимизация для степеней двойки в ipow32/64 (v0.18.2⁠)

Прочее

  • Тип литерала массива теперь может быть выведен из его содержимого (v0.9.0⁠)
  • Обновлена стандартная библиотека до Unicode 13.0.0 (v0.10.0⁠)

Как выполнить обновление?

  1. Change your mappings apiVersion in subgraph.yaml to 0.0.9:
...dataSources:  ...    mapping:      ...      apiVersion: 0.0.9      ...
  1. Обновите используемую Вами версию graph-cli до latest, выполнив команду:
# если он у Вас установлен глобальноnpm install --global @graphprotocol/graph-cli@latest# или в Вашем субграфе, если он у Вас как зависимость devnpm install --save-dev @graphprotocol/graph-cli@latest
  1. Сделайте то же самое для graph-ts, но вместо глобальной установки сохраните его в основных зависимостях:
npm install --save @graphprotocol/graph-ts@latest
  1. Следуйте остальной части руководства, чтобы исправить языковые изменения.
  2. Снова запустите codegen и deploy.

Критические изменения

Обнуляемость

В более старой версии AssemblyScript можно было создать такой код:

function load(): Value | null { ... }let maybeValue = load();maybeValue.aMethod();

Однако в новой версии, поскольку значение обнуляемо, требуется проверка, например, такая:

let maybeValue = load()if (maybeValue) {  maybeValue.aMethod() // `maybeValue` is not null anymore}

Или принудительно вот такая:

let maybeValue = load()! // прерывается во время выполнения, если значение равно nullmaybeValue.aMethod()

If you are unsure which to choose, we recommend always using the safe version. If the value doesn’t exist you might want to just do an early if statement with a return in you Subgraph handler.

Затенение переменных

Раньше можно было использовать затенение переменных⁠, и такой код работал:

let a = 10let b = 20let a = a + b

Однако теперь это больше невозможно, и компилятор возвращает эту ошибку:

ERROR TS2451: Cannot redeclare block-scoped variable 'a' let a = a + b; ~~~~~~~~~~~~~in assembly/index.ts(4,3)

Вам нужно будет переименовать дублированные переменные, если Вы используете затенение переменных.

Нулевые сравнения

By doing the upgrade on your Subgraph, sometimes you might get errors like these:

ERROR TS2322: Type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt | null' is not assignable to type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt'.     if (decimals == null) {                     ~~~~ in src/mappings/file.ts(41,21)

Для решения этой проблемы можно просто изменить оператор if на что-то вроде этого:

if (!decimals) {  // или  if (decimals === null) {

Подобное относится к случаям, когда вместо == используется !=.

Кастинг

Раньше преобразование типов обычно выполнялось с использованием ключевого слова as, например:

let byteArray = new ByteArray(10)let uint8Array = byteArray as Uint8Array // эквивалентно: <Uint8Array>byteArray

Однако это работает только в двух случаях:

  • Примитивное преобразование (между такими типами, как u8, i32, bool; например: let b: isize = 10; b as usize);
  • Укрупнение по наследованию классов (subclass → superclass)

Примеры:

// примитивный кастингlet a: usize = 10let b: isize = 5let c: usize = a + (b as usize)
// приведение к базовому типу при наследовании классовclass Bytes extends Uint8Array {}let bytes = new Bytes(2)// <Uint8Array>bytes // то же самое, что: bytes as Uint8Array

Есть два сценария, где Вам может понадобиться преобразование типов, но использование as/<T>var небезопасно:

  • Понижение уровня наследования классов (superclass → subclass)
  • Между двумя типами, имеющими общий супер класс
// понижение уровня наследования классовclass Bytes extends Uint8Array {}let uint8Array = new Uint8Array(2)// <Bytes>uint8Array // перерывы в работе :(
// между двумя типами, имеющими общий суперклассclass Bytes extends Uint8Array {}class ByteArray extends Uint8Array {}let bytes = new Bytes(2)// <ByteArray>bytes // перерывы в работе :(

В таких случаях Вы можете использовать функцию changetype<T>:

// понижение уровня наследования классовclass Bytes extends Uint8Array {}let uint8Array = new Uint8Array(2)changetype<Bytes>(uint8Array) // работает :)
// между двумя типами, имеющими общий суперклассclass Bytes extends Uint8Array {}class ByteArray extends Uint8Array {}let bytes = new Bytes(2)changetype<ByteArray>(bytes) // работает :)

Если Вы просто хотите убрать возможность обнуления, Вы можете продолжить использовать оператор as (или <T>variable), но помните, что это значение не может быть нулевым, иначе оно приведет к ошибке.

// удалить значение NULLlet previousBalance = AccountBalance.load(balanceId) // AccountBalance | nullif (previousBalance != null) {  return previousBalance as AccountBalance // безопасно удалить значение NULL}let newBalance = new AccountBalance(balanceId)

В случае возможности обнуления мы рекомендуем ознакомиться с функцией проверки обнуления⁠, которая сделает код чище 🙂

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

  • Bytes.fromByteArray
  • Bytes.fromUint8Array
  • BigInt.fromByteArray
  • ByteArray.fromBigInt

Проверка нулевого значения с доступом к свойству

Чтобы использовать функцию проверки на обнуляемость⁠, Вы можете использовать либо операторы if, либо тернарный оператор (? и :), например:

let something: string | null = 'data'let somethingOrElse = something ? something : 'else'// илиlet somethingOrElseif (something) {  somethingOrElse = something} else {  somethingOrElse = 'else'}

Однако это работает только тогда, когда Вы выполняете if / тернарную операцию для переменной, а не для доступа к свойству, например:

class Container {  data: string | null}let container = new Container()container.data = 'data'let somethingOrElse: string = container.data ? container.data : 'else' // не компилируется

В результате чего выдается ошибка:

ERROR TS2322: Type '~lib/string/String | null' is not assignable to type '~lib/string/String'.   let somethingOrElse: string = container.data ? container.data : "else";                                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Чтобы решить эту проблему, Вы можете создать переменную для доступа к этому свойству, чтобы компилятор мог выполнять проверку допустимости значений NULL:

class Container {  data: string | null}let container = new Container()container.data = 'data'let data = container.datalet somethingOrElse: string = data ? data : 'else' // компилируется просто отлично :)

Перегрузка оператора при доступе к свойствам

Если Вы попытаетесь суммировать (например) тип, допускающий значение Null (из доступа к свойству), с типом, не допускающим значение Null, компилятор AssemblyScript вместо того, чтобы выдать предупреждение об ошибке компиляции, предупреждающую, что одно из значений допускает значение Null, просто компилируется молча, давая возможность сломать код во время выполнения.

class BigInt extends Uint8Array {  @operator('+')  plus(other: BigInt): BigInt {    // ...  }}class Wrapper {  public constructor(public n: BigInt | null) {}}let x = BigInt.fromI32(2)let y: BigInt | null = nullx + y // выдает ошибку времени компиляции о возможности обнуленияlet wrapper = new Wrapper(y)wrapper.n = wrapper.n + x // не выдает ошибок времени компиляции, как это должно быть

We’ve opened a issue on the AssemblyScript compiler for this, but for now if you do these kind of operations in your Subgraph mappings, you should change them to do a null check before it.

let wrapper = new Wrapper(y)if (!wrapper.n) {  wrapper.n = BigInt.fromI32(0)}wrapper.n = wrapper.n + x // теперь `n` гарантированно будет BigInt

Инициализация значения

Если у Вас есть такой код:

var value: Type // nullvalue.x = 10value.y = 'content'

It will compile but break at runtime, that happens because the value hasn’t been initialized, so make sure your Subgraph has initialized their values, like this:

var value = new Type() // initializedvalue.x = 10value.y = 'content'

Также, если у Вас есть свойства, допускающие значение NULL, в объекте GraphQL, например:

type Total @entity {  id: Bytes!  amount: BigInt}

И у Вас есть код, аналогичный этому:

let total = Total.load('latest')if (total === null) {  total = new Total('latest')}total.amount = total.amount + BigInt.fromI32(1)

Вам необходимо убедиться, что значение total.amount инициализировано, потому что, если Вы попытаетесь получить доступ к сумме, как в последней строке, произойдет сбой. Таким образом, Вы либо инициализируете его первым:

let total = Total.load('latest')if (total === null) {  total = new Total('latest')  total.amount = BigInt.fromI32(0)}total.tokens = total.tokens + BigInt.fromI32(1)

Или Вы можете просто изменить свою схему GraphQL, чтобы не использовать для этого свойства тип, допускающий обнуление, тогда мы инициализируем его как ноль на этапе codegen 😉

type Total @entity {  id: Bytes!  amount: BigInt!}
let total = Total.load('latest')if (total === null) {  total = new Total('latest') // уже инициализирует свойства, не допускающие значения NULL}total.amount = total.amount + BigInt.fromI32(1)

Инициализация свойств класса

Если Вы экспортируете какие-либо классы со свойствами, которые являются другими классами (декларированными Вами или стандартной библиотекой), то это выглядит следующим образом:

class Thing {}export class Something {  value: Thing}

Компилятор выдаст ошибку, потому что Вам нужно либо добавить инициализатор для свойств, являющихся классами, либо добавить оператор !:

export class Something {  constructor(public value: Thing) {}}// илиexport class Something {  value: Thing  constructor(value: Thing) {    this.value = value  }}// илиexport class Something {  value!: Thing}

Инициализация массива

Класс Array по-прежнему принимает число для инициализации длины списка, однако следует учитывать, что операции, такие как .push, будут увеличивать размер массива, а не добавлять элемент в начало. Например:

let arr = new Array<string>(5) // ["", "", "", "", ""]arr.push('something') // ["", "", "", "", "", "something"] // размер 6 :(

В зависимости от используемых типов, например, допускающих значение NULL, и способа доступа к ним, можно столкнуться с ошибкой времени выполнения, подобной этой:

ERRO Handler skipped due to execution failure, error: Mapping aborted at ~lib/array.ts, line 110, column 40, with message: Element type must be nullable if array is holey  wasm backtrace:     0: 0x19c4 - <unknown>!~lib/@graphprotocol/graph-ts/index/format         1: 0x1e75 - <unknown>!~lib/@graphprotocol/graph-ts/common/collections/Entity#constructor        2: 0x30b9 - <unknown>!node_modules/@graphprotocol/graph-ts/global/global/id_of_type

Чтобы действительно добавить элемент в начало, следует инициализировать Array с нулевым размером, например, так:

let arr = new Array<string>(0) // []arr.push('something') // ["something"]

Или Вы должны изменить его через индекс:

let arr = new Array<string>(5) // ["", "", "", "", ""]arr[0] = 'something' // ["something", "", "", "", ""]

Схема GraphQL

Это не прямое изменение AssemblyScript, но Вам, возможно, придется обновить файл schema.graphql.

Теперь Вы больше не можете определять поля в своих типах, которые являются списками, не допускающими значение NULL. Если у Вас такая схема:

type Something @entity {  id: Bytes!}type MyEntity @entity {  id: Bytes!  invalidField: [Something]! # no longer valid}

Вам нужно добавить ! к элементу типа List, например, так:

type Something @entity {  id: Bytes!}type MyEntity @entity {  id: Bytes!  invalidField: [Something!]! # valid}

Это изменение связано с различиями в обработке возможности обнуления между версиями AssemblyScript и связано с файлом src/generated/schema.ts (значение по умолчанию, хотя Вы могли его изменить).

Прочее

  • Map#set и Set#add приведены в соответствие со спецификацией, возвращая this (v0.9.2⁠)
  • Массивы больше не наследуются от ArrayBufferView, а теперь являются отдельными (v0.10.0⁠)
  • Классы, инициализируемые из объектных литералов, больше не могут определять конструктор (v0.10.0⁠)
  • Результат бинарной операции ** теперь является общим целочисленным знаменателем, если оба операнда - целые числа. Ранее результат был числом с плавающей точкой, как при вызове Math/f.pow (v0.11.0⁠)
  • При приведении к bool значение NaN теперь принудительно преобразуется в false (v0.14.9⁠)
  • При сдвиге небольшого целочисленного значения типа i8/u8 или i16/u16 на результат влияют только 3 или 4 младших бита значения RHS, аналогично результату i32.shl, на который влияют только 5 младших битов значения RHS. Пример: someI8 << 8 ранее выдавало значение 0, а теперь выдает someI8 благодаря маскировке RHS как 8 & 7 = 0 (3 бита) (v0.17.0⁠)
  • Исправлена ошибка в сравнении строк разной длины (v0.17.8⁠)