@syldel/hl-shared-types 0.0.16 → 0.0.17

package/README.md

@@ -16,6 +16,33 @@ Ce package centralise les définitions TypeScript pour l'écosystème **Hyperliq
 * **Account** : États du compte, positions Perp et soldes Spot.
 * **Market** : Métadonnées des actifs et résumés de marché.
 * **Orders** : Définitions des ordres ouverts et historiques.
+* **Format** : les règles de **tick et de lot** d'Hyperliquid — la seule logique exécutable
+  du package, et la seule qui décide ce qui part vers l'exchange.
+
+---
+
+## ⚠️ `format/` : du code, pas seulement des types
+
+`formatPrice`, `formatSize`, `priceDecimals` et `snapPrice` appliquent les règles de
+[tick and lot size](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size)
+d'Hyperliquid. Elles vivent ici pour qu'il n'en existe **qu'une seule implémentation** :
+le gateway les applique en sortie, et le bot doit pouvoir savoir *avant d'envoyer* ce qui
+sera posé. Deux implémentations, c'est la garantie qu'un émetteur croira un jour avoir posé
+autre chose que ce qui l'a été — ce qui s'est produit, et se paie sur un stop loss.
+
+Trois conséquences pour qui touche à ce dossier :
+
+* **aucune dépendance**, ici moins qu'ailleurs : le consommateur de ce code est le processus
+  qui signe les transactions ;
+* **rien ne passe par `Number`** — tout le calcul se fait sur les chiffres écrits, en
+  `BigInt` ;
+* **la conformité se prouve** : `test/tick-and-lot.spec.ts` rejoue *tous* les exemples de la
+  documentation, sourcés et datés. `npm run build` lance les tests avant de compiler — une
+  logique exécutable non testée ne se publie pas.
+
+```bash
+npm test
+```
 
 ---
 

package/dist/format/index.d.ts

@@ -0,0 +1 @@
+export * from './tick-and-lot';

package/dist/format/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./tick-and-lot"), exports);

package/dist/format/tick-and-lot.d.ts

