Shopify Function WebAssembly API

The Shopify Wasm API provides functions for your Shopify Function to read and write data. This API facilitates communication between the Shopify platform (host) and the guest Wasm module, primarily through a set of imported functions that the Wasm module can call. The following sections describe the value representation format, along with status codes, error codes, and the NanBoxed value structure used by the API.

NanBox Value Structure (64-bit)

Input values in the Wasm API are represented as 64-bit NaN-boxed values, represented as i64 constants in WebAssembly. NaN-boxing provides a performant way to represent multiple value types (such as numbers, strings, booleans, objects, arrays, or errors) within 64-bits, without requiring additional memory allocations for type information. The API uses specific bit patterns within the 64 bits to encode value information.

NaN-box Value Representation

 63  62        52 51 50 49    46 45       32 31                 0
+---+------------+--+--+--------+-----------+--------------------+ 
| 0 | 11111111111| 1 | 1 | TTTT  |   LENGTH  |       VALUE        |
+---+------------+--+--+--------+-----------+--------------------+ 
 ^        ^         ^     ^          ^              ^
Sign  Exponent   Quiet  Tag bits   Length      Value bits
(0)   (all 1s)   NaN    (type)    (14 bits)   (32 bits - data/ptr)

• Sign bit: 0
• Exponent: 11 bits, all 1's.
• Quiet NaN: 1 bit set to 1.
• Tag bits (TTTT): 4 bits indicating value type (0-15). See Value Types below for details.
• Length field: 14 bits for string/array length.
• Value field: 32 bits for actual data or a pointer to heap-allocated structures.

64-bit floating point values

When a value is a floating-point number (type tag 2), it is not encoded through NaN-boxing. Instead, it directly uses the standard IEEE 754 double-precision binary floating-point format:

 63  62        52 51                                         0
+---+------------+--------------------------------------------+
| S |  Exponent  |                  Mantissa                  |
+---+------------+--------------------------------------------+
 ^       ^                             ^
Sign  Exponent                      Mantissa
(variable) (variable)              (variable)

Floating point numbers in our API follow the IEEE-754 specification.

Value Types

The Tag bits (TTTT) in the NanBox structure determine the logical type of the i64 value. The following type tags are used:

• 0: Null - Null value
• 1: Bool - Boolean value (true/false)
• 2: Number - Numeric value (f64)
• 3: String - UTF-8 encoded string (pointer + length)
• 4: Object - Key-value collection (pointer + length)
• 5: Array - Indexed collection of values (pointer + length)
• 15: Error - Read error codes

Reading Data

To read input data provided by the Shopify platform, your Wasm module will use a set of imported API functions. These functions allow you to access the root input value and traverse complex data structures like objects and arrays. For a complete list and detailed signatures of these read functions, refer to the C header file or the WebAssembly Text Format definition.

Each read operation that retrieves data typically returns a NaN-boxed value. This value should be interpreted according to the NanBox structure and Value Types detailed above.

Read Error Codes (i32 type)

When a 64-bit NaN-boxed value has its type tag bits set to 15 (Error), it signifies that a read error occurred. The lower 32 bits of this i64 (the "Value field" in the NanBox structure) will then contain one of the following i32 error codes:

• 0: DecodeError - Value could not be decoded
• 1: NotAnObject - Expected an object but received another type
• 2: ByteArrayOutOfBounds - Byte array index out of bounds
• 3: ReadError - Error occurred during reading
• 4: NotAnArray - Expected an array but received another type
• 5: IndexOutOfBounds - Array index out of bounds
• 6: NotIndexable - Value is not indexable (not an object or array)

Shopify does not consider additions to this list to be a breaking change, so developers are encouraged to handle the case that new error values are emitted.

Writing Data

To write output data back to the Shopify platform, your Wasm module will use a corresponding set of imported API functions. These functions allow you to construct complex data structures, such as objects and arrays, and populate them with various value types (strings, numbers, booleans, null) as defined in the Value Types section. For a complete list and detailed signatures of these write functions, refer to the C header file or the WebAssembly Text Format definition.

Most write operations return an i32 status code. A value of 0 (Success) indicates the operation was successful, while other values signify errors.

Write Status Codes (i32 type)

These are the i32 status codes returned by write operations:

• 0: Success - The operation was successful
• 1: IoError - Error occurred during writing
• 2: ExpectedKey - Expected a key but received a value
• 3: ObjectLengthError - Object length mismatch
• 4: ValueAlreadyWritten - Value already written
• 5: NotAnObject - Expected an object but received another type
• 6: ValueNotFinished - Value creation not completed
• 7: ArrayLengthError - Array length mismatch
• 8: NotAnArray - Expected an array but received another type

Shopify does not consider additions to this list to be a breaking change, so developers are encouraged to handle the case that new status codes are emitted.