tigerbeetle-node 0.12.105 → 0.12.106

package/README.md

@@ -3,7 +3,7 @@ title: Node.js
 ---
 
 This file is generated by
-[src/clients/docs_generate.zig](/src/clients/docs_generate.zig).
+[/src/clients/docs_generate.zig](/src/clients/docs_generate.zig).
 # tigerbeetle-node
 
 The TigerBeetle client for Node.js.
@@ -11,18 +11,20 @@ The TigerBeetle client for Node.js.
 ### Prerequisites
 
 Linux >= 5.6 is the only production environment we
-support. But for ease of development we also support macOS.
+support. But for ease of development we also support macOS. Windows is not yet supported.
 * NodeJS >= `14`
 
 ## Setup
 
-Run:
+First, create a directory for your project and `cd` into the directory.
+
+Then, install the TigerBeetle client:
 
 ```console
 $ npm install tigerbeetle-node
 ```
 
-Now, create `test.js` and copy this into it:
+Now, create `main.js` and copy this into it:
 
 ```javascript
 const { createClient } = require("tigerbeetle-node");
@@ -32,7 +34,7 @@ console.log("Import ok!");
 Finally, build and run:
 
 ```console
-$ node run test.js
+$ node main.js
 ```
 
 Now that all prerequisites and dependencies are correctly set
@@ -48,17 +50,15 @@ steps that are run in CI to test support:
 * [Ubuntu](https://github.com/tigerbeetledb/tigerbeetle/blob/main/src/clients/node/scripts/test_install_on_ubuntu.sh)
 * [RHEL](https://github.com/tigerbeetledb/tigerbeetle/blob/main/src/clients/node/scripts/test_install_on_rhelubi.sh)
 
-## Example projects
+## 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.
+* [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.
 ### 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
@@ -81,14 +81,14 @@ 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 are
-three replicas running on ports `3001`, `3002`, and
-`3003`.
+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']
+  replica_addresses: [process.env.TB_ADDRESS || '3000']
 });
 ```
 
@@ -139,8 +139,32 @@ For example, to link two accounts where the first account
 additionally has the `debits_must_not_exceed_credits` constraint:
 
 ```javascript
-let account0 = { /* ... account values ... */ };
-let account1 = { /* ... account values ... */ };
+let account0 = {
+  id: 100n,
+  reserved: Buffer.alloc(48, 0),
+  user_data: 0n,
+  ledger: 1,
+  code: 1,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  timestamp: 0n,
+  flags: 0,
+};
+let account1 = {
+  id: 101n,
+  user_data: 0n,
+  reserved: Buffer.alloc(48, 0),
+  ledger: 1,
+  code: 1,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  timestamp: 0n,
+  flags: 0,
+};
 account0.flags = AccountFlags.linked | AccountFlags.debits_must_not_exceed_credits;
 accountErrors = await client.createAccounts([account0, account1]);
 ```