@@ -0,0 +1,89 @@
+/**
+ * ============================================================================
+ * PRIX ET TAILLES : LES RÈGLES DE TICK ET DE LOT D'HYPERLIQUID
+ *
+ * Source : https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size
+ * relevée le 2026-09-23. Deux règles, et une exception :
+ *
+ * - **taille** : tronquée à `szDecimals`, propre à chaque actif (réponse `meta`) ;
+ * - **prix** : au plus 5 chiffres significatifs, ET au plus
+ *   `MAX_DECIMALS - szDecimals` décimales, `MAX_DECIMALS` valant 6 en perp et
+ *   8 en spot ;
+ * - **un prix entier est toujours accepté**, quel que soit son nombre de
+ *   chiffres significatifs (`123456` est valide là où `12345.6` ne l'est pas).
+ *
+ * Ce module vit ici, et non dans le gateway ou le bot, pour qu'il n'en existe
+ * **qu'une seule implémentation** : un prix mal écrit est refusé par
+ * Hyperliquid, ou accepté sous une forme tronquée qui n'est plus celle qu'on
+ * voulait. Sur un stop loss, la différence entre les deux, c'est une position
+ * protégée et une position qui ne l'est pas. Deux implémentations, c'est la
+ * garantie qu'un émetteur croira un jour avoir posé autre chose que ce qui
+ * l'a été.
+ *
+ * ⚠️ Un faux gateway de test, lui, doit garder sa **copie indépendante** : s'il
+ * importait ces fonctions, un défaut s'y annulerait des deux côtés et aucun
+ * test ne le verrait.
+ *
+ * Rien ne passe par `Number` : tout le calcul se fait sur les chiffres écrits,
+ * en `BigInt`. Un `parseFloat` réintroduirait exactement l'erreur d'arrondi que
+ * ces règles servent à éviter.
+ * ============================================================================
+ */
+/** Marché visé : les deux n'ont pas le même plafond de décimales. */
+export type HLMarketType = 'perp' | 'spot';
+/**
+ * Sens de l'arrondi. `truncate` va vers zéro — c'est ce que fait Hyperliquid,
+ * et le seul sens autorisé pour une taille. `up` et `down` vont vers +∞ et
+ * −∞, ce qui ne diffère de `truncate` que sur une valeur négative.
+ */
+export type RoundingMode = 'truncate' | 'up' | 'down' | 'nearest';
+/** Levée plutôt que de rendre une valeur que l'exchange refuserait. */
+export declare class TickAndLotError extends Error {
+    constructor(message: string);
+}
+/** `MAX_DECIMALS` de la documentation, par type de marché. */
+export declare const MAX_PRICE_DECIMALS: Readonly<Record<HLMarketType, number>>;
+/** Le plafond de chiffres significatifs d'un prix non entier. */
+export declare const MAX_PRICE_SIGNIFICANT_DIGITS = 5;
+/**
+ * Arrondit une valeur à `decimals` décimales, dans le sens demandé, sans
+ * jamais passer par un flottant.
+ */
+export declare function roundDecimal(value: string | number, decimals: number, mode?: RoundingMode): string;
+/**
+ * Le nombre de décimales que ce prix a le droit d'avoir — les deux règles
+ * réunies en un seul nombre.
+ *
+ * Le plancher à zéro **est** l'exception des entiers : quand les chiffres
+ * significatifs en réclameraient moins que zéro décimale (un prix au-delà de
+ * 99 999), la documentation autorise malgré tout n'importe quel entier, donc
+ * on s'arrête à l'entier plutôt que de raboter aussi les unités.
+ */
+export declare function priceDecimals(price: string | number, szDecimals: number, type?: HLMarketType): number;
+/**
+ * Le prix, réécrit comme Hyperliquid l'accepte : tronqué à ce que
+ * `priceDecimals` autorise.
+ *
+ * @throws {TickAndLotError} si la valeur est illisible, ou tronquée à zéro.
+ */
+export declare function formatPrice(price: string | number, szDecimals: number, type?: HLMarketType): string;
+/**
+ * La taille, réécrite comme Hyperliquid l'accepte : **tronquée** à
+ * `szDecimals`, jamais arrondie. Arrondir vers le haut, ce serait trader plus
+ * que ce qui a été calculé — dépasser une position sur un ordre `reduceOnly`,
+ * ou le collatéral sur une ouverture.
+ *
+ * @throws {TickAndLotError} si la valeur est illisible, ou tronquée à zéro.
+ */
+export declare function formatSize(size: string | number, szDecimals: number): string;
+/**
+ * Pose un prix sur la grille de l'actif **dans un sens choisi**, et garantit
+ * que le résultat en est un point fixe : `formatPrice(snapPrice(p)) === snapPrice(p)`.
+ *
+ * C'est ce que `formatPrice` seul ne sait pas faire — il tronque toujours.
+ * Un émetteur qui veut qu'un stop ne s'éloigne jamais de son ancre a besoin du
+ * sens opposé, et il a besoin que le formatage final ne défasse pas ce choix.
+ *
+ * @throws {TickAndLotError} si la valeur est illisible, ou ramenée à zéro.
+ */
+export declare function snapPrice(price: string | number, szDecimals: number, type?: HLMarketType, mode?: RoundingMode): string;

