@lifi/perps-sdk 0.1.1-alpha.9 → 1.0.0

package/dist/esm/utils/calculations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculations.d.ts","sourceRoot":"","sources":["../../../src/utils/calculations.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/calculations.js

@@ -0,0 +1,291 @@
+/**
+ * Universal perpetual futures calculation utilities.
+ *
+ * Pure functions for computing position-related values that any consumer
+ * of the perps SDK would need. All parameters are required — no default
+ * values for critical financial parameters.
+ */
+/**
+ * Calculate position size in asset units from margin.
+ *
+ * @param marginUsd - Margin amount in USD
+ * @param leverage - Position leverage
+ * @param price - Current asset price
+ * @returns Position size in asset units
+ * @example
+ * ```ts
+ * calculatePositionSize(100, 10, 2000) // 0.5 (ETH at $2000)
+ * ```
+ * @public
+ */
+export function calculatePositionSize(marginUsd, leverage, price) {
+    return (marginUsd * leverage) / price;
+}
+/**
+ * Calculate notional value of a position.
+ *
+ * @param size - Position size in asset units
+ * @param price - Current asset price
+ * @returns Notional value in USD
+ * @public
+ */
+export function calculateNotionalValue(size, price) {
+    return Math.abs(size) * price;
+}
+/**
+ * Calculate unrealized PnL.
+ *
+ * @param entryPrice - Position entry price
+ * @param currentPrice - Current market price
+ * @param size - Position size (positive for long, negative for short)
+ * @returns Unrealized PnL in USD
+ * @public
+ */
+export function calculateUnrealizedPnl(entryPrice, currentPrice, size) {
+    return (currentPrice - entryPrice) * size;
+}
+/**
+ * Calculate return on equity (ROE) percentage.
+ *
+ * @param pnl - Profit/loss in USD
+ * @param margin - Initial margin in USD
+ * @returns ROE as percentage (e.g., 10 for 10%)
+ * @public
+ */
+export function calculateRoe(pnl, margin) {
+    if (margin === 0) {
+        return 0;
+    }
+    return (pnl / margin) * 100;
+}
+/**
+ * Calculate required margin for a position.
+ *
+ * @param notionalValue - Position notional value in USD
+ * @param leverage - Position leverage
+ * @returns Required margin in USD
+ * @public
+ */
+export function calculateRequiredMargin(notionalValue, leverage) {
+    return notionalValue / leverage;
+}
+/**
+ * Estimate trading fees.
+ *
+ * @param sizeUsd - Position size in USD (notional value)
+ * @param feeRate - Fee rate as decimal (e.g., 0.00035 for 0.035%)
+ * @returns Estimated fee in USD
+ * @public
+ */
+export function estimateFees(sizeUsd, feeRate) {
+    return sizeUsd * feeRate;
+}
+/**
+ * Apply slippage to a price for order execution.
+ *
+ * @param price - Base price
+ * @param slippagePercent - Slippage tolerance as percentage (e.g., 0.5 for 0.5%)
+ * @param isBuy - True if buying (price goes up), false if selling (price goes down)
+ * @returns Price adjusted for slippage
+ * @public
+ */
+export function applySlippage(price, slippagePercent, isBuy) {
+    const multiplier = 1 + slippagePercent / 100;
+    return isBuy ? price * multiplier : price / multiplier;
+}
+/**
+ * Distance from the current price to the liquidation price, as a percentage of
+ * the current price.
+ *
+ * @param liquidationPrice - The position's liquidation price
+ * @param currentPrice - Current market price
+ * @returns Absolute distance as a percentage, or 0 when current price is zero
+ * @public
+ */
+export function liquidationDistancePercent(params) {
+    const { liquidationPrice, currentPrice } = params;
+    if (currentPrice === 0) {
+        return 0;
+    }
+    return Math.abs((liquidationPrice - currentPrice) / currentPrice) * 100;
+}
+/**
+ * Effective leverage of an open position.
+ *
+ * leverage = positionValueUsd / marginUsd
+ *
+ * @param positionValueUsd - Position notional value in USD
+ * @param marginUsd - Margin backing the position in USD
+ * @returns Effective leverage, or 0 when margin is zero
+ * @public
+ */
+export function effectiveLeverage(params) {
+    const { positionValueUsd, marginUsd } = params;
+    if (marginUsd === 0) {
+        return 0;
+    }
+    return positionValueUsd / marginUsd;
+}
+/**
+ * Margin that can be removed from a position while keeping its leverage at or
+ * below the asset's maximum.
+ *
+ * The minimum margin to stay within `maxLeverage` is the required margin for
+ * the position's notional (see {@link calculateRequiredMargin}); anything above
+ * that is removable.
+ *
+ * @param marginUsed - Margin currently backing the position in USD
+ * @param positionValueUsd - Position notional value in USD
+ * @param maxLeverage - Maximum leverage allowed for the asset
+ * @returns Removable margin in USD (never negative); falls back to the full
+ *   `marginUsed` when `maxLeverage` is zero (no constraint available)
+ * @public
+ */
+export function removableMargin(params) {
+    const { marginUsed, positionValueUsd, maxLeverage } = params;
+    if (maxLeverage === 0) {
+        return marginUsed;
+    }
+    const minMargin = calculateRequiredMargin(positionValueUsd, maxLeverage);
+    return Math.max(0, marginUsed - minMargin);
+}
+/**
+ * Calculate expected gain/loss for a TP or SL trigger price.
+ * Returns signed values — positive means profit, negative means loss.
+ *
+ * @param triggerPrice - The TP or SL target price
+ * @param entryPrice - Position entry / current market price
+ * @param leverage - Position leverage multiplier
+ * @param isLong - True for long positions, false for short
+ * @param margin - Margin amount in USD
+ * @public
+ */
+export function calculateExpectedPnl(triggerPrice, entryPrice, leverage, isLong, margin) {
+    if (!triggerPrice || entryPrice === 0 || margin === 0) {
+        return null;
+    }
+    const priceDiff = isLong
+        ? triggerPrice - entryPrice
+        : entryPrice - triggerPrice;
+    const percent = (priceDiff / entryPrice) * leverage * 100;
+    const amount = margin * (percent / 100);
+    return { amount, percent };
+}
+/**
+ * Convert a percentage gain/loss to a target price.
+ *
+ * @param percent - Target gain/loss percentage (positive = profitable direction)
+ * @param entryPrice - Position entry price
+ * @param leverage - Position leverage multiplier
+ * @param isLong - True for long positions, false for short
+ * @public
+ */
+export function priceFromPercent(percent, entryPrice, leverage, isLong) {
+    if (entryPrice === 0 || leverage === 0) {
+        return 0;
+    }
+    const priceDelta = (percent / 100 / leverage) * entryPrice;
+    return isLong ? entryPrice + priceDelta : entryPrice - priceDelta;
+}
+/**
+ * Convert a target price to a percentage gain/loss.
+ *
+ * @param price - Target price
+ * @param entryPrice - Position entry price
+ * @param leverage - Position leverage multiplier
+ * @param isLong - True for long positions, false for short
+ * @public
+ */
+export function percentFromPrice(price, entryPrice, leverage, isLong) {
+    if (entryPrice === 0 || leverage === 0) {
+        return 0;
+    }
+    const priceDiff = isLong ? price - entryPrice : entryPrice - price;
+    return (priceDiff / entryPrice) * leverage * 100;
+}
+/**
+ * Calculate realized PnL as a percentage of position value at close.
+ *
+ * @param realizedPnl - The realized profit/loss in USD
+ * @param size - Position size in asset units at close
+ * @param price - Price at close
+ * @returns PnL as a percentage of position value
+ * @public
+ */
+export function calculateRealizedPnlPercent(realizedPnl, size, price) {
+    const positionValue = Math.abs(size) * price;
+    if (positionValue === 0) {
+        return 0;
+    }
+    return (realizedPnl / positionValue) * 100;
+}
+/**
+ * Walk one side of an orderbook to fill `sizeUsd` notional, accumulating base
+ * size and notional level-by-level to derive the VWAP fill. Levels are consumed
+ * in array order — the caller passes asks for a buy and bids for a sell, each
+ * already ordered best-price-first. When the book cannot absorb the full
+ * notional, the walk stops at the last level and flags `insufficientLiquidity`,
+ * returning the best obtainable fill.
+ *
+ * @public
+ */
+export function walkOrderbook(levels, sizeUsd) {
+    let remaining = sizeUsd;
+    let baseSize = 0;
+    let filledNotional = 0;
+    for (const level of levels) {
+        if (remaining <= 0) {
+            break;
+        }
+        const price = Number.parseFloat(level.price);
+        const levelNotional = Number.parseFloat(level.size) * price;
+        const take = Math.min(remaining, levelNotional);
+        filledNotional += take;
+        baseSize += take / price;
+        remaining -= take;
+    }
+    return {
+        baseSize,
+        filledNotional,
+        vwap: baseSize === 0 ? 0 : filledNotional / baseSize,
+        insufficientLiquidity: remaining > 0,
+    };
+}
+/**
+ * Build a {@link Quote} from a resolved market, its live {@link MarketPrice},
+ * and its orderbook snapshot. Pure: walks the relevant side (buy → asks,
+ * sell → bids) for the VWAP fill, derives the price impact in basis points
+ * versus mark, applies the base taker fee on the filled notional, and carries
+ * the market's `funding` (`null` for spot, which has none).
+ *
+ * @public
+ */
+export function buildQuote(input) {
+    const { market, price, side, sizeUsd, feeTier } = input;
+    const markPrice = Number.parseFloat(price.markPrice);
+    const levels = side === 'buy' ? input.asks : input.bids;
+    const walk = walkOrderbook(levels, sizeUsd);
+    const priceImpactBps = markPrice === 0 || walk.vwap === 0
+        ? 0
+        : Math.abs((walk.vwap - markPrice) / markPrice) * 10_000;
+    const feeUsd = estimateFees(walk.filledNotional, Number.parseFloat(feeTier.taker));
+    return {
+        provider: input.provider,
+        symbol: input.symbol,
+        marketId: market.id,
+        type: input.type,
+        side,
+        sizeUsd: sizeUsd.toString(),
+        baseSize: walk.baseSize.toString(),
+        markPrice: price.markPrice,
+        expectedFillPrice: walk.vwap.toString(),
+        priceImpactBps: priceImpactBps.toString(),
+        feeTier,
+        isDefaultFeeTier: true,
+        feeUsd: feeUsd.toString(),
+        funding: price.funding ?? null,
+        insufficientLiquidity: walk.insufficientLiquidity,
+        timestamp: input.timestamp,
+    };
+}
+//# sourceMappingURL=calculations.js.map

