@lacspace/inventory 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data 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 conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+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.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,105 @@
+<div align="center">
+
+# @lacspace/inventory
+
+**A stock-tracking engine that prevents overselling — reserve, commit & restock over a plain state object.**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/inventory?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/inventory)
+[![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/inventory?label=minzip)](https://bundlephobia.com/package/@lacspace/inventory)
+[![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/inventory)
+[![license](https://img.shields.io/npm/l/@lacspace/inventory?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> Overselling is one bug: you let two orders take the last unit. This is the maths that stops it — pure, immutable functions over a plain `{ onHand, reserved }` state. **Bring your own store** (a DB row, a cache, a signal); this decides what's allowed.
+
+- 🚫 **No overselling** — `reserve`/`commit` throw an `InventoryError` before they'd go negative
+- 🧊 **Immutable** — every op returns a new `Stock`; your input is never mutated
+- 🧠 **available = onHand − reserved** — the one invariant, enforced everywhere
+- 🧩 **Headless** — persist the state however you like; this is just the rules
+- ⚡ Isomorphic — Node, edge runtimes & browsers · 📦 ESM + CJS · fully typed · zero deps
+
+## Install
+
+```bash
+npm i @lacspace/inventory      # or pnpm add / yarn add / bun add
+```
+
+## Reserve → commit
+
+```ts
+import { createStock, reserve, commit, available } from "@lacspace/inventory";
+
+let stock = createStock(10); // { onHand: 10, reserved: 0 }
+
+stock = reserve(stock, 3); // hold 3 for a pending order
+available(stock); // 7
+
+stock = commit(stock, 3); // ship them
+stock; // { onHand: 7, reserved: 0 }
+```
+
+## Overselling throws
+
+```ts
+import { createStock, reserve, InventoryError } from "@lacspace/inventory";
+
+const stock = createStock(2);
+
+try {
+  reserve(stock, 5); // only 2 available
+} catch (e) {
+  e instanceof InventoryError; // true — nothing was oversold
+}
+```
+
+## Restock, release & low-stock alerts
+
+```ts
+import { createStock, reserve, release, restock, isLow, isOutOfStock } from "@lacspace/inventory";
+
+let stock = restock(createStock(0), 20); // delivery arrives
+stock = reserve(stock, 18);
+
+isLow(stock, 5); // true  — 2 available
+isOutOfStock(stock); // false
+
+stock = release(stock, 18); // cart abandoned → put them back
+```
+
+## API
+
+| Function | Description |
+| --- | --- |
+| `createStock(onHand?)` | new `{ onHand, reserved: 0 }` (default `0`) |
+| `available(stock)` | `onHand - reserved` |
+| `reserve(stock, qty)` | hold `qty`; **throws** if `qty > available` |
+| `release(stock, qty)` | free a reservation (never below `0`) |
+| `commit(stock, qty)` | fulfil: `onHand -= qty`, `reserved -= qty`; **throws** if `qty > reserved` |
+| `restock(stock, qty)` | add `qty` to `onHand` |
+| `adjust(stock, delta)` | signed correction to `onHand` (clamped at `0`) |
+| `isLow(stock, threshold)` | `available <= threshold` |
+| `isOutOfStock(stock)` | `available <= 0` |
+| `InventoryError` | thrown on oversell / invalid quantity |
+
+## Licensing
+
+This package is **free** under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — permissive freedoms. Use it in personal and commercial projects at no cost; just keep the notice.
+
+Not every Lacspace package is free. We also offer **Commercial** (paid), **Client-specific**, and **Private** (proprietary) packages under separate terms. See the full **[Lacspace Licence Centre](https://lacspace.com/licenses)**.
+
+<!-- LACSPACE-DEV-PLATFORM -->
+
+---
+
+## The Lacspace Developer Platform
+
+`@lacspace/inventory` is part of **63+ zero-dependency, isomorphic TypeScript packages**. Explore the ecosystem:
+
+- 🗂️ **All packages** — https://developer.lacspace.com/packages
+- 🧭 **Developer handbook** — https://developer.lacspace.com/handbook
+- 🧪 **Live playground** — https://developer.lacspace.com/playground
+- 🖥️ **Finished app templates** — https://templates.lacspace.com
+- 🚀 **Scaffold a full app** — `npm create lacspace-app@latest`
+
+Free under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — a permissive, free-to-use licence.

package/dist/index.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+// src/index.ts
+var InventoryError = class _InventoryError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InventoryError";
+    Object.setPrototypeOf(this, _InventoryError.prototype);
+  }
+};
+function toCount(n, label) {
+  const v = Math.trunc(n);
+  if (!Number.isFinite(v)) throw new InventoryError(`${label} must be a finite number`);
+  return v;
+}
+function requireQty(qty) {
+  const q = toCount(qty, "qty");
+  if (q < 0) throw new InventoryError("qty must be >= 0");
+  return q;
+}
+function createStock(onHand = 0) {
+  const n = toCount(onHand, "onHand");
+  if (n < 0) throw new InventoryError("onHand must be >= 0");
+  return { onHand: n, reserved: 0 };
+}
+function available(stock) {
+  return stock.onHand - stock.reserved;
+}
+function reserve(stock, qty) {
+  const q = requireQty(qty);
+  if (q > available(stock)) {
+    throw new InventoryError(
+      `Cannot reserve ${q}: only ${available(stock)} available`
+    );
+  }
+  return { onHand: stock.onHand, reserved: stock.reserved + q };
+}
+function release(stock, qty) {
+  const q = requireQty(qty);
+  return { onHand: stock.onHand, reserved: stock.reserved - Math.min(q, stock.reserved) };
+}
+function commit(stock, qty) {
+  const q = requireQty(qty);
+  if (q > stock.reserved) {
+    throw new InventoryError(
+      `Cannot commit ${q}: only ${stock.reserved} reserved`
+    );
+  }
+  return { onHand: stock.onHand - q, reserved: stock.reserved - q };
+}
+function restock(stock, qty) {
+  const q = requireQty(qty);
+  return { onHand: stock.onHand + q, reserved: stock.reserved };
+}
+function adjust(stock, delta) {
+  const d = toCount(delta, "delta");
+  return { onHand: Math.max(0, stock.onHand + d), reserved: stock.reserved };
+}
+function isLow(stock, threshold) {
+  return available(stock) <= toCount(threshold, "threshold");
+}
+function isOutOfStock(stock) {
+  return available(stock) <= 0;
+}
+
+exports.InventoryError = InventoryError;
+exports.adjust = adjust;
+exports.available = available;
+exports.commit = commit;
+exports.createStock = createStock;
+exports.isLow = isLow;
+exports.isOutOfStock = isOutOfStock;
+exports.release = release;
+exports.reserve = reserve;
+exports.restock = restock;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @lacspace/inventory — a stock-tracking engine that prevents overselling.\n *\n * Bring-your-own-store: this package is a set of pure, immutable functions over\n * a plain `Stock` state object `{ onHand, reserved }`. You decide where the\n * state lives (a database row, a cache, a signal); this decides the maths.\n *\n * The core guarantee: you can never reserve or fulfil more than is available,\n * so a race between two checkouts fails loudly instead of overselling.\n */\n\n/** Stock state for a single SKU. Both fields are non-negative integers. */\nexport interface Stock {\n  /** Physical units in the warehouse. */\n  onHand: number;\n  /** Units held for pending orders (not yet shipped). */\n  reserved: number;\n}\n\n/** Thrown when an operation would oversell or is otherwise invalid. */\nexport class InventoryError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"InventoryError\";\n    // Restore the prototype chain for instanceof across transpile targets.\n    Object.setPrototypeOf(this, InventoryError.prototype);\n  }\n}\n\nfunction toCount(n: number, label: string): number {\n  const v = Math.trunc(n);\n  if (!Number.isFinite(v)) throw new InventoryError(`${label} must be a finite number`);\n  return v;\n}\n\n/** Require a non-negative quantity for an operation. */\nfunction requireQty(qty: number): number {\n  const q = toCount(qty, \"qty\");\n  if (q < 0) throw new InventoryError(\"qty must be >= 0\");\n  return q;\n}\n\n/** Create a new stock state with the given quantity on hand (default `0`). */\nexport function createStock(onHand = 0): Stock {\n  const n = toCount(onHand, \"onHand\");\n  if (n < 0) throw new InventoryError(\"onHand must be >= 0\");\n  return { onHand: n, reserved: 0 };\n}\n\n/** Units that can still be reserved: `onHand - reserved`. */\nexport function available(stock: Stock): number {\n  return stock.onHand - stock.reserved;\n}\n\n/**\n * Reserve `qty` units for a pending order. Increases `reserved`.\n *\n * @throws {InventoryError} if `qty` exceeds {@link available} (would oversell).\n */\nexport function reserve(stock: Stock, qty: number): Stock {\n  const q = requireQty(qty);\n  if (q > available(stock)) {\n    throw new InventoryError(\n      `Cannot reserve ${q}: only ${available(stock)} available`,\n    );\n  }\n  return { onHand: stock.onHand, reserved: stock.reserved + q };\n}\n\n/**\n * Release a previously-held reservation (e.g. an abandoned cart). Never drops\n * `reserved` below `0` — it releases at most what is currently reserved.\n */\nexport function release(stock: Stock, qty: number): Stock {\n  const q = requireQty(qty);\n  return { onHand: stock.onHand, reserved: stock.reserved - Math.min(q, stock.reserved) };\n}\n\n/**\n * Fulfil (ship) `qty` reserved units: decrements both `onHand` and `reserved`.\n *\n * @throws {InventoryError} if `qty` exceeds the currently reserved amount.\n */\nexport function commit(stock: Stock, qty: number): Stock {\n  const q = requireQty(qty);\n  if (q > stock.reserved) {\n    throw new InventoryError(\n      `Cannot commit ${q}: only ${stock.reserved} reserved`,\n    );\n  }\n  return { onHand: stock.onHand - q, reserved: stock.reserved - q };\n}\n\n/** Add `qty` units to `onHand` (a delivery / restock). */\nexport function restock(stock: Stock, qty: number): Stock {\n  const q = requireQty(qty);\n  return { onHand: stock.onHand + q, reserved: stock.reserved };\n}\n\n/**\n * Apply a signed correction to `onHand` (stock-take, shrinkage, returns).\n * `onHand` is clamped at `0`; `reserved` is left untouched.\n */\nexport function adjust(stock: Stock, delta: number): Stock {\n  const d = toCount(delta, \"delta\");\n  return { onHand: Math.max(0, stock.onHand + d), reserved: stock.reserved };\n}\n\n/** `true` when {@link available} is at or below `threshold`. */\nexport function isLow(stock: Stock, threshold: number): boolean {\n  return available(stock) <= toCount(threshold, \"threshold\");\n}\n\n/** `true` when nothing is available to reserve (`available <= 0`). */\nexport function isOutOfStock(stock: Stock): boolean {\n  return available(stock) <= 0;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,55 @@
+/**
+ * @lacspace/inventory — a stock-tracking engine that prevents overselling.
+ *
+ * Bring-your-own-store: this package is a set of pure, immutable functions over
+ * a plain `Stock` state object `{ onHand, reserved }`. You decide where the
+ * state lives (a database row, a cache, a signal); this decides the maths.
+ *
+ * The core guarantee: you can never reserve or fulfil more than is available,
+ * so a race between two checkouts fails loudly instead of overselling.
+ */
+/** Stock state for a single SKU. Both fields are non-negative integers. */
+interface Stock {
+    /** Physical units in the warehouse. */
+    onHand: number;
+    /** Units held for pending orders (not yet shipped). */
+    reserved: number;
+}
+/** Thrown when an operation would oversell or is otherwise invalid. */
+declare class InventoryError extends Error {
+    constructor(message: string);
+}
+/** Create a new stock state with the given quantity on hand (default `0`). */
+declare function createStock(onHand?: number): Stock;
+/** Units that can still be reserved: `onHand - reserved`. */
+declare function available(stock: Stock): number;
+/**
+ * Reserve `qty` units for a pending order. Increases `reserved`.
+ *
+ * @throws {InventoryError} if `qty` exceeds {@link available} (would oversell).
+ */
+declare function reserve(stock: Stock, qty: number): Stock;
+/**
+ * Release a previously-held reservation (e.g. an abandoned cart). Never drops
+ * `reserved` below `0` — it releases at most what is currently reserved.
+ */
+declare function release(stock: Stock, qty: number): Stock;
+/**
+ * Fulfil (ship) `qty` reserved units: decrements both `onHand` and `reserved`.
+ *
+ * @throws {InventoryError} if `qty` exceeds the currently reserved amount.
+ */
+declare function commit(stock: Stock, qty: number): Stock;
+/** Add `qty` units to `onHand` (a delivery / restock). */
+declare function restock(stock: Stock, qty: number): Stock;
+/**
+ * Apply a signed correction to `onHand` (stock-take, shrinkage, returns).
+ * `onHand` is clamped at `0`; `reserved` is left untouched.
+ */
+declare function adjust(stock: Stock, delta: number): Stock;
+/** `true` when {@link available} is at or below `threshold`. */
+declare function isLow(stock: Stock, threshold: number): boolean;
+/** `true` when nothing is available to reserve (`available <= 0`). */
+declare function isOutOfStock(stock: Stock): boolean;
+
+export { InventoryError, type Stock, adjust, available, commit, createStock, isLow, isOutOfStock, release, reserve, restock };

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @lacspace/inventory — a stock-tracking engine that prevents overselling.
+ *
+ * Bring-your-own-store: this package is a set of pure, immutable functions over
+ * a plain `Stock` state object `{ onHand, reserved }`. You decide where the
+ * state lives (a database row, a cache, a signal); this decides the maths.
+ *
+ * The core guarantee: you can never reserve or fulfil more than is available,
+ * so a race between two checkouts fails loudly instead of overselling.
+ */
+/** Stock state for a single SKU. Both fields are non-negative integers. */
+interface Stock {
+    /** Physical units in the warehouse. */
+    onHand: number;
+    /** Units held for pending orders (not yet shipped). */
+    reserved: number;
+}
+/** Thrown when an operation would oversell or is otherwise invalid. */
+declare class InventoryError extends Error {
+    constructor(message: string);
+}
+/** Create a new stock state with the given quantity on hand (default `0`). */
+declare function createStock(onHand?: number): Stock;
+/** Units that can still be reserved: `onHand - reserved`. */
+declare function available(stock: Stock): number;
+/**
+ * Reserve `qty` units for a pending order. Increases `reserved`.
+ *
+ * @throws {InventoryError} if `qty` exceeds {@link available} (would oversell).
+ */
+declare function reserve(stock: Stock, qty: number): Stock;
+/**
+ * Release a previously-held reservation (e.g. an abandoned cart). Never drops
+ * `reserved` below `0` — it releases at most what is currently reserved.
+ */
+declare function release(stock: Stock, qty: number): Stock;
+/**
+ * Fulfil (ship) `qty` reserved units: decrements both `onHand` and `reserved`.
+ *
+ * @throws {InventoryError} if `qty` exceeds the currently reserved amount.
+ */
+declare function commit(stock: Stock, qty: number): Stock;
+/** Add `qty` units to `onHand` (a delivery / restock). */
+declare function restock(stock: Stock, qty: number): Stock;
+/**
+ * Apply a signed correction to `onHand` (stock-take, shrinkage, returns).
+ * `onHand` is clamped at `0`; `reserved` is left untouched.
+ */
+declare function adjust(stock: Stock, delta: number): Stock;
+/** `true` when {@link available} is at or below `threshold`. */
+declare function isLow(stock: Stock, threshold: number): boolean;
+/** `true` when nothing is available to reserve (`available <= 0`). */
+declare function isOutOfStock(stock: Stock): boolean;
+
+export { InventoryError, type Stock, adjust, available, commit, createStock, isLow, isOutOfStock, release, reserve, restock };

package/dist/index.js

@@ -0,0 +1,66 @@
+// src/index.ts
+var InventoryError = class _InventoryError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InventoryError";
+    Object.setPrototypeOf(this, _InventoryError.prototype);
+  }
+};
+function toCount(n, label) {
+  const v = Math.trunc(n);
+  if (!Number.isFinite(v)) throw new InventoryError(`${label} must be a finite number`);
+  return v;
+}
+function requireQty(qty) {
+  const q = toCount(qty, "qty");
+  if (q < 0) throw new InventoryError("qty must be >= 0");
+  return q;
+}
+function createStock(onHand = 0) {
+  const n = toCount(onHand, "onHand");
+  if (n < 0) throw new InventoryError("onHand must be >= 0");
+  return { onHand: n, reserved: 0 };
+}
+function available(stock) {
+  return stock.onHand - stock.reserved;
+}
+function reserve(stock, qty) {
+  const q = requireQty(qty);
+  if (q > available(stock)) {
+    throw new InventoryError(
+      `Cannot reserve ${q}: only ${available(stock)} available`
+    );
+  }
+  return { onHand: stock.onHand, reserved: stock.reserved + q };
+}
+function release(stock, qty) {
+  const q = requireQty(qty);
+  return { onHand: stock.onHand, reserved: stock.reserved - Math.min(q, stock.reserved) };
+}
+function commit(stock, qty) {
+  const q = requireQty(qty);
+  if (q > stock.reserved) {
+    throw new InventoryError(
+      `Cannot commit ${q}: only ${stock.reserved} reserved`
+    );
+  }
+  return { onHand: stock.onHand - q, reserved: stock.reserved - q };
+}
+function restock(stock, qty) {
+  const q = requireQty(qty);
+  return { onHand: stock.onHand + q, reserved: stock.reserved };
+}
+function adjust(stock, delta) {
+  const d = toCount(delta, "delta");
+  return { onHand: Math.max(0, stock.onHand + d), reserved: stock.reserved };
+}
+function isLow(stock, threshold) {
+  return available(stock) <= toCount(threshold, "threshold");
+}
+function isOutOfStock(stock) {
+  return available(stock) <= 0;
+}
+
+export { InventoryError, adjust, available, commit, createStock, isLow, isOutOfStock, release, reserve, restock };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AAoBO,IAAM,cAAA,GAAN,MAAM,eAAA,SAAuB,KAAA,CAAM;AAAA,EACxC,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,gBAAA;AAEZ,IAAA,MAAA,CAAO,cAAA,CAAe,IAAA,EAAM,eAAA,CAAe,SAAS,CAAA;AAAA,EACtD;AACF;AAEA,SAAS,OAAA,CAAQ,GAAW,KAAA,EAAuB;AACjD,EAAA,MAAM,CAAA,GAAI,IAAA,CAAK,KAAA,CAAM,CAAC,CAAA;AACtB,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,CAAC,CAAA,QAAS,IAAI,cAAA,CAAe,CAAA,EAAG,KAAK,CAAA,wBAAA,CAA0B,CAAA;AACpF,EAAA,OAAO,CAAA;AACT;AAGA,SAAS,WAAW,GAAA,EAAqB;AACvC,EAAA,MAAM,CAAA,GAAI,OAAA,CAAQ,GAAA,EAAK,KAAK,CAAA;AAC5B,EAAA,IAAI,CAAA,GAAI,CAAA,EAAG,MAAM,IAAI,eAAe,kBAAkB,CAAA;AACtD,EAAA,OAAO,CAAA;AACT;AAGO,SAAS,WAAA,CAAY,SAAS,CAAA,EAAU;AAC7C,EAAA,MAAM,CAAA,GAAI,OAAA,CAAQ,MAAA,EAAQ,QAAQ,CAAA;AAClC,EAAA,IAAI,CAAA,GAAI,CAAA,EAAG,MAAM,IAAI,eAAe,qBAAqB,CAAA;AACzD,EAAA,OAAO,EAAE,MAAA,EAAQ,CAAA,EAAG,QAAA,EAAU,CAAA,EAAE;AAClC;AAGO,SAAS,UAAU,KAAA,EAAsB;AAC9C,EAAA,OAAO,KAAA,CAAM,SAAS,KAAA,CAAM,QAAA;AAC9B;AAOO,SAAS,OAAA,CAAQ,OAAc,GAAA,EAAoB;AACxD,EAAA,MAAM,CAAA,GAAI,WAAW,GAAG,CAAA;AACxB,EAAA,IAAI,CAAA,GAAI,SAAA,CAAU,KAAK,CAAA,EAAG;AACxB,IAAA,MAAM,IAAI,cAAA;AAAA,MACR,CAAA,eAAA,EAAkB,CAAC,CAAA,OAAA,EAAU,SAAA,CAAU,KAAK,CAAC,CAAA,UAAA;AAAA,KAC/C;AAAA,EACF;AACA,EAAA,OAAO,EAAE,MAAA,EAAQ,KAAA,CAAM,QAAQ,QAAA,EAAU,KAAA,CAAM,WAAW,CAAA,EAAE;AAC9D;AAMO,SAAS,OAAA,CAAQ,OAAc,GAAA,EAAoB;AACxD,EAAA,MAAM,CAAA,GAAI,WAAW,GAAG,CAAA;AACxB,EAAA,OAAO,EAAE,MAAA,EAAQ,KAAA,CAAM,MAAA,EAAQ,QAAA,EAAU,KAAA,CAAM,QAAA,GAAW,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,KAAA,CAAM,QAAQ,CAAA,EAAE;AACxF;AAOO,SAAS,MAAA,CAAO,OAAc,GAAA,EAAoB;AACvD,EAAA,MAAM,CAAA,GAAI,WAAW,GAAG,CAAA;AACxB,EAAA,IAAI,CAAA,GAAI,MAAM,QAAA,EAAU;AACtB,IAAA,MAAM,IAAI,cAAA;AAAA,MACR,CAAA,cAAA,EAAiB,CAAC,CAAA,OAAA,EAAU,KAAA,CAAM,QAAQ,CAAA,SAAA;AAAA,KAC5C;AAAA,EACF;AACA,EAAA,OAAO,EAAE,QAAQ,KAAA,CAAM,MAAA,GAAS,GAAG,QAAA,EAAU,KAAA,CAAM,WAAW,CAAA,EAAE;AAClE;AAGO,SAAS,OAAA,CAAQ,OAAc,GAAA,EAAoB;AACxD,EAAA,MAAM,CAAA,GAAI,WAAW,GAAG,CAAA;AACxB,EAAA,OAAO,EAAE,MAAA,EAAQ,KAAA,CAAM,SAAS,CAAA,EAAG,QAAA,EAAU,MAAM,QAAA,EAAS;AAC9D;AAMO,SAAS,MAAA,CAAO,OAAc,KAAA,EAAsB;AACzD,EAAA,MAAM,CAAA,GAAI,OAAA,CAAQ,KAAA,EAAO,OAAO,CAAA;AAChC,EAAA,OAAO,EAAE,MAAA,EAAQ,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,KAAA,CAAM,MAAA,GAAS,CAAC,CAAA,EAAG,QAAA,EAAU,KAAA,CAAM,QAAA,EAAS;AAC3E;AAGO,SAAS,KAAA,CAAM,OAAc,SAAA,EAA4B;AAC9D,EAAA,OAAO,SAAA,CAAU,KAAK,CAAA,IAAK,OAAA,CAAQ,WAAW,WAAW,CAAA;AAC3D;AAGO,SAAS,aAAa,KAAA,EAAuB;AAClD,EAAA,OAAO,SAAA,CAAU,KAAK,CAAA,IAAK,CAAA;AAC7B","file":"index.js","sourcesContent":["/**\n * @lacspace/inventory — a stock-tracking engine that prevents overselling.\n *\n * Bring-your-own-store: this package is a set of pure, immutable functions over\n * a plain `Stock` state object `{ onHand, reserved }`. You decide where the\n * state lives (a database row, a cache, a signal); this decides the maths.\n *\n * The core guarantee: you can never reserve or fulfil more than is available,\n * so a race between two checkouts fails loudly instead of overselling.\n */\n\n/** Stock state for a single SKU. Both fields are non-negative integers. */\nexport interface Stock {\n  /** Physical units in the warehouse. */\n  onHand: number;\n  /** Units held for pending orders (not yet shipped). */\n  reserved: number;\n}\n\n/** Thrown when an operation would oversell or is otherwise invalid. */\nexport class InventoryError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"InventoryError\";\n    // Restore the prototype chain for instanceof across transpile targets.\n    Object.setPrototypeOf(this, InventoryError.prototype);\n  }\n}\n\nfunction toCount(n: number, label: string): number {\n  const v = Math.trunc(n);\n  if (!Number.isFinite(v)) throw new InventoryError(`${label} must be a finite number`);\n  return v;\n}\n\n/** Require a non-negative quantity for an operation. */\nfunction requireQty(qty: number): number {\n  const q = toCount(qty, \"qty\");\n  if (q < 0) throw new InventoryError(\"qty must be >= 0\");\n  return q;\n}\n\n/** Create a new stock state with the given quantity on hand (default `0`). */\nexport function createStock(onHand = 0): Stock {\n  const n = toCount(onHand, \"onHand\");\n  if (n < 0) throw new InventoryError(\"onHand must be >= 0\");\n  return { onHand: n, reserved: 0 };\n}\n\n/** Units that can still be reserved: `onHand - reserved`. */\nexport function available(stock: Stock): number {\n  return stock.onHand - stock.reserved;\n}\n\n/**\n * Reserve `qty` units for a pending order. Increases `reserved`.\n *\n * @throws {InventoryError} if `qty` exceeds {@link available} (would oversell).\n */\nexport function reserve(stock: Stock, qty: number): Stock {\n  const q = requireQty(qty);\n  if (q > available(stock)) {\n    throw new InventoryError(\n      `Cannot reserve ${q}: only ${available(stock)} available`,\n    );\n  }\n  return { onHand: stock.onHand, reserved: stock.reserved + q };\n}\n\n/**\n * Release a previously-held reservation (e.g. an abandoned cart). Never drops\n * `reserved` below `0` — it releases at most what is currently reserved.\n */\nexport function release(stock: Stock, qty: number): Stock {\n  const q = requireQty(qty);\n  return { onHand: stock.onHand, reserved: stock.reserved - Math.min(q, stock.reserved) };\n}\n\n/**\n * Fulfil (ship) `qty` reserved units: decrements both `onHand` and `reserved`.\n *\n * @throws {InventoryError} if `qty` exceeds the currently reserved amount.\n */\nexport function commit(stock: Stock, qty: number): Stock {\n  const q = requireQty(qty);\n  if (q > stock.reserved) {\n    throw new InventoryError(\n      `Cannot commit ${q}: only ${stock.reserved} reserved`,\n    );\n  }\n  return { onHand: stock.onHand - q, reserved: stock.reserved - q };\n}\n\n/** Add `qty` units to `onHand` (a delivery / restock). */\nexport function restock(stock: Stock, qty: number): Stock {\n  const q = requireQty(qty);\n  return { onHand: stock.onHand + q, reserved: stock.reserved };\n}\n\n/**\n * Apply a signed correction to `onHand` (stock-take, shrinkage, returns).\n * `onHand` is clamped at `0`; `reserved` is left untouched.\n */\nexport function adjust(stock: Stock, delta: number): Stock {\n  const d = toCount(delta, \"delta\");\n  return { onHand: Math.max(0, stock.onHand + d), reserved: stock.reserved };\n}\n\n/** `true` when {@link available} is at or below `threshold`. */\nexport function isLow(stock: Stock, threshold: number): boolean {\n  return available(stock) <= toCount(threshold, \"threshold\");\n}\n\n/** `true` when nothing is available to reserve (`available <= 0`). */\nexport function isOutOfStock(stock: Stock): boolean {\n  return available(stock) <= 0;\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lacspace/inventory",
+  "version": "1.0.0",
+  "description": "Stock-tracking engine that prevents overselling — reserve, release, commit & restock over a plain { onHand, reserved } state. Immutable, bring-your-own-store, throws before it oversells. Isomorphic (Node, edge, browser).",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "inventory",
+    "stock",
+    "stock-management",
+    "reservation",
+    "oversell",
+    "ecommerce",
+    "warehouse",
+    "fulfilment",
+    "immutable",
+    "headless",
+    "isomorphic",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://developer.lacspace.com/packages/inventory",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "inventory"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}