@@ -158,9 +182,45 @@ See all error conditions in the [create_accounts
 reference](https://docs.tigerbeetle.com/reference/operations/create_accounts).
 
 ```javascript
-let account2 = { /* ... account values ... */ };
-let account3 = { /* ... account values ... */ };
-let account4 = { /* ... account values ... */ };
+let account2 = {
+  id: 102n,
+  reserved: Buffer.alloc(48, 0),
+  user_data: 0n,
+  ledger: 1,
+  code: 1,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  timestamp: 0n,
+  flags: 0,
+};
+let account3 = {
+  id: 103n,
+  user_data: 0n,
+  reserved: Buffer.alloc(48, 0),
+  ledger: 1,
+  code: 1,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  timestamp: 0n,
+  flags: 0,
+};
+let account4 = {
+  id: 104n,
+  user_data: 0n,
+  reserved: Buffer.alloc(48, 0),
+  ledger: 1,
+  code: 1,
+  debits_pending: 0n,
+  debits_posted: 0n,
+  credits_pending: 0n,
+  credits_posted: 0n,
+  timestamp: 0n,
+  flags: 0,
+};
 accountErrors = await client.createAccounts([account2, account3, account4]);
 for (const error of accountErrors) {
   switch (error.result) {
@@ -220,8 +280,8 @@ reference](https://docs.tigerbeetle.com/reference/transfers).
 let transfer = {
   id: 1n,
   pending_id: 0n,
-  debit_account_id: 1n,
-  credit_account_id: 2n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
   user_data: 0n,
   reserved: 0n,
   timeout: 0n,
@@ -316,8 +376,34 @@ bitwise-or:
 For example, to link `transfer0` and `transfer1`:
 
 ```javascript
-transfer0 = { /* ... transfer values ... */ };
-transfer1 = { /* ... transfer values ... */ };
+let transfer0 = {
+  id: 2n,
+  pending_id: 0n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  user_data: 0n,
+  reserved: 0n,
+  timeout: 0n,
+  ledger: 1,
+  code: 720,
+  flags: 0,
+  amount: 10n,
+  timestamp: 0n,
+};
+let transfer1 = {
+  id: 3n,
+  pending_id: 0n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  user_data: 0n,
+  reserved: 0n,
+  timeout: 0n,
+  ledger: 1,
+  code: 720,
+  flags: 0,
+  amount: 10n,
+  timestamp: 0n,
+};
 transfer0.flags = TransferFlags.linked;
 // Create the transfer
 transferErrors = await client.createTransfers([transfer0, transfer1]);
@@ -340,13 +426,37 @@ appropriate accounts and apply them to the `debits_posted` and
 `credits_posted` balances.
 
 ```javascript
-transfer = {
-  id: 2n,
-  pending_id: 1n,
+let transfer2 = {
+  id: 4n,
+  pending_id: 0n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  user_data: 0n,
+  reserved: 0n,
+  timeout: 0n,
+  ledger: 1,
+  code: 720,
+  flags: TransferFlags.pending,
+  amount: 10n,
+  timestamp: 0n,
+};
+transferErrors = await client.createTransfers([transfer2]);
+
+let transfer3 = {
+  id: 5n,
+  pending_id: 4n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  user_data: 0n,
+  reserved: 0n,
+  timeout: 0n,
+  ledger: 1,
+  code: 720,
   flags: TransferFlags.post_pending_transfer,
+  amount: 10n,
   timestamp: 0n,
 };
-transferErrors = await client.createTransfers([transfer]);
+transferErrors = await client.createTransfers([transfer3]);
 ```
 
 #### Void a Pending Transfer
@@ -358,13 +468,37 @@ appropriate accounts and **not** apply them to the `debits_posted` and
 `credits_posted` balances.
 
 ```javascript
-transfer = {
-  id: 2n,
-  pending_id: 1n,
+let transfer4 = {
+  id: 4n,
+  pending_id: 0n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  user_data: 0n,
+  reserved: 0n,
+  timeout: 0n,
+  ledger: 1,
+  code: 720,
+  flags: TransferFlags.pending,
+  amount: 10n,
+  timestamp: 0n,
+};
+transferErrors = await client.createTransfers([transfer4]);
+
+let transfer5 = {
+  id: 7n,
+  pending_id: 6n,
+  debit_account_id: 102n,
+  credit_account_id: 103n,
+  user_data: 0n,
+  reserved: 0n,
+  timeout: 0n,
+  ledger: 1,
+  code: 720,
   flags: TransferFlags.void_pending_transfer,
+  amount: 10n,
   timestamp: 0n,
 };
-transferErrors = await client.createTransfers([transfer]);
+transferErrors = await client.createTransfers([transfer5]);
 ```
 
 ## Transfer Lookup
@@ -388,8 +522,8 @@ console.log(transfers);
  * [{
  *   id: 1n,
  *   pending_id: 0n,
- *   debit_account_id: 1n,
- *   credit_account_id: 2n,
+ *   debit_account_id: 102n,
+ *   credit_account_id: 103n,
  *   user_data: 0n,
  *   reserved: 0n,
  *   timeout: 0n,
@@ -423,7 +557,7 @@ chain will have their error result set to `linked_event_failed`.
 ```javascript
 const batch = [];
 let linkedFlag = 0;
-linkedFlag |= CreateTransferFlags.linked;
+linkedFlag |= TransferFlags.linked;
 
 // An individual transfer (successful):
 batch.push({ id: 1n /* , ... */ });
@@ -469,9 +603,9 @@ const errors = await client.createTransfers(batch);
 In a POSIX shell run:
 
 ```console
-$ git clone https://github.com/${GITHUB_REPOSITY:-tigerbeetledb/tigerbeetle}
+$ git clone https://github.com/tigerbeetledb/tigerbeetle
 $ cd tigerbeetle
-$ git checkout $GIT_SHA
+$ git submodule update --init --recursive
 $ ./scripts/install_zig.sh
 $ cd src/clients/node
 $ npm install --include dev

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tigerbeetle-node",
-  "version": "0.12.105",
+  "version": "0.12.106",
   "description": "TigerBeetle Node.js client",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",