@nktkas/hyperliquid 0.30.3 → 0.32.0

package/src/transport/websocket/_subscriptionManager.ts

@@ -0,0 +1,194 @@
+import type { ReconnectingWebSocket } from "@nktkas/rews";
+import type { ISubscription } from "../_base.js";
+import type { HyperliquidEventTarget } from "./_hyperliquidEventTarget.js";
+import { WebSocketPostRequest, WebSocketRequestError } from "./_postRequest.js";
+
+/** Internal state for managing a subscription. */
+interface SubscriptionState {
+  /** Map of event listeners to their unsubscribe functions. */
+  listeners: Map<(data: CustomEvent) => void, () => Promise<void>>;
+  /** Promise tracking the subscription request. */
+  promise: Promise<unknown>;
+  /** Whether the subscription request has completed. */
+  promiseFinished: boolean;
+  /** Controller to signal subscription failure. */
+  failureController: AbortController;
+}
+
+/** Maximum number of subscriptions allowed by Hyperliquid. */
+const MAX_SUBSCRIPTIONS = 1000;
+
+/** Maximum number of unique user subscriptions allowed by Hyperliquid. */
+const MAX_UNIQUE_USER_SUBSCRIPTIONS = 10;
+
+/**
+ * Manages WebSocket subscriptions to Hyperliquid event channels.
+ * Handles subscription lifecycle, resubscription on reconnect, and cleanup.
+ */
+export class WebSocketSubscriptionManager {
+  /** Enable automatic re-subscription to Hyperliquid subscription after reconnection. */
+  resubscribe: boolean;
+
+  protected readonly _socket: ReconnectingWebSocket;
+  protected readonly _postRequest: WebSocketPostRequest;
+  protected readonly _hlEvents: HyperliquidEventTarget;
+  protected _subscriptions: Map<string, SubscriptionState> = new Map();
+
+  constructor(
+    socket: ReconnectingWebSocket,
+    postRequest: WebSocketPostRequest,
+    hlEvents: HyperliquidEventTarget,
+    resubscribe: boolean,
+  ) {
+    this._socket = socket;
+    this._postRequest = postRequest;
+    this._hlEvents = hlEvents;
+    this.resubscribe = resubscribe;
+
+    // Subscribe to socket events
+    socket.addEventListener("open", () => this._handleOpen());
+    socket.addEventListener("close", () => this._handleClose());
+    socket.addEventListener("error", () => this._handleClose());
+  }
+
+  // ============================================================
+  // Public methods
+  // ============================================================
+
+  /**
+   * Subscribes to a Hyperliquid event channel.
+   * Sends a subscription request to the server and listens for events.
+   *
+   * @param channel The event channel to listen to.
+   * @param payload A payload to send with the subscription request.
+   * @param listener A function to call when the event is dispatched.
+   * @return A promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+   *
+   * @throws {WebSocketRequestError} An error that occurs when a WebSocket request fails.
+   */
+  async subscribe<T>(
+    channel: string,
+    payload: unknown,
+    listener: (data: CustomEvent<T>) => void,
+  ): Promise<ISubscription> {
+    // Create a unique identifier for the subscription
+    const id = WebSocketPostRequest.requestToId(payload);
+
+    // Initialize new subscription, if it doesn't exist
+    let subscription = this._subscriptions.get(id);
+    if (!subscription) {
+      // Check unique subscription limits
+      if (this._subscriptions.size >= MAX_SUBSCRIPTIONS) {
+        throw new WebSocketRequestError("Cannot subscribe to more than 1000 channels");
+      }
+      // Check unique user subscription limits
+      if (this._hasUserParam(payload) && this._countUniqueUserSubscriptions() >= MAX_UNIQUE_USER_SUBSCRIPTIONS) {
+        throw new WebSocketRequestError("Cannot track more than 10 unique users");
+      }
+
+      // Send subscription request
+      const promise = this._postRequest.request("subscribe", payload)
+        .finally(() => subscription!.promiseFinished = true);
+
+      // Cache subscription info
+      subscription = {
+        listeners: new Map(),
+        promise,
+        promiseFinished: false,
+        failureController: new AbortController(),
+      };
+      this._subscriptions.set(id, subscription);
+    }
+
+    // Initialize new listener, if it doesn't exist
+    let unsubscribe = subscription.listeners.get(listener);
+    if (!unsubscribe) {
+      // Create new unsubscribe function
+      unsubscribe = async () => {
+        // Remove listener and cleanup
+        this._hlEvents.removeEventListener(channel, listener);
+        const subscription = this._subscriptions.get(id);
+        subscription?.listeners.delete(listener);
+
+        // If no listeners remain, remove subscription entirely
+        if (subscription?.listeners.size === 0) {
+          // Cleanup subscription
+          this._subscriptions.delete(id);
+
+          // If the socket is open, send unsubscription request
+          if (this._socket.readyState === 1) { // OPEN
+            await this._postRequest.request("unsubscribe", payload);
+          }
+        }
+      };
+
+      // Add listener and cache unsubscribe function
+      this._hlEvents.addEventListener(channel, listener);
+      subscription.listeners.set(listener, unsubscribe);
+    }
+
+    // Wait for the initial subscription request to complete
+    await subscription.promise;
+
+    // Return subscription control object
+    return {
+      unsubscribe,
+      failureSignal: subscription.failureController.signal,
+    };
+  }
+
+  // ============================================================
+  // Socket event handlers
+  // ============================================================
+
+  /** Resubscribes to all existing subscriptions if auto-resubscribe is enabled. */
+  protected _handleOpen(): void {
+    if (this.resubscribe) {
+      for (const [id, subscription] of this._subscriptions.entries()) {
+        // Reconnect only previously connected subscriptions to avoid double subscriptions due to message buffering
+        if (subscription.promiseFinished) {
+          subscription.promise = this._postRequest.request("subscribe", JSON.parse(id))
+            .catch((error) => subscription.failureController.abort(error))
+            .finally(() => subscription.promiseFinished = true);
+          subscription.promiseFinished = false;
+        }
+      }
+    }
+  }
+
+  /** Cleans up subscriptions if resubscribe is disabled or socket is terminated. */
+  protected _handleClose(): void {
+    if (!this.resubscribe || this._socket.terminationSignal.aborted) {
+      for (const subscriptionInfo of this._subscriptions.values()) {
+        for (const [_, unsubscribe] of subscriptionInfo.listeners) {
+          unsubscribe(); // does not cause an error if used when the connection is closed
+        }
+      }
+    }
+  }
+
+  // ============================================================
+  // Subscription limit checks
+  // ============================================================
+
+  /** Checks if a payload contains a user parameter. */
+  protected _hasUserParam(payload: unknown): boolean {
+    return typeof payload === "object" && payload !== null && "user" in payload;
+  }
+
+  /** Counts the number of unique users across all active subscriptions. */
+  protected _countUniqueUserSubscriptions(): number {
+    const users = new Set<string>();
+    for (const id of this._subscriptions.keys()) {
+      try {
+        const payload = JSON.parse(id);
+        if (this._hasUserParam(payload)) {
+          users.add(payload.user);
+        }
+      } catch {
+        // Ignore parsing errors
+      }
+    }
+    return users.size;
+  }
+}

