@happyvertical/smrt-inventory

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.5万

Multi-location stock tracking for the SMRT framework — Sku, InventoryLocation, StockLevel, StockMovement, lot and serial tracking, and stock-mutation and lot services

原始使用文档
文档目录19 节
  1. Installation
  2. Usage
  3. Set up SKUs, locations, and a stock service
  4. Move stock through its lifecycle
  5. Query balances and the audit log
  6. Catch the insufficient-stock error
  7. Multi-tenancy
  8. Opt-in DispatchBus wiring
  9. API
  10. Models
  11. Collections
  12. Service
  13. Lots and serials
  14. Types
  15. Dependencies
  16. License
  17. Database initialization
  18. Reorder policies and movement actors
  19. Svelte components

@happyvertical/smrt-inventory

Multi-location stock tracking for the s-m-r-t framework. Strictly industry-neutral — the same primitives serve apparel, furniture, automotive, CPG, electronics, and any other vertical that counts discrete units across locations.

Installation

pnpm add @happyvertical/smrt-inventory

Usage

Set up SKUs, locations, and a stock service

import {
  createStockService,
  InventoryLocationCollection,
} from '@happyvertical/smrt-inventory';
// The `@happyvertical/smrt-products` root entry pulls in Vite virtual
// modules (`@smrt/client` etc.) and won't resolve under plain Node /
// tsx. Import from the `/collections` subpath for server-side scripts,
// tests, and SSR runtimes that don't run the Vite plugin.
import { SkuCollection } from '@happyvertical/smrt-products/collections';

const db = { type: 'sqlite', url: 'app.db' };
const skus = await SkuCollection.create({ db });
const locations = await InventoryLocationCollection.create({ db });
const stock = await createStockService({ db });

const widget = await skus.create({
  productId: 'prod-1',
  code: 'WIDGET-001',
  barcode: '0123456789012',
  attributes: { finish: 'matte' },
});
await widget.save();

const warehouse = await locations.create({
  code: 'WH-EAST',
  name: 'Warehouse East',
  kind: 'warehouse',
});
await warehouse.save();

Move stock through its lifecycle

Every method writes one (or two, for transfers) StockMovement audit rows so the ledger stays in lockstep with the materialized levels.

// Inbound receipt — +qty available.
await stock.receive(widget.id!, warehouse.id!, 100, {
  sourceType: 'PurchaseOrder',
  sourceId: po.id,
});

// Reserve against an order — available → allocated.
// Throws InsufficientStockError if there isn't enough available.
await stock.reserve(widget.id!, warehouse.id!, 10, {
  sourceType: 'Contract',
  sourceId: order.id,
});

// Ship — removes from allocated, leaves the building.
await stock.fulfill(widget.id!, warehouse.id!, 10, {
  sourceType: 'Fulfillment',
  sourceId: shipment.id,
});

// Cycle count caught five extra units — non-zero signed delta.
await stock.adjust(widget.id!, warehouse.id!, 5, {
  sourceType: 'CycleCount',
  sourceId: count.id,
});

// Move stock between locations — writes transfer_out + transfer_in legs.
await stock.transfer(widget.id!, warehouse.id!, store.id!, 12, {
  sourceType: 'TransferOrder',
  sourceId: xfer.id,
});

Query balances and the audit log

import {
  StockLevelCollection,
  StockMovementCollection,
} from '@happyvertical/smrt-inventory';

const levels = await StockLevelCollection.create({ db });
const movements = await StockMovementCollection.create({ db });

// What's on hand at this location across every state?
const here = await levels.findByLocation(warehouse.id!);

// What's the available total for a SKU across all locations?
const availableTotal = await levels.totalForSku(widget.id!, 'available');

// What movements were caused by a particular contract?
const audit = await movements.findBySource('Contract', order.id);

Catch the insufficient-stock error

import { InsufficientStockError } from '@happyvertical/smrt-inventory';

try {
  await stock.reserve(widget.id!, warehouse.id!, 9999);
} catch (err) {
  if (err instanceof InsufficientStockError) {
    console.log(
      `Only ${err.available} available for ${err.skuId} at ${err.locationId}, requested ${err.requested}`,
    );
  } else {
    throw err;
  }
}

Multi-tenancy

The inventory models (InventoryLocation, StockLevel, StockMovement, and the lot models Lot, LotUsage, LotCorrection, LotDocument, LotStockLevel) use @TenantScoped({ mode: 'optional' }) with a nullable tenantId. The catalog shapes (Sku, Product, ProductVariant, Material) live in @happyvertical/smrt-products and carry their own tenant decoration there; the cross-package id refs flow through unchanged. Wrap mutations in withTenant() from @happyvertical/smrt-tenancy to scope queries automatically.

