tigerbeetle-node 0.14.178 → 0.14.179

package/src/index.ts

@@ -5,8 +5,10 @@ import {
   CreateAccountsError,
   CreateTransfersError,
   Operation,
-  GetAccountTransfers,
+  AccountFilter,
+  AccountBalance,
 } from './bindings'
+import { randomFillSync } from 'node:crypto'
 
 const binding: Binding = (() => {
   const { arch, platform } = process
@@ -66,8 +68,8 @@ const binding: Binding = (() => {
 export type Context = object // tb_client
 export type AccountID = bigint // u128
 export type TransferID = bigint // u128
-export type Event = Account | Transfer | AccountID | TransferID | GetAccountTransfers
-export type Result = CreateAccountsError | CreateTransfersError | Account | Transfer
+export type Event = Account | Transfer | AccountID | TransferID | AccountFilter
+export type Result = CreateAccountsError | CreateTransfersError | Account | Transfer | AccountBalance
 export type ResultCallback = (error: Error | null, results: Result[] | null) => void
 
 interface BindingInitArgs {
@@ -93,7 +95,8 @@ export interface Client {
   createTransfers: (batch: Transfer[]) => Promise<CreateTransfersError[]>
   lookupAccounts: (batch: AccountID[]) => Promise<Account[]>
   lookupTransfers: (batch: TransferID[]) => Promise<Transfer[]>
-  getAccountTransfers: (filter: GetAccountTransfers) => Promise<Transfer[]>
+  getAccountTransfers: (filter: AccountFilter) => Promise<Transfer[]>
+  getAccountHistory: (filter: AccountFilter) => Promise<AccountBalance[]>
   destroy: () => void
 }
 
@@ -129,6 +132,49 @@ export function createClient (args: ClientInitArgs): Client {
     lookupAccounts(batch) { return request(Operation.lookup_accounts, batch) },
     lookupTransfers(batch) { return request(Operation.lookup_transfers, batch) },
     getAccountTransfers(filter) { return request(Operation.get_account_transfers, [filter]) },
+    getAccountHistory(filter) { return request(Operation.get_account_history, [filter]) },
     destroy() { binding.deinit(context) },
   }
 }
+
+let idLastTimestamp = 0;
+let idLastBuffer = new DataView(new ArrayBuffer(16));
+
+/**
+ * Generates a Universally Unique and Sortable Identifier as a u128 bigint.
+ *
+ * @remarks
+ * Based on {@link https://github.com/ulid/spec}, IDs returned are guaranteed to be monotonically
+ * increasing.
+ */
+export function id(): bigint {
+  // Ensure timestamp monotonically increases and generate a new random on each new timestamp.
+  let timestamp = Date.now()
+  if (timestamp <= idLastTimestamp) {
+    timestamp = idLastTimestamp
+  } else {
+    idLastTimestamp = timestamp
+    randomFillSync(idLastBuffer)
+  }
+
+  // Increment the u80 in idLastBuffer using carry arithmetic on u32s (as JS doesn't have fast u64).
+  const littleEndian = true
+  const randomLo32 = idLastBuffer.getUint32(0, littleEndian) + 1
+  const randomHi32 = idLastBuffer.getUint32(4, littleEndian) + (randomLo32 > 0xFFFFFFFF ? 1 : 0)
+  const randomHi16 = idLastBuffer.getUint16(8, littleEndian) + (randomHi32 > 0xFFFFFFFF ? 1 : 0)
+  if (randomHi16 > 0xFFFF) {
+    throw new Error('random bits overflow on monotonic increment')
+  }
+
+  // Store the incremented random monotonic and the timestamp into the buffer.
+  idLastBuffer.setUint32(0, randomLo32 & 0xFFFFFFFF, littleEndian)
+  idLastBuffer.setUint32(4, randomHi32 & 0xFFFFFFFF, littleEndian)
+  idLastBuffer.setUint16(8, randomHi16, littleEndian) // No need to mask since checked above.
+  idLastBuffer.setUint16(10, timestamp & 0xFFFF, littleEndian) // timestamp lo.
+  idLastBuffer.setUint32(12, (timestamp >>> 16) & 0xFFFFFFFF, littleEndian) // timestamp hi.
+
+  // Then return the buffer's contents as a little-endian u128 bigint.
+  const lo = idLastBuffer.getBigUint64(0, littleEndian)
+  const hi = idLastBuffer.getBigUint64(8, littleEndian)
+  return (hi << 64n) | lo
+}

package/src/node.zig

@@ -15,8 +15,9 @@ const Transfer = tb.Transfer;
 const TransferFlags = tb.TransferFlags;
 const CreateAccountsResult = tb.CreateAccountsResult;
 const CreateTransfersResult = tb.CreateTransfersResult;
-const GetAccountTransfers = tb.GetAccountTransfers;
-const GetAccountTransfersFlags = tb.GetAccountTransfersFlags;
+const AccountFilter = tb.AccountFilter;
+const AccountFilterFlags = tb.AccountFilterFlags;
+const AccountBalance = tb.AccountBalance;
 
 const Storage = @import("../../../storage.zig").Storage;
 const StateMachine = @import("../../../state_machine.zig").StateMachineType(Storage, constants.state_machine_config);
@@ -367,7 +368,7 @@ fn decode_array(comptime Event: type, env: c.napi_env, array: c.napi_value, even
     for (events, 0..) |*event, i| {
         const object = try translate.array_element(env, array, @intCast(i));
         switch (Event) {
-            Account, Transfer, GetAccountTransfers => {
+            Account, Transfer, AccountFilter, AccountBalance => {
                 inline for (std.meta.fields(Event)) |field| {
                     const value: field.type = switch (@typeInfo(field.type)) {
                         .Struct => |info| @bitCast(try @field(
@@ -419,6 +420,8 @@ fn encode_array(comptime Result: type, env: c.napi_env, results: []const Result)
             const FieldInt = switch (@typeInfo(field.type)) {
                 .Struct => |info| info.backing_integer.?,
                 .Enum => |info| info.tag_type,
+                // Arrays are only used for padding/reserved fields.
+                .Array => continue,
                 else => field.type,
             };
 
@@ -474,9 +477,7 @@ fn BufferType(comptime op: Operation) type {
             // Allocate enough bytes to hold memory for the Events and the Results.
             const max_bytes = @max(
                 @sizeOf(Event) * count,
-                @sizeOf(Result) *
-                    // Ad-hoc hack, event and result sizes are not the same size.
-                    if (op == .get_account_transfers) 8190 else count,
+                @sizeOf(Result) * event_count(op, count),
             );
             if (@sizeOf(vsr.Header) + max_bytes > constants.message_size_max) {
                 return translate.throw(env, "Batch is larger than the maximum message size.");
@@ -496,9 +497,7 @@ fn BufferType(comptime op: Operation) type {
         fn free(buffer: Buffer) void {
             const max_bytes = @max(
                 @sizeOf(Event) * buffer.count,
-                @sizeOf(Result) *
-                    //TODO(batiati): Refine the way we handle events with asymmetric results.
-                    if (op == .get_account_transfers) 8190 else buffer.count,
+                @sizeOf(Result) * event_count(op, buffer.count),
             );
             const bytes: []align(max_align) u8 = @alignCast(buffer.ptr[0..max_bytes]);
             allocator.free(bytes);
@@ -510,10 +509,16 @@ fn BufferType(comptime op: Operation) type {
         }
 
         fn results(buffer: Buffer) []Result {
-            const result_bytes = buffer.ptr[0 .. @sizeOf(Result) *
-                // Ad-hoc hack, event and result sizes are not the same size.
-                if (op == .get_account_transfers) 8190 else buffer.count];
+            const result_bytes = buffer.ptr[0 .. @sizeOf(Result) * event_count(op, buffer.count)];
             return @alignCast(std.mem.bytesAsSlice(Result, result_bytes));
         }
+
+        fn event_count(operation: Operation, count: usize) usize {
+            // TODO(batiati): Refine the way we handle events with asymmetric results.
+            return switch (operation) {
+                .get_account_transfers, .get_account_history => 8190,
+                else => count,
+            };
+        }
     };
 }

package/src/test.ts

@@ -6,8 +6,10 @@ import {
   TransferFlags,
   CreateAccountError,
   CreateTransferError,
-  GetAccountTransfers,
-  GetAccountTransfersFlags,
+  AccountFilter,
+  AccountFilterFlags,
+  AccountFlags,
+  id,
 } from '.'
 
 const client = createClient({
@@ -57,6 +59,20 @@ test.skip = (name: string, fn: () => Promise<void>) => {
   console.log(name + ': SKIPPED')
 }
 
+test('id() monotonically increasing', async (): Promise<void> => {
+  let idA = id();
+  for (let i = 0; i < 10_000_000; i++) {
+    // Ensure ID is monotonic between milliseconds if the loop executes too fast.
+    if (i % 10_000 == 0) {
+      await new Promise(resolve => setTimeout(resolve, 1))
+    }
+
+    const idB = id();
+    assert.ok(idB > idA, 'id() returned an id that did not monotonically increase');
+    idA = idB;
+  }
+})
+
 test('range check `code` on Account to be u16', async (): Promise<void> => {
   const account = { ...accountA, id: 0n }
 
@@ -404,7 +420,7 @@ test('can get account transfers', async (): Promise<void> => {
     reserved: 0,
     ledger: 1,
     code: 718,
-    flags: 0,
+    flags: AccountFlags.history,
     timestamp: 0n
   }
   const account_errors = await client.createAccounts([accountC])
@@ -434,19 +450,26 @@ test('can get account transfers', async (): Promise<void> => {
   assert.strictEqual(transfers_created_result.length, 0)
 
   // Query all transfers for accountC:
-  var filter: GetAccountTransfers = {
+  var filter: AccountFilter = {
     account_id: accountC.id,
     timestamp_min: 0n,
     timestamp_max: 0n,
     limit: 8190,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits,
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits,
   }
   var transfers = await client.getAccountTransfers(filter)
+  var history = await client.getAccountHistory(filter)
   assert.strictEqual(transfers.length, transfers_created.length)
+  assert.strictEqual(history.length, transfers.length)
+
   var timestamp = 0n;
+  var i = 0;
   for (var transfer of transfers) {
     assert.ok(timestamp < transfer.timestamp);
     timestamp = transfer.timestamp;
+
+    assert.ok(history[i].timestamp == transfer.timestamp);
+    i++;
   }
 
   // Query only the debit transfers for accountC, descending:
@@ -455,14 +478,22 @@ test('can get account transfers', async (): Promise<void> => {
     timestamp_min: 0n,
     timestamp_max: 0n,
     limit: 8190,
-    flags: GetAccountTransfersFlags.debits |  GetAccountTransfersFlags.reversed,
+    flags: AccountFilterFlags.debits |  AccountFilterFlags.reversed,
   }
   transfers = await client.getAccountTransfers(filter)
+  history = await client.getAccountHistory(filter)
+
   assert.strictEqual(transfers.length, transfers_created.length / 2)
+  assert.strictEqual(history.length, transfers.length)
+
   timestamp = 1n << 64n;
+  i = 0;
   for (var transfer of transfers) {
     assert.ok(transfer.timestamp < timestamp);
     timestamp = transfer.timestamp;
+
+    assert.ok(history[i].timestamp == transfer.timestamp);
+    i++;    
   }
 
   // Query only the credit transfers for accountC, descending:
@@ -471,14 +502,22 @@ test('can get account transfers', async (): Promise<void> => {
     timestamp_min: 0n,
     timestamp_max: 0n,
     limit: 8190,
-    flags: GetAccountTransfersFlags.credits |  GetAccountTransfersFlags.reversed,
+    flags: AccountFilterFlags.credits |  AccountFilterFlags.reversed,
   }
   transfers = await client.getAccountTransfers(filter)
+  history = await client.getAccountHistory(filter)
+
   assert.strictEqual(transfers.length, transfers_created.length / 2)
+  assert.strictEqual(history.length, transfers.length)
+
   timestamp = 1n << 64n;
+  i = 0;
   for (var transfer of transfers) {
     assert.ok(transfer.timestamp < timestamp);
     timestamp = transfer.timestamp;
+
+    assert.ok(history[i].timestamp == transfer.timestamp);
+    i++;    
   }
 
   // Query the first 5 transfers for accountC:
@@ -487,14 +526,22 @@ test('can get account transfers', async (): Promise<void> => {
     timestamp_min: 0n,
     timestamp_max: 0n,
     limit: transfers_created.length / 2,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits,
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits,
   }
   transfers = await client.getAccountTransfers(filter)
+  history = await client.getAccountHistory(filter)
+
   assert.strictEqual(transfers.length, transfers_created.length / 2)
+  assert.strictEqual(history.length, transfers.length)
+
   timestamp = 0n;
+  i = 0;
   for (var transfer of transfers) {
     assert.ok(timestamp < transfer.timestamp);
     timestamp = transfer.timestamp;
+
+    assert.ok(history[i].timestamp == transfer.timestamp);
+    i++;    
   }
 
   // Query the next 5 transfers for accountC, with pagination:
@@ -503,13 +550,21 @@ test('can get account transfers', async (): Promise<void> => {
     timestamp_min: timestamp + 1n,
     timestamp_max: 0n,
     limit: transfers_created.length / 2,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits,
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits,
   }
   transfers = await client.getAccountTransfers(filter)
+  history = await client.getAccountHistory(filter)
+
   assert.strictEqual(transfers.length, transfers_created.length / 2)
+  assert.strictEqual(history.length, transfers.length)
+
+  i = 0;
   for (var transfer of transfers) {
     assert.ok(timestamp < transfer.timestamp);
     timestamp = transfer.timestamp;
+
+    assert.ok(history[i].timestamp == transfer.timestamp);
+    i++;    
   }
 
   // Query again, no more transfers should be found:
@@ -518,10 +573,13 @@ test('can get account transfers', async (): Promise<void> => {
     timestamp_min: timestamp + 1n,
     timestamp_max: 0n,
     limit: transfers_created.length / 2,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits,
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits,
   }
   transfers = await client.getAccountTransfers(filter)
+  history = await client.getAccountHistory(filter)
+
   assert.strictEqual(transfers.length, 0)
+  assert.strictEqual(history.length, transfers.length)
 
   // Query the first 5 transfers for accountC ORDER BY DESC:
   filter = {
@@ -529,14 +587,22 @@ test('can get account transfers', async (): Promise<void> => {
     timestamp_min: 0n,
     timestamp_max: 0n,
     limit: transfers_created.length / 2,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits | GetAccountTransfersFlags.reversed,
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits | AccountFilterFlags.reversed,
   }
   transfers = await client.getAccountTransfers(filter)
+  history = await client.getAccountHistory(filter)
+
   assert.strictEqual(transfers.length, transfers_created.length / 2)
+  assert.strictEqual(history.length, transfers.length)
+
   timestamp = 1n << 64n;
+  i = 0;
   for (var transfer of transfers) {
     assert.ok(timestamp > transfer.timestamp);
     timestamp = transfer.timestamp;
+
+    assert.ok(history[i].timestamp == transfer.timestamp);
+    i++;    
   }
 
   // Query the next 5 transfers for accountC, with pagination:
@@ -545,13 +611,21 @@ test('can get account transfers', async (): Promise<void> => {
     timestamp_min: 0n,
     timestamp_max: timestamp - 1n,
     limit: transfers_created.length / 2,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits | GetAccountTransfersFlags.reversed,
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits | AccountFilterFlags.reversed,
   }
   transfers = await client.getAccountTransfers(filter)
+  history = await client.getAccountHistory(filter)
+
   assert.strictEqual(transfers.length, transfers_created.length / 2)
+  assert.strictEqual(history.length, transfers.length)
+
+  i = 0;
   for (var transfer of transfers) {
     assert.ok(timestamp > transfer.timestamp);
     timestamp = transfer.timestamp;
+
+    assert.ok(history[i].timestamp == transfer.timestamp);
+    i++;    
   }
 
   // Query again, no more transfers should be found:
@@ -560,73 +634,90 @@ test('can get account transfers', async (): Promise<void> => {
     timestamp_min: 0n,
     timestamp_max: timestamp - 1n,
     limit: transfers_created.length / 2,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits | GetAccountTransfersFlags.reversed,
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits | AccountFilterFlags.reversed,
   }
   transfers = await client.getAccountTransfers(filter)
-  assert.strictEqual(transfers.length, 0)  
+  history = await client.getAccountHistory(filter)
+
+  assert.strictEqual(transfers.length, 0)
+  assert.strictEqual(history.length, transfers.length)
 
   // Invalid account:
-  assert.strictEqual((await client.getAccountTransfers({
+  filter = {
     account_id: 0n,
     timestamp_min: 0n,
     timestamp_max: 0n,
     limit: 8190,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits,
-  })).length, 0)
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits,
+  }
+  assert.strictEqual((await client.getAccountTransfers(filter)).length, 0)
+  assert.strictEqual((await client.getAccountHistory(filter)).length, 0)
 
   // Invalid timestamp min:
-  assert.strictEqual((await client.getAccountTransfers({
+  filter = {
     account_id: accountC.id,
     timestamp_min: (1n << 64n) - 1n, // ulong max value
     timestamp_max: 0n,
     limit: 8190,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits,
-  })).length, 0)
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits,
+  }
+  assert.strictEqual((await client.getAccountTransfers(filter)).length, 0)
+  assert.strictEqual((await client.getAccountHistory(filter)).length, 0)
 
   // Invalid timestamp max:
-  assert.strictEqual((await client.getAccountTransfers({
+  filter = {
     account_id: accountC.id,
     timestamp_min: 0n,
     timestamp_max: (1n << 64n) - 1n, // ulong max value
     limit: 8190,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits,
-  })).length, 0)
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits,
+  }
+  assert.strictEqual((await client.getAccountTransfers(filter)).length, 0)
+  assert.strictEqual((await client.getAccountHistory(filter)).length, 0)
 
   // Invalid timestamp range:
-  assert.strictEqual((await client.getAccountTransfers({
+  filter = {
     account_id: accountC.id,
     timestamp_min: (1n << 64n) - 2n, // ulong max - 1
     timestamp_max: 1n,
     limit: 8190,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits,
-  })).length, 0)
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits,
+  }
+  assert.strictEqual((await client.getAccountTransfers(filter)).length, 0)
+  assert.strictEqual((await client.getAccountHistory(filter)).length, 0)
 
   // Zero limit:
-  assert.strictEqual((await client.getAccountTransfers({
+  filter = {
     account_id: accountC.id,
     timestamp_min: 0n,
     timestamp_max: 0n,
     limit: 0,
-    flags: GetAccountTransfersFlags.credits | GetAccountTransfersFlags.debits,
-  })).length, 0)
+    flags: AccountFilterFlags.credits | AccountFilterFlags.debits,
+  }
+  assert.strictEqual((await client.getAccountTransfers(filter)).length, 0)
+  assert.strictEqual((await client.getAccountHistory(filter)).length, 0)
 
   // Empty flags:
-  assert.strictEqual((await client.getAccountTransfers({
+  filter = {
     account_id: accountC.id,
     timestamp_min: 0n,
     timestamp_max: 0n,
     limit: 8190,
-    flags: GetAccountTransfersFlags.none,
-  })).length, 0)
+    flags: AccountFilterFlags.none,
+  }  
+  assert.strictEqual((await client.getAccountTransfers(filter)).length, 0)
+  assert.strictEqual((await client.getAccountHistory(filter)).length, 0)
 
   // Invalid flags:
-  assert.strictEqual((await client.getAccountTransfers({
+  filter = {
     account_id: accountC.id,
     timestamp_min: 0n,
     timestamp_max: 0n,
     limit: 8190,
     flags: 0xFFFF,
-  })).length, 0)
+  }
+  assert.strictEqual((await client.getAccountTransfers(filter)).length, 0)
+  assert.strictEqual((await client.getAccountHistory(filter)).length, 0)
 
 })