package/src/transport/websocket/mod.ts

@@ -0,0 +1,278 @@
+/**
+ * WebSocket transport for {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions | subscriptions} and {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests | POST requests}.
+ *
+ * Use {@link WebSocketTransport} for real-time subscriptions and for lower-latency API requests.
+ *
+ * @example Subscriptions
+ * ```ts
+ * import { SubscriptionClient, WebSocketTransport } from "@nktkas/hyperliquid";
+ *
+ * const transport = new WebSocketTransport();
+ * const client = new SubscriptionClient({ transport });
+ *
+ * const subscription = await client.allMids((data) => {
+ *   console.log(data.mids);
+ * });
+ *
+ * await subscription.unsubscribe();
+ * ```
+ *
+ * @module
+ */
+
+import { ReconnectingWebSocket, type ReconnectingWebSocketOptions } from "@nktkas/rews";
+import type { IRequestTransport, ISubscription, ISubscriptionTransport } from "../_base.js";
+import { AbortSignal_ } from "../_polyfills.js";
+import { HyperliquidEventTarget } from "./_hyperliquidEventTarget.js";
+import { WebSocketPostRequest, WebSocketRequestError } from "./_postRequest.js";
+import { WebSocketSubscriptionManager } from "./_subscriptionManager.js";
+
+export { WebSocketRequestError };
+
+/** Configuration options for the WebSocket transport layer. */
+export interface WebSocketTransportOptions {
+  /**
+   * Indicates this transport uses testnet endpoint.
+   *
+   * Default: `false`
+   */
+  isTestnet?: boolean;
+  /**
+   * Custom WebSocket endpoint for API and Subscription requests.
+   * - Mainnet:
+   *   - API: `wss://api.hyperliquid.xyz/ws`
+   *   - Explorer: `wss://rpc.hyperliquid.xyz/ws`
+   * - Testnet:
+   *   - API: `wss://api.hyperliquid-testnet.xyz/ws`
+   *   - Explorer: `wss://rpc.hyperliquid-testnet.xyz/ws`
+   *
+   * Default: `wss://api.hyperliquid.xyz/ws` for mainnet, `wss://api.hyperliquid-testnet.xyz/ws` for testnet
+   */
+  url?: string | URL;
+  /**
+   * Timeout for requests in ms. Set to `null` to disable.
+   *
+   * Default: `10_000`
+   */
+  timeout?: number | null;
+  /** Reconnection policy configuration for closed connections. */
+  reconnect?: ReconnectingWebSocketOptions;
+  /**
+   * Enable automatic re-subscription to Hyperliquid subscription after reconnection.
+   *
+   * Default: `true`
+   */
+  resubscribe?: boolean;
+}
+
+/** Mainnet API WebSocket URL. */
+export const MAINNET_API_WS_URL = "wss://api.hyperliquid.xyz/ws";
+/** Testnet API WebSocket URL. */
+export const TESTNET_API_WS_URL = "wss://api.hyperliquid-testnet.xyz/ws";
+/** Mainnet RPC WebSocket URL. */
+export const MAINNET_RPC_WS_URL = "wss://rpc.hyperliquid.xyz/ws";
+/** Testnet RPC WebSocket URL. */
+export const TESTNET_RPC_WS_URL = "wss://rpc.hyperliquid-testnet.xyz/ws";
+
+/**
+ * WebSocket transport for Hyperliquid API.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests
+ */
+export class WebSocketTransport implements IRequestTransport, ISubscriptionTransport {
+  /** Indicates this transport uses testnet endpoint. */
+  readonly isTestnet: boolean;
+  /** The WebSocket that is used for communication. */
+  readonly socket: ReconnectingWebSocket;
+  /** Enable automatic re-subscription to Hyperliquid subscription after reconnection. */
+  get resubscribe(): boolean {
+    return this._subscriptionManager.resubscribe;
+  }
+  set resubscribe(value: boolean) {
+    this._subscriptionManager.resubscribe = value;
+  }
+  /** Timeout for requests in ms. Set to `null` to disable. */
+  get timeout(): number | null {
+    return this._postRequest.timeout;
+  }
+  set timeout(value: number | null) {
+    this._postRequest.timeout = value;
+  }
+
+  protected readonly _postRequest: WebSocketPostRequest;
+  protected readonly _hlEvents: HyperliquidEventTarget;
+  protected readonly _subscriptionManager: WebSocketSubscriptionManager;
+  protected _keepAliveInterval: ReturnType<typeof setInterval> | undefined;
+
+  /**
+   * Creates a new WebSocket transport instance.
+   *
+   * @param options Configuration options for the WebSocket transport layer.
+   */
+  constructor(options?: WebSocketTransportOptions) {
+    this.isTestnet = options?.isTestnet ?? false;
+
+    this.socket = new ReconnectingWebSocket(
+      options?.url ?? (this.isTestnet ? TESTNET_API_WS_URL : MAINNET_API_WS_URL),
+      options?.reconnect,
+    );
+
+    this._hlEvents = new HyperliquidEventTarget(this.socket);
+    this._postRequest = new WebSocketPostRequest(
+      this.socket,
+      this._hlEvents,
+      options?.timeout === undefined ? 10_000 : options.timeout,
+    );
+    this._subscriptionManager = new WebSocketSubscriptionManager(
+      this.socket,
+      this._postRequest,
+      this._hlEvents,
+      options?.resubscribe ?? true,
+    );
+
+    this._initKeepAlive();
+  }
+
+  // ============================================================
+  // Public methods
+  // ============================================================
+
+  /**
+   * Sends a request to the Hyperliquid API via WebSocket.
+   *
+   * @param endpoint The API endpoint to send the request to.
+   * @param payload The payload to send with the request.
+   * @param signal {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
+   * @return A promise that resolves with parsed JSON response body.
+   *
+   * @throws {WebSocketRequestError} An error that occurs when a WebSocket request fails.
+   */
+  async request<T>(endpoint: "info" | "exchange", payload: unknown, signal?: AbortSignal): Promise<T> {
+    const payload_ = { type: endpoint === "exchange" ? "action" : endpoint, payload };
+    return await this._postRequest.request<T>("post", payload_, signal);
+  }
+
+  /**
+   * Subscribes to a Hyperliquid event channel.
+   * Sends a subscription request to the server and listens for events.
+   *
+   * @param channel The event channel to listen to.
+   * @param payload A payload to send with the subscription request.
+   * @param listener A function to call when the event is dispatched.
+   * @return A promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+   *
+   * @throws {WebSocketRequestError} An error that occurs when a WebSocket request fails.
+   */
+  subscribe<T>(
+    channel: string,
+    payload: unknown,
+    listener: (data: CustomEvent<T>) => void,
+  ): Promise<ISubscription> {
+    return this._subscriptionManager.subscribe(channel, payload, listener);
+  }
+
+  /**
+   * Waits until the WebSocket connection is ready.
+   *
+   * @param signal {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the promise.
+   * @return A promise that resolves when the connection is ready.
+   *
+   * @throws {WebSocketRequestError} When the connection cannot be established.
+   */
+  ready(signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      // Combine the provided signal with the socket's termination signal
+      const combinedSignal = signal
+        ? AbortSignal_.any([this.socket.terminationSignal, signal])
+        : this.socket.terminationSignal;
+
+      // Check if already aborted
+      if (combinedSignal.aborted) {
+        return reject(
+          new WebSocketRequestError("Failed to establish WebSocket connection", { cause: combinedSignal.reason }),
+        );
+      }
+
+      // Check if already open
+      if (this.socket.readyState === ReconnectingWebSocket.OPEN) return resolve();
+
+      // Set up event listeners
+      const handleOpen = () => {
+        combinedSignal.removeEventListener("abort", handleAbort);
+        resolve();
+      };
+      const handleAbort = () => {
+        this.socket.removeEventListener("open", handleOpen);
+        return reject(
+          new WebSocketRequestError("Failed to establish WebSocket connection", { cause: combinedSignal.reason }),
+        );
+      };
+
+      this.socket.addEventListener("open", handleOpen, { once: true });
+      combinedSignal.addEventListener("abort", handleAbort, { once: true });
+    });
+  }
+
+  /**
+   * Closes the WebSocket connection and waits until it is fully closed.
+   *
+   * @param signal {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the promise.
+   * @return A promise that resolves when the connection is fully closed.
+   *
+   * @throws {WebSocketRequestError} When the connection cannot be closed.
+   */
+  close(signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      // Check if already aborted
+      if (signal?.aborted) {
+        return reject(
+          new WebSocketRequestError("Failed to close WebSocket connection", { cause: signal.reason }),
+        );
+      }
+
+      // Check if already closed
+      if (this.socket.readyState === ReconnectingWebSocket.CLOSED) return resolve();
+
+      // Set up event listeners
+      const handleClose = () => {
+        signal?.removeEventListener("abort", handleAbort);
+        resolve();
+      };
+      const handleAbort = () => {
+        return reject(
+          new WebSocketRequestError("Failed to close WebSocket connection", { cause: signal?.reason }),
+        );
+      };
+
+      this.socket.addEventListener("close", handleClose, { once: true, signal });
+      this.socket.addEventListener("error", handleClose, { once: true, signal });
+      signal?.addEventListener("abort", handleAbort, { once: true });
+
+      // Initiate close
+      this.socket.close();
+    });
+  }
+
+  // ============================================================
+  // Keep-Alive Logic
+  // ============================================================
+
+  protected _initKeepAlive(): void {
+    const start = () => {
+      if (this._keepAliveInterval) return;
+      this._keepAliveInterval = setInterval(() => {
+        this.socket.send('{"method":"ping"}');
+      }, 30_000);
+    };
+    const stop = () => {
+      clearInterval(this._keepAliveInterval);
+      this._keepAliveInterval = undefined;
+    };
+
+    this.socket.addEventListener("open", start);
+    this.socket.addEventListener("close", stop);
+    this.socket.addEventListener("error", stop);
+  }
+}

