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

package/message.js

@@ -1,17 +1,20 @@
+import { SendThrow } from './util.js'
 import { INVALID_ARGUMENT_WITH_CS } from './errors.js'
 import { TX_TYPE_LIST } from './transaction.js'
-import { Debug } from '@streetbyters/js-debug'
+import {
+  addresses,
+  signedData as validateSignedData,
+  cloneAndFreeze
+} from './validation.js'
 
 export const SUBSCRIBEMessage = 'subscribe',
-  UNSUBSCRIBEMessage = 'unsubscribe'
-
-export const Block = 0,
+  UNSUBSCRIBEMessage = 'unsubscribe',
+  Block = 0,
   Transaction = 1,
   Subscription = 2,
   Listen = 3,
-  MSG = 4
-
-export const OK = 1,
+  MSG = 4,
+  OK = 1,
   FAIL = 2
 
 export default class Message {
@@ -41,10 +44,16 @@ export default class Message {
   } = {}) {
     this._is_web = isWeb
     this._type = type
-    if (addrs && Array.isArray(addrs)) this._addresses = addrs
-    if (typeof signedData === 'object') this._signedAddresses = signedData
-    if (txTypes && Array.isArray(txTypes)) this._txTypes = txTypes
-    if (data) this._data = data
+
+    if (addrs && Array.isArray(addrs))
+      this._addresses = Object.freeze(addresses(addrs))
+
+    if (signedData !== null) this._signedAddresses = cloneAndFreeze(signedData)
+
+    if (txTypes && Array.isArray(txTypes))
+      this._txTypes = Object.freeze([...txTypes])
+
+    if (data !== null) this._data = cloneAndFreeze(data)
   }
 
   get IsWeb() {
@@ -55,14 +64,22 @@ export default class Message {
     return this._type
   }
 
+  /** @returns {ReadonlyArray<string>|undefined} Frozen snapshot when present. */
   get Addresses() {
     return this._addresses
   }
 
+  /** @returns {Readonly<Record<string, string>>|undefined} Frozen snapshot when present. */
   get SignedAddresses() {
     return this._signedAddresses
   }
 
+  /** @returns {ReadonlyArray<import('./transaction.js').TXType>|undefined} Frozen snapshot when present. */
+  get TXTypes() {
+    return this._txTypes
+  }
+
+  /** @returns {import('./types.js').JSONValue|undefined} Frozen snapshot when present. */
   get Data() {
     return this._data
   }
@@ -71,47 +88,50 @@ export default class Message {
     return this._state
   }
 
+  /** @param {string} value @returns {import('./types.js').ParseResult<'message', Readonly<Message>>} */
   static FromJSON(value) {
-    try {
-      const msg = new Message(),
-        parsed = JSON.parse(value)
-
-      msg._type = parsed.type
-      if (typeof parsed.addresses !== 'undefined')
-        msg._addresses = parsed.addresses
-      if (typeof parsed.signed_addresses !== 'undefined')
-        msg._signedAddresses = parsed.signed_addresses
-      if (typeof parsed.data !== 'undefined') msg._data = parsed.data
-      if (typeof parsed.tx_types !== 'undefined') msg._txTypes = parsed.tx_types
-      if (typeof parsed.state !== 'undefined') msg._state = parsed.state
-
-      msg._validate()
+    if (typeof value !== 'string')
+      return { message: null, error: new Error('Invalid message JSON') }
 
-      return { message: this, error: null }
-    } catch (e) {
-      Debug.error(e)
-      return { message: null, error: e }
+    try {
+      return Message.FromObject(JSON.parse(value))
+    } catch {
+      return { message: null, error: new Error('Invalid message JSON') }
     }
   }
 
+  /** @param {Record<string, unknown>} obj @returns {import('./types.js').ParseResult<'message', Readonly<Message>>} */
   static FromObject(obj) {
     try {
+      if (!obj || typeof obj !== 'object' || Array.isArray(obj))
+        SendThrow(new TypeError('Invalid message'))
+
       const msg = new Message()
 
       msg._type = obj.type
-      if (typeof obj.addresses !== 'undefined') msg._addresses = obj.addresses
+
+      if (typeof obj.is_web !== 'undefined') msg._is_web = obj.is_web
+
+      if (typeof obj.addresses !== 'undefined')
+        msg._addresses = Object.freeze(addresses(obj.addresses))
+
       if (typeof obj.signed_addresses !== 'undefined')
-        msg._signedAddresses = obj.signed_addresses
-      if (typeof obj.data !== 'undefined') msg._data = obj.data
-      if (typeof obj.tx_types !== 'undefined') msg._txTypes = obj.tx_types
+        msg._signedAddresses = Object.freeze(
+          validateSignedData(obj.signed_addresses)
+        )
+
+      if (typeof obj.data !== 'undefined') msg._data = cloneAndFreeze(obj.data)
+
+      if (typeof obj.tx_types !== 'undefined')
+        msg._txTypes = cloneAndFreeze(obj.tx_types)
+
       if (typeof obj.state !== 'undefined') msg._state = obj.state
 
       msg._validate()
 
-      return { message: this, error: null }
-    } catch (e) {
-      Debug.error(e)
-      return { message: null, error: e }
+      return { message: Object.freeze(msg), error: null }
+    } catch {
+      return { message: null, error: new Error('Invalid message payload') }
     }
   }
 
@@ -126,7 +146,8 @@ export default class Message {
         ? { signed_addresses: this._signedAddresses }
         : {}),
       ...(this._txTypes ? { tx_types: this._txTypes } : {}),
-      ...(this._data ? { data: this._data } : {})
+      ...(typeof this._data !== 'undefined' ? { data: this._data } : {}),
+      ...(typeof this._state !== 'undefined' ? { state: this._state } : {})
     })
   }
 