package/dist/format/tick-and-lot.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * ============================================================================
+ * PRIX ET TAILLES : LES RÈGLES DE TICK ET DE LOT D'HYPERLIQUID
+ *
+ * Source : https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/tick-and-lot-size
+ * relevée le 2026-09-23. Deux règles, et une exception :
+ *
+ * - **taille** : tronquée à `szDecimals`, propre à chaque actif (réponse `meta`) ;
+ * - **prix** : au plus 5 chiffres significatifs, ET au plus
+ *   `MAX_DECIMALS - szDecimals` décimales, `MAX_DECIMALS` valant 6 en perp et
+ *   8 en spot ;
+ * - **un prix entier est toujours accepté**, quel que soit son nombre de
+ *   chiffres significatifs (`123456` est valide là où `12345.6` ne l'est pas).
+ *
+ * Ce module vit ici, et non dans le gateway ou le bot, pour qu'il n'en existe
+ * **qu'une seule implémentation** : un prix mal écrit est refusé par
+ * Hyperliquid, ou accepté sous une forme tronquée qui n'est plus celle qu'on
+ * voulait. Sur un stop loss, la différence entre les deux, c'est une position
+ * protégée et une position qui ne l'est pas. Deux implémentations, c'est la
+ * garantie qu'un émetteur croira un jour avoir posé autre chose que ce qui
+ * l'a été.
+ *
+ * ⚠️ Un faux gateway de test, lui, doit garder sa **copie indépendante** : s'il
+ * importait ces fonctions, un défaut s'y annulerait des deux côtés et aucun
+ * test ne le verrait.
+ *
+ * Rien ne passe par `Number` : tout le calcul se fait sur les chiffres écrits,
+ * en `BigInt`. Un `parseFloat` réintroduirait exactement l'erreur d'arrondi que
+ * ces règles servent à éviter.
+ * ============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PRICE_SIGNIFICANT_DIGITS = exports.MAX_PRICE_DECIMALS = exports.TickAndLotError = void 0;
+exports.roundDecimal = roundDecimal;
+exports.priceDecimals = priceDecimals;
+exports.formatPrice = formatPrice;
+exports.formatSize = formatSize;
+exports.snapPrice = snapPrice;
+/** Levée plutôt que de rendre une valeur que l'exchange refuserait. */
+class TickAndLotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TickAndLotError';
+    }
+}
+exports.TickAndLotError = TickAndLotError;
+/** `MAX_DECIMALS` de la documentation, par type de marché. */
+exports.MAX_PRICE_DECIMALS = {
+    perp: 6,
+    spot: 8,
+};
+/** Le plafond de chiffres significatifs d'un prix non entier. */
+exports.MAX_PRICE_SIGNIFICANT_DIGITS = 5;
+/** Un décimal simple, signe optionnel : `12`, `-0.5`, `.75`, `3.`. */
+const PLAIN_DECIMAL = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
+const EXPONENTIAL = /^([+-]?)(\d+)(?:\.(\d+))?[eE]([+-]?\d+)$/;
+/**
+ * Réécrit une notation scientifique en décimal simple. `String(0.0000001)`
+ * rend `'1e-7'`, que la documentation n'accepte pas et que nous refuserions
+ * plus loin : autant l'écrire correctement ici.
+ */
+function expandExponential(text) {
+    const match = EXPONENTIAL.exec(text);
+    if (!match)
+        return text;
+    const [, sign, int, frac = '', exponentText] = match;
+    const digits = `${int}${frac}`;
+    const pointIndex = int.length + Number(exponentText);
+    if (pointIndex <= 0) {
+        return `${sign}0.${'0'.repeat(-pointIndex)}${digits}`;
+    }
+    if (pointIndex >= digits.length) {
+        return `${sign}${digits}${'0'.repeat(pointIndex - digits.length)}`;
+    }
+    return `${sign}${digits.slice(0, pointIndex)}.${digits.slice(pointIndex)}`;
+}
+/**
+ * Rend le texte décimal d'une valeur.
+ *
+ * Un `number` est une valeur **calculée** : on l'écrit exactement, notation
+ * scientifique dépliée. Une `string` est un texte qui vient déjà d'ailleurs —
+ * d'un DTO, de l'API — et doit donc être un décimal simple : une notation
+ * scientifique y signale qu'un flottant s'est glissé en amont, et la laisser
+ * passer masquerait le défaut.
+ */
+function toDecimalText(value, field) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new TickAndLotError(`${field} is not finite: ${String(value)}`);
+        }
+        return expandExponential(String(value));
+    }
+    const text = String(value).trim();
+    if (!PLAIN_DECIMAL.test(text)) {
+        throw new TickAndLotError(`${field} is not a plain decimal string: ${JSON.stringify(value)}`);
+    }
+    return text;
+}
+function split(text) {
+    const negative = text.startsWith('-');
+    const [int = '', frac = ''] = text.replace(/^[+-]/, '').split('.');
+    return { negative, int: int || '0', frac };
+}
+/** Réécrit une valeur mise à l'échelle, sans zéro de queue ni `-0`. */
+function formatUnits(negative, units, decimals) {
+    const digits = units.toString().padStart(decimals + 1, '0');
+    const int = digits.slice(0, digits.length - decimals);
+    const frac = decimals > 0 ? digits.slice(digits.length - decimals).replace(/0+$/, '') : '';
+    const body = frac ? `${int}.${frac}` : int;
+    return negative && units !== 0n ? `-${body}` : body;
+}
+function assertWholeCount(value, field) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new TickAndLotError(`${field} must be a non-negative integer: ${String(value)}`);
+    }
+}
+/**
+ * L'exposant décimal de la valeur — `2` pour 345, `-3` pour 0,001234 — ou
+ * `null` pour zéro, qui n'en a pas.
+ */
+function log10Floor(text) {
+    const { int, frac } = split(text);
+    const significantInt = int.replace(/^0+/, '');
+    if (significantInt)
+        return significantInt.length - 1;
+    const leadingZeros = /^0*/.exec(frac)?.[0].length ?? 0;
+    if (leadingZeros === frac.length)
+        return null;
+    return -(leadingZeros + 1);
+}
+/**
+ * Arrondit une valeur à `decimals` décimales, dans le sens demandé, sans
+ * jamais passer par un flottant.
+ */
+function roundDecimal(value, decimals, mode = 'truncate') {
+    assertWholeCount(decimals, 'decimals');
+    const { negative, int, frac } = split(toDecimalText(value, 'value'));
+    const kept = frac.slice(0, decimals).padEnd(decimals, '0');
+    const dropped = frac.slice(decimals);
+    let units = BigInt(`${int}${kept}`);
+    if (/[1-9]/.test(dropped)) {
+        const awayFromZero = mode === 'nearest'
+            ? dropped.charAt(0) >= '5'
+            : mode === 'up'
+                ? !negative
+                : mode === 'down'
+                    ? negative
+                    : false;
+        if (awayFromZero)
+            units += 1n;
+    }
+    return formatUnits(negative, units, decimals);
+}
+/**
+ * Le nombre de décimales que ce prix a le droit d'avoir — les deux règles
+ * réunies en un seul nombre.
+ *
+ * Le plancher à zéro **est** l'exception des entiers : quand les chiffres
+ * significatifs en réclameraient moins que zéro décimale (un prix au-delà de
+ * 99 999), la documentation autorise malgré tout n'importe quel entier, donc
+ * on s'arrête à l'entier plutôt que de raboter aussi les unités.
+ */
+function priceDecimals(price, szDecimals, type = 'perp') {
+    assertWholeCount(szDecimals, 'szDecimals');
+    const byDecimals = Math.max(exports.MAX_PRICE_DECIMALS[type] - szDecimals, 0);
+    const magnitude = log10Floor(toDecimalText(price, 'price'));
+    if (magnitude === null)
+        return byDecimals;
+    const bySignificantDigits = exports.MAX_PRICE_SIGNIFICANT_DIGITS - 1 - magnitude;
+    return Math.min(byDecimals, Math.max(bySignificantDigits, 0));
+}
+/**
+ * Le prix, réécrit comme Hyperliquid l'accepte : tronqué à ce que
+ * `priceDecimals` autorise.
+ *
+ * @throws {TickAndLotError} si la valeur est illisible, ou tronquée à zéro.
+ */
+function formatPrice(price, szDecimals, type = 'perp') {
+    const decimals = priceDecimals(price, szDecimals, type);
+    const formatted = roundDecimal(price, decimals, 'truncate');
+    if (formatted === '0') {
+        throw new TickAndLotError('Price is too small and was truncated to 0');
+    }
+    return formatted;
+}
+/**
+ * La taille, réécrite comme Hyperliquid l'accepte : **tronquée** à
+ * `szDecimals`, jamais arrondie. Arrondir vers le haut, ce serait trader plus
+ * que ce qui a été calculé — dépasser une position sur un ordre `reduceOnly`,
+ * ou le collatéral sur une ouverture.
+ *
+ * @throws {TickAndLotError} si la valeur est illisible, ou tronquée à zéro.
+ */
+function formatSize(size, szDecimals) {
+    assertWholeCount(szDecimals, 'szDecimals');
+    const formatted = roundDecimal(size, szDecimals, 'truncate');
+    if (formatted === '0') {
+        throw new TickAndLotError('Size is too small and was truncated to 0');
+    }
+    return formatted;
+}
+/**
+ * Pose un prix sur la grille de l'actif **dans un sens choisi**, et garantit
+ * que le résultat en est un point fixe : `formatPrice(snapPrice(p)) === snapPrice(p)`.
+ *
+ * C'est ce que `formatPrice` seul ne sait pas faire — il tronque toujours.
+ * Un émetteur qui veut qu'un stop ne s'éloigne jamais de son ancre a besoin du
+ * sens opposé, et il a besoin que le formatage final ne défasse pas ce choix.
+ *
+ * @throws {TickAndLotError} si la valeur est illisible, ou ramenée à zéro.
+ */
+function snapPrice(price, szDecimals, type = 'perp', mode = 'truncate') {
+    const snapped = roundDecimal(price, priceDecimals(price, szDecimals, type), mode);
+    // Un arrondi vers l'extérieur peut franchir un palier — 9,9999 devient 10 —
+    // et la grille change avec l'ordre de grandeur. On la recalcule une fois.
+    const settled = roundDecimal(snapped, priceDecimals(snapped, szDecimals, type), mode);
+    if (settled === '0') {
+        throw new TickAndLotError('Price is too small and was snapped to 0');
+    }
+    if (formatPrice(settled, szDecimals, type) !== settled) {
+        throw new TickAndLotError(`snapPrice produced ${settled}, which is not on the grid for szDecimals ${szDecimals}`);
+    }
+    return settled;
+}