import { withTenant } from '@happyvertical/smrt-tenancy';

await withTenant({ tenantId: 'tenant-a' }, async () => {
  // Every read/write through skus, locations, levels, movements, and the
  // StockService is filtered by tenant_id = 'tenant-a'.
  await stock.receive(widget.id!, warehouse.id!, 100);
});

Opt-in DispatchBus wiring

The package ships handlers that bridge contract:created → reserve() and fulfillment:shipped → fulfill(). Off by default; install them explicitly in your smrt.ts to enable automatic stock motion:

import { createDispatchBus } from '@happyvertical/smrt-core';
import { installInventoryDispatchHandlers } from '@happyvertical/smrt-inventory';

const bus = await createDispatchBus({ db });
const handlers = await installInventoryDispatchHandlers({
  dispatchBus: bus,
  db,
});

// In smrt-commerce (or your own code):
await bus.emit('contract:created', {
  contractId: order.id,
  lines: [{ skuId, locationId, qty }],
});

// Later, on shipment:
await bus.emit('fulfillment:shipped', {
  fulfillmentId: shipment.id,
  lines: [{ skuId, locationId, qty }],
});

Per-handler toggles (installContractReserved, installFulfillmentShipped) let consumers pick exactly the signals they care about. The production_order:posted handler is intentionally not installed here; that bridge lives in @happyvertical/smrt-manufacturing.

API

Models

ExportDescription
InventoryLocationPhysical or virtual stocking site with open-ended kind.
StockLevelMaterialized (skuId, locationId, state) → qty row. Never mutate directly — use StockService.
StockMovementAppend-only audit row. One per mutation; two for transfers. Carries a nullable lotId.
LotA batch (kind: 'lot') or single unit ('serial') with a number, attributes and status. Write via LotService.
LotStockLevelMaterialized (lotId, locationId, state) → qty row. Written only by StockService.
LotUsageA lot used by a consumer (consumerType + consumerId; 'Lot' for assemblies). Never deleted; unlinked instead.
LotCorrectionAppend-only record of every correction, with reason, old and new value.
LotDocumentA stored file (an Asset id) attached to a lot. Detached, never deleted.

Collections

ExportDescription
InventoryLocationCollectionfindByCode, findByKind, findByPlace, findActive
StockLevelCollectiongetLevel, findBySku, findByLocation, totalForSku, totalForLocation
StockMovementCollectionfindBySku, findByLocation, findBySource, findByReason
LotCollectionfindByLotNumber(number, { skuId? }) (case-insensitive)
LotStockLevelCollectiongetLevel(lotId, locationId, state?), onHand(lotId, state?)
LotUsageCollectionfindActiveForLot, findForConsumer
LotCorrectionCollection, LotDocumentCollectionRead access

All catalog shapes (Product, Material, ProductVariant, Sku) live in @happyvertical/smrt-products. This package adds the stock-motion layer (InventoryLocation, StockLevel, StockMovement, StockService) on top.

Service

ExportDescription
StockServiceThe only sanctioned mutation surface. Six methods: receive, reserve, release, fulfill, transfer, adjust.
createStockService({ db })Convenience factory.
InsufficientStockErrorThrown by reserve / fulfill / transfer / negative adjust when stock would go negative. Carries skuId, locationId, state, requested, available.
LotService / createLotService({ db })Lots and serials: receiveLot, correctLotNumber, correctAttributes, setStatus, recordUsage, unlinkUsage, attachDocument, detachDocument, history, traceForward, traceBack, withTransaction.
DuplicateLotError, LotInUseError, LotMismatchError, LotNotFoundError, LotCorrectionErrorLot failures.
installInventoryDispatchHandlers({ dispatchBus, db })Opt-in DispatchBus wiring for contract:created and fulfillment:shipped.

Lots and serials

Pass lotId to any StockService mutation and the same deltas are applied per lot (with the same non-negative rule) and the lot is stamped on every movement; SKU-level balances behave as before. LotService creates the lots. Receiving a lot moves no stock, so compose both in one transaction:

await stock.withTransaction(async (tx) => {
  const lots = await createLotService({ db: tx.db });
  const lot = await lots.receiveLot({ lotNumber: 'B-1042', skuId, receivedQty: 40 });
  await tx.receive(skuId, locationId, 40, { lotId: lot.id });
});
await lots.recordUsage(lot.id, { consumerType: 'ProductionOrder', consumerId });
const trace = await lots.traceForward(lot.id);        // where it went
const sources = await lots.traceBack('ProductionOrder', consumerId); // where it came from