package/dist/esm/utils/calculations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculations.js","sourceRoot":"","sources":["../../../src/utils/calculations.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/depositChain.d.ts

@@ -0,0 +1,25 @@
+import type { AccountConfig } from '@lifi/perps-types';
+import { ChainId } from '@lifi/types';
+/**
+ * Perps provider keys that have a declared LI.FI deposit-target chain.
+ *
+ * @public
+ */
+export type DepositProviderKey = AccountConfig['provider'];
+/**
+ * Declared single source of truth: perps provider key → the LI.FI chain a
+ * client opens the swap widget against to fund that provider. Values come from
+ * the `@lifi/types` `ChainId` enum; never hardcode the numeric ids.
+ *
+ * @public
+ */
+export declare const LIFI_DEPOSIT_CHAIN_BY_PROVIDER: Record<DepositProviderKey, ChainId>;
+/**
+ * Resolve the LI.FI deposit-target chain for a perps provider key.
+ *
+ * @returns The `@lifi/types` `ChainId`, or `undefined` for a provider key with
+ *   no declared deposit chain (the `/providers` wire key is an open `string`).
+ * @public
+ */
+export declare function lifiDepositChainForProvider(providerKey: string): ChainId | undefined;
+//# sourceMappingURL=depositChain.d.ts.map

