kempo-inventory 0.2.0 → 0.2.2

package/README.md

@@ -314,7 +314,8 @@ Every function resolves to `[error, result]`, where `error` is `{ code, msg }` o
 | `createItem({ sku, name, description, quantity, fields, userId }, { owner })` | Create. `owner` makes it your extension's |
 | `updateItem(id, { sku, name, description, fields, userId }, { owner })` | Update; `fields` is merged, and an empty value clears a field. SKU, name and category of an owned item need its `owner` |
 | `deleteItem(id, { userId, owner })` | Delete an item and its history (owned items need their `owner`) |
-| `adjustStock(id, { delta, reason, note, userId })` | The only way quantity changes, for anyone. Atomic; refuses to go below zero |
+| `adjustStock(id, { delta, reason, note, userId })` | The way quantity changes, for anyone. Atomic; refuses to go below zero |
+| `adjustStockMany(changes, { reason, note, ref, userId, owner })` | Several stock changes together: every one happens or none does. `changes` is `[{ id, delta }]`. Use it when one event touches several items, such as the materials of a recipe |
 | `unregisterItems(owner, { release })` | Delete every item you own, or with `release` hand them back to people |
 | `getMovements({ itemId, limit, offset })` | Stock history |
 | `getFields({ category, owner })`, `getField(key, category)` | Read field definitions. `getFields()` is every field (each with its `category` key and `categoryName`); with `category` it is what an item in that category shows |
@@ -328,6 +329,26 @@ Every function resolves to `[error, result]`, where `error` is `{ code, msg }` o
 
 An item looks like `{ id, sku, name, description, category, tags, quantity, fields: { ...custom values }, owner, created, updated }`.
 
+### Several items at once
+
+`adjustStock` changes one item in its own transaction, so a sale that uses resin, paint and filament could take the resin and then find the paint short. `adjustStockMany` applies the whole set together:
+
+```javascript
+import { adjustStockMany } from 'kempo-inventory/sdk';
+
+const [error, { items }] = await adjustStockMany(
+  [{ id: resin.id, delta: -175 }, { id: paint.id, delta: -20 }],
+  { reason: 'sale', ref: 'order-1042', owner: 'my-extension' },
+);
+// error.code 409 and error.msg "Insufficient stock of Paint (ml)": nothing changed
+```
+
+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.
+
+### 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".)
+
 ### Hooks
 
 Declare these in your `kempo-config.json` `hooks`. Every payload also carries `actor`: the extension that made the change through the SDK, or `''` for a person using the admin.

package/admin/edit/index.page.html

@@ -12,6 +12,12 @@ locked: true
 
   <div id="editItem" style="max-width: 44rem;"></div>
 
+  <!--
+    An extension can add to this page by supplying a fragment with this name in its own admin/
+    directory (inventory-item-actions.fragment.html). It reads the item from ?id= in the address.
+  -->
+  <fragment name="inventory-item-actions"></fragment>
+
   <script type="module">
     import { getItem, getFields } from '/inventory/sdk.js';
     import { getAllCurrentUserPermissions } from '/kempo/sdk.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo-inventory",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A basic inventory management system for kempo cms",
   "license": "MIT",
   "author": "Dustin Poissant",

package/sdk.js

@@ -32,6 +32,7 @@ export {
   deleteItem,
   unregisterItems,
   adjustStock,
+  adjustStockMany,
   getMovements,
 } from './server/utils/items.js';
 

package/server/utils/items.js

@@ -377,6 +377,102 @@ export const adjustStock = async (id, { delta, reason = 'adjustment', note = '',
   }
 };
 
