@nktkas/hyperliquid 0.25.7 → 0.25.9

package/src/src/api/info/userFees.ts

@@ -225,7 +225,52 @@ export const UserFeesResponse = /* @__PURE__ */ (() => {
         v.nullable(v.unknown()),
         v.description("Timestamp when next trial becomes available."),
       ),
-      stakingLink: v.nullable(v.unknown()),
+      /**
+       * Permanent link between staking and trading accounts.
+       * Staking user gains full control of trading account funds.
+       * Staking user forfeits own fee discounts.
+       */
+      stakingLink: v.pipe(
+        v.nullable(
+          v.object({
+            /**
+             * Linked account address:
+             * - When queried by staking account: contains trading account address.
+             * - When queried by trading account: contains staking account address.
+             */
+            stakingUser: v.pipe(
+              Address,
+              v.description(
+                "Linked account address:" +
+                  "\n- When queried by staking account: contains trading account address." +
+                  "\n- When queried by trading account: contains staking account address.",
+              ),
+            ),
+            /**
+             * Link status:
+             * - `requested` = link initiated by trading user, awaiting staking user confirmation.
+             * - `stakingUser` = response queried by staking account.
+             * - `tradingUser` = response queried by trading account.
+             */
+            type: v.pipe(
+              v.union([
+                v.literal("requested"),
+                v.literal("stakingUser"),
+                v.literal("tradingUser"),
+              ]),
+              v.description(
+                "Link status:" +
+                  "\n- `requested` = link initiated by trading user, awaiting staking user confirmation" +
+                  "\n- `stakingUser` = response queried by staking account" +
+                  "\n- `tradingUser` = response queried by trading account",
+              ),
+            ),
+          }),
+        ),
+        v.description(
+          "Permanent link between staking and trading accounts. Staking user gains full control of trading account funds. Staking user forfeits own fee discounts.",
+        ),
+      ),
       /** Active staking discount details. */
       activeStakingDiscount: v.pipe(
         v.object({

package/src/src/api/subscription/spotState.ts

@@ -0,0 +1,96 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser } from "../_base.js";
+import type { SubscriptionRequestConfig } from "./_types.js";
+import type { Subscription } from "../../transport/base.js";
+
+import { BalanceSchema } from "../_common_schemas.js";
+
+// -------------------- Schemas --------------------
+
+/** Subscription to spot state events for a specific user. */
+export const SpotStateRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of subscription. */
+      type: v.pipe(
+        v.literal("spotState"),
+        v.description("Type of subscription."),
+      ),
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+    }),
+    v.description("Subscription to spot state events for a specific user."),
+  );
+})();
+export type SpotStateRequest = v.InferOutput<typeof SpotStateRequest>;
+
+/** Event of user spot state. */
+export const SpotStateEvent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+      /** Spot state of the user. */
+      spotState: v.pipe(
+        v.object({
+          /** Balance for each token. */
+          balances: v.pipe(
+            v.array(BalanceSchema),
+            v.description("Balance for each token."),
+          ),
+        }),
+        v.description("Spot state of the user."),
+      ),
+    }),
+    v.description("Event of user spot state."),
+  );
+})();
+export type SpotStateEvent = v.InferOutput<typeof SpotStateEvent>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode spotState} function. */
+export type SpotStateParameters = Omit<v.InferInput<typeof SpotStateRequest>, "type">;
+
+/**
+ * Subscribe to spot state updates for a specific user.
+ * @param config - General configuration for Subscription API subscriptions.
+ * @param params - Parameters specific to the API subscription.
+ * @param listener - A callback function to be called when the event is received.
+ * @returns A request-promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+ * @example
+ * ```ts
+ * import { WebSocketTransport } from "@nktkas/hyperliquid";
+ * import { spotState } from "@nktkas/hyperliquid/api/subscription";
+ *
+ * const transport = new WebSocketTransport();
+ *
+ * const sub = await spotState(
+ *   { transport },
+ *   { user: "0x..." },
+ *   (data) => console.log(data),
+ * );
+ * ```
+ */
+export function spotState(
+  config: SubscriptionRequestConfig,
+  params: DeepImmutable<SpotStateParameters>,
+  listener: (data: SpotStateEvent) => void,
+): Promise<Subscription> {
+  const payload = parser(SpotStateRequest)({ type: "spotState", user: params.user });
+  return config.transport.subscribe<SpotStateEvent>(payload.type, payload, (e) => {
+    if (e.detail.user === payload.user) {
+      listener(e.detail);
+    }
+  });
+}