package/dist/esm/utils/depositChain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"depositChain.d.ts","sourceRoot":"","sources":["../../../src/utils/depositChain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAErC;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,UAAU,CAAC,CAAA;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,EAAE,MAAM,CACjD,kBAAkB,EAClB,OAAO,CAIR,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,GAClB,OAAO,GAAG,SAAS,CAErB"}

package/dist/esm/utils/depositChain.js

@@ -0,0 +1,23 @@
+import { ChainId } from '@lifi/types';
+/**
+ * Declared single source of truth: perps provider key → the LI.FI chain a
+ * client opens the swap widget against to fund that provider. Values come from
+ * the `@lifi/types` `ChainId` enum; never hardcode the numeric ids.
+ *
+ * @public
+ */
+export const LIFI_DEPOSIT_CHAIN_BY_PROVIDER = {
+    hyperliquid: ChainId.HPL,
+    lighter: ChainId.LTR,
+};
+/**
+ * Resolve the LI.FI deposit-target chain for a perps provider key.
+ *
+ * @returns The `@lifi/types` `ChainId`, or `undefined` for a provider key with
+ *   no declared deposit chain (the `/providers` wire key is an open `string`).
+ * @public
+ */
+export function lifiDepositChainForProvider(providerKey) {
+    return LIFI_DEPOSIT_CHAIN_BY_PROVIDER[providerKey];
+}
+//# sourceMappingURL=depositChain.js.map

