@transia/isomorphic 1.0.1

package/src/utils/index.ts

@@ -0,0 +1,93 @@
+import { randomBytes as cryptoRandomBytes } from 'crypto'
+import type { BytesToHexFn, HexToBytesFn, RandomBytesFn } from './types'
+import { HexToStringFn, StringToHexFn } from './types'
+import { HEX_REGEX } from './shared'
+
+const OriginalBuffer = Symbol('OriginalBuffer')
+
+/**
+ * An extended Uint8Array that incorporates a reference to the original Node.js Buffer.
+ *
+ * When converting a Node.js Buffer to a Uint8Array, there's an optimization that shares
+ * the memory of the original Buffer with the resulting Uint8Array instead of copying data.
+ * The Uint8ArrayWithReference interface is used to attach a reference to the original Buffer, ensuring
+ * its persistence in memory (preventing garbage collection) as long as the Uint8Array exists.
+ * This strategy upholds the ownership semantics of the slice of the ArrayBuffer.
+ */
+interface Uint8ArrayWithReference extends Uint8Array {
+  [OriginalBuffer]: Buffer
+}
+
+/**
+ * Converts a Node.js Buffer to a Uint8Array for uniform behavior with browser implementations.
+ *
+ * Choices:
+ * 1. Directly returning the Buffer:
+ *    - Operation: Return Buffer as is (a Buffer *IS* an instanceof Uint8Array).
+ *    - Pros: Most memory and performance efficient.
+ *    - Cons: Violates strict Uint8Array typing and may lead to issues where Buffer-specific features are [ab]used.
+ *
+ * 2. Using `new Uint8Array(buffer)` or `Uint8Array.from(buffer)`:
+ *    - Operation: Copies the buffer's data into a new Uint8Array.
+ *    - Pros: Ensures data isolation; memory-safe.
+ *    - Cons: Less performant due to data duplication.
+ *
+ * 3. Using buf.buffer slice:
+ *    - Operation: Shares memory between Buffer and Uint8Array.
+ *    - Pros: Performant.
+ *    - Cons: Risks with shared memory and potential for invalid references.
+ *
+ * 4. Using buf.buffer slice and keeping a Buffer reference for ownership semantics:
+ *    - Operation: Shares memory and associates the original Buffer with the resulting Uint8Array.
+ *    - Pros: Performant while ensuring the original Buffer isn't garbage collected.
+ *    - Cons: Risks with shared memory but mitigates potential for invalid references.
+ *
+ * The chosen method (4) prioritizes performance by sharing memory while ensuring buffer ownership.
+ *
+ * @param {Buffer} buffer - The Node.js Buffer to convert.
+ * @returns {Uint8Array} Resulting Uint8Array sharing the same memory as the Buffer and maintaining a reference to it.
+ */
+function toUint8Array(buffer: Buffer): Uint8Array {
+  const u8Array = new Uint8Array(
+    buffer.buffer.slice(
+      buffer.byteOffset,
+      buffer.byteOffset + buffer.byteLength,
+    ),
+  ) as Uint8ArrayWithReference
+  u8Array[OriginalBuffer] = buffer
+  return u8Array
+}
+
+/* eslint-disable func-style -- Typed to ensure uniformity between node and browser implementations and docs */
+export const bytesToHex: typeof BytesToHexFn = (bytes) => {
+  const buf = Buffer.from(bytes)
+  return buf.toString('hex').toUpperCase()
+}
+
+export const hexToBytes: typeof HexToBytesFn = (hex) => {
+  if (!HEX_REGEX.test(hex)) {
+    throw new Error('Invalid hex string')
+  }
+  return toUint8Array(Buffer.from(hex, 'hex'))
+}
+
+export const randomBytes: typeof RandomBytesFn = (size) => {
+  return toUint8Array(cryptoRandomBytes(size))
+}
+
+export const hexToString: typeof HexToStringFn = (
+  hex: string,
+  encoding = 'utf8',
+): string => {
+  if (!HEX_REGEX.test(hex)) {
+    throw new Error('Invalid hex string')
+  }
+  return new TextDecoder(encoding).decode(hexToBytes(hex))
+}
+
+export const stringToHex: typeof StringToHexFn = (string: string): string => {
+  return bytesToHex(new TextEncoder().encode(string))
+}
+/* eslint-enable func-style */
+
+export * from './shared'

package/src/utils/shared.ts

@@ -0,0 +1,21 @@
+import { concatBytes } from '@noble/hashes/utils'
+
+export const HEX_REGEX = /^[A-F0-9]*$/iu
+
+export function concat(views: Uint8Array[]): Uint8Array {
+  return concatBytes(...views)
+}
+
+export function equal(buf1: Uint8Array, buf2: Uint8Array): boolean {
+  if (buf1.byteLength !== buf2.byteLength) {
+    return false
+  }
+  const dv1 = new Int8Array(buf1)
+  const dv2 = new Int8Array(buf2)
+  for (let i = 0; i !== buf1.byteLength; i++) {
+    if (dv1[i] !== dv2[i]) {
+      return false
+    }
+  }
+  return true
+}

