@tchain/tcabci-read-js-client 2.7.12 → 2.8.0

package/README.md

@@ -1,65 +1,81 @@
-# TCABCI Read Node Javascript WebSocket Client
+# TCABCI Read Node JavaScript Client
 
-TransferChain Fastest Read Network WebSocket Client
-Read Node Address: [https://read-node-01.transferchain.io](https://read-node-01.transferchain.io)
-Read Node WebSocket Address: [wss://read-node-01.transferchain.io/ws](wss://read-node-01.transferchain.io/ws)
+HTTP queries, transaction broadcasts and WebSocket subscriptions for the
+TransferChain read network. Uses ESM and supports Node.js 24+ or browsers with
+Fetch, WebSocket, AbortController, TextEncoder and TextDecoder.
 
-## Networks
-
-- medusa - v2
-
-## Installation
-
-```shell
-$ npm i @tchain/tcabci-read-js-client
+```sh
+npm install @tchain/tcabci-read-js-client
 ```
 
-## Example
-
-**Subscribe, Listen and Unsubscribe Example**
-
 ```js
 import TCaBCIClient from '@tchain/tcabci-read-js-client'
 
 const client = new TCaBCIClient()
-// OR
-const client = new TCaBCIClient([
-  'https://read-node-01.transferchain.io',
-  'wss://read-node-01.transferchain.io/ws'
-])
-// OR
-// With addresses and WebSocket library and network name, version
-const client = new TCaBCIClient(
-  [
-    'https://read-node-01.transferchain.io',
-    'wss://read-node-01.transferchain.io/ws'
-  ],
-  WebSocket,
-  'transferchain',
-  'v1'
-)
 
-client.Start()
+client.SetSuccessCallback(() => {
+  // Obtain a valid address-to-signature map from your signing layer.
+  client.Subscribe(['<public-address>'], {
+    '<public-address>': '<signature>'
+  })
+})
+client.SetListenCallback((block, transaction, message) => {
+  // Handle the received immutable data snapshot.
+})
+client.SetErrorCallback(error => {
+  // Handle a sanitized transport/protocol error.
+})
+
+await client.Start() // Starts connecting; the success callback reports OPEN.
+// When finished:
+await client.Dispose() // Also clears application callbacks.
+```
 
-client.Subscribe(['<your-public-address-one>', '<your-public-address-two>'])
+For an injected WebSocket implementation, pass its constructor as the second
+argument. The first argument is an optional `[httpsURL, wssURL]` endpoint pair;
+the third and fourth arguments select the chain. The fifth argument accepts
+client limits and transport options.
 
-client.SetListenCallback(() => {
-  // If a transaction has been sent to your addresses, the callback you set here will be called.
+```js
+const client = new TCaBCIClient([], WebSocket, 'medusa', 'v2', {
+  timeoutMs: 30000,
+  maxRequestBytes: 16 * 1024 * 1024,
+  maxResponseBytes: 64 * 1024 * 1024,
+  maxConcurrentRequests: 32,
+  maxMessageBytes: 16 * 1024 * 1024,
+  maxEnqueuedMessages: 100,
+  maxPendingCallbacks: 1000
 })
 
-client.SetErrorCallback(() => {
-  // If network errors will be called.
+const controller = new AbortController()
+const result = await client.Tx('<transaction-id>', '<signature>', {
+  signal: controller.signal,
+  timeoutMs: 10000
 })
+```
 
-client.SetCloseCallback(() => {
-  // If server side close will be called.
-})
+Each address list accepts 1–251 entries; each address accepts 1–2048 characters.
+Active subscriptions are deduplicated and bounded to 251 addresses. Signed data
+is an address-to-signature string map. Caller objects are neither frozen nor
+overwritten.
 
-client.Unsubscribe()
-client.Stop()
-```
+HTTP redirects are rejected. Remote plaintext endpoints require explicit
+`allowInsecure: true`; exact localhost/loopback endpoints support local
+integration. Read-only operations may retry transient failures; broadcasts are
+attempted once. The deadline includes retries and response consumption. HTTP
+errors retain status, without response bodies or raw parser causes.
+
+`Stop()` is idempotent, aborts HTTP work and releases subscription state. Await
+pending HTTP promises to observe their cancellation and completed byte cleanup.
+`Dispose()` additionally drops application callback references. Close codes use
+browser-compatible values: 1000 or 3000–4999. Offline binary messages are
+rejected; string queues have finite count and byte limits. Transport payload
+logging is disabled, including when `SetDebug(true)` is called. Frozen snapshots
+do not imply secure erasure of JavaScript strings.
+
+TypeScript declarations accompany the ESM API. Tests are intentionally local
+only under the ignored `test/` directory and are excluded from the package.
 
 ## License
 
-tcabci-read-js-client is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license
-text.
+Apache License, Version 2.0. See [LICENSE](LICENSE).

package/block.d.ts

@@ -1,13 +1,22 @@
-import { Transaction } from './transaction'
+import { Transaction } from './transaction.js'
+import { ParseResult } from './types.js'
 
 export declare class Block {
-  get Height(): number
-  get TXS(): number
-  get Hash(): string | null
-  get Transactions(): Transaction[]
-  get ChainName(): string
-  get ChainVersion(): string
-
-  static FromJSON(value: string): { block?: Block; error?: Error }
-  static FromObject(obj: Record<string, any>): { block?: Block; error?: Error }
+  get Height(): number | undefined
+
+  get TXS(): number | undefined
+
+  get Hash(): string | undefined
+
+  get Transactions(): readonly Transaction[] | undefined
+
+  get ChainName(): string | undefined
+
+  get ChainVersion(): string | undefined
+
+  static FromJSON(value: string): ParseResult<'block', Readonly<Block>>
+
+  static FromObject(
+    obj: Record<string, unknown>
+  ): ParseResult<'block', Readonly<Block>>
 }

package/block.js

@@ -1,5 +1,5 @@
+import { SendThrow } from './util.js'
 import { Transaction } from './transaction.js'
-import { Debug } from '@streetbyters/js-debug'
 
 export class Block {
   _height
@@ -21,6 +21,7 @@ export class Block {
     return this._hash
   }
 
+  /** @returns {ReadonlyArray<Readonly<Transaction>>|undefined} Frozen parsed transactions. */
   get Transactions() {
     return this._transactions
   }
@@ -35,59 +36,54 @@ export class Block {
 
   /**
    * @param {string} value
-   * @return {{block: ?Block, error: ?Error}}
+   * @return {import('./types.js').ParseResult<'block', Readonly<Block>>}
    * @constructor
    */
   static FromJSON(value) {
     try {
-      const bl = new Block(),
-        parsed = JSON.parse(value)
-
-      bl._transactions = []
-
-      if (typeof parsed.height !== 'undefined') bl._height = parsed.height
-      if (typeof parsed.txs !== 'undefined') bl._txs = parsed.txs
-      if (typeof parsed.hash !== 'undefined') bl._hash = parsed.hash
-      if (typeof parsed.chain_name !== 'undefined')
-        bl._chainName = parsed.chain_name
-      if (typeof parsed.chain_version !== 'undefined')
-        bl._chainVersion = parsed.chain_version
-
-      if (typeof parsed.transactions !== 'undefined') {
-        for (let i = 0; i < parsed.transactions.length; i++) {
-          const { transaction, error } = Transaction.FromObject(
-            parsed.transactions[i]
-          )
-          if (error) {
-            return { block: null, error: error }
-          }
-
-          bl._transactions.push(transaction)
-        }
-      }
-
-      return { block: bl, error: null }
-    } catch (e) {
-      Debug.error(e)
-      return { block: null, error: e }
+      return Block.FromObject(JSON.parse(value))
+    } catch {
+      return { block: null, error: new Error('Invalid block JSON') }
     }
   }
 
-  /**
-   * @param {object} obj
-   * @return {{block: ?Block, error: ?Error}}
-   * @constructor
-   */
+  /** @param {Record<string, unknown>} obj @returns {import('./types.js').ParseResult<'block', Readonly<Block>>} */
   static FromObject(obj) {
     try {
+      if (!obj || typeof obj !== 'object' || Array.isArray(obj))
+        SendThrow(new TypeError('Invalid block'))
+
+      for (const field of ['height', 'txs']) {
+        if (
+          typeof obj[field] !== 'undefined' &&
+          (!Number.isSafeInteger(obj[field]) || obj[field] < 0)
+        )
+          SendThrow(new TypeError('Invalid block counter'))
+      }
+
+      for (const field of ['hash', 'chain_name', 'chain_version']) {
+        if (typeof obj[field] !== 'undefined' && typeof obj[field] !== 'string')
+          SendThrow(new TypeError('Invalid block field'))
+      }
+
+      if (
+        typeof obj.transactions !== 'undefined' &&
+        (!Array.isArray(obj.transactions) || obj.transactions.length > 100000)
+      )
+        SendThrow(new TypeError('Invalid block transactions'))
+
       const bl = new Block()
 
       bl._transactions = []
 
       if (typeof obj.height !== 'undefined') bl._height = obj.height
+
       if (typeof obj.txs !== 'undefined') bl._txs = obj.txs
+
       if (typeof obj.hash !== 'undefined') bl._hash = obj.hash
+
       if (typeof obj.chain_name !== 'undefined') bl._chainName = obj.chain_name
+
       if (typeof obj.chain_version !== 'undefined')
         bl._chainVersion = obj.chain_version
 
@@ -96,6 +92,7 @@ export class Block {
           const { transaction, error } = Transaction.FromObject(
             obj.transactions[i]
           )
+
           if (error) {
             return { block: null, error: error }
           }
@@ -104,10 +101,11 @@ export class Block {
         }
       }
 
-      return { block: bl, error: null }
-    } catch (e) {
-      Debug.error(e)
-      return { block: null, error: e }
+      Object.freeze(bl._transactions)
+
+      return { block: Object.freeze(bl), error: null }
+    } catch {
+      return { block: null, error: new Error('Invalid block payload') }
     }
   }
 }

package/breaker.d.ts

@@ -1,3 +1,7 @@
 export declare class Breaker {
-  execute(fn: () => Promise<any>): Promise<any>
+  execute<T>(
+    fn: () => Promise<T>,
+    signal?: AbortSignal,
+    retry?: boolean
+  ): Promise<T>
 }

package/breaker.js

@@ -1,52 +1,55 @@
-import {
-  ConsecutiveBreaker,
-  ExponentialBackoff,
-  retry,
-  handleType,
-  circuitBreaker,
-  wrap
-} from 'cockatiel'
-import { FetchError } from './errors.js'
+import { ConsecutiveBreaker, handleType, circuitBreaker } from 'cockatiel'
+import { FetchError, ERR_NETWORK } from './errors.js'
+
+const retryable = (error) =>
+  error instanceof FetchError &&
+  ([502, 503, 504].includes(error.status) || error.message === ERR_NETWORK)
 
 export class Breaker {
-  _options = {
-    halfOpenAfter: 10 * 1000,
+  _circuitBreakerPolicy = circuitBreaker(handleType(FetchError, retryable), {
+    halfOpenAfter: 10000,
     breaker: new ConsecutiveBreaker(10)
-  }
-  _retryPolicy = retry(
-    handleType(FetchError, err => [502, 503, 504].includes(err.status)).orType(
-      Error,
-      err => {
-        return err.message.toLowerCase().search('failed to fetch') > -1
-      }
-    ),
-    {
-      maxAttempts: 10,
-      backoff: new ExponentialBackoff({
-        initialDelay: 500,
-        maxDelay: 15000
-      })
-    }
-  )
-  _circuitBreakerPolicy = circuitBreaker(
-    handleType(FetchError, err => [502, 503, 504].includes(err.status)).orType(
-      Error,
-      err => {
-        return err.message.toLowerCase().search('failed to fetch') > -1
-      }
-    ),
-    this._options
-  )
-  _retryWithBreaker = wrap(this._retryPolicy, this._circuitBreakerPolicy)
-  constructor() {}
+  })
 
   /**
-   * @param {function} fn
-   * @return {Promise<*>}
+   * @template T
+   * @param {function(): Promise<T>} fn
+   * @param {AbortSignal} [signal] Cancels retry backoff immediately.
+   * @param {boolean} [retry=true] Disable for non-idempotent writes.
+   * @returns {Promise<T>}
    */
-  execute(fn) {
-    return this._retryWithBreaker.execute(fn).catch(err => {
-      return Promise.reject(err)
-    })
+  async execute(fn, signal, retry = true) {
+    for (let attempt = 0; ; attempt++) {
+      signal?.throwIfAborted()
+
+      try {
+        return await this._circuitBreakerPolicy.execute(fn, signal)
+      } catch (error) {
+        if (!retry || attempt >= 3 || signal?.aborted || !retryable(error))
+          throw error
+
+        await this._delay(
+          Math.min(500 * 2 ** attempt, 15000) * (0.5 + Math.random()),
+          signal
+        )
+      }
+    }
+  }
+
+  async _delay(ms, signal) {
+    let timer, abort
+
+    try {
+      await new Promise((resolve, reject) => {
+        abort = () => reject(new FetchError('Request aborted'))
+        timer = setTimeout(resolve, ms)
+
+        if (signal?.aborted) abort()
+        else signal?.addEventListener('abort', abort, { once: true })
+      })
+    } finally {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', abort)
+    }
   }
 }

package/bytea.d.ts

@@ -1,4 +1,5 @@
 export declare class Bytea {
   constructor(bytes: Uint8Array, status: number)
+
   ToJSON(): string
 }

package/bytea.js

@@ -0,0 +1,16 @@
+export class Bytea {
+  #bytes
+  #status
+
+  constructor(bytes, status) {
+    this.#bytes = bytes
+    this.#status = status
+  }
+
+  ToJSON() {
+    return JSON.stringify({
+      bytes: this.#bytes,
+      status: this.#status
+    })
+  }
+}

package/callback.d.ts

@@ -1,11 +1,16 @@
-import { Transaction } from './transaction'
-import { Block } from './block'
+import { Transaction } from './transaction.js'
+import { Block } from './block.js'
+import Message from './message.js'
+import { SocketCloseEvent } from './types.js'
 
-export declare type SuccessCallback = (event: Event) => void
-export declare type ErrorCallback = (event: Event) => void
-export declare type CloseCallback = (event: Event) => void
-export declare type ListenCallback = (
+export type SuccessCallback = (event: Event) => void
+
+export type ErrorCallback = (event: Error | Event) => void
+
+export type CloseCallback = (event: SocketCloseEvent) => void
+
+export type ListenCallback = (
   block: Block | null,
   tx: Transaction | null,
-  msg: any | null
+  msg: Message | null
 ) => void