package/dist/esm/utils/depositChain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"depositChain.js","sourceRoot":"","sources":["../../../src/utils/depositChain.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AASrC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAGvC;IACF,WAAW,EAAE,OAAO,CAAC,GAAG;IACxB,OAAO,EAAE,OAAO,CAAC,GAAG;CACrB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CACzC,WAAmB;IAEnB,OAAO,8BAA8B,CAAC,WAAiC,CAAC,CAAA;AAC1E,CAAC"}

package/dist/esm/utils/explorer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Block-explorer URL resolution.
+ *
+ * Provider plugins resolve a tx hash to a fully-qualified explorer URL during
+ * wire→domain mapping. The explorer target is a function of the settling chain,
+ * so the map is keyed by chain id rather than by provider.
+ */
+/**
+ * Settling chains a perps tx can be observed on.
+ *
+ * @public
+ */
+export declare const ExplorerChainId: {
+    readonly ETHEREUM: 1;
+    readonly ARBITRUM_ONE: 42161;
+    readonly LIGHTER: 304;
+    readonly HYPERLIQUID: 999;
+};
+/**
+ * Union of {@link ExplorerChainId} values.
+ *
+ * @public
+ */
+export type ExplorerChainId = (typeof ExplorerChainId)[keyof typeof ExplorerChainId];
+/**
+ * Build a fully-resolved block-explorer URL for a tx on a known chain.
+ *
+ * @returns The explorer URL, or `undefined` when the hash is empty (no on-chain
+ *   tx to link).
+ * @public
+ */
+export declare function explorerTxUrl(chainId: ExplorerChainId, txHash: string | undefined): string | undefined;
+//# sourceMappingURL=explorer.d.ts.map

package/dist/esm/utils/explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorer.d.ts","sourceRoot":"","sources":["../../../src/utils/explorer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;CAKlB,CAAA;AAEV;;;;GAIG;AACH,MAAM,MAAM,eAAe,GACzB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAA;AASxD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,MAAM,GAAG,SAAS,CAKpB"}

package/dist/esm/utils/explorer.js

@@ -0,0 +1,38 @@
+/**
+ * Block-explorer URL resolution.
+ *
+ * Provider plugins resolve a tx hash to a fully-qualified explorer URL during
+ * wire→domain mapping. The explorer target is a function of the settling chain,
+ * so the map is keyed by chain id rather than by provider.
+ */
+/**
+ * Settling chains a perps tx can be observed on.
+ *
+ * @public
+ */
+export const ExplorerChainId = {
+    ETHEREUM: 1,
+    ARBITRUM_ONE: 42161,
+    LIGHTER: 304,
+    HYPERLIQUID: 999,
+};
+const TX_BASE_URL_BY_CHAIN = {
+    [ExplorerChainId.ETHEREUM]: 'https://etherscan.io/tx/',
+    [ExplorerChainId.ARBITRUM_ONE]: 'https://arbiscan.io/tx/',
+    [ExplorerChainId.LIGHTER]: 'https://app.lighter.xyz/explorer/logs/',
+    [ExplorerChainId.HYPERLIQUID]: 'https://app.hyperliquid.xyz/explorer/tx/',
+};
+/**
+ * Build a fully-resolved block-explorer URL for a tx on a known chain.
+ *
+ * @returns The explorer URL, or `undefined` when the hash is empty (no on-chain
+ *   tx to link).
+ * @public
+ */
+export function explorerTxUrl(chainId, txHash) {
+    if (!txHash) {
+        return undefined;
+    }
+    return `${TX_BASE_URL_BY_CHAIN[chainId]}${txHash}`;
+}
+//# sourceMappingURL=explorer.js.map

