orderflow-metrics 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 This project follows [Semantic Versioning](https://semver.org/); pre-1.0 the
 public API may still change between minor versions.
 
+## [0.28.0] - 2026-08-29
+
+### Added
+- Book-depth liquidity (`bookdepth`) — `depthWithin` (resting size within ±bps
+  of mid, split by side), `orderBookSlope` (cumulative size per unit of relative
+  price distance — how steeply the book thickens away from mid), and
+  `costOfRoundTrip` (the basis-point "liquidity tax" of buying then selling a
+  given size, walking both sides of the book). Snapshot statistics of the
+  *standing* book, complementing `amihudIlliquidity` (impact over time) and
+  `simulateMarketOrder` (a single execution). Operate on plain `Level[]` arrays
+  sorted best-first. Test suite included. (Python: 0.16.0.)
+
 ## [0.27.0] - 2026-08-28
 
 ### Added

package/README.md

@@ -237,6 +237,27 @@ r.slippageBps;   // cost vs mid, in basis points
 r.remainingSize; // > 0 if the book was too thin
 ```
 
+### Book-depth liquidity
+
+Read liquidity off a book snapshot — near-touch depth, how steeply the book
+thickens away from mid, and the round-trip cost of a given size. Take plain
+`Level[]` arrays sorted best-first (bids high→low, asks low→high):
+
+```ts
+import { depthWithin, orderBookSlope, costOfRoundTrip } from "orderflow-metrics";
+
+const bids = [{ price: 99.95, size: 6 }, { price: 99.9, size: 10 }];
+const asks = [{ price: 100.0, size: 5 }, { price: 100.05, size: 8 }];
+
+depthWithin(bids, asks, 10);     // { bidDepth, askDepth, total } within ±10 bps of mid
+orderBookSlope(asks, 99.975);    // cumulative size per unit of relative price move
+costOfRoundTrip(bids, asks, 15); // { roundTripBps, avgBuyPrice, avgSellPrice, filledSize }
+```
+
+- `depthWithin` — resting size within ±bps of mid, split by side
+- `orderBookSlope` — (Σ size) / (relative distance to the outermost level)
+- `costOfRoundTrip` — basis-point liquidity tax of buying then selling `size`
+
 ## Execution scheduling
 
 Split a parent order into child slices:

package/dist/bookdepth.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Book-depth liquidity metrics — reading liquidity straight off a limit-order
+ * book snapshot.
+ *
+ * Where `amihudIlliquidity` (see `liquidity.ts`) measures liquidity from
+ * realized price impact over time, these functions measure it from the *shape*
+ * of the resting book at a single instant: how much size is quoted near the
+ * touch, how steeply depth thickens away from mid, and what a round trip would
+ * actually cost. They complement `simulateMarketOrder` (which walks the book
+ * for one execution): these are summary statistics of the standing book, not a
+ * fill simulation.
+ *
+ * Every function takes plain `Level[]` arrays sorted best-first — bids by
+ * descending price, asks by ascending price — exactly as `OrderBook.depth()`
+ * returns them.
+ */
+import type { Level } from "./orderbook.ts";
+/** Resting size available within a price band around the mid. */
+export interface DepthWithin {
+    /** total bid size within the band */
+    bidDepth: number;
+    /** total ask size within the band */
+    askDepth: number;
+    /** bidDepth + askDepth */
+    total: number;
+}
+/**
+ * Total resting size within `±bps` of the mid price, split by side.
+ *
+ * A snapshot of near-touch liquidity: how much can trade close to the current
+ * price before walking into deeper, worse-priced levels. The band half-width is
+ * `mid · bps / 10_000`, applied symmetrically. Levels must be sorted best-first.
+ * Returns zeros if either side is empty (no mid) or `bps <= 0`.
+ */
+export declare function depthWithin(bids: readonly Level[], asks: readonly Level[], bps: number): DepthWithin;
+/**
+ * Order-book slope: cumulative resting size divided by the relative price
+ * distance from `refPrice` to the outermost supplied level.
+ *
+ *   slope = (Σ size) / ( |P_last − refPrice| / refPrice )
+ *
+ * It answers "how much size is packed per unit of relative price move" — a
+ * steeper (larger) slope means depth builds up quickly near the reference
+ * price, i.e. a thicker, more liquid book. Pass one side's levels (best-first)
+ * and a reference price (typically the mid). Returns 0 for empty input, a
+ * non-positive `refPrice`, or when the outermost level sits at the reference
+ * price (zero distance).
+ */
+export declare function orderBookSlope(levels: readonly Level[], refPrice: number): number;
+/** The cost of buying then selling the same size against the standing book. */
+export interface RoundTripCost {
+    /** size-weighted average price paid buying `size` from the asks */
+    avgBuyPrice: number;
+    /** size-weighted average price received selling `size` into the bids */
+    avgSellPrice: number;
+    /** round-trip cost in basis points of mid: (avgBuy − avgSell) / mid · 10⁴ */
+    roundTripBps: number;
+    /** size actually round-tripped (min of the fill each side supports) */
+    filledSize: number;
+}
+/**
+ * Round-trip liquidity cost: the basis-point gap between the VWAP of buying
+ * `size` from the asks and the VWAP of selling `size` into the bids, measured
+ * against the mid. This is the immediate "liquidity tax" of entering and
+ * exiting a position of `size` — spread plus the price impact of walking both
+ * sides of the book.
+ *
+ * Levels must be sorted best-first. `filledSize` is the smaller of the two
+ * sides' fills, so a book too thin on one side reports how much actually
+ * round-tripped. Returns zeros if either side is empty or `size <= 0`.
+ */
+export declare function costOfRoundTrip(bids: readonly Level[], asks: readonly Level[], size: number): RoundTripCost;
+//# sourceMappingURL=bookdepth.d.ts.map

package/dist/bookdepth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bookdepth.d.ts","sourceRoot":"","sources":["../src/bookdepth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf;AAOD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,KAAK,EAAE,EACtB,IAAI,EAAE,SAAS,KAAK,EAAE,EACtB,GAAG,EAAE,MAAM,GACV,WAAW,CAWb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,QAAQ,EAAE,MAAM,GACf,MAAM,CAOR;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;CACpB;AAmBD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,KAAK,EAAE,EACtB,IAAI,EAAE,SAAS,KAAK,EAAE,EACtB,IAAI,EAAE,MAAM,GACX,aAAa,CAoBf"}

package/dist/bookdepth.js

@@ -0,0 +1,119 @@
+/**
+ * Book-depth liquidity metrics — reading liquidity straight off a limit-order
+ * book snapshot.
+ *
+ * Where `amihudIlliquidity` (see `liquidity.ts`) measures liquidity from
+ * realized price impact over time, these functions measure it from the *shape*
+ * of the resting book at a single instant: how much size is quoted near the
+ * touch, how steeply depth thickens away from mid, and what a round trip would
+ * actually cost. They complement `simulateMarketOrder` (which walks the book
+ * for one execution): these are summary statistics of the standing book, not a
+ * fill simulation.
+ *
+ * Every function takes plain `Level[]` arrays sorted best-first — bids by
+ * descending price, asks by ascending price — exactly as `OrderBook.depth()`
+ * returns them.
+ */
+function mid(bids, asks) {
+    if (bids.length === 0 || asks.length === 0)
+        return null;
+    return (bids[0].price + asks[0].price) / 2;
+}
+/**
+ * Total resting size within `±bps` of the mid price, split by side.
+ *
+ * A snapshot of near-touch liquidity: how much can trade close to the current
+ * price before walking into deeper, worse-priced levels. The band half-width is
+ * `mid · bps / 10_000`, applied symmetrically. Levels must be sorted best-first.
+ * Returns zeros if either side is empty (no mid) or `bps <= 0`.
+ */
+export function depthWithin(bids, asks, bps) {
+    const m = mid(bids, asks);
+    if (m === null || bps <= 0)
+        return { bidDepth: 0, askDepth: 0, total: 0 };
+    const band = (m * bps) / 10_000;
+    const lo = m - band;
+    const hi = m + band;
+    let bidDepth = 0;
+    for (const l of bids)
+        if (l.price >= lo)
+            bidDepth += l.size;
+    let askDepth = 0;
+    for (const l of asks)
+        if (l.price <= hi)
+            askDepth += l.size;
+    return { bidDepth, askDepth, total: bidDepth + askDepth };
+}
+/**
+ * Order-book slope: cumulative resting size divided by the relative price
+ * distance from `refPrice` to the outermost supplied level.
+ *
+ *   slope = (Σ size) / ( |P_last − refPrice| / refPrice )
+ *
+ * It answers "how much size is packed per unit of relative price move" — a
+ * steeper (larger) slope means depth builds up quickly near the reference
+ * price, i.e. a thicker, more liquid book. Pass one side's levels (best-first)
+ * and a reference price (typically the mid). Returns 0 for empty input, a
+ * non-positive `refPrice`, or when the outermost level sits at the reference
+ * price (zero distance).
+ */
+export function orderBookSlope(levels, refPrice) {
+    if (levels.length === 0 || refPrice <= 0)
+        return 0;
+    let cum = 0;
+    for (const l of levels)
+        cum += l.size;
+    const dist = Math.abs(levels[levels.length - 1].price - refPrice) / refPrice;
+    if (dist === 0)
+        return 0;
+    return cum / dist;
+}
+function vwapFill(levels, size) {
+    let remaining = size;
+    let notional = 0;
+    let filled = 0;
+    for (const l of levels) {
+        if (remaining <= 0)
+            break;
+        const take = Math.min(remaining, l.size);
+        notional += take * l.price;
+        filled += take;
+        remaining -= take;
+    }
+    return { notional, filled };
+}
+/**
+ * Round-trip liquidity cost: the basis-point gap between the VWAP of buying
+ * `size` from the asks and the VWAP of selling `size` into the bids, measured
+ * against the mid. This is the immediate "liquidity tax" of entering and
+ * exiting a position of `size` — spread plus the price impact of walking both
+ * sides of the book.
+ *
+ * Levels must be sorted best-first. `filledSize` is the smaller of the two
+ * sides' fills, so a book too thin on one side reports how much actually
+ * round-tripped. Returns zeros if either side is empty or `size <= 0`.
+ */
+export function costOfRoundTrip(bids, asks, size) {
+    const m = mid(bids, asks);
+    const zero = {
+        avgBuyPrice: 0,
+        avgSellPrice: 0,
+        roundTripBps: 0,
+        filledSize: 0,
+    };
+    if (m === null || size <= 0)
+        return zero;
+    const buy = vwapFill(asks, size);
+    const sell = vwapFill(bids, size);
+    if (buy.filled === 0 || sell.filled === 0)
+        return zero;
+    const avgBuyPrice = buy.notional / buy.filled;
+    const avgSellPrice = sell.notional / sell.filled;
+    return {
+        avgBuyPrice,
+        avgSellPrice,
+        roundTripBps: ((avgBuyPrice - avgSellPrice) / m) * 10_000,
+        filledSize: Math.min(buy.filled, sell.filled),
+    };
+}
+//# sourceMappingURL=bookdepth.js.map

package/dist/bookdepth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bookdepth.js","sourceRoot":"","sources":["../src/bookdepth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAcH,SAAS,GAAG,CAAC,IAAsB,EAAE,IAAsB;IACzD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,IAAsB,EACtB,IAAsB,EACtB,GAAW;IAEX,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1B,IAAI,CAAC,KAAK,IAAI,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC1E,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,MAAM,CAAC;IAChC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IACpB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE;YAAE,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC;IAC5D,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE;YAAE,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC;IAC5D,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAwB,EACxB,QAAgB;IAEhB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACnD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC,GAAG,QAAQ,CAAC;IAC7E,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACzB,OAAO,GAAG,GAAG,IAAI,CAAC;AACpB,CAAC;AAcD,SAAS,QAAQ,CACf,MAAwB,EACxB,IAAY;IAEZ,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,SAAS,IAAI,CAAC;YAAE,MAAM;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACzC,QAAQ,IAAI,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC;QAC3B,MAAM,IAAI,IAAI,CAAC;QACf,SAAS,IAAI,IAAI,CAAC;IACpB,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAsB,EACtB,IAAsB,EACtB,IAAY;IAEZ,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1B,MAAM,IAAI,GAAkB;QAC1B,WAAW,EAAE,CAAC;QACd,YAAY,EAAE,CAAC;QACf,YAAY,EAAE,CAAC;QACf,UAAU,EAAE,CAAC;KACd,CAAC;IACF,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,WAAW,GAAG,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC;IAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC;IACjD,OAAO;QACL,WAAW;QACX,YAAY;QACZ,YAAY,EAAE,CAAC,CAAC,WAAW,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM;QACzD,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -16,6 +16,8 @@ export type { BookSide, Level } from "./orderbook.ts";
 export { OrderBook } from "./orderbook.ts";
 export type { Fill, MarketOrderResult } from "./simulate.ts";
 export { simulateMarketOrder } from "./simulate.ts";
+export type { DepthWithin, RoundTripCost } from "./bookdepth.ts";
+export { depthWithin, orderBookSlope, costOfRoundTrip, } from "./bookdepth.ts";
 export { twap, pov } from "./scheduling.ts";
 export type { Bar } from "./bars.ts";
 export { tickBars, volumeBars, dollarBars } from "./bars.ts";

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -9,6 +9,7 @@ export { realizedVariance, realizedVolatility, annualizedVolatility, } from "./v
 export { autocorrelation, varianceRatio } from "./efficiency.js";
 export { OrderBook } from "./orderbook.js";
 export { simulateMarketOrder } from "./simulate.js";
+export { depthWithin, orderBookSlope, costOfRoundTrip, } from "./bookdepth.js";
 export { twap, pov } from "./scheduling.js";
 export { tickBars, volumeBars, dollarBars } from "./bars.js";
 export { squareRootImpact, linearPermanentImpact, linearTemporaryImpact, almgrenChrissCost, markout, averageMarkout, } from "./impact.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EACL,IAAI,EACJ,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEjE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,OAAO,EACP,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAElE,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,OAAO,EACP,IAAI,EACJ,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EACL,IAAI,EACJ,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEjE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EACL,WAAW,EACX,cAAc,EACd,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,OAAO,EACP,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAElE,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,OAAO,EACP,IAAI,EACJ,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,GACb,MAAM,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orderflow-metrics",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Microstructure metrics in dependency-free TypeScript — OFI, VPIN, information-driven bars, market impact (square-root & Almgren-Chriss), markouts, implementation shortfall, high-low spread estimators (Corwin-Schultz, Abdi-Ranaldo), range-based volatility (Parkinson, Garman-Klass, Rogers-Satchell, Yang-Zhang), Hurst exponent, realized skewness & kurtosis, bipower variation & jump detection, jump-robust variance (MinRV, MedRV) & realized quarticity, realized semivariance & signed jump variation, order-flow entropy, online/streaming estimators (Welford, EWMA, rolling window), realized covariance/correlation/beta, microstructure-noise-robust variance (subsampling, volatility signature, two-scale realized variance), Kyle's lambda, trade-sign classification, Amihud illiquidity.",
   "type": "module",
   "main": "./dist/index.js",

package/src/bookdepth.ts

@@ -0,0 +1,149 @@
+/**
+ * Book-depth liquidity metrics — reading liquidity straight off a limit-order
+ * book snapshot.
+ *
+ * Where `amihudIlliquidity` (see `liquidity.ts`) measures liquidity from
+ * realized price impact over time, these functions measure it from the *shape*
+ * of the resting book at a single instant: how much size is quoted near the
+ * touch, how steeply depth thickens away from mid, and what a round trip would
+ * actually cost. They complement `simulateMarketOrder` (which walks the book
+ * for one execution): these are summary statistics of the standing book, not a
+ * fill simulation.
+ *
+ * Every function takes plain `Level[]` arrays sorted best-first — bids by
+ * descending price, asks by ascending price — exactly as `OrderBook.depth()`
+ * returns them.
+ */
+
+import type { Level } from "./orderbook.ts";
+
+/** Resting size available within a price band around the mid. */
+export interface DepthWithin {
+  /** total bid size within the band */
+  bidDepth: number;
+  /** total ask size within the band */
+  askDepth: number;
+  /** bidDepth + askDepth */
+  total: number;
+}
+
+function mid(bids: readonly Level[], asks: readonly Level[]): number | null {
+  if (bids.length === 0 || asks.length === 0) return null;
+  return (bids[0].price + asks[0].price) / 2;
+}
+
+/**
+ * Total resting size within `±bps` of the mid price, split by side.
+ *
+ * A snapshot of near-touch liquidity: how much can trade close to the current
+ * price before walking into deeper, worse-priced levels. The band half-width is
+ * `mid · bps / 10_000`, applied symmetrically. Levels must be sorted best-first.
+ * Returns zeros if either side is empty (no mid) or `bps <= 0`.
+ */
+export function depthWithin(
+  bids: readonly Level[],
+  asks: readonly Level[],
+  bps: number,
+): DepthWithin {
+  const m = mid(bids, asks);
+  if (m === null || bps <= 0) return { bidDepth: 0, askDepth: 0, total: 0 };
+  const band = (m * bps) / 10_000;
+  const lo = m - band;
+  const hi = m + band;
+  let bidDepth = 0;
+  for (const l of bids) if (l.price >= lo) bidDepth += l.size;
+  let askDepth = 0;
+  for (const l of asks) if (l.price <= hi) askDepth += l.size;
+  return { bidDepth, askDepth, total: bidDepth + askDepth };
+}
+
+/**
+ * Order-book slope: cumulative resting size divided by the relative price
+ * distance from `refPrice` to the outermost supplied level.
+ *
+ *   slope = (Σ size) / ( |P_last − refPrice| / refPrice )
+ *
+ * It answers "how much size is packed per unit of relative price move" — a
+ * steeper (larger) slope means depth builds up quickly near the reference
+ * price, i.e. a thicker, more liquid book. Pass one side's levels (best-first)
+ * and a reference price (typically the mid). Returns 0 for empty input, a
+ * non-positive `refPrice`, or when the outermost level sits at the reference
+ * price (zero distance).
+ */
+export function orderBookSlope(
+  levels: readonly Level[],
+  refPrice: number,
+): number {
+  if (levels.length === 0 || refPrice <= 0) return 0;
+  let cum = 0;
+  for (const l of levels) cum += l.size;
+  const dist = Math.abs(levels[levels.length - 1].price - refPrice) / refPrice;
+  if (dist === 0) return 0;
+  return cum / dist;
+}
+
+/** The cost of buying then selling the same size against the standing book. */
+export interface RoundTripCost {
+  /** size-weighted average price paid buying `size` from the asks */
+  avgBuyPrice: number;
+  /** size-weighted average price received selling `size` into the bids */
+  avgSellPrice: number;
+  /** round-trip cost in basis points of mid: (avgBuy − avgSell) / mid · 10⁴ */
+  roundTripBps: number;
+  /** size actually round-tripped (min of the fill each side supports) */
+  filledSize: number;
+}
+
+function vwapFill(
+  levels: readonly Level[],
+  size: number,
+): { notional: number; filled: number } {
+  let remaining = size;
+  let notional = 0;
+  let filled = 0;
+  for (const l of levels) {
+    if (remaining <= 0) break;
+    const take = Math.min(remaining, l.size);
+    notional += take * l.price;
+    filled += take;
+    remaining -= take;
+  }
+  return { notional, filled };
+}
+
+/**
+ * Round-trip liquidity cost: the basis-point gap between the VWAP of buying
+ * `size` from the asks and the VWAP of selling `size` into the bids, measured
+ * against the mid. This is the immediate "liquidity tax" of entering and
+ * exiting a position of `size` — spread plus the price impact of walking both
+ * sides of the book.
+ *
+ * Levels must be sorted best-first. `filledSize` is the smaller of the two
+ * sides' fills, so a book too thin on one side reports how much actually
+ * round-tripped. Returns zeros if either side is empty or `size <= 0`.
+ */
+export function costOfRoundTrip(
+  bids: readonly Level[],
+  asks: readonly Level[],
+  size: number,
+): RoundTripCost {
+  const m = mid(bids, asks);
+  const zero: RoundTripCost = {
+    avgBuyPrice: 0,
+    avgSellPrice: 0,
+    roundTripBps: 0,
+    filledSize: 0,
+  };
+  if (m === null || size <= 0) return zero;
+  const buy = vwapFill(asks, size);
+  const sell = vwapFill(bids, size);
+  if (buy.filled === 0 || sell.filled === 0) return zero;
+  const avgBuyPrice = buy.notional / buy.filled;
+  const avgSellPrice = sell.notional / sell.filled;
+  return {
+    avgBuyPrice,
+    avgSellPrice,
+    roundTripBps: ((avgBuyPrice - avgSellPrice) / m) * 10_000,
+    filledSize: Math.min(buy.filled, sell.filled),
+  };
+}

package/src/index.ts

@@ -32,6 +32,12 @@ export type { BookSide, Level } from "./orderbook.ts";
 export { OrderBook } from "./orderbook.ts";
 export type { Fill, MarketOrderResult } from "./simulate.ts";
 export { simulateMarketOrder } from "./simulate.ts";
+export type { DepthWithin, RoundTripCost } from "./bookdepth.ts";
+export {
+  depthWithin,
+  orderBookSlope,
+  costOfRoundTrip,
+} from "./bookdepth.ts";
 export { twap, pov } from "./scheduling.ts";
 export type { Bar } from "./bars.ts";
 export { tickBars, volumeBars, dollarBars } from "./bars.ts";