logistics-ts

Explainable supply-chain algorithms for TypeScript: safety stock, reorder point, EOQ, ABC/XYZ classification, and demand forecasting (including intermittent-demand Croston/SBA/TSB) — dependency-light, and built for both humans and AI agents to read and trust.

[!WARNING] Under active development — pre-1.0. The public API is not yet stable.

Why

Every team building an MRP/ERP/inventory app re-implements the same supply-chain mathematics — safety stock, reorder points, EOQ, demand classification, intermittent-demand forecasting. logistics-ts provides those algorithms as small, well-typed, dependency-free packages so you can stop maintaining them yourself.

Every result is explainable: instead of a bare number, functions return the value alongside the method used, the inputs, and the reasoning:

{ value: 42, method: 'king-combined', inputs: {...}, reasoning: [...], citations: [...] }

That's true for both humans auditing a number and AI agents building on top of the library.

Install

npm i logistics-ts

This umbrella package re-exports everything under namespaces. Prefer the scoped packages — @logistics-ts/core, @logistics-ts/classification, @logistics-ts/forecasting, @logistics-ts/inventory — when you want the smallest install and best tree-shaking. ESM-only; requires Node ≥ 20 (also runs in the browser, edge, and Lambda).

Quick start

import { core, forecasting, inventory } from 'logistics-ts'

// No data yet? Generate a reproducible synthetic catalogue.
const { demand, leadTimes } = core.generateExampleData({ items: 5, seed: 42 })

// Dense, zero-filled monthly series for one item.
const series = core.bucketize(demand, 'month')[0]
const quantities = series.buckets.map((b) => b.quantity)

// Forecast next month — autoForecast classifies the demand pattern,
// backtests candidate methods, and picks the best by MASE.
const f = forecasting.autoForecast(quantities, { horizon: 1 })
console.log(f.value.forecast[0], f.method, f.reasoning)

// Size a safety stock (95% cycle service level) — 'auto' uses whatever
// variability data you supply (here demand only).
const ss = inventory.safetyStock(
  { meanDemand: core.mean(quantities), meanLeadTime: 1, demandStdDev: core.standardDeviation(quantities) },
  { method: 'auto', serviceLevel: 0.95 },
)
console.log(ss.value, ss.reasoning, ss.citations)

Every returned object is an Explained<T>: { value, method, inputs, reasoning, citations?, warnings? }. Read .value for the number; read the rest to explain, audit, or debug it.

For the whole "flag everything that needs reordering across a catalogue" flow in one call, see inventory.issues and the runnable examples/ in the repo.

For AI agents

This library is built to be consumed by coding agents. Beyond the rich TSDoc on every export:

• llms.txt — the entry point: what the library is, the API map, and links to everything below.
• AGENTS.md — a "which function for which problem" decision table and the full gotchas list.
• Shipped skills (in this package's skills/ directory, included in the npm tarball) — forecast-and-replenish and inventory-analysis are end-to-end recipes.
• examples/ — three runnable scripts in the repo.

Packages

| Package | Responsibility | |---------|----------------| | @logistics-ts/core | Types, column store, data loading, shared numerics, the Explained result wrapper | | @logistics-ts/forecasting | Moving average, exponential smoothing, Croston/SBA/TSB, auto method selection | | @logistics-ts/classification | ABC, XYZ, FSN, ABC-XYZ matrix, demand-pattern (SBC) classification | | @logistics-ts/inventory | Safety stock, reorder point, EOQ/EPQ, coverage, turnover, issue analysis | | logistics-ts (this package) | Umbrella package: re-exports everything under namespaces, adds InventoryAnalyzer, ships agent skills |

Dependency direction is enforced in CI as a strict layered order — each package may import only from lower layers:

core  →  classification  →  forecasting  →  inventory  →  logistics-ts

core has zero runtime dependencies; forecasting's auto method selection routes through classification (SBC demand patterns); inventory's auto safety stock builds on both.

Links

• Repository
• Issues
• Contributor guide (AGENTS.md)

License

MIT