10 minutes
AssemblyScript Migrationsguide
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)! 🎉
Det kommer att möjliggöra för undergrafutvecklare att använda nyare funktioner i AS-språket och standardbiblioteket.
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.
Funktioner
Ny funktionalitet
TypedArray
s can now be built fromArrayBuffer
s by using the newwrap
static method (v0.8.1)- New standard library functions:
String#toUpperCase
,String#toLowerCase
,String#localeCompare
andTypedArray#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 onNumber#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)
anddecodeURI(Component)
(v0.18.27) - Add
toString
,toDateString
andtoTimeString
toDate
(v0.18.29) - Add
toUTCString
forDate
(v0.18.30) - Add
nonnull/NonNullable
builtin type (v0.19.2)
Optimeringar
Math
functions such asexp
,exp2
,log
,log2
andpow
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)
Annat
- 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)
Hur uppgraderar du?
- Change your mappings
apiVersion
insubgraph.yaml
to0.0.6
:
...dataSources: ... mapping: ... apiVersion: 0.0.6 ...
- Update the
graph-cli
you’re using to thelatest
version by running:
# om du har den globalt installeradnpm install --global @graphprotocol/graph-cli@latest# eller i din subgraf om du har det som ett utvecklingsberoendenpm install --save-dev @graphprotocol/graph-cli@latest
- Do the same for
graph-ts
, but instead of installing globally, save it in your main dependencies:
npm install --save @graphprotocol/graph-ts@latest
- Följ resten av guiden för att åtgärda språkbrytande ändringar.
- Run
codegen
anddeploy
again.
Språkbrytande ändringar
Nullbarhet
I den äldre versionen av AssemblyScript kunde du skapa kod som detta:
function load(): Value | null { ... }let maybeValue = load();maybeValue.aMethod();
Men i den nyare versionen, eftersom värdet är nullable, måste du kontrollera, så här:
let maybeValue = load()if (maybeValue) { maybeValue.aMethod() // `maybeValue` is not null anymore}
Eller gör så här:
let maybeValue = load()! // bryts i runtime om värdet är nullmaybeValue.aMethod()
Om du är osäker på vilken du ska välja, rekommenderar vi alltid att använda den säkra versionen. Om värdet inte finns kanske du bara vill göra ett tidigt villkorligt uttalande med en retur i din undergrafshanterare.
Variabelskuggning
Before you could do variable shadowing and code like this would work:
let a = 10let b = 20let a = a + b
Men nu är detta inte längre möjligt, och kompilatorn returnerar detta fel:
ERROR TS2451: Cannot redeclare block-scoped variable 'a' let a = a + b; ~~~~~~~~~~~~~in assembly/index.ts(4,3)
Du måste döpa om dina duplicerade variabler om du hade variabelskuggning.
Jämförelser med nollvärden
När du gör uppgraderingen av din subgraf kan du ibland få fel som dessa:
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) {
Samma gäller om du använder != istället för ==.
Kasting
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
Detta fungerar dock endast i två scenarier:
- Primitive casting (between types such as
u8
,i32
,bool
; eg:let b: isize = 10; b as usize
); - Uppkasting vid klassarv (underklass → överklass)
Exempel:
// 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:
- Downcasting vid arv av klasser (superklass → subklass)
- Mellan två typer som delar en superklass
// 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.
// ta bort ogiltighetlet 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 🙂
Vi har också lagt till några fler statiska metoder i vissa typer för att underlätta kastning, de är:
- Bytes.fromByteArray
- Bytes.fromUint8Array
- BigInt.fromByteArray
- ByteArray.fromBigInt
Kontroll av nollställbarhet med tillgång till egendom
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 ? container.data : 'else' // Kompilerar inte
Vilket ger detta fel:
ERROR TS2322: Type '~lib/string/String | null' is not assignable to type '~lib/string/String'. let somethingOrElse: string = container.data ? container.data : "else"; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
För att åtgärda problemet kan du skapa en variabel för den egenskapen så att kompilatorn kan utföra den magiska nollbarhetskontrollen:
class Container { data: string | null}let container = new Container()container.data = 'data'let data = container.datalet somethingOrElse: string = data ? data : 'else' // kompilerar helt okej :)
Operatörsöverladdning med egenskapsaccess
Om du försöker summera (till exempel) en nullable typ (från en property access) med en non nullable, kommer AssemblyScript-kompilatorn istället för att ge en kompileringsfelsvarning om att ett av värdena är nullable, bara att kompilera tyst, vilket gör att koden kan gå sönder vid körning.
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 // ge kompileringsfel om ogiltighetlet wrapper = new Wrapper(y)wrapper.n = wrapper.n + x // ger inte kompileringsfel som det borde
Vi har öppnat en fråga om AssemblyScript-kompilatorn för detta, men om du gör den här typen av operationer i dina subgraf-mappningar bör du ändra dem så att de gör en null-kontroll innan den.
let wrapper = new Wrapper(y)if (!wrapper.n) { wrapper.n = BigInt.fromI32(0)}wrapper.n = wrapper.n + x // nu är `n` garanterat ett BigInt
Initialisering av värde
Om du har någon kod som denna:
var value: Type // nullvalue.x = 10value.y = 'content'
Det kommer att kompilera men brytas vid körning, det händer eftersom värdet inte har initialiserats, så se till att din subgraf har initialiserat sina värden, så här:
var value = new Type() // initializedvalue.x = 10value.y = 'content'
Även om du har nullable properties i en GraphQL-entitet, som denna:
type Total @entity { id: Bytes! amount: BigInt}
Och du har en kod som liknar den här:
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') // initierar redan icke-nullställbara egenskaper}total.amount = total.amount + BigInt.fromI32(1)
Initialisering av klassegenskaper
Om du exporterar några klasser med egenskaper som är andra klasser (deklarerade av dig eller av standardbiblioteket) på det här sättet:
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}
Initialisering av Array
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 :(
Beroende på vilka typer du använder, t.ex. nullable-typer, och hur du kommer åt dem, kan du stöta på ett runtime-fel som det här:
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"]
Eller så bör du mutera den via index:
let arr = new Array<string>(5) // ["", "", "", "", ""]arr[0] = 'something' // ["something", "", "", "", ""]
GraphQL-schema
This is not a direct AssemblyScript change, but you may have to update your schema.graphql
file.
Nu kan du inte längre definiera fält i dina typer som är Non-Nullable Lists. Om du har ett schema som detta:
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).
Annat
- Aligned
Map#set
andSet#add
with the spec, returningthis
(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 callingMath/f.pow
(v0.11.0) - Coerce
NaN
tofalse
when casting tobool
(v0.14.9) - When shifting a small integer value of type
i8
/u8
ori16
/u16
, only the 3 respectively 4 least significant bits of the RHS value affect the result, analogous to the result of ani32.shl
only being affected by the 5 least significant bits of the RHS value. Example:someI8 << 8
previously produced the value0
, but now producessomeI8
due to masking the RHS as8 & 7 = 0
(3 bits) (v0.17.0) - Bug fix of relational string comparisons when sizes differ (v0.17.8)