+/*
+  Thrown inside a transaction to roll everything back with a message the caller can show.
+*/
+class Refusal {
+  constructor(error){
+    this.error = error;
+  }
+}
+
+/*
+  Applies several stock changes together: every one happens or none does. This is what makes
+  taking the materials for a whole recipe safe, where one adjustStock per item could take the resin
+  and then fail on the paint. `changes` is [{ id, delta, reason?, note? }]; changes to the same item
+  are added together, and one that nets to nothing is left out. Each item runs through the same
+  before_adjust guard as adjustStock, and fires the same stock:adjusted notification once everything
+  is committed.
+
+    const [error, result] = await adjustStockMany(
+      [{ id: resin.id, delta: -175 }, { id: paint.id, delta: -20 }],
+      { reason: 'sale', ref: 'order-1042', owner: 'my-extension' },
+    );
+
+  `ref` is recorded on every movement so the change can be found and reversed later. A refusal for
+  lack of stock is a 409 that names the item, and nothing has changed. Resolves to
+  [null, { items }] with the items as they are now.
+*/
+export const adjustStockMany = async (changes, { reason = 'adjustment', note = '', ref = '', userId = '', owner = '' } = {}) => {
+  if(!Array.isArray(changes) || !changes.length) return [{ code: 400, msg: 'changes must be a non-empty list' }, null];
+
+  const totals = new Map();
+  for(const change of changes){
+    const id = String(change?.id ?? '');
+    const delta = toInt(change?.delta, NaN);
+    if(!id) return [{ code: 400, msg: 'Every change needs an item id' }, null];
+    if(Number.isNaN(delta)) return [{ code: 400, msg: 'Every delta must be a whole number' }, null];
+    const entry = totals.get(id) ?? { id, delta: 0, reason: change.reason, note: change.note };
+    entry.delta += delta;
+    totals.set(id, entry);
+  }
+  /* In a fixed order, so two overlapping calls lock rows the same way round and cannot deadlock. */
+  const wanted = [...totals.values()].filter(entry => entry.delta !== 0).sort((a, b) => a.id.localeCompare(b.id));
+  if(!wanted.length) return [null, { items: [] }];
+
+  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 adjust stock' }, null];
+  }
+  const existing = new Map(rows.map(row => [row.id, shape(row)]));
+  const missing = wanted.find(entry => !existing.has(entry.id));
+  if(missing) return [{ code: 404, msg: 'An item in this change no longer exists' }, null];
+
+  const drafts = new Map();
+  for(const entry of wanted){
+    const draft = { delta: entry.delta, reason: entry.reason ?? reason, note: entry.note ?? note };
+    const refused = await guard(EVENTS.stockBeforeAdjust, { item: existing.get(entry.id), draft, userId, actor: owner });
+    if(refused) return [refused, null];
+    const delta = toInt(draft.delta, NaN);
+    if(Number.isNaN(delta) || delta === 0) return [{ code: 400, msg: 'delta must be a non-zero whole number' }, null];
+    drafts.set(entry.id, { delta, reason: String(draft.reason || 'adjustment'), note: String(draft.note || '') });
+  }
+
+  try {
+    const applied = await db.transaction(async tx => {
+      const results = [];
+      for(const entry of wanted){
+        const { delta, reason: why, note: text } = drafts.get(entry.id);
+        const [row] = await tx.update(kempoInventoryItem)
+          .set({ quantity: sql`${kempoInventoryItem.quantity} + ${delta}`, updated: new Date() })
+          .where(and(eq(kempoInventoryItem.id, entry.id), sql`${kempoInventoryItem.quantity} + ${delta} >= 0`))
+          .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,
+          note: ref ? `${text ? `${text} ` : ''}[${ref}]` : text, userId, created: new Date(),
+        }).returning();
+        results.push({ row, movement, delta });
+      }
+      return results;
+    });
+    const items = [];
+    for(const { row, movement, delta } of applied){
+      const item = shape(row);
+      items.push(item);
+      await notify(EVENTS.stockAdjusted, {
+        item, previousQuantity: item.quantity - delta, delta, 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 adjust stock' }, null];
+  }
+};
+
 export const getMovements = async ({ itemId, limit = 50, offset = 0 } = {}) => {
   try {
     const where = itemId ? eq(kempoInventoryMovement.itemId, itemId) : undefined;