kempo-inventory 0.3.5 → 0.3.6

package/README.md

@@ -321,7 +321,7 @@ Every function resolves to `[error, result]`, where `error` is `{ code, msg }` o
 | `unregisterFields(owner)` | Remove every field your extension owns, and their values |
 | `FIELD_TYPES`, `EVENTS` | The field types and the hook event names |
 
-An item looks like `{ id, sku, name, description, category, tags, quantity, fields: { ...custom values }, owner, created, updated }`.
+An item looks like `{ id, sku, name, description, category, tags, quantity, held, fields: { ...custom values }, owner, created, updated }`.
 
 ### Several items at once
 
@@ -339,6 +339,32 @@ const [error, { items }] = await adjustStockMany(
 
 Changes to the same item are added together and one that nets to nothing is left out. Every item goes through the same `before_adjust` guard as `adjustStock`, and each fires `stock:adjusted` once everything is committed. `ref` is written on every stock movement (as `[order-1042]` in its note) so the change can be found, and reversed, later.
 
+### Held stock
+
+An item has two figures: **`quantity`**, what is *available* now, and **`held`**, what is set aside for something that has not finished — an order waiting for its payment, a job waiting for its materials. The stock the item really has is the two added together.
+
+`quantity` stays the figure everything already reads, so holding stock lowers what can be sold or used everywhere without anything else having to know about holds. Three moves, each all or nothing across every item in the call, and each recorded as a movement (`heldDelta`, `heldAfter`):
+
+| Function | Moves | When |
+|---|---|---|
+| `holdStock(changes, options)` | available → **held** | an order is placed |
+| `releaseStock(changes, options)` | held → **available** | it was cancelled, expired or failed |
+| `consumeHeld(changes, options)` | held → **gone** | it was fulfilled: the units have left |
+
+```javascript
+import { holdStock, consumeHeld, releaseStock } from 'kempo-inventory/sdk';
+
+const [error, { items }] = await holdStock([{ id: resin.id, quantity: 175 }], { ref: 'order-1042', owner: 'my-extension' });
+// error.code 409 and "Not enough of Resin (g) is available to hold": nothing changed
+
+await consumeHeld([{ id: resin.id, quantity: 175 }], { ref: 'order-1042', owner: 'my-extension' });   // paid
+await releaseStock([{ id: resin.id, quantity: 175 }], { ref: 'order-1042', owner: 'my-extension' });   // or not
+```
+
+`changes` is `[{ id, quantity }]` (or one `{ id, quantity }`), with `quantity` a whole number above zero; the same item twice is added together. Every move is a single conditional update, so concurrent callers cannot hold what is not available, release what is not held, or take either figure below zero. `ref` is written on every movement so what was held for an order can be found and given back later.
+
+Holding and releasing change what is available, so they also fire `stock:adjusted` (with `reason` `hold` or `release`), and anything that reacts to availability — such as kempo-products-inventory — stays correct. `stock:held` fires for all three. `adjustStock` leaves `held` alone, and an item with stock on hold cannot be deleted until it is given back. The admin list shows an **On hold** column once anything is held.
+
 ### Adding to the item page
 
 An extension can add to the admin item page by supplying a fragment named `inventory-item-actions`, in `admin/inventory-item-actions.fragment.html` in its own package. It appears under the item form, and reads the item from `?id=` in the address. (kempo-products-inventory uses it for "Make product from this item".)
@@ -355,6 +381,7 @@ Declare these in your `kempo-config.json` `hooks`. Every payload also carries `a
 | `kempo-inventory:item:before_update` | `{ item, changes: { sku?, name?, description?, fields? }, userId }` | edit `changes` |
 | `kempo-inventory:item:before_delete` | `{ item, userId }` | refuse only |
 | `kempo-inventory:stock:before_adjust` | `{ item, draft: { delta, reason, note }, userId }` | edit `draft` |
+| `kempo-inventory:stock:before_hold` | `{ item, draft: { kind, quantity, reason, note }, userId }` (`kind` is `hold`, `release` or `consume`) | edit `draft` |
 | `kempo-inventory:category:before_update` | `{ name, newName, changes: { description?, tags?, image? }, userId }` | refuse only |
 | `kempo-inventory:category:before_delete` | `{ category, name, userId }` (`category` is `null` for one with no record) | refuse only |
 | `kempo-inventory:field:before_create` | `{ draft }` | refuse only |
@@ -371,6 +398,7 @@ Ownership is checked first, so these only run for changes that would otherwise g
 | `kempo-inventory:item:updated` | `{ item, previous, userId }` |
 | `kempo-inventory:item:deleted` | `{ item, userId }` |
 | `kempo-inventory:stock:adjusted` | `{ item, previousQuantity, delta, reason, note, movement, userId }` |
+| `kempo-inventory:stock:held` | `{ item, kind, quantity, previousQuantity, previousHeld, movement, userId }` |
 | `kempo-inventory:category:updated` | `{ category, previous, moved, userId }` |
 | `kempo-inventory:category:deleted` | `{ category, userId }` |
 | `kempo-inventory:field:created` | `{ field }` |

package/admin/index.page.html

@@ -105,13 +105,15 @@ locked: true
     let fields = [];
     /* The Managed by column only appears once an extension owns an item. */
     let owners = false;
+    /* The Held column only appears once something is set aside. */
+    let holds = false;
 
     /*
       Display-only values are precomputed as plain strings so the table never formats
       user-supplied text itself.
     */
     const decorate = (item, ctx) => {
-      const record = { ...item, qtyText: String(item.quantity), tagsText: item.tags.join(', '), ownerText: item.owner };
+      const record = { ...item, qtyText: String(item.quantity), heldText: String(item.held ?? 0), tagsText: item.tags.join(', '), ownerText: item.owner };
       /* Only the fields that apply to this item's category; a column another category's items fill stays blank here. */
       for(const field of applicableFields(fields, item.category).filter(f => f.listed)) record[`f_${field.key}`] = displayValue(field, item.fields[field.key], ctx);
       return record;
@@ -122,6 +124,7 @@ locked: true
       { name: 'name', label: 'Name', size: 240, editable: false },
       { name: 'category', label: 'Category', size: 140, editable: false },
       { name: 'qtyText', label: 'Quantity', size: 100, editable: false },
+      ...(holds ? [{ name: 'heldText', label: 'On hold', size: 100, editable: false }] : []),
       { name: 'tagsText', label: 'Tags', size: 160, editable: false },
       ...(owners ? [{ name: 'ownerText', label: 'Managed by', size: 170, editable: false }] : []),
       /* One column per key: a key two categories both use is one column. */
@@ -151,6 +154,7 @@ locked: true
         return;
       }
       owners = data.items.some(i => i.owner);
+      holds = data.items.some(i => i.held > 0);
       $table.setData({ records: data.items.map(i => decorate(i, data.context)), fields: columns() });
     };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo-inventory",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "A basic inventory management system for kempo cms",
   "license": "MIT",
   "author": "Dustin Poissant",
@@ -15,8 +15,8 @@
   "type": "module",
   "main": "sdk.js",
   "scripts": {
-    "test": "node scripts/run-tests.js unit node --test",
-    "test:integration": "node scripts/run-tests.js integration node --test",
+    "test": "node scripts/run-tests.js unit node --test --test-concurrency=1",
+    "test:integration": "node scripts/run-tests.js integration node --test --test-concurrency=1",
     "link:local": "npm install ../kempo ../kempo-server ../kempo-ui --no-save --no-legacy-peer-deps --force",
     "docs:build": "node scripts/build-docs.js",
     "docs:dev": "npx kempo-server --root docs --port 4050"

package/sdk.js

@@ -36,6 +36,8 @@ export {
   getMovements,
 } from './server/utils/items.js';
 
+export { holdStock, releaseStock, consumeHeld } from './server/utils/holds.js';
+
 export {
   getFields,
   getField,

package/server/db/schema.js

@@ -10,7 +10,8 @@ export const kempoInventoryItem = pgTable('kempoInventoryItem', {
   name: text('name').notNull(),
   description: text('description').notNull().default(''),
   category: text('category').notNull().default(''), // built in and optional; '' means uncategorised
-  quantity: integer('quantity').notNull().default(0),
+  quantity: integer('quantity').notNull().default(0), // what is AVAILABLE; held units are not in it
+  held: integer('held').notNull().default(0), // set aside for something unfinished (an order awaiting payment); see holds.js
   tags: jsonb('tags').notNull().default([]), // built in: short lower-case labels search finds
   data: jsonb('data').notNull().default({}),
   owner: text('owner').notNull().default(''), // '' for items people manage, or the extension that created it; see ownership.js
@@ -49,6 +50,8 @@ export const kempoInventoryMovement = pgTable('kempoInventoryMovement', {
   itemId: text('itemId').notNull(),
   delta: integer('delta').notNull(),
   quantityAfter: integer('quantityAfter').notNull(),
+  heldDelta: integer('heldDelta').notNull().default(0), // the change to `held`: + when stock is set aside, - when it is given back or used
+  heldAfter: integer('heldAfter').notNull().default(0),
   reason: text('reason').notNull().default('adjustment'),
   note: text('note').notNull().default(''),
   userId: text('userId').notNull().default(''),

package/server/utils/events.js

@@ -18,6 +18,8 @@ export const EVENTS = {
   itemDeleted: 'kempo-inventory:item:deleted',
   stockBeforeAdjust: 'kempo-inventory:stock:before_adjust',
   stockAdjusted: 'kempo-inventory:stock:adjusted',
+  stockBeforeHold: 'kempo-inventory:stock:before_hold',
+  stockHeld: 'kempo-inventory:stock:held',
   categoryBeforeUpdate: 'kempo-inventory:category:before_update',
   categoryUpdated: 'kempo-inventory:category:updated',
   categoryBeforeDelete: 'kempo-inventory:category:before_delete',

package/server/utils/holds.js

@@ -0,0 +1,154 @@
+import db from 'kempo/server/db/index.js';
+import { and, eq, inArray, sql } from 'drizzle-orm';
+import crypto from 'crypto';
+import { kempoInventoryItem, kempoInventoryMovement } from '../db/schema.js';
+import { EVENTS, guard, notify } from './hooks.js';
+
+/*
+  Held stock: units that are set aside for something that has not finished — an order waiting for
+  its payment, a job waiting for its materials.
+
+  An item has two figures:
+
+    quantity   what is **available**: what can be sold or used now. This is the figure everything
+               else already reads, so a hold lowers availability everywhere without anything else
+               having to know holds exist.
+    held       what is set aside. Nobody can take it as available, and it is still the store's.
+
+  The stock an item really has is `quantity + held`. Three moves, each all-or-nothing across every
+  item in the call, each recorded as a movement:
+
+    holdStock      available → held     (an order is placed)
+    releaseStock   held → available     (it was cancelled, expired or failed)
+    consumeHeld    held → gone          (it was fulfilled: the units have left)
+
+  Every move is one conditional UPDATE, so concurrent callers cannot hold what is not there, release
+  what is not held, or take a figure below zero.
+
+    const [error, { items }] = await holdStock([{ id: resin.id, quantity: 175 }], { ref: 'order-1042', owner: 'my-extension' });
+    // ...paid:
+    await consumeHeld([{ id: resin.id, quantity: 175 }], { ref: 'order-1042', owner: 'my-extension' });
+    // ...or not:
+    await releaseStock([{ id: resin.id, quantity: 175 }], { ref: 'order-1042', owner: 'my-extension' });
+
+  `ref` is written on every movement, so what was held for an order can be found and given back
+  later. A refusal is a 409 that names the item, and nothing has changed.
+*/
+
+const newId = () => crypto.randomBytes(8).toString('hex');
+
+class Refusal {
+  constructor(error){
+    this.error = error;
+  }
+}
+
+/* What each move does to `quantity` and to `held`, per unit. */
+const MOVES = {
+  hold: { available: -1, held: 1 },
+  release: { available: 1, held: -1 },
+  consume: { available: 0, held: -1 },
+};
+
+const move = async (kind, input, { reason = '', note = '', ref = '', userId = '', owner = '' } = {}) => {
+  const list = Array.isArray(input) ? input : [input];
+  if(!list.length || list.some(entry => !entry || typeof entry !== 'object')) return [{ code: 400, msg: 'changes must be a non-empty list of { id, quantity }' }, null];
+
+  const totals = new Map();
+  for(const entry of list){
+    const id = String(entry.id ?? '');
+    const quantity = Number(entry.quantity);
+    if(!id) return [{ code: 400, msg: 'Every change needs an item id' }, null];
+    if(!Number.isInteger(quantity) || quantity <= 0) return [{ code: 400, msg: 'Every quantity must be a whole number above zero' }, null];
+    totals.set(id, (totals.get(id) ?? 0) + quantity);
+  }
+  /* In a fixed order, so two overlapping calls lock rows the same way round and cannot deadlock. */
+  const wanted = [...totals.entries()].map(([id, quantity]) => ({ id, quantity })).sort((a, b) => a.id.localeCompare(b.id));
+
+  let rows;
+  try {
+    rows = await db.select().from(kempoInventoryItem).where(inArray(kempoInventoryItem.id, wanted.map(entry => entry.id)));
+  } catch {
+    return [{ code: 500, msg: `Failed to ${kind} stock` }, null];
+  }
+  const existing = new Map(rows.map(row => [row.id, row]));
+  if(wanted.some(entry => !existing.has(entry.id))) return [{ code: 404, msg: 'An item in this change no longer exists' }, null];
+
+  const drafts = new Map();
+  for(const entry of wanted){
+    const draft = { kind, quantity: entry.quantity, reason: reason || kind, note };
+    const refused = await guard(EVENTS.stockBeforeHold, { item: existing.get(entry.id), draft, userId, actor: owner });
+    if(refused) return [refused, null];
+    const quantity = Number(draft.quantity);
+    if(!Number.isInteger(quantity) || quantity <= 0) return [{ code: 400, msg: 'quantity must be a whole number above zero' }, null];
+    drafts.set(entry.id, { quantity, reason: String(draft.reason || kind), note: String(draft.note || '') });
+  }
+
+  const { available, held } = MOVES[kind];
+
+  try {
+    const applied = await db.transaction(async tx => {
+      const results = [];
+      for(const entry of wanted){
+        const { quantity, reason: why, note: text } = drafts.get(entry.id);
+        const availableDelta = available * quantity;
+        const heldDelta = held * quantity;
+        const [row] = await tx.update(kempoInventoryItem)
+          .set({
+            quantity: sql`${kempoInventoryItem.quantity} + ${availableDelta}`,
+            held: sql`${kempoInventoryItem.held} + ${heldDelta}`,
+            updated: new Date(),
+          })
+          .where(and(
+            eq(kempoInventoryItem.id, entry.id),
+            sql`${kempoInventoryItem.quantity} + ${availableDelta} >= 0`,
+            sql`${kempoInventoryItem.held} + ${heldDelta} >= 0`,
+          ))
+          .returning();
+        if(!row){
+          const name = existing.get(entry.id).name;
+          throw new Refusal({
+            code: 409,
+            msg: kind === 'hold' ? `Not enough of ${name} is available to hold` : `${name} does not have that much on hold`,
+          });
+        }
+        const [movement] = await tx.insert(kempoInventoryMovement).values({
+          id: newId(), itemId: entry.id, delta: availableDelta, quantityAfter: row.quantity, heldDelta, heldAfter: row.held,
+          reason: why, note: ref ? `${text ? `${text} ` : ''}[${ref}]` : text, userId, created: new Date(),
+        }).returning();
+        results.push({ row, movement, availableDelta, heldDelta, quantity });
+      }
+      return results;
+    });
+
+    const items = [];
+    for(const { row, movement, availableDelta, heldDelta, quantity } of applied){
+      const item = { id: row.id, sku: row.sku, name: row.name, quantity: row.quantity, held: row.held, category: row.category, owner: row.owner };
+      items.push(item);
+      await notify(EVENTS.stockHeld, {
+        item, kind, quantity, previousQuantity: row.quantity - availableDelta, previousHeld: row.held - heldDelta,
+        movement, userId, actor: owner,
+      });
+      /* What is available changed, so everything listening for that is told in the usual way. */
+      if(availableDelta !== 0){
+        await notify(EVENTS.stockAdjusted, {
+          item, previousQuantity: row.quantity - availableDelta, delta: availableDelta,
+          reason: movement.reason, note: movement.note, movement, userId, actor: owner,
+        });
+      }
+    }
+    return [null, { items }];
+  } catch(error) {
+    if(error instanceof Refusal) return [error.error, null];
+    return [{ code: 500, msg: `Failed to ${kind} stock` }, null];
+  }
+};
+
+/* Sets units aside: they stop being available and are counted as held. */
+export const holdStock = (changes, options) => move('hold', changes, options);
+
+/* Gives held units back: they are available again. */
+export const releaseStock = (changes, options) => move('release', changes, options);
+
+/* Finishes with held units: they were used or sold, so they are no longer held and not available. */
+export const consumeHeld = (changes, options) => move('consume', changes, options);

package/server/utils/items.js

@@ -30,6 +30,7 @@ const shape = row => row && ({
   description: row.description,
   category: row.category,
   quantity: row.quantity,
+  held: row.held ?? 0,
   tags: row.tags ?? [],
   fields: row.data ?? {},
   owner: row.owner,
@@ -317,6 +318,7 @@ export const deleteItem = async (id, { userId = '', owner = '' } = {}) => {
   const [lookupError, existing] = await getItem(id);
   if(lookupError) return [lookupError, null];
   if(existing.owner !== owner) return [notYours('item', existing, owner), null];
+  if(existing.held > 0) return [{ code: 409, msg: `${existing.held} of this item are on hold for something unfinished, so it cannot be deleted yet` }, null];
 
   const refused = await guard(EVENTS.itemBeforeDelete, { item: existing, userId, actor: owner });
   if(refused) return [refused, null];
@@ -359,7 +361,7 @@ export const adjustStock = async (id, { delta, reason = 'adjustment', note = '',
         .returning();
       if(!row) return null;
       const [movement] = await tx.insert(kempoInventoryMovement).values({
-        id: newId(), itemId: id, delta: change, quantityAfter: row.quantity,
+        id: newId(), itemId: id, delta: change, quantityAfter: row.quantity, heldAfter: row.held,
         reason: String(draft.reason || 'adjustment'), note: String(draft.note || ''), userId, created: new Date(),
       }).returning();
       return { row, movement };
@@ -451,7 +453,7 @@ export const adjustStockMany = async (changes, { reason = 'adjustment', note = '
           .returning();
         if(!row) throw new Refusal({ code: 409, msg: `Insufficient stock of ${existing.get(entry.id).name}` });
         const [movement] = await tx.insert(kempoInventoryMovement).values({
-          id: newId(), itemId: entry.id, delta, quantityAfter: row.quantity, reason: why,
+          id: newId(), itemId: entry.id, delta, quantityAfter: row.quantity, heldAfter: row.held, reason: why,
           note: ref ? `${text ? `${text} ` : ''}[${ref}]` : text, userId, created: new Date(),
         }).returning();
         results.push({ row, movement, delta });

package/update.js

@@ -8,6 +8,11 @@ import { getSetting, setSetting, deleteSetting } from 'kempo/server/sdk.js';
   this on a database that already has the change is harmless.
 */
 export default async () => {
+  // Next: held stock. `quantity` stays what is available; `held` is what is set aside (server/utils/holds.js)
+  await db.execute(sql`ALTER TABLE "kempoInventoryItem" ADD COLUMN IF NOT EXISTS "held" integer NOT NULL DEFAULT 0`);
+  await db.execute(sql`ALTER TABLE "kempoInventoryMovement" ADD COLUMN IF NOT EXISTS "heldDelta" integer NOT NULL DEFAULT 0`);
+  await db.execute(sql`ALTER TABLE "kempoInventoryMovement" ADD COLUMN IF NOT EXISTS "heldAfter" integer NOT NULL DEFAULT 0`);
+
   // Next: media_provider is retired. kempo-media sits on kempo-files, so new uploads go through it whenever it is installed.
   await deleteSetting('kempo-inventory', 'media_provider');