@logistics-ts/classification 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,188 @@
+import { Explained, DemandSeries } from '@logistics-ts/core';
+
+/**
+ * ABC classification — a Pareto split of items by their contribution to total
+ * consumption value (or volume). A-items are the vital few that dominate the
+ * total and warrant the tightest inventory control; C-items are the trivial
+ * many.
+ *
+ * @see Silver, E.A., Pyke, D.F. & Thomas, D.J. (2017). Inventory and Production
+ *   Management in Supply Chains, 4th ed.
+ */
+
+/** An item to be ranked, with its annual volume and (optionally) unit value. */
+interface AbcItem {
+    itemId: string;
+    /** Annual consumption volume (units). */
+    volume: number;
+    /** Unit value/cost. Required when classifying `by: 'value'`. */
+    unitValue?: number;
+}
+interface AbcOptions {
+    /** Rank by consumption value (`volume × unitValue`) or by raw volume. Default `'value'`. */
+    by?: 'value' | 'volume';
+    /**
+     * Cumulative-share cutoffs `[aMax, bMax]` separating A|B and B|C. Defaults to
+     * the conventional `[0.8, 0.95]`. Cutoffs are convention, not theory.
+     */
+    cutoffs?: [number, number];
+}
+interface AbcClassification {
+    itemId: string;
+    class: 'A' | 'B' | 'C';
+    /** The ranked metric for this item (value or volume). */
+    metric: number;
+    /** This item's share of the total metric. */
+    share: number;
+    /** Cumulative share up to and including this item, in ranked order. */
+    cumulativeShare: number;
+}
+/**
+ * Classifies items into A/B/C by cumulative share of the ranked metric.
+ *
+ * @example
+ * ```ts
+ * abc([
+ *   { itemId: 'A', volume: 100, unitValue: 50 },
+ *   { itemId: 'B', volume: 500, unitValue: 1 },
+ * ]).value
+ * ```
+ */
+declare function abc(items: readonly AbcItem[], options?: AbcOptions): Explained<AbcClassification[]>;
+
+/**
+ * XYZ classification — groups items by demand variability, measured as the
+ * coefficient of variation (CV) of demand across periods. X-items have stable,
+ * predictable demand; Z-items are erratic and hard to forecast.
+ *
+ * Pair with {@link abc} (see {@link abcXyzMatrix}) to set inventory policy: the
+ * value axis says how much control an item deserves, the variability axis says
+ * how much buffer it needs.
+ */
+
+interface XyzOptions {
+    /**
+     * CV cutoffs `[xMax, yMax]` separating X|Y and Y|Z. Defaults to `[0.5, 1.0]`.
+     * Cutoffs are convention; tune them to your catalogue.
+     */
+    cutoffs?: [number, number];
+}
+interface XyzClassification {
+    itemId: string;
+    class: 'X' | 'Y' | 'Z';
+    /** Coefficient of variation of the item's per-period demand. */
+    coefficientOfVariation: number;
+}
+/**
+ * Classifies bucketed demand series into X/Y/Z by coefficient of variation.
+ * Feed the dense, zero-filled output of {@link bucketize} so the CV reflects the
+ * true period-to-period variability.
+ *
+ * An item with no demand (undefined CV) is classified `Z` with a warning.
+ */
+declare function xyz(series: readonly DemandSeries[], options?: XyzOptions): Explained<XyzClassification[]>;
+
+/**
+ * FSN classification — Fast-, Slow-, and Non-moving items by how frequently they
+ * see demand. It surfaces dead stock (N) and high-turnover items (F) that need
+ * different replenishment and review policies.
+ *
+ * This implementation measures **movement frequency** (the fraction of periods
+ * with demand) from a demand series alone. Turnover-based FSN (demand ÷ average
+ * stock) is an alternative that requires stock data and is a future addition.
+ */
+
+interface FsnOptions {
+    /**
+     * Movement-frequency boundary between Slow and Fast (fraction of periods with
+     * demand). Default 0.5. Items with no demand at all are Non-moving.
+     */
+    fastCutoff?: number;
+}
+interface FsnClassification {
+    itemId: string;
+    class: 'F' | 'S' | 'N';
+    /** Fraction of periods with demand (0 = never moved, 1 = every period). */
+    movementRatio: number;
+}
+/**
+ * Classifies bucketed demand series into Fast / Slow / Non-moving.
+ * Feed the dense, zero-filled output of {@link bucketize}.
+ */
+declare function fsn(series: readonly DemandSeries[], options?: FsnOptions): Explained<FsnClassification[]>;
+
+/**
+ * ABC-XYZ matrix — joins the value axis (ABC) with the variability axis (XYZ)
+ * into nine cells, each with a concrete inventory-policy hint. This is the
+ * payoff of running both classifications: it turns two labels into an action.
+ */
+
+/** A `${ABC}${XYZ}` cell label, e.g. `'AX'`. */
+type AbcXyzClass = 'AX' | 'AY' | 'AZ' | 'BX' | 'BY' | 'BZ' | 'CX' | 'CY' | 'CZ';
+interface AbcXyzCell {
+    itemId: string;
+    abc: AbcClassification['class'];
+    xyz: XyzClassification['class'];
+    class: AbcXyzClass;
+    /** Recommended inventory policy for this cell. */
+    policyHint: string;
+}
+/**
+ * Combines {@link abc} and {@link xyz} results into the nine-cell matrix. Items
+ * present in only one of the two inputs are skipped and reported as a warning.
+ *
+ * @example
+ * ```ts
+ * const cells = abcXyzMatrix(abc(items).value, xyz(series).value).value
+ * ```
+ */
+declare function abcXyzMatrix(abcResult: readonly AbcClassification[], xyzResult: readonly XyzClassification[]): Explained<AbcXyzCell[]>;
+
+/**
+ * Demand-pattern classification via the Syntetos–Boylan–Croston (SBC) scheme.
+ * Two statistics place a series in one of four quadrants:
+ *
+ * - **ADI** — average demand interval (periods per demand occurrence);
+ * - **CV²** — squared coefficient of variation of the non-zero demand sizes.
+ *
+ * The quadrant drives forecasting method selection (see M3): smooth/erratic
+ * series suit exponential smoothing, intermittent/lumpy series suit Croston and
+ * its variants.
+ *
+ * @see Syntetos, A.A., Boylan, J.E. & Croston, J.D. (2005). On the categorization
+ *   of demand patterns. Journal of the Operational Research Society, 56(5),
+ *   495–503.
+ */
+
+/** One of the four SBC demand patterns. */
+type DemandPattern = 'smooth' | 'erratic' | 'intermittent' | 'lumpy';
+interface DemandPatternOptions {
+    /** ADI boundary between frequent and intermittent demand. Default 1.32. */
+    adiCutoff?: number;
+    /** CV² boundary between stable and variable demand size. Default 0.49. */
+    cv2Cutoff?: number;
+}
+interface DemandPatternResult {
+    pattern: DemandPattern;
+    /** Average demand interval. */
+    adi: number;
+    /** Squared coefficient of variation of non-zero demand sizes. */
+    cv2: number;
+    /** Forecasting method families suited to this pattern (see M3). */
+    recommendedMethods: string[];
+}
+/**
+ * Classifies a demand series into an SBC pattern.
+ *
+ * @param series - Demand per period, **including zero periods** (use
+ *   {@link bucketize} from core to produce a dense, zero-filled series).
+ * @param options - Optional cutoff overrides.
+ *
+ * @example
+ * ```ts
+ * classifyDemandPattern([0, 4, 0, 0, 6, 0, 5]).value.pattern // 'intermittent'
+ * ```
+ */
+declare function classifyDemandPattern(series: readonly number[], options?: DemandPatternOptions): Explained<DemandPatternResult>;
+
+export { type AbcClassification, type AbcItem, type AbcOptions, type AbcXyzCell, type AbcXyzClass, type DemandPattern, type DemandPatternOptions, type DemandPatternResult, type FsnClassification, type FsnOptions, type XyzClassification, type XyzOptions, abc, abcXyzMatrix, classifyDemandPattern, fsn, xyz };

