Docs
⌘ K

12 分

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.

This guide is applicable for anyone using graph-cli/graph-ts below version 0.22.0. If you’re already at a higher than (or equal) version to that, you’ve already been using version 0.19.10 of AssemblyScript 🙂

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

特徴

新機能

  • TypedArrays can now be built from ArrayBuffers by using the new wrap static method⁠ (v0.8.1⁠)
  • New standard library functions: String#toUpperCase, String#toLowerCase, String#localeCompareand TypedArray#set (v0.9.0⁠)
  • Added support for x instanceof GenericClass (v0.9.2⁠)
  • Added StaticArray<T>, a more efficient array variant (v0.9.3⁠)
  • Added Array<T>#flat (v0.10.0⁠)
  • Implemented radix argument on Number#toString (v0.10.1⁠)
  • Added support for separators in floating point literals (v0.13.7⁠)
  • Added support for first class functions (v0.14.0⁠)
  • Add builtins: i32/i64/f32/f64.add/sub/mul (v0.14.13⁠)
  • Implement Array/TypedArray/String#at (v0.18.2⁠)
  • Added support for template literal strings (v0.18.17⁠)
  • Add encodeURI(Component) and decodeURI(Component) (v0.18.27⁠)
  • Add toString, toDateString and toTimeString to Date (v0.18.29⁠)
  • Add toUTCString for Date (v0.18.30⁠)
  • Add nonnull/NonNullable builtin type (v0.19.2⁠)

最適化

  • Math functions such as exp, exp2, log, log2 and pow have been replaced by faster variants (v0.9.0⁠)
  • Slightly optimize Math.mod (v0.17.1⁠)
  • Cache more field accesses in std Map and Set (v0.17.8⁠)
  • Optimize for powers of two in ipow32/64 (v0.18.2⁠)

その他

  • The type of an array literal can now be inferred from its contents (v0.9.0⁠)
  • Updated stdlib to 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. Update the graph-cli you’re using to the latest version by running:
# if you have it globally installednpm install --global @graphprotocol/graph-cli@latest# or in your subgraph if you have it as a dev dependencynpm install --save-dev @graphprotocol/graph-cli@latest
  1. Do the same for graph-ts, but instead of installing globally, save it in your main dependencies:
npm install --save @graphprotocol/graph-ts@latest
  1. ガイドの残りの部分に従って、言語の変更を修正します。
  2. Run codegen and deploy again.

変更点

ヌル可能性

古いバージョンの AssemblyScript では、以下のようなコードを作ることができました:

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

しかし、新しいバージョンでは、値が nullable であるため、次のようにチェックする必要があります:

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

あるいは、次のように強制します:

let maybeValue = load()! // breaks in runtime if value is 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.

変数シャドウイング

Before you could do variable shadowing⁠ and code like this would work:

et 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)

変数シャドウイングを行っていた場合は、重複する変数の名前を変更する必要があります。

Null 比較

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)

To solve you can simply change the if statement to something like this:

if (!decimals) {  // or  if (decimals === null) {

== の代わりに != を実行している場合も同様です。

鋳造

The common way to do casting before was to just use the as keyword, like this:

let byteArray = new ByteArray(10)let uint8Array = byteArray as Uint8Array // equivalent to: <Uint8Array>byteArray

しかし、これは 2 つのシナリオでしか機能しません。

  • Primitive casting (between types such as u8, i32, bool; eg: let b: isize = 10; b as usize);
  • クラス継承のアップキャスティング（サブクラス → スーパークラス）

例

// primitive castinglet a: usize = 10let b: isize = 5let c: usize = a + (b as usize)
// upcasting on class inheritanceclass Bytes extends Uint8Array {}let bytes = new Bytes(2)// <Uint8Array>bytes // same as: bytes as Uint8Array

There are two scenarios where you may want to cast, but using as/<T>var isn’t safe:

  • クラス継承のダウンキャスト（スーパークラス → サブクラス）
  • スーパークラスを共有する 2 つの型の間
// downcasting on class inheritanceclass Bytes extends Uint8Array {}let uint8Array = new Uint8Array(2)// <Bytes>uint8Array // breaks in runtime :(
// between two types that share a superclassclass Bytes extends Uint8Array {}class ByteArray extends Uint8Array {}let bytes = new Bytes(2)// <ByteArray>bytes // breaks in runtime :(

For those cases, you can use the changetype<T> function:

// downcasting on class inheritanceclass Bytes extends Uint8Array {}let uint8Array = new Uint8Array(2)changetype<Bytes>(uint8Array) // works :)
// between two types that share a superclassclass Bytes extends Uint8Array {}class ByteArray extends Uint8Array {}let bytes = new Bytes(2)changetype<ByteArray>(bytes) // works :)

If you just want to remove nullability, you can keep using the as operator (or <T>variable), but make sure you know that value can’t be null, otherwise it will break.

// remove nullabilitylet previousBalance = AccountBalance.load(balanceId) // AccountBalance | nullif (previousBalance != null) {  return previousBalance as AccountBalance // safe remove null}let newBalance = new AccountBalance(balanceId)

For the nullability case we recommend taking a look at the nullability check feature⁠, it will make your code cleaner 🙂

また、キャストを容易にするために、いくつかの型にスタティックメソッドを追加しました。

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

プロパティアクセスによる Nullability チェック

To use the nullability check feature⁠ you can use either if statements or the ternary operator (? and :) like this:

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

However that only works when you’re doing the if / ternary on a variable, not on a property access, like this:

class Container {  data: string | null}let container = new Container()container.data = 'data'let somethingOrElse: string = container.data ?

すると、このようなエラーが出力されます。

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

この問題を解決するには、そのプロパティアクセスのための変数を作成して、コンパイラが nullability check のマジックを行うようにします。

class Container {  data: string | null}let container = new Container()container.data = 'data'let data = container.datalet somethingOrElse: string = data :)

