tigerbeetle-node 0.8.1 → 0.9.143

package/README.md

@@ -1,250 +1,650 @@
+---
+title: Node.js
+---
+
+This file is generated by
+[/src/clients/docs_generate.zig](/src/clients/docs_generate.zig).
 # tigerbeetle-node
-[TigerBeetle](https://github.com/coilhq/tigerbeetle) client for Node.js.
 
-## Installation
-The following steps will install the `tigerbeetle-node` module to your current working directory.
+The TigerBeetle client for Node.js.
 
-### Prerequisites 
+### Prerequisites
 
-* NodeJS >= `14.0.0`. _(If the correct version is not installed, an installation error will occur)_ 
+Linux >= 5.6 is the only production environment we
+support. But for ease of development we also support macOS and Windows.
+* NodeJS >= `14`
 
-> Your operating system should be Linux (kernel >= v5.6) or macOS. Windows support is not yet available but is in the works.
+## Setup
 
-### YARN Package Manager Installation
-```shell
-yarn add tigerbeetle-node
-```
-or
-### NPM Package Manager Installation
-```shell
+First, create a directory for your project and `cd` into the directory.
+
+Then, install the TigerBeetle client:
+
+```console
 npm install tigerbeetle-node
 ```
 
-## Usage
-A client needs to be configured with a `cluster_id` and `replica_addresses`. 
-This instantiates the client where memory is allocated to internally buffer events to be sent. 
-For the moment, only one client can be instantiated globally per process. 
-Future releases will allow multiple client instantiations.
-```js
-import { createClient } from 'tigerbeetle-node'
+Now, create `main.js` and copy this into it:
+
+```javascript
+const { createClient } = require("tigerbeetle-node");
+console.log("Import ok!");
+```
+
+Finally, build and run:
+
+```console
+node main.js
+```
+
+Now that all prerequisites and dependencies are correctly set
+up, let's dig into using TigerBeetle.
+
+If you run into issues, check out the distribution-specific install
+steps that are run in CI to test support:
+
+* [Alpine](https://github.com/tigerbeetle/tigerbeetle/blob/main/src/clients/node/scripts/test_install_on_alpine.sh)
+* [Amazon Linux](https://github.com/tigerbeetle/tigerbeetle/blob/main/src/clients/node/scripts/test_install_on_amazonlinux.sh)
+* [Debian](https://github.com/tigerbeetle/tigerbeetle/blob/main/src/clients/node/scripts/test_install_on_debian.sh)
+* [Fedora](https://github.com/tigerbeetle/tigerbeetle/blob/main/src/clients/node/scripts/test_install_on_fedora.sh)
+* [Ubuntu](https://github.com/tigerbeetle/tigerbeetle/blob/main/src/clients/node/scripts/test_install_on_ubuntu.sh)
+* [RHEL](https://github.com/tigerbeetle/tigerbeetle/blob/main/src/clients/node/scripts/test_install_on_rhelubi.sh)
+
+## Sample projects
 
+This document is primarily a reference guide to
+the client. Below are various sample projects demonstrating
+features of TigerBeetle.
+
+* [Basic](/src/clients/node/samples/basic/): Create two accounts and transfer an amount between them.
+* [Two-Phase Transfer](/src/clients/node/samples/two-phase/): Create two accounts and start a pending transfer between
+them, then post the transfer.
+* [Many Two-Phase Transfers](/src/clients/node/samples/two-phase-many/): Create two accounts and start a number of pending transfer
+between them, posting and voiding alternating transfers.
+### Sidenote: `BigInt`
+TigerBeetle uses 64-bit integers for many fields while JavaScript's
+builtin `Number` maximum value is `2^53-1`. The `n` suffix in JavaScript
+means the value is a `BigInt`. This is useful for literal numbers. If
+you already have a `Number` variable though, you can call the `BigInt`
+constructor to get a `BigInt` from it. For example, `1n` is the same as
+`BigInt(1)`.
+
+## Creating a Client
+
+A client is created with a cluster ID and replica
+addresses for all replicas in the cluster. The cluster
+ID and replica addresses are both chosen by the system that
+starts the TigerBeetle cluster.
+
+Clients are thread-safe and a single instance should be shared
+between multiple concurrent tasks.
+
+Multiple clients are useful when connecting to more than
+one TigerBeetle cluster.
+
+In this example the cluster ID is `0` and there is one
+replica. The address is read from the `TB_ADDRESS`
+environment variable and defaults to port `3000`.
+
+```javascript
 const client = createClient({
   cluster_id: 0,
-  replica_addresses: ['3001', '3002', '3003']
-})
-```
-
-One of the ways TigerBeetle achieves its performance is through batching. 
-This is reflected in the below function interfaces where each one takes in an array of events.
-
-### Account Creation
-
-```js
-const account = {
-    id: 137n, // u128
-    user_data: 0n, // u128, opaque third-party identifier to link this account to an external entity:
-    reserved: Buffer.alloc(48, 0), // [48]u8
-    ledger: 1,   // u32, ledger value
-    code: 718, // u16, a chart of accounts code describing the type of account (e.g. clearing, settlement)
-    flags: 0,  // u16
-    debits_pending: 0n,  // u64
-    debits_posted: 0n,  // u64
-    credits_pending: 0n, // u64
-    credits_posted: 0n, // u64
-    timestamp: 0n, // u64, Reserved: This will be set by the server.
-}
-
-const errors = await client.createAccounts([account])
+  replica_addresses: [process.env.TB_ADDRESS || '3000']
+});
 ```
-Successfully executed events return an empty array whilst unsuccessful ones return an array with errors for **only the ones that failed**. An error will point to the index in the submitted array of the failed event.
-```js
-  const errors = await client.createAccounts([account1, account2, account3])
 
-  // errors = [{ index: 1, code: 1 }]
-  const error = errors[0]
-  switch (error.code) {
-    case CreateAccountError.exists: {
-      console.error(`Batch event at ${error.index} already exists.`)
-    }
-  }
+The following are valid addresses:
+* `3000` (interpreted as `127.0.0.1:3000`)
+* `127.0.0.1:3000` (interpreted as `127.0.0.1:3000`)
+* `127.0.0.1` (interpreted as `127.0.0.1:3001`, `3001` is the default port)
+
+## Creating Accounts
+
+See details for account fields in the [Accounts
+reference](https://docs.tigerbeetle.com/reference/accounts).
+
+```javascript
+let account = {
+  id: 137n,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  reserved: 0,
+  ledger: 1,
+  code: 718,
+  flags: 0,
+  timestamp: 0n,
+};
+
+let accountErrors = await client.createAccounts([account]);
 ```
-The example above shows that the event in index 1 failed with error 1. This means that `account1` and `account3` were created successfully but not `account2`.
 
-The `flags` on an account provide a way for you to enforce policies by toggling the bits below.
-| bit 0    | bit 1                            | bit 2                                   |
-|----------|----------------------------------|-----------------------------------------|
-| `linked` | `debits_must_not_exceed_credits` | `credits_must_not_exceed_debits` |
+### Account Flags
+
+The account flags value is a bitfield. See details for
+these flags in the [Accounts
+reference](https://docs.tigerbeetle.com/reference/accounts#flags).
+
+To toggle behavior for an account, combine enum values stored in the
+`AccountFlags` object (in TypeScript it is an actual enum) with
+bitwise-or:
+
+* `AccountFlags.linked`
+* `AccountFlags.debits_must_not_exceed_credits`
+* `AccountFlags.credits_must_not_exceed_credits`
+
+
+For example, to link two accounts where the first account
+additionally has the `debits_must_not_exceed_credits` constraint:
+
+```javascript
+let account0 = {
+  id: 100n,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  reserved: 0,
+  ledger: 1,
+  code: 1,
+  timestamp: 0n,
+  flags: 0,
+};
+let account1 = {
+  id: 101n,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  reserved: 0,
+  ledger: 1,
+  code: 1,
+  timestamp: 0n,
+  flags: 0,
+};
+account0.flags = AccountFlags.linked | AccountFlags.debits_must_not_exceed_credits;
+accountErrors = await client.createAccounts([account0, account1]);
+```
 
-The creation of an account can be linked to the successful creation of another by setting the `linked` flag (see [linked events](#linked-events)). By setting `debits_must_not_exceed_credits`, then any transfer such that `debits_posted + debits_pending + amount > credits_posted` will fail. Similarly for `credits_must_not_exceed_debits`.
-```js
-  enum CreateAccountFlags {
-    linked = (1 << 0),
-    debits_must_not_exceed_credits = (1 << 1),
-    credits_must_not_exceed_debits = (1 << 2)
+### Response and Errors
+
+The response is an empty array if all accounts were
+created successfully. If the response is non-empty, each
+object in the response array contains error information
+for an account that failed. The error object contains an
+error code and the index of the account in the request
+batch.
+
+See all error conditions in the [create_accounts
+reference](https://docs.tigerbeetle.com/reference/operations/create_accounts).
+
+```javascript
+let account2 = {
+  id: 102n,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  reserved: 0,
+  ledger: 1,
+  code: 1,
+  timestamp: 0n,
+  flags: 0,
+};
+let account3 = {
+  id: 103n,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  reserved: 0,
+  ledger: 1,
+  code: 1,
+  timestamp: 0n,
+  flags: 0,
+};
+let account4 = {
+  id: 104n,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  reserved: 0,
+  ledger: 1,
+  code: 1,
+  timestamp: 0n,
+  flags: 0,
+};
+accountErrors = await client.createAccounts([account2, account3, account4]);
+for (const error of accountErrors) {
+  switch (error.result) {
+    case CreateAccountError.exists:
+      console.error(`Batch account at ${error.index} already exists.`);
+	  break;
+    default:
+      console.error(`Batch account at ${error.index} failed to create: ${CreateAccountError[error.result]}.`);
   }
+}
+```
 
-  let flags = 0
-  flags |= CreateAccountFlags.debits_must_not_exceed_credits
+To handle errors you can either 1) exactly match error codes returned
+from `client.createAccounts` with enum values in the
+`CreateAccountError` object, or you can 2) look up the error code in
+the `CreateAccountError` object for a human-readable string.
+
+## Account Lookup
+
+Account lookup is batched, like account creation. Pass
+in all IDs to fetch. The account for each matched ID is returned.
+
+If no account matches an ID, no object is returned for
+that account. So the order of accounts in the response is
+not necessarily the same as the order of IDs in the
+request. You can refer to the ID field in the response to
+distinguish accounts.
+
+```javascript
+const accounts = await client.lookupAccounts([137n, 138n]);
+console.log(accounts);
+/*
+ * [{
+ *   id: 137n,
+ *   debits_pending: 0n,
+ *   debits_posted: 0n,
+ *   credits_pending: 0n,
+ *   credits_posted: 0n,
+ *   user_data_128: 0n,
+ *   user_data_64: 0n,
+ *   user_data_32: 0,
+ *   reserved: 0,
+ *   ledger: 1,
+ *   code: 718,
+ *   flags: 0,
+ *   timestamp: 1623062009212508993n,
+ * }]
+ */
 ```
 
-### Account Lookup
+## Create Transfers
+
+This creates a journal entry between two accounts.
 
-The `id` of the account is used for lookups. Only matched accounts are returned.
-```js
-  // account 137n exists, 138n does not
-  const accounts = await client.lookupAccounts([137n, 138n])
+See details for transfer fields in the [Transfers
+reference](https://docs.tigerbeetle.com/reference/transfers).
+
+```javascript
+let transfer = {
+  id: 1n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  amount: 10n,
+  pending_id: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  timeout: 0,
+  ledger: 1,
+  code: 720,
+  flags: 0,
+  timestamp: 0n,
+};
+let transferErrors = await client.createTransfers([transfer]);
+```
 
-  /**
-   * const accounts = [{
-   *   id: 137n,
-   *   user_data: 0n,
-   *   reserved: Buffer,
-   *   ledger: 1,
-   *   code: 718,
-   *   flags: 0,
-   *   debits_pending: 0n,
-   *   debits_posted: 0n,
-   *   credits_pending: 0n,
-   *   credits_posted: 0n,
-   *   timestamp: 1623062009212508993n,
-   * }]
-   */
+### Response and Errors
+
+The response is an empty array if all transfers were created
+successfully. If the response is non-empty, each object in the
+response array contains error information for a transfer that
+failed. The error object contains an error code and the index of the
+transfer in the request batch.
+
+See all error conditions in the [create_transfers
+reference](https://docs.tigerbeetle.com/reference/operations/create_transfers).
+
+```javascript
+for (const error of transferErrors) {
+  switch (error.result) {
+    case CreateTransferError.exists:
+      console.error(`Batch transfer at ${error.index} already exists.`);
+	  break;
+    default:
+      console.error(`Batch transfer at ${error.index} failed to create: ${CreateTransferError[error.result]}.`);
+  }
+}
 ```
 
-### Creating a Transfer
+To handle errors you can either 1) exactly match error codes returned
+from `client.createTransfers` with enum values in the
+`CreateTransferError` object, or you can 2) look up the error code in
+the `CreateTransferError` object for a human-readable string.
 
-This creates a journal entry between two accounts.
-```js
-const transfer = {
-    id: 1n, // u128
-    // Double-entry accounting:
-    debit_account_id: 1n,  // u128
-    credit_account_id: 2n, // u128
-    // Opaque third-party identifier to link this transfer to an external entity:
-    user_data: 0n, // u128  
-    reserved: 0n, // u128
-    // Timeout applicable for a pending/2-phase transfer:
-    timeout: 0n, // u64, in nano-seconds.
-    // Collection of accounts usually grouped by the currency: 
-    // You can't transfer money between accounts with different ledgers:
-    ledger: 720,  // u32, ledger for transfer (e.g. currency).
-    // Chart of accounts code describing the reason for the transfer:
-    code: 1,  // u16, (e.g. deposit, settlement)
-    flags: 0, // u16
-    amount: 10n, // u64
-    timestamp: 0n, //u64, Reserved: This will be set by the server.
+## Batching
+
+TigerBeetle performance is maximized when you batch
+API requests. The client does not do this automatically for
+you. So, for example, you *can* insert 1 million transfers
+one at a time like so:
+
+```javascript
+for (let i = 0; i < transfers.len; i++) {
+  const transferErrors = await client.createTransfers(transfers[i]);
+  // error handling omitted
 }
-const errors = await client.createTransfers([transfer])
 ```
-Two-phase transfers are supported natively by toggling the appropriate flag. TigerBeetle will then adjust the `credits_pending` and `debits_pending` fields of the appropriate accounts. A corresponding commit transfer then needs to be sent to accept or reject the transfer.
 
-Transfers within a batch may also be linked (see [linked events](#linked-events)).
-```js
-  enum TransferFlags {
-    linked = (1 << 0),
-    pending = (1 << 1),
-    post_pending_transfer = (1 << 2),
-    void_pending_transfer = (1 << 3)
-  }
-  
-  // Two-phase transfer (pending):
-  let flags = 0n
-  flags |= TransferFlags.pending
-
-  // Linked two-phase transfer (pending):
-  let flags = 0n
-  flags |= TransferFlags.linked
-  flags |= TransferFlags.pending
-```
-
-### Post a Pending Transfer (2-Phase)
-
-With `flags = post_pending_transfer`, TigerBeetle will accept the transfer. TigerBeetle will atomically rollback the changes to `debits_pending` and `credits_pending` of the appropriate accounts and apply them to the `debits_posted` and `credits_posted` balances.
-```js
-const post = {
-    id: 2n, // u128, must correspond to the transfer id
-    pending_id: 1n, // u128, id of the pending transfer
-    flags: TransferFlags.post_pending_transfer, // to void, use [void_pending_transfer]
-    timestamp: 0n, // u64, Reserved: This will be set by the server.
+But the insert rate will be a *fraction* of
+potential. Instead, **always batch what you can**.
+
+The maximum batch size is set in the TigerBeetle server. The default
+is 8191.
+
+```javascript
+const BATCH_SIZE = 8191;
+for (let i = 0; i < transfers.length; i += BATCH_SIZE) {
+  const transferErrors = await client.createTransfers(transfers.slice(i, Math.min(transfers.length, BATCH_SIZE)));
+  // error handling omitted
 }
-const errors = await client.createTransfers([post])
 ```
 
-### Linked Events
+### Queues and Workers
+
+If you are making requests to TigerBeetle from workers
+pulling jobs from a queue, you can batch requests to
+TigerBeetle by having the worker act on multiple jobs from
+the queue at once rather than one at a time. i.e. pulling
+multiple jobs from the queue rather than just one.
+
+## Transfer Flags
+
+The transfer `flags` value is a bitfield. See details for these flags in
+the [Transfers
+reference](https://docs.tigerbeetle.com/reference/transfers#flags).
+
+To toggle behavior for a transfer, combine enum values stored in the
+`TransferFlags` object (in TypeScript it is an actual enum) with
+bitwise-or:
+
+* `TransferFlags.linked`
+* `TransferFlags.pending`
+* `TransferFlags.post_pending_transfer`
+* `TransferFlags.void_pending_transfer`
+
+For example, to link `transfer0` and `transfer1`:
+
+```javascript
+let transfer0 = {
+  id: 2n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  amount: 10n,
+  pending_id: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  timeout: 0,
+  ledger: 1,
+  code: 720,
+  flags: 0,
+  timestamp: 0n,
+};
+let transfer1 = {
+  id: 3n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  amount: 10n,
+  pending_id: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  timeout: 0,
+  ledger: 1,
+  code: 720,
+  flags: 0,
+  timestamp: 0n,
+};
+transfer0.flags = TransferFlags.linked;
+// Create the transfer
+transferErrors = await client.createTransfers([transfer0, transfer1]);
+```
+
+### Two-Phase Transfers
+
+Two-phase transfers are supported natively by toggling the appropriate
+flag. TigerBeetle will then adjust the `credits_pending` and
+`debits_pending` fields of the appropriate accounts. A corresponding
+post pending transfer then needs to be sent to post or void the
+transfer.
+
+#### Post a Pending Transfer
+
+With `flags` set to `post_pending_transfer`,
+TigerBeetle will post the transfer. TigerBeetle will atomically roll
+back the changes to `debits_pending` and `credits_pending` of the
+appropriate accounts and apply them to the `debits_posted` and
+`credits_posted` balances.
+
+```javascript
+let transfer2 = {
+  id: 4n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  amount: 10n,
+  pending_id: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  timeout: 0,
+  ledger: 1,
+  code: 720,
+  flags: TransferFlags.pending,
+  timestamp: 0n,
+};
+transferErrors = await client.createTransfers([transfer2]);
+
+let transfer3 = {
+  id: 5n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  amount: 10n,
+  pending_id: 4n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  timeout: 0,
+  ledger: 1,
+  code: 720,
+  flags: TransferFlags.post_pending_transfer,
+  timestamp: 0n,
+};
+transferErrors = await client.createTransfers([transfer3]);
+```
+
+#### Void a Pending Transfer
+
+In contrast, with `flags` set to `void_pending_transfer`,
+TigerBeetle will void the transfer. TigerBeetle will roll
+back the changes to `debits_pending` and `credits_pending` of the
+appropriate accounts and **not** apply them to the `debits_posted` and
+`credits_posted` balances.
+
+```javascript
+let transfer4 = {
+  id: 4n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  amount: 10n,
+  pending_id: 0n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  timeout: 0,
+  ledger: 1,
+  code: 720,
+  flags: TransferFlags.pending,
+  timestamp: 0n,
+};
+transferErrors = await client.createTransfers([transfer4]);
+
+let transfer5 = {
+  id: 7n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  amount: 10n,
+  pending_id: 6n,
+  user_data_128: 0n,
+  user_data_64: 0n,
+  user_data_32: 0,
+  timeout: 0,
+  ledger: 1,
+  code: 720,
+  flags: TransferFlags.void_pending_transfer,
+  timestamp: 0n,
+};
+transferErrors = await client.createTransfers([transfer5]);
+```
 
-When the `linked` flag is specified for the `createAccount`, `createTransfer`, `commitTransfer` event, it links an event with the next event in the batch, to create a chain of events, of arbitrary length, which all succeed or fail together. The tail of a chain is denoted by the first event without this flag. The last event in a batch may therefore never have the `linked` flag set as this would leave a chain open-ended. Multiple chains or individual events may coexist within a batch to succeed or fail independently. Events within a chain are executed within order, or are rolled back on error, so that the effect of each event in the chain is visible to the next, and so that the chain is either visible or invisible as a unit to subsequent events after the chain. The event that was the first to break the chain will have a unique error result. Other events in the chain will have their error result set to `linked_event_failed`.
+## Transfer Lookup
+
+NOTE: While transfer lookup exists, it is not a flexible query API. We
+are developing query APIs and there will be new methods for querying
+transfers in the future.
+
+Transfer lookup is batched, like transfer creation. Pass in all `id`s to
+fetch, and matched transfers are returned.
+
+If no transfer matches an `id`, no object is returned for that
+transfer. So the order of transfers in the response is not necessarily
+the same as the order of `id`s in the request. You can refer to the
+`id` field in the response to distinguish transfers.
+
+```javascript
+const transfers = await client.lookupTransfers([1n, 2n]);
+console.log(transfers);
+/*
+ * [{
+ *   id: 1n,
+ *   debit_account_id: 102n,
+ *   credit_account_id: 103n,
+ *   amount: 10n,
+ *   pending_id: 0n,
+ *   user_data_128: 0n,
+ *   user_data_64: 0n,
+ *   user_data_32: 0,
+ *   timeout: 0,
+ *   ledger: 1,
+ *   code: 720,
+ *   flags: 0,
+ *   timestamp: 1623062009212508993n,
+ * }]
+ */
+```
 
-```js
-let batch = []
-let linkedFlag = 0
-linkedFlag |= CreateTransferFlags.linked
+## Linked Events
+
+When the `linked` flag is specified for an account when creating accounts or
+a transfer when creating transfers, it links that event with the next event in the
+batch, to create a chain of events, of arbitrary length, which all
+succeed or fail together. The tail of a chain is denoted by the first
+event without this flag. The last event in a batch may therefore never
+have the `linked` flag set as this would leave a chain
+open-ended. Multiple chains or individual events may coexist within a
+batch to succeed or fail independently.
+
+Events within a chain are executed within order, or are rolled back on
+error, so that the effect of each event in the chain is visible to the
+next, and so that the chain is either visible or invisible as a unit
+to subsequent events after the chain. The event that was the first to
+break the chain will have a unique error result. Other events in the
+chain will have their error result set to `linked_event_failed`.
+
+```javascript
+const batch = [];
+let linkedFlag = 0;
+linkedFlag |= TransferFlags.linked;
 
 // An individual transfer (successful):
-batch.push({ id: 1n, ... })
+batch.push({ id: 1n /* , ... */ });
 
 // A chain of 4 transfers (the last transfer in the chain closes the chain with linked=false):
-batch.push({ id: 2n, ..., flags: linkedFlag }) // Commit/rollback.
-batch.push({ id: 3n, ..., flags: linkedFlag }) // Commit/rollback.
-batch.push({ id: 2n, ..., flags: linkedFlag }) // Fail with exists
-batch.push({ id: 4n, ..., flags: 0 })          // Fail without committing.
+batch.push({ id: 2n, /* ..., */ flags: linkedFlag }); // Commit/rollback.
+batch.push({ id: 3n, /* ..., */ flags: linkedFlag }); // Commit/rollback.
+batch.push({ id: 2n, /* ..., */ flags: linkedFlag }); // Fail with exists
+batch.push({ id: 4n, /* ..., */ flags: 0 });          // Fail without committing.
 
 // An individual transfer (successful):
 // This should not see any effect from the failed chain above.
-batch.push({ id: 2n, ..., flags: 0 })
+batch.push({ id: 2n, /* ..., */ flags: 0 });
 
 // A chain of 2 transfers (the first transfer fails the chain):
-batch.push({ id: 2n, ..., flags: linkedFlag })
-batch.push({ id: 3n, ..., flags: 0 })
+batch.push({ id: 2n, /* ..., */ flags: linkedFlag });
+batch.push({ id: 3n, /* ..., */ flags: 0 });
 
 // A chain of 2 transfers (successful):
-batch.push({ id: 3n, ..., flags: linkedFlag })
-batch.push({ id: 4n, ..., flags: 0 })
+batch.push({ id: 3n, /* ..., */ flags: linkedFlag });
+batch.push({ id: 4n, /* ..., */ flags: 0 });
 
-const errors = await client.createTransfers(batch)
+const errors = await client.createTransfers(batch);
 
 /**
+ * console.log(errors);
  * [
  *  { index: 1, error: 1 },  // linked_event_failed
  *  { index: 2, error: 1 },  // linked_event_failed
  *  { index: 3, error: 25 }, // exists
  *  { index: 4, error: 1 },  // linked_event_failed
- * 
+ *
  *  { index: 6, error: 17 }, // exists_with_different_flags
  *  { index: 7, error: 1 },  // linked_event_failed
  * ]
  */
 ```
 
-### Development
+## Development Setup
 
-Follow these steps to get up and running when cloning the repo:
-```shell
-git clone --recurse-submodules https://github.com/coilhq/tigerbeetle-node.git
-cd tigerbeetle-node/
-yarn install --immutable
-```
+### On Linux and macOS
 
-Build locally using `yarn`:
-```shell
-# Run the following from this directory:
-yarn && yarn build
-```
+In a POSIX shell run:
 
-* **Please note: `yarn clean` will remove Zig and NodeAPI C headers, which mean you need to run:**
-```shell
-./scripts/postinstall.sh #Install Zig and NodeJS C Headers
+```console
+git clone https://github.com/tigerbeetle/tigerbeetle
+cd tigerbeetle
+git submodule update --init --recursive
+./scripts/install_zig.sh
+cd src/clients/node
+npm install --include dev
+npm pack
 ```
 
-***Yarn - Run Test***
-Ensure TigerBeetle (`init` & `start`) is running on the port configured in `test.ts`, then run:
-```shell
-./tigerbeetle init --cluster=1 --replica=0 --directory=.
-./tigerbeetle start --cluster=1 --replica=0 --directory=. --addresses=3001
-yarn test
-```
+### On Windows
+
+In PowerShell run:
 
-***Yarn - Run Benchmark***
-Run the benchmark (The `benchmark` will automatically start TigerBeetle on port `3001` _(single replica)_:
-```shell
-yarn benchmark
+```console
+git clone https://github.com/tigerbeetle/tigerbeetle
+cd tigerbeetle
+git submodule update --init --recursive
+.\scripts\install_zig.bat
+cd src/clients/node
+npm install --include dev
+npm pack
 ```