package/dist/esm/utils/explorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorer.js","sourceRoot":"","sources":["../../../src/utils/explorer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,QAAQ,EAAE,CAAC;IACX,YAAY,EAAE,KAAK;IACnB,OAAO,EAAE,GAAG;IACZ,WAAW,EAAE,GAAG;CACR,CAAA;AAUV,MAAM,oBAAoB,GAAoC;IAC5D,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,0BAA0B;IACtD,CAAC,eAAe,CAAC,YAAY,CAAC,EAAE,yBAAyB;IACzD,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,wCAAwC;IACnE,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,0CAA0C;CAC1E,CAAA;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAwB,EACxB,MAA0B;IAE1B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,GAAG,oBAAoB,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,CAAA;AACpD,CAAC"}

package/dist/esm/utils/fillClassification.d.ts

@@ -0,0 +1,13 @@
+import { FillClassification } from '@lifi/perps-types';
+/**
+ * Classify a perpetual fill into the Open/Close/Increase/Reduce/Switch
+ * taxonomy from `FillClassification`.
+ *
+ * @param startPosition Signed position held BEFORE this fill (`> 0` long,
+ *   `< 0` short, `0` flat).
+ * @param side Hyperliquid-style: `'B'` for buy, anything else for sell.
+ * @param sz Unsigned fill size, parsed with `parseFloat`.
+ * @public
+ */
+export declare function classifyFillFromPosition(startPosition: string, side: string, sz: string): FillClassification;
+//# sourceMappingURL=fillClassification.d.ts.map

package/dist/esm/utils/fillClassification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fillClassification.d.ts","sourceRoot":"","sources":["../../../src/utils/fillClassification.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,kBAAkB,CAkCpB"}

package/dist/esm/utils/fillClassification.js

@@ -0,0 +1,44 @@
+import { FillClassification } from '@lifi/perps-types';
+/**
+ * Classify a perpetual fill into the Open/Close/Increase/Reduce/Switch
+ * taxonomy from `FillClassification`.
+ *
+ * @param startPosition Signed position held BEFORE this fill (`> 0` long,
+ *   `< 0` short, `0` flat).
+ * @param side Hyperliquid-style: `'B'` for buy, anything else for sell.
+ * @param sz Unsigned fill size, parsed with `parseFloat`.
+ * @public
+ */
+export function classifyFillFromPosition(startPosition, side, sz) {
+    const start = parseFloat(startPosition);
+    const delta = side === 'B' ? parseFloat(sz) : -parseFloat(sz);
+    const end = start + delta;
+    if (start === 0) {
+        return end > 0
+            ? FillClassification.OPENED_LONG
+            : FillClassification.OPENED_SHORT;
+    }
+    if (start > 0) {
+        if (end === 0) {
+            return FillClassification.CLOSED_LONG;
+        }
+        if (end < 0) {
+            return FillClassification.SWITCHED_SHORT;
+        }
+        if (end > start) {
+            return FillClassification.INCREASED_LONG;
+        }
+        return FillClassification.REDUCED_LONG;
+    }
+    if (end === 0) {
+        return FillClassification.CLOSED_SHORT;
+    }
+    if (end > 0) {
+        return FillClassification.SWITCHED_LONG;
+    }
+    if (end < start) {
+        return FillClassification.INCREASED_SHORT;
+    }
+    return FillClassification.REDUCED_SHORT;
+}
+//# sourceMappingURL=fillClassification.js.map

