What is AssemblyScript?

Subgraphs are written in a language called AssemblyScript. While it looks similar and also uses the .ts file extension, AssemblyScript is not TypeScript. It compiles to WebAssembly(WASM) and allows JavaScript/TypeScript developers to output WASM using a language with familiar syntax. It requires stricter typing than TypeScript, but tries to stay as close as possible, but also has a lot of limitations and missing features compared to JS/TS.

Types

As we mentioned in previously AssemblyScript requires stricter typing than TypeScript. You can see the differences in the table below:

Main tripping points for new Subgraph developers

Note: The following references the AssemblyScript version 0.19.10. currently used for writing subgraphs.

1. A very common mistake by new subgraph developers is trying to use console.log. AssemblyScript does not support console.log which will result in the following error

   Critical: Could not create WasmInstance from valid module with context: unknown import: wasi_snapshot_preview1::fd_write has not been defined

   TheGraph provides an alternative via the Logging API available through the graph-ts library

2. No support for Promises/async/await. Currently there’s no alternative.

3. No support for closures. More info can be found in The AssemblyScript Book

4. As we mentioned earlier AS is strictly typed, which means there is no undefined or any types.

5. There are no union types, except with null. For example the following code is invalid:

   function foo(a: i32 | string): void {
   	...
   }

   Similar effect can be achieved by using generics:

   function foo<T>(a: T): void {
     ...
   }

6. Object literals are not allowed :

   var a = {}
   a.prop = "hello world"

   All Objects have to be typed, use either Map or Class

   var a = new Map<string,string>()
   a.set("prop", "hello world")
    
   class A {
     constructor(public prop: string) {}
   }
   var a = new A("hello world")

7. Nullability checks are limited to locals. What does this mean?

   For example, lets assume we have class Foo with field bar

   class Foo {
     constructor(public bar: string | null) {}
   }
   var a = new Foo("hello");

   In TS we can do the following:

   function doSomething(foo: Foo): void {
     if (foo.bar) {
       foo.bar.length // error
     }
   }

   But in AS this will result in the following error:

   ERROR TS2322: Type '~lib/string/String | null' is not assignable to type '~lib/string/String'.

   In AS, first you need to assign the value of the property to a local variable

   function doSomething(foo: Foo): void {
   	var something = foo.something
   	if (something) {
   		something.length // works
   	}
   }

8. There’s no BigInt type out of the box. TheGraph provides an alternative via the graph-ts library.

9. It is not possible to make HTTP request.

10. No Regex, JSON, Base64 support out of the box. Requires third party libraries.

11. Can not import and use TypeScript libraries. There are AssemblyScript specific libraries like graph-ts, matchstick-as, as-base64

12. == vs === is confusing - Because AssemblyScript is strictly typed language, it is not possible to compare two values of different types. This is evaluated at compile time and the compilation will fail:

    1 == "1" 
     
    // ERROR TS2365: Operator '===' cannot be applied to types 'i32' and '~lib/string/String'.
    // 1 === "1"
    // ~~~~~~~~~

    This makes the === operator obsolete, but because people are used to it, it was added to AssemblyScript as well. The problem is, the === operator has a different functionality. AssemblyScript uses === for identity comparisons, i.e. if it’s the same object.

    Let’s see the following examples:

    var s1 = "1";
    var s2 = "123".substring(0, 1);
    s1 === s1 // true
    s1 === s2 // false
    s2 === s2 // true
    s1 === 1 // ERROR TS2365: Operator '===' cannot be applied to types '~lib/string/String' and 'i32'.
    s1 == s2 // true

    In AssemblyScript version afterv0.20.x, the behaviour of the === has been changed to be the same as == , but in the current TheGraph version, be sure to use only == , because in some cases === may cause unexpected behaviour.

    More information about other AssembyScript Concepts are available here

The Graph AssemblyScript Library (graph-ts)

The graph-ts library provides the following functionalities and APIs:

• Adds support for Solidity types as Address, Tuples, BigInt , Bytes, etc.
• ethereum API for working with Ethereum smart contracts, events, blocks, transactions, and Ethereum values.
• store API to load, save, update and remove entities from and to the Graph Node store.
• log API to log messages to the Graph Node output and the Graph Explorer.
• ipfs API to load files from IPFS - deprecated on the Subgraph Studio in favour of File Data Sources
• json API to parse JSON data.
• crypto API to use cryptographic functions, currently only supports keccak256
• Handles the conversion between different type systems such as Ethereum, JSON, GraphQL and AssemblyScript.

How to install and to see more details on the available APIs, follow TheGraph documentation here.

There are some common tripping points when new subgraph developers start using the graph-ts library, but before continuing be sure to first get familiar with AssemblyScript and graph-ts.

1. Creating an ethereum.Value that represents a tuple - Creating an ethereum.Value form tuple is not as straightforward as it may seem and many developers get stuck on it. Here’s how to do it:

// For example we want to create the following tuple (uint256,string)
// First create an array of ethereum.Value
let uintValue = ethereum.Value.fromBigInt(BigInt.fromI32(152);
let stringValue = ethereum.Value.fromString("string value");
let tupleArray: Array<ethereum.Value> = [uintValue, stringValue]
 
// Now we have to convert the array into a tuple
// To do that we will use the internal changetype function provided by AS
// Your IDE may complain that such function does not exist, but it is a valid function.
let tuple = changetype<ethereum.Tuple>(tupleArray)
 
// Now create a tuple Value from the tuple
let tupleValue = ethereum.Value.fromTuple(tuple)

1. Updating entity array fields - It is not possible to directly push or remove items from an array field. To update a an array fields, first you need to assign the value of the field to a variable, update the variable, by pushing or removing the desired item and then overwriting the field value with the new array. Lets assume we have the following entity:

type MyEntity @entity {
  id: Bytes!
  arrayField: [String!]!
}

Here’s how to add a new value to an existing array

let myEntity = MyEntity.load(entityId)
let array = myEntity.arrayField;
array.push("Hello");
myEntity.arrayField = array;
myEnitty.save();