package/dist/index.d.ts

@@ -1 +1,2 @@
 export * from './interfaces';
+export * from './format';

package/dist/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./interfaces"), exports);
+__exportStar(require("./format"), exports);

package/package.json

@@ -1,50 +1,54 @@
-{
-  "name": "@syldel/hl-shared-types",
-  "version": "0.0.16",
-  "description": "Shared TypeScript interfaces and types for Hyperliquid integration.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Syldel/hl-shared-types.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Syldel/hl-shared-types/issues"
-  },
-  "homepage": "https://github.com/Syldel/hl-shared-types#readme",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "clean": "rm -rf dist",
-    "build": "npm run lint && npm run clean && tsc",
-    "prepublishOnly": "npm run build",
-    "release": "npm run build && npm version patch && npm publish"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "hyperliquid",
-    "trading",
-    "types",
-    "interfaces",
-    "crypto",
-    "exchange",
-    "defi"
-  ],
-  "author": "Syl. D.",
-  "license": "ISC",
-  "devDependencies": {
-    "eslint": "^9.39.2",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jsonc": "^2.21.0",
-    "eslint-plugin-prettier": "^5.5.5",
-    "jsonc-eslint-parser": "^2.4.2",
-    "prettier": "^3.8.0",
-    "typescript": "^5.3.3",
-    "typescript-eslint": "^8.53.0"
-  }
-}
+{
+  "name": "@syldel/hl-shared-types",
+  "version": "0.0.17",
+  "description": "Shared TypeScript interfaces and types for Hyperliquid integration.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Syldel/hl-shared-types.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Syldel/hl-shared-types/issues"
+  },
+  "homepage": "https://github.com/Syldel/hl-shared-types#readme",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "clean": "rm -rf dist",
+    "build": "npm run lint && npm run test && npm run clean && tsc",
+    "prepublishOnly": "npm run build",
+    "release": "npm run build && npm version patch && npm publish"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "hyperliquid",
+    "trading",
+    "types",
+    "interfaces",
+    "crypto",
+    "exchange",
+    "defi"
+  ],
+  "author": "Syl. D.",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsonc": "^2.21.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "jest": "^30.5.2",
+    "jsonc-eslint-parser": "^2.4.2",
+    "prettier": "^3.8.0",
+    "ts-jest": "^29.4.13",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.53.0"
+  }
+}