package/dist/esm/utils/fillClassification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fillClassification.js","sourceRoot":"","sources":["../../../src/utils/fillClassification.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAEtD;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACtC,aAAqB,EACrB,IAAY,EACZ,EAAU;IAEV,MAAM,KAAK,GAAG,UAAU,CAAC,aAAa,CAAC,CAAA;IACvC,MAAM,KAAK,GAAG,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IAC7D,MAAM,GAAG,GAAG,KAAK,GAAG,KAAK,CAAA;IAEzB,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,OAAO,GAAG,GAAG,CAAC;YACZ,CAAC,CAAC,kBAAkB,CAAC,WAAW;YAChC,CAAC,CAAC,kBAAkB,CAAC,YAAY,CAAA;IACrC,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;YACd,OAAO,kBAAkB,CAAC,WAAW,CAAA;QACvC,CAAC;QACD,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACZ,OAAO,kBAAkB,CAAC,cAAc,CAAA;QAC1C,CAAC;QACD,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;YAChB,OAAO,kBAAkB,CAAC,cAAc,CAAA;QAC1C,CAAC;QACD,OAAO,kBAAkB,CAAC,YAAY,CAAA;IACxC,CAAC;IAED,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;QACd,OAAO,kBAAkB,CAAC,YAAY,CAAA;IACxC,CAAC;IACD,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QACZ,OAAO,kBAAkB,CAAC,aAAa,CAAA;IACzC,CAAC;IACD,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;QAChB,OAAO,kBAAkB,CAAC,eAAe,CAAA;IAC3C,CAAC;IACD,OAAO,kBAAkB,CAAC,aAAa,CAAA;AACzC,CAAC"}

package/dist/esm/utils/format.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Options shared by the human-facing display formatters.
+ *
+ * @public
+ */
+export interface FormatOptions {
+    /** Fixed number of decimal places. Defaults are per-formatter. */
+    decimals?: number;
+    /** Rendered when the value is null/undefined/NaN/non-finite. Defaults to `'—'`. */
+    placeholder?: string;
+    /** BCP 47 locale controlling digit grouping and separators (e.g. `'en-US'`). */
+    locale?: string;
+}
+type FormatInput = number | string | null | undefined;
+/**
+ * Format a USD value, unsigned: `$1,234.50`, `-$1,500.00`, `$0.00`.
+ *
+ * Two decimal places with locale digit grouping. Negatives place the `-`
+ * before the `$`. Null/undefined/non-finite input renders the placeholder.
+ *
+ * @public
+ */
+export declare function formatUsd(value: FormatInput, options?: FormatOptions): string;
+/**
+ * Format a USD value with an explicit sign: `+$1.43`, `-$1.43`, `$0.00`.
+ *
+ * The sign is derived after rounding, so sub-cent magnitudes render `$0.00`
+ * (no spurious `+`/`-`). Null/undefined/non-finite input renders the
+ * placeholder.
+ *
+ * @public
+ */
+export declare function formatSignedUsd(value: FormatInput, options?: FormatOptions): string;
+/**
+ * Format a percentage with an explicit sign and no grouping: `+1.43%`,
+ * `-1.43%`, `0.00%`.
+ *
+ * The sign is derived after rounding, so sub-threshold magnitudes render
+ * `0.00%`. Null/undefined/non-finite input renders the placeholder.
+ *
+ * @public
+ */
+export declare function formatSignedPercent(value: FormatInput, options?: FormatOptions): string;
+/**
+ * Format a price, unsigned, with decimals auto-detected from magnitude:
+ * `$1,234.50`, `$0.1234`, `-$1,500.00`.
+ *
+ * Decimals follow {@link autoDecimals} unless `options.decimals` is given.
+ * Grouping applies once the absolute value reaches 1000. Negatives place the
+ * `-` before the `$`. Null/undefined/non-finite input renders the placeholder.
+ *
+ * @public
+ */
+export declare function formatPrice(value: FormatInput, options?: FormatOptions): string;
+/**
+ * Format a USD value compactly with a `B`/`M`/`K` suffix: `$1.23B`, `$45.6M`,
+ * `$789.0K`, `$12.34`.
+ *
+ * Negatives place the `-` before the `$`. Null/undefined/non-finite input
+ * renders the placeholder.
+ *
+ * @public
+ */
+export declare function formatCompactUsd(value: FormatInput, options?: FormatOptions): string;
+export {};
+//# sourceMappingURL=format.d.ts.map

package/dist/esm/utils/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/utils/format.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAID,KAAK,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;AA+DrD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAcR;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAcR;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAUR;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAkBR"}