@@ -138,21 +159,18 @@ export default class Message {
       throw new Error(INVALID_ARGUMENT_WITH_CS('is_web'))
     }
 
-    if (typeof this._type === 'undefined') {
+    if (
+      ![
+        SUBSCRIBEMessage,
+        UNSUBSCRIBEMessage,
+        Block,
+        Transaction,
+        Subscription,
+        Listen,
+        MSG
+      ].includes(this._type)
+    )
       throw new Error(INVALID_ARGUMENT_WITH_CS('type'))
-    } else {
-      if (
-        typeof this._type === 'string' &&
-        ![SUBSCRIBEMessage, UNSUBSCRIBEMessage].includes(this._type)
-      ) {
-        throw new Error(INVALID_ARGUMENT_WITH_CS('type'))
-      } else if (
-        typeof this._type === 'number' &&
-        ![Block, Transaction, Subscription, Listen, MSG].includes(this._type)
-      ) {
-        throw new Error(INVALID_ARGUMENT_WITH_CS('type'))
-      }
-    }
 
     if (
       typeof this._addresses !== 'undefined' &&
@@ -168,7 +186,13 @@ export default class Message {
       throw new Error(INVALID_ARGUMENT_WITH_CS('signedAddresses'))
     }
 
-    if (typeof this._txTypes !== 'undefined' && this._txTypes.length) {
+    if (typeof this._txTypes !== 'undefined') {
+      if (
+        !Array.isArray(this._txTypes) ||
+        this._txTypes.length > TX_TYPE_LIST.length
+      )
+        throw new Error(INVALID_ARGUMENT_WITH_CS('tx_types'))
+
       for (let i = 0; i < this._txTypes.length; i++) {
         if (!TX_TYPE_LIST.includes(this._txTypes[i])) {
           throw new Error(INVALID_ARGUMENT_WITH_CS('tx_types'))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tchain/tcabci-read-js-client",
-  "version": "2.7.12",
+  "version": "2.8.0",
   "description": "TransferChain Fastest Read Network WebSocket Client",
   "homepage": "https://github.com/TransferChain/tcabci-read-js-client#readme",
   "bugs": {
@@ -24,35 +24,40 @@
     "transaction.js",
     "util.js",
     "websocket.js",
-    "websocketOptions.js"
+    "websocketOptions.js",
+    "bytea.js",
+    "validation.js"
   ],
   "type": "module",
   "main": "client.js",
-  "scripts": {
-    "format": "oxfmt ./",
-    "lint": "oxfmt ./ && oxlint --fix ./",
-    "lint:check": "oxfmt --check ./ && oxlint ./",
-    "test": "export NODE_ENV=test || SET \"NODE_ENV=test\" && mocha  --require esm --timeout 5000",
-    "test:all": "export NODE_ENV=test || SET \"NODE_ENV=test\" && mocha  --require esm --timeout 5000 '*_test.js'",
-    "test:coverage": "export NODE_ENV=test || SET \"NODE_ENV=test\" && nyc --reporter=text mocha  --require esm --timeout 5000"
-  },
+  "types": "client.d.ts",
   "dependencies": {
-    "@streetbyters/js-debug": "^0.1.3",
     "cockatiel": "^4.0.0",
     "reconnecting-websocket": "^4.4.0"
   },
   "devDependencies": {
     "@types/chai": "^5.2.3",
     "chai": "^6.2.2",
-    "esm": "^3.2.25",
-    "express": "^5.2.1",
-    "globals": "^16.5.0",
     "mocha": "^11.8.0",
-    "nyc": "^18.0.0",
     "oxfmt": "^0.63.0",
     "oxlint": "^1.84.0",
+    "typescript": "^5.9.3",
     "unit.js": "^2.1.1",
     "ws": "^8.21.3"
   },
-  "packageManager": "pnpm@12.5.1"
-}
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "format": "oxfmt ./",
+    "lint": "oxfmt ./ && oxlint --fix ./",
+    "lint:check": "oxfmt --check ./ && oxlint ./",
+    "test": "pnpm run test:unit && pnpm run test:security && pnpm run test:types",
+    "test:all": "pnpm test",
+    "test:coverage": "node --experimental-test-coverage --test test/security.test.js",
+    "test:unit": "mocha --timeout 5000 test/errors_test.js test/websocketOptions_test.js test/websocket_test.js",
+    "test:security": "node --test test/security.test.js",
+    "test:types": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 test/consumer.ts",
+    "test:integration": "mocha --timeout 7000 test/client_test.js"
+  }
+}

package/transaction.d.ts

@@ -1,104 +1,190 @@
-export declare type TXType = string
-
-export declare const TX_TYPE_MASTER: TXType,
-  TX_TYPE_ADDRESS: TXType,
-  TX_TYPE_ADDRESSES: TXType,
-  TX_TYPE_ACCOUNT: TXType,
-  TX_TYPE_ACCOUNT_INITIAL_TXS: TXType,
-  TX_TYPE_MESSAGE: TXType,
-  TX_TYPE_MESSAGE_SENT: TXType,
-  TX_TYPE_MESSAGE_THREAD_DELETE: TXType,
-  TX_TYPE_TRANSFER: TXType,
-  TX_TYPE_TRANSFER_CANCEL: TXType,
-  TX_TYPE_TRANSFER_SENT: TXType,
-  TX_TYPE_TRANSFER_RECEIVE_DELETE: TXType,
-  TX_TYPE_TRANSFER_INFO: TXType,
-  TX_TYPE_STORAGE: TXType,
-  TX_TYPE_STORAGE_DELETE: TXType,
-  TX_TYPE_BACKUP: TXType,
-  TX_TYPE_CONTACT: TXType,
-  TX_TYPE_FILE_VIRTUAL: TXType,
-  TX_TYPE_FILE_FS: TXType,
-  TX_TYPE_RFILE_VIRTUAL: TXType,
-  TX_TYPE_RFILE_FS: TXType,
-  TX_TYPE_DFILE_VIRTUAL: TXType,
-  TX_TYPE_DFILE_FS: TXType,
-  TX_TYPE_PFILE_VIRTUAL: TXType,
-  TX_TYPE_REQUEST: TXType,
-  TX_TYPE_REQUEST_IN: TXType,
-  TX_TYPE_REQUEST_UPLOAD: TXType,
-  TX_TYPE_REQUEST_CANCEL: TXType,
-  TX_TYPE_DATA_ROOM: TXType,
-  TX_TYPE_DATA_ROOMF: TXType,
-  TX_TYPE_DATA_ROOM_POLICY: TXType,
-  TX_TYPE_DATA_ROOM_DATA: TXType,
-  TX_TYPE_DATA_ROOM_DATA_DELETE: TXType,
-  TX_TYPE_DATA_ROOM_DATA_POLICY: TXType,
-  TX_TYPE_DATA_ROOME: TXType,
-  TX_TYPE_DATA_ROOME_DATA: TXType,
-  TX_TYPE_MULTI_DATA_ROOM: TXType,
-  TX_TYPE_MULTI_STORAGE: TXType,
-  TX_TYPE_MULTI_TRANSFER: TXType,
-  TX_TYPE_MULTI_TRANSFER_SENT: TXType,
-  TX_TYPE_MULTI_BACKUP: TXType,
-  TX_TYPE_MULTI_PASSWD: TXType,
-  TX_TYPE_MULTI_COLLECTION: TXType,
-  TX_TYPE_MULTI_DATAV2: TXType,
-  TX_TYPE_PASSWD_DATA: TXType,
-  TX_TYPE_PASSWD_ROOM: TXType,
-  TX_TYPE_PASSWD_ROOMF: TXType,
-  TX_TYPE_PASSWD_ROOM_POLICY: TXType,
-  TX_TYPE_PASSWD_ROOM_DATA: TXType,
-  TX_TYPE_PASSWD_ROOM_DATA_DELETE: TXType,
-  TX_TYPE_PASSWD_ROOM_DATA_POLICY: TXType,
-  TX_TYPE_DATAV2: TXType,
-  TX_TYPE_DATAV2_POLICY: TXType,
-  TX_TYPE_COLLECTION: TXType,
-  TX_TYPE_COLLECTION_POLICY: TXType,
-  TX_TYPE_DATAV2_COLLECTION: TXType,
-  TX_TYPE_DATAV2F: TXType
-
-export declare const TX_TYPE_LIST: TXType[]
+import { JSONValue, ParseResult } from './types.js'
 
+export type TXType =
+  | 'initial_storage'
+  | 'interim_storage'
+  | 'interim_storages'
+  | 'initial_account'
+  | 'initial_account_txs'
+  | 'message'
+  | 'inherit_message'
+  | 'inherit_message_recv'
+  | 'transfer'
+  | 'transfer_Cancel'
+  | 'transfer_sent'
+  | 'transfer_receive_delete'
+  | 'transfer_info'
+  | 'storage'
+  | 'storage_delete'
+  | 'backup'
+  | 'interim_message'
+  | 'fs_virt'
+  | 'fs_real'
+  | 'fs_rvirt'
+  | 'fs_rreal'
+  | 'fs_dvirt'
+  | 'fs_dreal'
+  | 'fs_pvirt'
+  | 'request'
+  | 'request_in'
+  | 'request_upload'
+  | 'request_Cancel'
+  | 'data_room'
+  | 'data_roomF'
+  | 'data_room_policy'
+  | 'data_room_data'
+  | 'data_room_data_delete'
+  | 'data_room_data_policy'
+  | 'data_roomE'
+  | 'data_roomE_data'
+  | 'multi_data_room'
+  | 'multi_storage'
+  | 'multi_transfer'
+  | 'multi_transfer_sent'
+  | 'multi_backup'
+  | 'multi_passwd'
+  | 'multi_collection'
+  | 'multi_dataV2'
+  | 'passwd_data'
+  | 'passwd_room'
+  | 'passwd_roomF'
+  | 'passwd_room_policy'
+  | 'passwd_room_data'
+  | 'passwd_room_data_delete'
+  | 'passwd_room_data_policy'
+  | 'datav2'
+  | 'datav2_policy'
+  | 'coll'
+  | 'coll_policy'
+  | 'datav2_coll'
+  | 'datav2F'
+
+export declare const TX_TYPE_MASTER: 'initial_storage',
+  TX_TYPE_ADDRESS: 'interim_storage',
+  TX_TYPE_ADDRESSES: 'interim_storages',
+  TX_TYPE_ACCOUNT: 'initial_account',
+  TX_TYPE_ACCOUNT_INITIAL_TXS: 'initial_account_txs',
+  TX_TYPE_MESSAGE: 'message',
+  TX_TYPE_MESSAGE_SENT: 'inherit_message',
+  TX_TYPE_MESSAGE_THREAD_DELETE: 'inherit_message_recv',
+  TX_TYPE_TRANSFER: 'transfer',
+  TX_TYPE_TRANSFER_CANCEL: 'transfer_Cancel',
+  TX_TYPE_TRANSFER_SENT: 'transfer_sent',
+  TX_TYPE_TRANSFER_RECEIVE_DELETE: 'transfer_receive_delete',
+  TX_TYPE_TRANSFER_INFO: 'transfer_info',
+  TX_TYPE_STORAGE: 'storage',
+  TX_TYPE_STORAGE_DELETE: 'storage_delete',
+  TX_TYPE_BACKUP: 'backup',
+  TX_TYPE_CONTACT: 'interim_message',
+  TX_TYPE_FILE_VIRTUAL: 'fs_virt',
+  TX_TYPE_FILE_FS: 'fs_real',
+  TX_TYPE_RFILE_VIRTUAL: 'fs_rvirt',
+  TX_TYPE_RFILE_FS: 'fs_rreal',
+  TX_TYPE_DFILE_VIRTUAL: 'fs_dvirt',
+  TX_TYPE_DFILE_FS: 'fs_dreal',
+  TX_TYPE_PFILE_VIRTUAL: 'fs_pvirt',
+  TX_TYPE_REQUEST: 'request',
+  TX_TYPE_REQUEST_IN: 'request_in',
+  TX_TYPE_REQUEST_UPLOAD: 'request_upload',
+  TX_TYPE_REQUEST_CANCEL: 'request_Cancel',
+  TX_TYPE_DATA_ROOM: 'data_room',
+  TX_TYPE_DATA_ROOMF: 'data_roomF',
+  TX_TYPE_DATA_ROOM_POLICY: 'data_room_policy',
+  TX_TYPE_DATA_ROOM_DATA: 'data_room_data',
+  TX_TYPE_DATA_ROOM_DATA_DELETE: 'data_room_data_delete',
+  TX_TYPE_DATA_ROOM_DATA_POLICY: 'data_room_data_policy',
+  TX_TYPE_DATA_ROOME: 'data_roomE',
+  TX_TYPE_DATA_ROOME_DATA: 'data_roomE_data',
+  TX_TYPE_MULTI_DATA_ROOM: 'multi_data_room',
+  TX_TYPE_MULTI_STORAGE: 'multi_storage',
+  TX_TYPE_MULTI_TRANSFER: 'multi_transfer',
+  TX_TYPE_MULTI_TRANSFER_SENT: 'multi_transfer_sent',
+  TX_TYPE_MULTI_BACKUP: 'multi_backup',
+  TX_TYPE_MULTI_PASSWD: 'multi_passwd',
+  TX_TYPE_MULTI_COLLECTION: 'multi_collection',
+  TX_TYPE_MULTI_DATAV2: 'multi_dataV2',
+  TX_TYPE_PASSWD_DATA: 'passwd_data',
+  TX_TYPE_PASSWD_ROOM: 'passwd_room',
+  TX_TYPE_PASSWD_ROOMF: 'passwd_roomF',
+  TX_TYPE_PASSWD_ROOM_POLICY: 'passwd_room_policy',
+  TX_TYPE_PASSWD_ROOM_DATA: 'passwd_room_data',
+  TX_TYPE_PASSWD_ROOM_DATA_DELETE: 'passwd_room_data_delete',
+  TX_TYPE_PASSWD_ROOM_DATA_POLICY: 'passwd_room_data_policy',
+  TX_TYPE_DATAV2: 'datav2',
+  TX_TYPE_DATAV2_POLICY: 'datav2_policy',
+  TX_TYPE_COLLECTION: 'coll',
+  TX_TYPE_COLLECTION_POLICY: 'coll_policy',
+  TX_TYPE_DATAV2_COLLECTION: 'datav2_coll',
+  TX_TYPE_DATAV2F: 'datav2F',
+  TX_TYPE_LIST: readonly TXType[]
+
+export interface TransactionInput {
+  id: string
+  height: number
+  version: number
+  typ: TXType
+  sender_addr: string
+  recipient_addr: string
+  data: JSONValue
+  sign: string
+  fee: number
+  hash?: string
+  /** Date text/RFC3339Nano, Unix milliseconds or a caller-owned Date. */
+  inserted_at?: string | number | Date
+  additionalData?: JSONValue
+  cipherData?: JSONValue
+  chainName?: string
+  chainVersion?: string
+}
+
+/** Factory results and their JSON data are immutable snapshots. */
 export declare class Transaction {
-  constructor({
-    id,
-    height,
-    version,
-    typ,
-    sender_addr,
-    recipient_addr,
-    data,
-    sign,
-    fee,
-    hash,
-    inserted_at,
-    additionalData,
-    cipherData,
-    chainName,
-    chainVersion
-  }?: Record<string, any>)
-  get Order(): number
+  constructor(input?: Partial<TransactionInput>)
+
+  get Order(): number | undefined
+
   get ID(): string
+
   get Height(): number
+
   get Version(): number
+
   get Typ(): TXType
+
   get SenderAddr(): string
+
   get RecipientAddr(): string
-  get Data(): string
-  get AdditionalData(): string
-  get CipherData(): string
+
+  get Data(): JSONValue
+
+  get AdditionalData(): JSONValue | undefined
+
+  get CipherData(): JSONValue | undefined
+
   get Sign(): string
+
   get Fee(): number
-  get Hash(): string
-  get InsertedAt(): Date
-  get ChainName(): string
-  get ChainVersion(): string
-  static FromJSON(value: string): { transaction?: Transaction; error?: Error }
-  static FromObject(obj: Record<string, any>): {
-    transaction?: Transaction
-    error?: Error
-  }
+
+  get Hash(): string | undefined
+
+  /** Returns a detached Date; mutating it never changes the transaction. */
+  get InsertedAt(): Date | undefined
+
+  get ChainName(): string | undefined
+
+  get ChainVersion(): string | undefined
+
+  static FromJSON(
+    value: string
+  ): ParseResult<'transaction', Readonly<Transaction>>
+
+  static FromObject(
+    obj: Record<string, unknown>
+  ): ParseResult<'transaction', Readonly<Transaction>>
+
+  Validate(): void
+
   ToJSON(): string
-  ToObject(): Record<string, any>
+
+  ToObject(): Readonly<Record<string, JSONValue>>
 }