package/src/utils/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Convert a UInt8Array to hex. The returned hex will be in all caps.
+ *
+ * @param bytes - {Uint8Array} to convert to hex
+ */
+export declare function BytesToHexFn(bytes: Uint8Array | number[]): string
+
+/**
+ * Convert hex to a Uint8Array.
+ *
+ * @param hex - {string} to convert to a Uint8Array
+ */
+export declare function HexToBytesFn(hex: string): Uint8Array
+
+/**
+ * Create a Uint8Array of the supplied size.
+ *
+ * @param size - number of bytes to generate
+ */
+export declare function RandomBytesFn(size: number): Uint8Array
+
+/**
+ * Converts hex to its string equivalent. Useful to read the Domain field and some Memos.
+ *
+ * @param hex - The hex to convert to a string.
+ * @param encoding - The encoding to use. Defaults to 'utf8' (UTF-8). 'ascii' is also allowed.
+ * @returns The converted string.
+ */
+export declare function HexToStringFn(hex: string, encoding?: string): string
+
+/**
+ * Converts a utf-8 to its hex equivalent. Useful for Memos.
+ *
+ * @param string - The string to convert to Hex.
+ * @returns The Hex equivalent of the string.
+ */
+export declare function StringToHexFn(string: string): string

package/src/ws/browser.ts

@@ -0,0 +1,105 @@
+/* eslint-disable max-classes-per-file -- Needs to be a wrapper for ws */
+import { EventEmitter } from 'eventemitter3'
+
+// Define the global WebSocket class found on the native browser
+declare class WebSocket {
+  public onclose?: (closeEvent: CloseEvent) => void
+  public onopen?: (openEvent: Event) => void
+  public onerror?: (error: Error) => void
+  public onmessage?: (message: MessageEvent) => void
+  public readyState: number
+  public constructor(url: string)
+  public close(code?: number, reason?: Uint8Array): void
+  public send(message: string): void
+}
+
+interface WSWrapperOptions {
+  perMessageDeflate: boolean
+  handshakeTimeout: number
+  protocolVersion: number
+  origin: string
+  maxPayload: number
+  followRedirects: boolean
+  maxRedirects: number
+}
+
+/**
+ * Provides `EventEmitter` interface for native browser `WebSocket`,
+ * same, as `ws` package provides.
+ */
+export default class WSWrapper extends EventEmitter {
+  public static CONNECTING = 0
+  public static OPEN = 1
+  public static CLOSING = 2
+
+  public static CLOSED = 3
+  private readonly ws: WebSocket
+
+  /**
+   * Constructs a browser-safe websocket.
+   *
+   * @param url - URL to connect to.
+   * @param _protocols - Not used.
+   * @param _websocketOptions - Not used.
+   */
+  public constructor(
+    url: string,
+    _protocols: string | string[] | WSWrapperOptions | undefined,
+    _websocketOptions: WSWrapperOptions,
+  ) {
+    super()
+
+    this.ws = new WebSocket(url)
+
+    this.ws.onclose = (closeEvent: CloseEvent): void => {
+      let reason: Uint8Array | undefined
+      if (closeEvent.reason) {
+        const enc = new TextEncoder()
+        reason = enc.encode(closeEvent.reason)
+      }
+      this.emit('close', closeEvent.code, reason)
+    }
+
+    this.ws.onopen = (): void => {
+      this.emit('open')
+    }
+
+    this.ws.onerror = (error): void => {
+      this.emit('error', error)
+    }
+
+    this.ws.onmessage = (message: MessageEvent): void => {
+      this.emit('message', message.data)
+    }
+  }
+
+  /**
+   * Get the ready state of the websocket.
+   *
+   * @returns The Websocket's ready state.
+   */
+  public get readyState(): number {
+    return this.ws.readyState
+  }
+
+  /**
+   * Closes the websocket.
+   *
+   * @param code - Close code.
+   * @param reason - Close reason.
+   */
+  public close(code?: number, reason?: Buffer): void {
+    if (this.readyState === 1) {
+      this.ws.close(code, reason)
+    }
+  }
+
+  /**
+   * Sends a message over the Websocket connection.
+   *
+   * @param message - Message to send.
+   */
+  public send(message: string): void {
+    this.ws.send(message)
+  }
+}

package/src/ws/index.ts

@@ -0,0 +1,10 @@
+import WebSocket from 'ws'
+
+export default class Socket extends WebSocket {
+  constructor(...args) {
+    super(args[0], args[1], args[2])
+    this.setMaxListeners(Infinity)
+  }
+}
+
+export type ClientOptions = WebSocket.ClientOptions

package/utils/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@xrplf/isomorphic/utils",
+  "private": true,
+  "main": "../dist/utils",
+  "types": "../dist/utils",
+  "browser": "../dist/utils/browser.js"
+}

package/ws/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@xrplf/isomorphic/ws",
+  "private": true,
+  "main": "../dist/ws",
+  "types": "../dist/ws",
+  "browser": "../dist/ws/browser.js",
+  "dependencies": {
+    "ws": "^8.13.0",
+    "eventemitter3": "^5.0.1"
+  }
+}