package/dist/index.js

@@ -0,0 +1,194 @@
+import { explain, coefficientOfVariation, averageDemandInterval, squaredCvOfNonZero } from '@logistics-ts/core';
+
+// src/abc.ts
+function abc(items, options = {}) {
+  const { by = "value", cutoffs = [0.8, 0.95] } = options;
+  const [aMax, bMax] = cutoffs;
+  const metricOf = (item) => {
+    if (by === "value" && item.unitValue === void 0) {
+      throw new Error(`abc by 'value' requires unitValue; item "${item.itemId}" has none`);
+    }
+    const metric = by === "volume" ? item.volume : item.volume * item.unitValue;
+    if (!Number.isFinite(metric) || metric < 0) {
+      throw new Error(`abc: item "${item.itemId}" has an invalid ${by} metric (${metric})`);
+    }
+    return metric;
+  };
+  const ranked = items.map((item) => ({ itemId: item.itemId, metric: metricOf(item) })).sort((a, b) => b.metric - a.metric);
+  const total = ranked.reduce((sum, r) => sum + r.metric, 0);
+  const result = [];
+  let cumulative = 0;
+  const counts = { A: 0, B: 0, C: 0 };
+  for (const { itemId, metric } of ranked) {
+    let cls;
+    if (total === 0) {
+      cls = "C";
+    } else {
+      const cumulativeBefore = cumulative / total;
+      cls = cumulativeBefore < aMax ? "A" : cumulativeBefore < bMax ? "B" : "C";
+    }
+    cumulative += metric;
+    const share = total === 0 ? 0 : metric / total;
+    counts[cls]++;
+    result.push({
+      itemId,
+      class: cls,
+      metric,
+      share,
+      cumulativeShare: total === 0 ? 0 : cumulative / total
+    });
+  }
+  const warnings = total === 0 ? ["no consumption across any item; all classified C"] : void 0;
+  return explain(result, {
+    method: `abc-by-${by}`,
+    inputs: { items: items.length, aMax, bMax, total },
+    reasoning: [
+      `ranked ${items.length} items by ${by === "value" ? "consumption value" : "volume"}`,
+      `A until cumulative share reaches ${aMax * 100}%, then B until ${bMax * 100}%, then C; the item that crosses a cutoff is promoted to the higher class`,
+      `${counts.A} A-items, ${counts.B} B-items, ${counts.C} C-items`
+    ],
+    citations: ["Silver, Pyke & Thomas (2017), Inventory and Production Management"],
+    ...warnings ? { warnings } : {}
+  });
+}
+function xyz(series, options = {}) {
+  const { cutoffs = [0.5, 1] } = options;
+  const [xMax, yMax] = cutoffs;
+  const warnings = [];
+  const counts = { X: 0, Y: 0, Z: 0 };
+  const result = series.map((s) => {
+    const quantities = s.buckets.map((b) => b.quantity);
+    const cv = coefficientOfVariation(quantities);
+    let cls;
+    if (Number.isNaN(cv)) {
+      cls = "Z";
+      const hasDemand = quantities.some((q) => q > 0);
+      warnings.push(
+        hasDemand ? `item "${s.itemId}" has fewer than two periods; CV is undefined, classified Z` : `item "${s.itemId}" has no demand; classified Z`
+      );
+    } else {
+      cls = cv < xMax ? "X" : cv < yMax ? "Y" : "Z";
+    }
+    counts[cls]++;
+    return { itemId: s.itemId, class: cls, coefficientOfVariation: cv };
+  });
+  return explain(result, {
+    method: "xyz-coefficient-of-variation",
+    inputs: { items: series.length, xMax, yMax },
+    reasoning: [
+      `X < ${xMax} CV (stable), Y < ${yMax} (variable), Z \u2265 ${yMax} (erratic)`,
+      `${counts.X} X-items, ${counts.Y} Y-items, ${counts.Z} Z-items`
+    ],
+    ...warnings.length > 0 ? { warnings } : {}
+  });
+}
+function fsn(series, options = {}) {
+  const { fastCutoff = 0.5 } = options;
+  const counts = { F: 0, S: 0, N: 0 };
+  const result = series.map((s) => {
+    const periods = s.buckets.length;
+    const moved = s.buckets.filter((b) => b.quantity > 0).length;
+    const movementRatio = periods === 0 ? 0 : moved / periods;
+    const cls = moved === 0 ? "N" : movementRatio >= fastCutoff ? "F" : "S";
+    counts[cls]++;
+    return { itemId: s.itemId, class: cls, movementRatio };
+  });
+  return explain(result, {
+    method: "fsn-movement-frequency",
+    inputs: { items: series.length, fastCutoff },
+    reasoning: [
+      `N = no demand, F \u2265 ${fastCutoff} of periods with demand, S = the rest`,
+      `${counts.F} fast, ${counts.S} slow, ${counts.N} non-moving`
+    ]
+  });
+}
+var POLICY = {
+  AX: "high value, stable \u2014 tight control, low safety stock, automate reordering (JIT)",
+  AY: "high value, variable \u2014 tight control, moderate safety stock, forecast carefully",
+  AZ: "high value, erratic \u2014 manual review, buffer or make-to-order, avoid over-committing",
+  BX: "moderate value, stable \u2014 automate with standard safety stock",
+  BY: "moderate value, variable \u2014 standard control, moderate safety stock",
+  BZ: "moderate value, erratic \u2014 cautious stocking, periodic review",
+  CX: "low value, stable \u2014 simple rules, generous safety stock is cheap, bulk order",
+  CY: "low value, variable \u2014 simple rules, generous safety stock",
+  CZ: "low value, erratic \u2014 minimal stock or make-to-order; do not over-invest"
+};
+function abcXyzMatrix(abcResult, xyzResult) {
+  const xyzById = new Map(xyzResult.map((x) => [x.itemId, x.class]));
+  const warnings = [];
+  const cells = [];
+  for (const a of abcResult) {
+    const x = xyzById.get(a.itemId);
+    if (x === void 0) {
+      warnings.push(`item "${a.itemId}" has an ABC class but no XYZ class; skipped`);
+      continue;
+    }
+    const cls = `${a.class}${x}`;
+    cells.push({ itemId: a.itemId, abc: a.class, xyz: x, class: cls, policyHint: POLICY[cls] });
+  }
+  const abcIds = new Set(abcResult.map((a) => a.itemId));
+  for (const x of xyzResult) {
+    if (!abcIds.has(x.itemId)) {
+      warnings.push(`item "${x.itemId}" has an XYZ class but no ABC class; skipped`);
+    }
+  }
+  return explain(cells, {
+    method: "abc-xyz-matrix",
+    inputs: { abcItems: abcResult.length, xyzItems: xyzResult.length, matched: cells.length },
+    reasoning: [
+      "joined the value axis (ABC) with the variability axis (XYZ) by itemId",
+      "each cell carries a recommended inventory policy"
+    ],
+    ...warnings.length > 0 ? { warnings } : {}
+  });
+}
+var RECOMMENDED = {
+  smooth: ["SES", "Holt", "Holt-Winters"],
+  erratic: ["SES", "Holt"],
+  intermittent: ["Croston", "SBA"],
+  lumpy: ["SBA", "TSB"]
+};
+var DESCRIPTION = {
+  smooth: "frequent demand of stable size",
+  erratic: "frequent demand of highly variable size",
+  intermittent: "sporadic demand of stable size",
+  lumpy: "sporadic demand of highly variable size"
+};
+function classifyDemandPattern(series, options = {}) {
+  const { adiCutoff = 1.32, cv2Cutoff = 0.49 } = options;
+  const adi = averageDemandInterval(series);
+  const cv2 = squaredCvOfNonZero(series);
+  const warnings = [];
+  const nonZero = series.filter((v) => v !== 0).length;
+  if (nonZero === 0) warnings.push("series has no demand; classification is not meaningful");
+  else if (nonZero < 2) warnings.push("fewer than two demand occurrences; CV\xB2 is unreliable");
+  const effectiveAdi = Number.isNaN(adi) ? 1 : adi;
+  const effectiveCv2 = Number.isNaN(cv2) ? 0 : cv2;
+  const intermittent = effectiveAdi >= adiCutoff;
+  const variable = effectiveCv2 >= cv2Cutoff;
+  const pattern = intermittent ? variable ? "lumpy" : "intermittent" : variable ? "erratic" : "smooth";
+  const recommendedMethods = nonZero === 0 ? [] : [...RECOMMENDED[pattern]];
+  return explain(
+    { pattern, adi, cv2, recommendedMethods },
+    {
+      method: "syntetos-boylan-croston",
+      inputs: { adi: round(adi), cv2: round(cv2), adiCutoff, cv2Cutoff },
+      reasoning: [
+        `ADI ${fmt(adi)} ${intermittent ? "\u2265" : "<"} ${adiCutoff} \u2192 ${intermittent ? "sporadic" : "frequent"} demand`,
+        `CV\xB2 ${fmt(cv2)} ${variable ? "\u2265" : "<"} ${cv2Cutoff} \u2192 ${variable ? "variable" : "stable"} demand size`,
+        `classified as ${pattern}: ${DESCRIPTION[pattern]}`,
+        recommendedMethods.length > 0 ? `suited to ${recommendedMethods.join(", ")}` : "no demand to forecast"
+      ],
+      citations: ["Syntetos, Boylan & Croston (2005), JORS 56(5)"],
+      ...warnings.length > 0 ? { warnings } : {}
+    }
+  );
+}
+function round(x) {
+  return Number.isNaN(x) ? Number.NaN : Math.round(x * 1e3) / 1e3;
+}
+function fmt(x) {
+  return Number.isNaN(x) ? "n/a" : String(round(x));
+}
+
+export { abc, abcXyzMatrix, classifyDemandPattern, fsn, xyz };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@logistics-ts/classification",
+  "version": "0.0.1",
+  "description": "ABC, XYZ, FSN, ABC-XYZ matrix, and demand-pattern (SBC) classification for logistics-ts.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adam-drag/logistics-ts.git",
+    "directory": "packages/classification"
+  },
+  "homepage": "https://github.com/adam-drag/logistics-ts/tree/main/packages/classification",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@logistics-ts/core": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}