プロパティアクセスによるオペレーターオーバーロード

たとえば、(プロパティ アクセスからの) null 許容型と null 非許容型を合計しようとすると、AssemblyScript コンパイラは、値の 1 つが 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 // give compile time error about nullabilitylet wrapper = new Wrapper(y)wrapper.n = wrapper.n + x // doesn't give compile time errors as it should

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 // now `n` is guaranteed to be a 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'

また、以下のように GraphQL のエンティティに Nullable なプロパティがある場合も同様です。

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)

You’ll need to make sure to initialize the total.amount value, because if you try to access like in the last line for the sum, it will crash. So you either initialize it first:

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

Or you can just change your GraphQL schema to not use a nullable type for this property, then we’ll initialize it as zero on the codegen step 😉

type Total @entity {  id: Bytes!  amount: BigInt!}
let total = Total.load('latest')if (total === null) {  total = new Total('latest') // already initializes non-nullable properties}total.amount = total.amount + BigInt.fromI32(1)

クラスのプロパティの初期化

以下のように、他のクラス（自分で宣言したものや標準ライブラリで宣言したもの）のプロパティを持つクラスをエクスポートした場合、そのクラスのプロパティを初期化します:

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

The compiler will error because you either need to add an initializer for the properties that are classes, or add the ! operator:

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

配列の初期化

The Array class still accepts a number to initialize the length of the list, however you should take care because operations like .push will actually increase the size instead of adding to the beginning, for example:

let arr = new Array<string>(5) // ["", "", "", "", ""]arr.push('something') // ["", "", "", "", "", "something"] // size 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

To actually push at the beginning you should either, initialize the Array with size zero, like this:

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

あるいは、インデックス経由で変異させるべきでしょう：

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

GraphQLスキーマ

This is not a direct AssemblyScript change, but you may have to update your schema.graphql file.

この変更により、Non-Nullable Listのフィールドを型に定義することができなくなりました。仮に、以下のようなスキーマがあった場合：

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

You’ll have to add an ! to the member of the List type, like this:

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

This changed because of nullability differences between AssemblyScript versions, and it’s related to the src/generated/schema.ts file (default path, you might have changed this).

その他

  • Aligned Map#set and Set#add with the spec, returning this (v0.9.2⁠)
  • Arrays no longer inherit from ArrayBufferView, but are now distinct (v0.10.0⁠)
  • Classes initialized from object literals can no longer define a constructor (v0.10.0⁠)
  • The result of a ** binary operation is now the common denominator integer if both operands are integers. Previously, the result was a float as if calling Math/f.pow (v0.11.0⁠)
  • Coerce NaN to false when casting to bool (v0.14.9⁠)
  • When shifting a small integer value of type i8/u8 or i16/u16, only the 3 respectively 4 least significant bits of the RHS value affect the result, analogous to the result of an i32.shl only being affected by the 5 least significant bits of the RHS value. Example: someI8 << 8 previously produced the value 0, but now produces someI8 due to masking the RHS as 8 & 7 = 0 (3 bits) (v0.17.0⁠)
  • Bug fix of relational string comparisons when sizes differ (v0.17.8⁠)