A lot number is not unique by default (one supplier lot can arrive on two receipts); pass unique: true, or kind: 'serial', to make it so, or idempotencyKey to make a receipt retry-safe. A repeated idempotencyKey returns the first lot even if other fields differ, and a repeated recordUsage for one consumer returns the existing usage unchanged. StockService ignores lot.status; callers decide what a quarantined lot may do. Corrections always need a reason. No authorization is checked in the package; callers authorize and pass actorProfileId.

Existing deployments must generate and apply their normal s-m-r-t schema migration before using lots: five new tables (inventory_lots, inventory_lot_stock_levels, inventory_lot_usages, inventory_lot_corrections, inventory_lot_documents) and a nullable lot_id on inventory_stock_movements (UUID on PostgreSQL/DuckDB, text on SQLite). Existing rows and StockLevel's unique key are unchanged; runtime reads do not create tables.

Types

ExportDescription
StockState'available' | 'allocated' | 'wip' | 'qc_hold' | 'damaged'
InventoryLocationKindOpen-ended classifier string
StockMovementReasonCanonical reason vocabulary ('receipt', 'reservation', 'release', 'fulfillment', 'transfer_out', 'transfer_in', 'adjustment', 'production_consume', 'production_produce') plus free-form strings

Dependencies

PackagePurpose
@happyvertical/smrt-coreSmrtObject / SmrtCollection / DispatchBus
@happyvertical/smrt-tenancyOptional tenant scoping
@happyvertical/sqlDatabase adapter

License

MIT

Database initialization

StockService.create() and transaction-scoped service construction initialize their three collections sequentially. Each initialization checks framework system tables on the shared connection; parallel probes can interfere on DuckDB. This ordering does not change the single-transaction stock/audit contract or provision application schema at runtime.

The package test suite covers cold SQLite/DuckDB initialization and repeated transaction rollback. Set SMRT_TEST_POSTGRES_URL to an isolated PostgreSQL database to exercise the same fixture on PostgreSQL.

Reorder policies and movement actors

stock.setReorderPolicy(skuId, locationId, reorderPoint, reorderQuantity?) sets nullable decimal metadata on the available stock row. It creates a zero-balance row if necessary without inventing an audit movement. Values must be finite and non-negative; null disables monitoring, and omitting the reorder quantity clears its suggestion. Stock mutations preserve these settings. stock.levels.findBelowReorderPoint(locationId?) returns visible available rows whose quantity is strictly less than their configured point. Equality, unset thresholds, and other states do not count. Both methods retain normal tenant scoping and the setter participates in stock.withTransaction().

Every mutation accepts actorProfileId alongside source attribution. It is a nullable qualified reference to @happyvertical/smrt-profiles:Profile, copied to every ledger row including both transfer legs. Omission records null for legacy callers and unattended automation. Supply the profile ID from trusted server context; this attribution field does not authorize the caller.

Existing deployments must generate and apply their normal s-m-r-t schema migration before using these fields: add nullable decimal reorder_point and reorder_quantity to inventory_stock_levels, and nullable profile-reference actor_profile_id to inventory_stock_movements (UUID on PostgreSQL/DuckDB, text on SQLite). Existing rows remain unset; runtime reads do not migrate tables.

Svelte components

The optional @happyvertical/smrt-inventory/svelte entry exports:

ComponentData / callback contract
StockLevelslevels, optional locationId; shows balance, reorder settings and low-stock status
MovementHistorymovements; read-only history with actor, source and note
AdjustStockFormskuId, locationId, onsubmit({ skuId, locationId, delta, reasonCode, note })
LocationListlocations, optional onedit(location); includes inactive locations
LocationFormoptional location, onsubmit({ id?, code, name, kind, placeId, active })

The entry also exports structural browser-safe data types. Hosts load authorized records and implement callbacks; components do not import database models, fetch endpoints, or manage authentication. Route adjustment submissions through StockService.adjust, attaching the trusted actor on the server. Save location forms through InventoryLocationCollection; deactivate using active: false rather than deleting history. Both forms accept disabled, prevent duplicate submissions while awaiting callbacks, and display callback failures. Reorder policy editing uses the service method above; stock quantities and movements remain read-only outside the adjustment workflow.

版本与发布记录

@happyvertical/smrt-inventory 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-inventory 的常见问题

@happyvertical/smrt-inventory 是什么?

Multi-location stock tracking for the SMRT framework — Sku, InventoryLocation, StockLevel, StockMovement, lot and serial tracking, and stock-mutation and lot services

如何安装 @happyvertical/smrt-inventory?

在项目目录运行 npm install @happyvertical/smrt-inventory,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-inventory 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-inventory 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-inventory 可以商用吗?

@happyvertical/smrt-inventory 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-inventory 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-inventory 在 2026/10/17 – 2026/11/15 这 30 天内被下载 14,753 次,日均约 492 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-inventory 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 365 个版本,其中过去 12 个月发布了 365 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。