package/src/src/api/subscription/userEvents.ts

@@ -198,7 +198,17 @@ export const TwapSliceFillsEvent = /* @__PURE__ */ (() => {
     v.object({
       /** Array of TWAP slice fills. */
       twapSliceFills: v.pipe(
-        v.array(TwapFillSchema),
+        v.array(
+          v.object({
+            /** Fill details for the TWAP slice. */
+            fill: TwapFillSchema,
+            /** ID of the TWAP. */
+            twapId: v.pipe(
+              UnsignedInteger,
+              v.description("ID of the TWAP."),
+            ),
+          }),
+        ),
         v.description("Array of TWAP slice fills."),
       ),
     }),

package/src/src/api/subscription/~client.ts

@@ -16,6 +16,7 @@ import { l2Book } from "./l2Book.js";
 import { notification } from "./notification.js";
 import { openOrders } from "./openOrders.js";
 import { orderUpdates } from "./orderUpdates.js";
+import { spotState } from "./spotState.js";
 import { trades } from "./trades.js";
 import { userEvents } from "./userEvents.js";
 import { userFills } from "./userFills.js";
@@ -68,6 +69,7 @@ export type {
   OrderUpdatesEvent as WsOrderUpdatesEvent,
   OrderUpdatesParameters as WsOrderUpdatesParameters,
 } from "./orderUpdates.js";
+export type { SpotStateEvent as WsSpotStateEvent, SpotStateParameters as WsSpotStateParameters } from "./spotState.js";
 export type { TradesEvent as WsTradesEvent, TradesParameters as WsTradesParameters } from "./trades.js";
 export type {
   UserEventsEvent as WsUserEventsEvent,
@@ -454,6 +456,29 @@ export class SubscriptionClient<
     return orderUpdates(this, ...args);
   }
 
+  /**
+   * Subscribe to spot state updates for a specific user.
+   * @param params - Parameters specific to the API subscription.
+   * @param listener - A callback function to be called when the event is received.
+   * @returns A request-promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
+   *
+   * @throws {TransportError} When the transport layer throws an error.
+   *
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
+   * @example
+   * ```ts
+   * import * as hl from "@nktkas/hyperliquid";
+   *
+   * const transport = new hl.WebSocketTransport();
+   *
+   * const client = new hl.SubscriptionClient({ transport });
+   * const sub = await client.spotState({ user: "0x..." }, (data) => console.log(data));
+   * ```
+   */
+  spotState(...args: OmitFirst<OverloadedParameters<typeof spotState>>) {
+    return spotState(this, ...args);
+  }
+
   /**
    * Subscribe to real-time trade updates for a specific asset.
    * @param params - Parameters specific to the API subscription.

package/src/src/api/subscription/~mod.ts

@@ -40,6 +40,7 @@ export * from "./l2Book.js";
 export * from "./notification.js";
 export * from "./openOrders.js";
 export * from "./orderUpdates.js";
+export * from "./spotState.js";
 export * from "./trades.js";
 export * from "./userEvents.js";
 export * from "./userFills.js";

package/src/src/signing/_signTypedData.ts

@@ -218,7 +218,7 @@ export async function getWalletChainId(wallet: AbstractWallet): Promise<`0x${str
   }
 }
 
-/** Get the wallet address from various wallet types. */
+/** Get the lowercase wallet address from various wallet types. */
 export async function getWalletAddress(wallet: AbstractWallet): Promise<`0x${string}`> {
   if (isAbstractViemWallet(wallet)) {
     if ("address" in wallet && wallet.address) {

package/src/src/transport/websocket/_hyperliquid_event_target.ts

@@ -46,6 +46,13 @@ interface PostResponse {
           }
           | string;
       };
+    }
+    /** Response containing error message. */
+    | {
+      /** Indicates that this is an action response. */
+      type: "error";
+      /** Contains the error message, e.g. 429 Too Many Requests */
+      payload: string;
     };
 }
 

package/src/src/transport/websocket/_websocket_async_request.ts

@@ -52,6 +52,12 @@ export class WebSocketAsyncRequest {
       this.queue.find((x) => x.id === id)?.resolve(event.detail);
     });
     hlEvents.addEventListener("post", (event) => {
+      if (event.detail.response.type === "error") {
+        this.queue
+          .find((x) => x.id === event.detail.id)
+          ?.reject(new WebSocketRequestError(event.detail.response.payload));
+        return;
+      }
       const data = event.detail.response.type === "info"
         ? event.detail.response.payload.data
         : event.detail.response.payload;

package/src/src/utils/{_minimalEIP712Signer.ts → _eip712.ts}

@@ -1,5 +1,3 @@
-// -------------------- EIP-712 --------------------
-
 import { keccak_256 } from "@noble/hashes/sha3.js";
 import * as secp from "@noble/secp256k1";
 
@@ -19,7 +17,7 @@ export interface Domain {
 }
 
 /** Signs typed data with a private key. */
-async function signTypedData(args: {
+export async function signTypedData(args: {
   privateKey: string | Uint8Array;
   domain?: Domain;
   types: Types;
@@ -36,20 +34,18 @@ async function signTypedData(args: {
 
   const hash = hashTypedData({ domain, types, primaryType, message });
 
-  const signature = await secp.signAsync(
-    hash,
-    privateKey instanceof Uint8Array ? privateKey : secp.etc.hexToBytes(cleanHex(privateKey)),
-    { prehash: false, format: "recovered" },
-  );
+  const pk = typeof privateKey === "string" ? secp.etc.hexToBytes(cleanHex(privateKey)) : privateKey;
+  const sigr = await secp.signAsync(hash, pk, { prehash: false, format: "recovered" });
 
-  const r = secp.etc.bytesToHex(signature.slice(1, 33));
-  const s = secp.etc.bytesToHex(signature.slice(33, 65));
-  const v = (signature[0] + 27).toString(16).padStart(2, "0");
+  const r = secp.etc.bytesToHex(sigr.slice(1, 33));
+  const s = secp.etc.bytesToHex(sigr.slice(33, 65));
+  const v = (sigr[0] + 27).toString(16).padStart(2, "0");
 
   return `0x${r}${s}${v}`;
 }
 
-function hashTypedData(args: {
+/** Hashes typed data according to EIP-712. */
+export function hashTypedData(args: {
   domain: Domain;
   types: Types;
   primaryType: string;
@@ -211,7 +207,7 @@ function cleanHex(hex: string): string {
   return hex.startsWith("0x") ? hex.slice(2) : hex;
 }
 
-// -------------------- Interaction API --------------------
+// -------------------- For SDK --------------------
 
 import type { AbstractViemLocalAccount } from "../signing/mod.js";
 
@@ -221,30 +217,27 @@ export class PrivateKeyEIP712Signer implements AbstractViemLocalAccount {
   address: `0x${string}`;
   constructor(privateKey: string | Uint8Array) {
     this.#privateKey = privateKey;
-    this.address = privateKeyToAddress(privateKey); // and validate the key
-  }
-  signTypedData(
-    params: {
-      domain: Domain;
-      types: Types;
-      primaryType: string;
-      message: Record<string, unknown>;
-    },
-  ): Promise<`0x${string}`> {
+    this.address = privateKeyToAddress(privateKey); // and validate the private key
+  }
+  signTypedData(params: {
+    domain: Domain;
+    types: Types;
+    primaryType: string;
+    message: Record<string, unknown>;
+  }): Promise<`0x${string}`> {
     return signTypedData({ privateKey: this.#privateKey, ...params });
   }
 }
 
 function privateKeyToAddress(privateKey: string | Uint8Array): `0x${string}` {
   const pk = typeof privateKey === "string" ? secp.etc.hexToBytes(cleanHex(privateKey)) : privateKey;
-
   const publicKey = secp.getPublicKey(pk, false);
-  const publicKeyWithoutPrefix = publicKey.slice(1);
+  return publicKeyToAddress(publicKey);
+}
 
+function publicKeyToAddress(publicKey: Uint8Array): `0x${string}` {
+  const publicKeyWithoutPrefix = publicKey.slice(1);
   const hash = keccak_256(publicKeyWithoutPrefix);
-
   const addressBytes = hash.slice(-20);
-  const address = secp.etc.bytesToHex(addressBytes);
-
-  return `0x${address}`;
+  return `0x${secp.etc.bytesToHex(addressBytes)}`;
 }

package/src/src/utils/_format.ts

@@ -1,11 +1,8 @@
-import { HyperliquidError } from "../_base.js";
-
 /**
  * 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, 8 for spot) - `szDecimals` decimal places
+ * - Maximum 6 (for perp) or 8 (for spot) - `szDecimals` decimal places
  * - Integer prices are always allowed regardless of significant figures
- * - Remove trailing zeros
  * @example
  * ```ts
  * import { formatPrice } from "@nktkas/hyperliquid/utils";
@@ -15,158 +12,162 @@ import { HyperliquidError } from "../_base.js";
  * const price = formatPrice("0.0000123456789", 0, false); // → "0.00001234"
  * ```
  */
-export function formatPrice(
-  price: string | number,
-  szDecimals: number,
-  isPerp: boolean = true,
-): string {
-  // Prepare: trim, validate, normalize leading/trailing zeros
-  let priceStr = prepareNumber(typeof price === "string" ? price : price.toString());
-
-  // Integer prices bypass sig figs limit per spec
-  if (!priceStr.includes(".")) {
-    return priceStr;
-  }
+export function formatPrice(price: string | number, szDecimals: number, isPerp: boolean = true): string {
+  price = price.toString().trim();
+  assertNumberString(price);
 
-  // Apply decimal limit: max (6 for perp, 8 for spot) - `szDecimals` decimals
+  // Integer prices are always allowed
+  if (/^-?\d+$/.test(price)) return trimZeros(price);
+
+  // Apply decimal limit: max 6 (perp) or 8 (spot) - szDecimals
   const maxDecimals = Math.max((isPerp ? 6 : 8) - szDecimals, 0);
-  priceStr = truncateDecimals(priceStr, maxDecimals);
+  price = StringMath.toFixedTruncate(price, maxDecimals);
 
   // Apply sig figs limit: max 5 significant figures
-  priceStr = truncateSigFigs(priceStr, 5);
+  price = StringMath.toPrecisionTruncate(price, 5);
 
-  return priceStr;
+  return price;
 }
 
 /**
  * Format size according to Hyperliquid {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size | rules}:
- * - Truncate to `szDecimals` decimal places
- * - Remove trailing zeros
+ * - Truncate decimal places to `szDecimals`
  * @example
  * ```ts
  * import { formatSize } from "@nktkas/hyperliquid/utils";
  *
  * const size = formatSize("1.23456789", 5); // → "1.23456"
  * ```
+ * @note May return 0 if the value is not suitable, but when closing a position, a size of 0 means the full size.
  */
 export function formatSize(size: string | number, szDecimals: number): string {
-  // Prepare: trim, validate, normalize leading/trailing zeros
-  let sizeStr = prepareNumber(typeof size === "string" ? size : size.toString());
-
-  // Truncate to `szDecimals` decimal places
-  sizeStr = truncateDecimals(sizeStr, szDecimals);
-
-  return sizeStr;
-}
-
-/**
- * Prepare number string for processing:
- * 1. Trim whitespace
- * 2. Validate format (decimal number, not hex/scientific)
- * 3. Normalize: remove leading zeros from integer part, trailing zeros from decimal part
- */
-function prepareNumber(numStr: string): string {
-  const trimmed = numStr.trim();
+  size = size.toString().trim();
+  assertNumberString(size);
 
-  // Validate: only decimal numbers allowed (no hex, scientific notation, etc)
-  if (!/^-?(\d+\.?\d*|\.\d+)$/.test(trimmed)) {
-    throw new HyperliquidError(`Invalid number format: ${numStr}`);
-  }
+  // Apply decimal limit: szDecimals
+  size = StringMath.toFixedTruncate(size, szDecimals);
 
-  // Normalize: remove leading zeros from integer, trailing zeros from decimal
-  const [int, dec] = trimmed.split(".");
-  const trimmedInt = int.replace(/^0+/, "") || "0";
-  const trimmedDec = dec?.replace(/0+$/, "");
-  return trimmedInt + (trimmedDec ? "." + trimmedDec : "");
+  return size;
 }
 
 /** String-based Math operations for arbitrary precision */
 const StringMath = {
-  /** Absolute value: remove negative sign if present */
-  abs(numStr: string): string {
-    return numStr[0] === "-" ? numStr.slice(1) : numStr;
-  },
-
   /** Floor log10 (magnitude): position of most significant digit */
-  log10Floor(numStr: string): number {
-    const abs = this.abs(numStr);
+  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 (int !== "0") {
+    if (Number(int) !== 0) {
       const trimmed = int.replace(/^0+/, "");
       return trimmed.length - 1;
     }
 
     // Number < 1: count leading zeros in decimal part
-    if (!dec) return -Infinity;
     const leadingZeros = dec.match(/^0*/)?.[0].length ?? 0;
     return -(leadingZeros + 1);
   },
 
   /** Multiply by 10^exp: shift decimal point left (negative) or right (positive) */
-  multiplyByPow10(numStr: string, exp: number): string {
-    if (exp === 0) return numStr;
+  multiplyByPow10(value: string, exp: number): string {
+    if (!Number.isInteger(exp)) throw new RangeError("Exponent must be an integer");
+    if (exp === 0) return trimZeros(value);
 
-    const neg = numStr[0] === "-";
-    const abs = neg ? numStr.slice(1) : numStr;
-    const [int, dec = ""] = abs.split(".");
+    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) {
-        return (neg ? "-" : "") + int + dec + "0".repeat(exp - dec.length);
+        result = int + dec + "0".repeat(exp - dec.length);
+      } else {
+        result = int + dec.slice(0, exp) + "." + dec.slice(exp);
       }
-      return (neg ? "-" : "") + int + dec.slice(0, exp) + "." + dec.slice(exp);
     } else {
       // Shift left: move digits from integer to decimal
       const absExp = -exp;
       if (absExp >= int.length) {
-        return (neg ? "-" : "") + "0." + "0".repeat(absExp - int.length) + int + dec;
+        result = "0." + "0".repeat(absExp - int.length) + int + dec;
+      } else {
+        result = int.slice(0, -absExp) + "." + int.slice(-absExp) + dec;
       }
-      return (neg ? "-" : "") + int.slice(0, -absExp) + "." + int.slice(-absExp) + dec;
     }
+
+    return trimZeros((neg ? "-" : "") + result);
   },
 
-  /** Truncate: remove decimal part */
-  trunc(numStr: string): string {
-    const dotIndex = numStr.indexOf(".");
-    return dotIndex === -1 ? numStr : numStr.slice(0, dotIndex);
+  /** 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 specified decimal places */
-function truncateDecimals(numStr: string, maxDecimals: number): string {
-  const dotIndex = numStr.indexOf(".");
-  if (dotIndex === -1) return numStr;
+  /** 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 truncated = numStr.substring(0, dotIndex + maxDecimals + 1);
+    const neg = value[0] === "-";
+    const abs = neg ? value.slice(1) : value;
 
-  // Remove trailing zeros from decimal
-  const [int, dec] = truncated.split(".");
-  const trimmedDec = dec?.replace(/0+$/, "");
-  return trimmedDec ? int + "." + trimmedDec : int;
-}
+    // Calculate how much to shift: align most significant digit to ones place + (maxSigFigs-1)
+    const magnitude = StringMath.log10Floor(abs);
+    const shiftAmount = precision - magnitude - 1;
 
-/** Truncate to specified significant figures using string-based math */
-function truncateSigFigs(numStr: string, maxSigFigs: number): string {
-  if (parseFloat(numStr) === 0) return "0";
+    // Shift right, truncate integer part, shift back
+    const shifted = StringMath.multiplyByPow10(abs, shiftAmount);
+    const truncated = StringMath.trunc(shifted);
+    const result = StringMath.multiplyByPow10(truncated, -shiftAmount);
 
-  const neg = numStr[0] === "-";
-  const abs = neg ? numStr.slice(1) : numStr;
+    // build final result and trim zeros
+    return trimZeros(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");
 
-  // Calculate how much to shift: align most significant digit to ones place + (maxSigFigs-1)
-  const magnitude = StringMath.log10Floor(abs);
-  const shiftAmount = maxSigFigs - magnitude - 1;
+    // Match number with up to `decimals` decimal places
+    const regex = new RegExp(`^-?(?:\\d+)?(?:\\.\\d{0,${decimals}})?`);
+    const result = value.match(regex)?.[0];
 
-  // Shift right, truncate integer part, shift back
-  const shifted = StringMath.multiplyByPow10(abs, shiftAmount);
-  const truncated = StringMath.trunc(shifted);
-  const result = StringMath.multiplyByPow10(truncated, -shiftAmount);
+    if (!result) {
+      throw new TypeError("Invalid number format");
+    }
 
-  // Remove trailing zeros introduced by shifting
-  const final = neg ? "-" + result : result;
-  const [int, dec] = final.split(".");
-  const trimmedDec = dec?.replace(/0+$/, "");
-  return trimmedDec ? int + "." + trimmedDec : int;
+    // Trim zeros after truncation
+    return trimZeros(result);
+  },
+};
+
+function trimZeros(value: string): string {
+  return value
+    // 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");
+  }
 }