package/src/utils/_format.ts

@@ -0,0 +1,196 @@
+/**
+ * Format price according to Hyperliquid {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size | rules}:
+ * - Maximum 5 significant figures
+ * - Maximum 6 (for perp) or 8 (for spot) - `szDecimals` decimal places
+ * - Integer prices are always allowed regardless of significant figures
+ *
+ * @param price The price to format (as string or number).
+ * @param szDecimals The size decimals of the asset.
+ * @param type The market type: "perp" for perpetuals or "spot" for spot markets. Default: `"perp"`.
+ * @return Formatted price string
+ *
+ * @throws {TypeError} If price is not a valid number string
+ * @throws {RangeError} If the formatted price is 0
+ *
+ * @example
+ * ```ts
+ * import { formatPrice } from "@nktkas/hyperliquid/utils";
+ * const price = formatPrice("0.0000123456789", 0, "spot"); // → "0.00001234"
+ * ```
+ */
+export function formatPrice(price: string | number, szDecimals: number, type: "perp" | "spot" = "perp"): string {
+  price = price.toString().trim();
+  assertNumberString(price);
+
+  // Integer prices are always allowed
+  if (/^-?\d+$/.test(price)) return formatDecimalString(price);
+
+  // Apply decimal limit: max 6 (perp) or 8 (spot) - szDecimals
+  const maxDecimals = Math.max((type === "perp" ? 6 : 8) - szDecimals, 0);
+  price = StringMath.toFixedTruncate(price, maxDecimals);
+
+  // Apply sig figs limit: max 5 significant figures
+  price = StringMath.toPrecisionTruncate(price, 5);
+
+  if (price === "0") {
+    throw new RangeError("Price is too small and was truncated to 0");
+  }
+
+  return price;
+}
+
+/**
+ * Format size according to Hyperliquid {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size | rules}:
+ * - Truncate decimal places to `szDecimals`
+ *
+ * @param size The size to format (as string or number).
+ * @param szDecimals The size decimals of the asset.
+ * @return Formatted size string
+ *
+ * @throws {TypeError} If size is not a valid number string
+ * @throws {RangeError} If the formatted size is 0
+ *
+ * @example
+ * ```ts
+ * import { formatSize } from "@nktkas/hyperliquid/utils";
+ *
+ * const size = formatSize("1.23456789", 5); // → "1.23456"
+ * ```
+ */
+export function formatSize(size: string | number, szDecimals: number): string {
+  size = size.toString().trim();
+  assertNumberString(size);
+
+  // Apply decimal limit: szDecimals
+  size = StringMath.toFixedTruncate(size, szDecimals);
+
+  if (size === "0") {
+    throw new RangeError("Size is too small and was truncated to 0");
+  }
+
+  return size;
+}
+
+/** String-based Math operations for arbitrary precision. */
+const StringMath = {
+  /** Floor log10 (magnitude): position of most significant digit. */
+  log10Floor(value: string): number {
+    const abs = value[0] === "-" ? value.slice(1) : value;
+
+    // Check if zero or invalid
+    const num = Number(abs);
+    if (num === 0 || isNaN(num)) return -Infinity;
+
+    const [int, dec] = abs.split(".");
+
+    // Number >= 1: magnitude = length of integer part - 1
+    if (Number(int) !== 0) {
+      const trimmed = int.replace(/^0+/, "");
+      return trimmed.length - 1;
+    }
+
+    // Number < 1: count leading zeros in decimal part
+    const leadingZeros = dec.match(/^0*/)?.[0].length ?? 0;
+    return -(leadingZeros + 1);
+  },
+
+  /** Multiply by 10^exp: shift decimal point left (negative) or right (positive). */
+  multiplyByPow10(value: string, exp: number): string {
+    if (!Number.isInteger(exp)) throw new RangeError("Exponent must be an integer");
+    if (exp === 0) return formatDecimalString(value);
+
+    const neg = value[0] === "-";
+    const abs = neg ? value.slice(1) : value;
+    const [intRaw, dec = ""] = abs.split(".");
+    // Normalize empty integer part to "0" (handles ".5" → "0.5")
+    const int = intRaw || "0";
+
+    let result: string;
+
+    if (exp > 0) {
+      // Shift right: move digits from decimal to integer
+      if (exp >= dec.length) {
+        result = int + dec + "0".repeat(exp - dec.length);
+      } else {
+        result = int + dec.slice(0, exp) + "." + dec.slice(exp);
+      }
+    } else {
+      // Shift left: move digits from integer to decimal
+      const absExp = -exp;
+      if (absExp >= int.length) {
+        result = "0." + "0".repeat(absExp - int.length) + int + dec;
+      } else {
+        result = int.slice(0, -absExp) + "." + int.slice(-absExp) + dec;
+      }
+    }
+
+    return formatDecimalString((neg ? "-" : "") + result);
+  },
+
+  /** Returns the integer part of a number by removing any fractional digits. */
+  trunc(value: string): string {
+    const dotIndex = value.indexOf(".");
+    return dotIndex === -1 ? value : value.slice(0, dotIndex) || "0";
+  },
+
+  /** Truncate to a certain number of significant figures. */
+  toPrecisionTruncate(value: string, precision: number): string {
+    if (!Number.isInteger(precision)) throw new RangeError("Precision must be an integer");
+    if (precision < 1) throw new RangeError("Precision must be positive");
+    if (/^-?0+(\.0*)?$/.test(value)) return "0"; // zero is special case (don't work with log10)
+
+    const neg = value[0] === "-";
+    const abs = neg ? value.slice(1) : value;
+
+    // Calculate how much to shift: align most significant digit to ones place + (maxSigFigs-1)
+    const magnitude = StringMath.log10Floor(abs);
+    const shiftAmount = precision - magnitude - 1;
+
+    // Shift right, truncate integer part, shift back
+    const shifted = StringMath.multiplyByPow10(abs, shiftAmount);
+    const truncated = StringMath.trunc(shifted);
+    const result = StringMath.multiplyByPow10(truncated, -shiftAmount);
+
+    // Build final result and trim zeros
+    return formatDecimalString(neg ? "-" + result : result);
+  },
+
+  /** Truncate to a certain number of decimal places. */
+  toFixedTruncate(value: string, decimals: number): string {
+    if (!Number.isInteger(decimals)) throw new RangeError("Decimals must be an integer");
+    if (decimals < 0) throw new RangeError("Decimals must be non-negative");
+
+    // Match number with up to `decimals` decimal places
+    const regex = new RegExp(`^-?(?:\\d+)?(?:\\.\\d{0,${decimals}})?`);
+    const result = value.match(regex)?.[0];
+
+    if (!result) {
+      throw new TypeError("Invalid number format");
+    }
+
+    // Trim zeros after truncation
+    return formatDecimalString(result);
+  },
+};
+
+function formatDecimalString(value: string): string {
+  return value
+    // remove leading/trailing whitespace
+    .trim() // "  123.45  " → "123.45"
+    // remove leading zeros
+    .replace(/^(-?)0+(?=\d)/, "$1") // "00123" → "123", "-00.5" → "-0.5"
+    // remove trailing zeros
+    .replace(/\.0*$|(\.\d+?)0+$/, "$1") // "1.2000" → "1.2", "5.0" → "5"
+    // add leading zero if starts with decimal point
+    .replace(/^(-?)\./, "$10.") // ".5" → "0.5", "-.5" → "-0.5"
+    // add "0" if string is empty after trimming
+    .replace(/^-?$/, "0") // "" → "0", "-" → "0"
+    // normalize negative zero
+    .replace(/^-0$/, "0"); // "-0" → "0"
+}
+
+function assertNumberString(value: string): void {
+  if (!/^-?(\d+\.?\d*|\.\d*)$/.test(value)) {
+    throw new TypeError("Invalid number format");
+  }
+}