@classytic/primitives 0.26.1 → 0.26.2

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.26.2
+
+### Added — `stockKeyFor` (`/item-identity`): one stock-key precedence for every package
+
+The product-level stock key, with a single precedence:
+
+1. the variant's stamped `skuRef` — assigned once at birth, immutable
+2. a **sole** variant with no stamp → the product's `_id`, never the label
+   (legacy writers derived `variantSku || productId`, and for one variant that
+   key IS the `_id`)
+3. a **sibling** with no stamp → its label, which genuinely is its legacy key
+4. nothing addressable → the product's `_id`
+
+The caller declares only what it HAS — `{ kind: 'sole' | 'label' | 'variant' }`
+— so the sole-vs-sibling decision is internal and a caller cannot make it wrong.
+That choice previously lived at every call site across three packages, in two
+functions with different fallbacks; they disagreed on a sole, unstamped,
+labelled variant, and the read then looked up a key no quant is stored under.
+
+It lives here, below every domain, because `@spinekit/order` and
+`@spinekit/catalog` must not import a peer domain — the rule sitting one layer
+too high is exactly why each package re-derived it.
+
 ## 0.26.1
 
 - `./testing/stock-key-seam` — new subpath; `scanStockKeySeam`, `assertStockKeySeam`, `takesStockKeyFromLabel`, `STOCK_KEY_SEAM_FIXTURES` for conformance-scanning packages that resolve stock keys

package/dist/item-identity.d.mts

@@ -31,6 +31,50 @@ interface SkuFields {
 declare function stockKeyOf(item: SkuFields, fallback?: string | {
   toString(): string;
 }): StockKey | undefined;
+/** The minimal product shape {@link stockKeyFor} reads. */
+interface StockKeySource {
+  _id: string | {
+    toString(): string;
+  };
+  variants?: ReadonlyArray<SkuFields> | null;
+}
+/**
+ * WHAT THE CALLER HAS — never what the key should be.
+ *
+ * - `sole`    nothing selected (a simple product, or a whole-product read)
+ * - `label`   an operator-typed / scanned SKU label
+ * - `variant` one variant record in hand, from iterating `variants`
+ */
+type StockKeySelector = {
+  readonly kind: "sole";
+} | {
+  readonly kind: "label";
+  readonly sku: string;
+} | {
+  readonly kind: "variant";
+  readonly variant: SkuFields;
+};
+/**
+ * THE product-level stock key. One precedence, for every package.
+ *
+ *   1. the variant's STAMPED `skuRef` — assigned once at birth, immutable
+ *   2. a SOLE variant with no stamp -> the product's `_id`. Never the label:
+ *      legacy writers derived `variantSku || productId`, and for one variant
+ *      that key IS the `_id`
+ *   3. a SIBLING with no stamp -> its label, which genuinely IS its legacy key
+ *   4. nothing addressable -> the product's `_id`
+ *
+ * The caller declares only what it HAS; the sole-vs-sibling decision is
+ * internal, so a caller cannot make it wrong. That choice previously lived at
+ * every call site across three packages, in two functions with different
+ * fallbacks — they disagreed on a sole, unstamped, labelled variant, and the
+ * read then looked up a key no quant is stored under.
+ *
+ * Lives HERE, below every domain, because `@spinekit/order` and
+ * `@spinekit/catalog` must not import a peer domain — the rule being one layer
+ * too high is exactly why each re-derived it.
+ */
+declare function stockKeyFor(product: StockKeySource, selector: StockKeySelector): StockKey;
 /**
  * {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
  * a reservation on `undefined` returns "out of stock" instead of failing.
@@ -58,4 +102,4 @@ declare function skuDisplay(item: SkuFields): SkuDisplay;
  */
 declare function looksLikeOpaqueId(value: string | undefined): boolean;
 //#endregion
-export { SkuDisplay, SkuFields, StockKey, looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };
+export { SkuDisplay, SkuFields, StockKey, StockKeySelector, StockKeySource, looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyFor, stockKeyOf };

package/dist/item-identity.mjs

@@ -14,6 +14,49 @@ function stockKeyOf(item, fallback) {
 	return nonEmpty(item.skuRef) ?? nonEmpty(item.sku) ?? (fallback !== void 0 ? String(fallback) : void 0);
 }
 /**
+* THE product-level stock key. One precedence, for every package.
+*
+*   1. the variant's STAMPED `skuRef` — assigned once at birth, immutable
+*   2. a SOLE variant with no stamp -> the product's `_id`. Never the label:
+*      legacy writers derived `variantSku || productId`, and for one variant
+*      that key IS the `_id`
+*   3. a SIBLING with no stamp -> its label, which genuinely IS its legacy key
+*   4. nothing addressable -> the product's `_id`
+*
+* The caller declares only what it HAS; the sole-vs-sibling decision is
+* internal, so a caller cannot make it wrong. That choice previously lived at
+* every call site across three packages, in two functions with different
+* fallbacks — they disagreed on a sole, unstamped, labelled variant, and the
+* read then looked up a key no quant is stored under.
+*
+* Lives HERE, below every domain, because `@spinekit/order` and
+* `@spinekit/catalog` must not import a peer domain — the rule being one layer
+* too high is exactly why each re-derived it.
+*/
+function stockKeyFor(product, selector) {
+	const productId = String(product._id);
+	const variants = product.variants ?? [];
+	const sole = variants.length <= 1;
+	switch (selector.kind) {
+		case "sole":
+			if (!sole) return productId;
+			return nonEmpty(variants[0]?.skuRef) ?? productId;
+		case "label": {
+			const matched = variants.find((v) => v.sku === selector.sku);
+			const stamp = nonEmpty(matched?.skuRef);
+			if (stamp !== void 0) return stamp;
+			if (sole) return productId;
+			return selector.sku;
+		}
+		case "variant": {
+			const stamp = nonEmpty(selector.variant.skuRef);
+			if (stamp !== void 0) return stamp;
+			if (sole) return productId;
+			return stockKeyOf(selector.variant, productId);
+		}
+	}
+}
+/**
 * {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
 * a reservation on `undefined` returns "out of stock" instead of failing.
 */
@@ -47,4 +90,4 @@ function looksLikeOpaqueId(value) {
 	return typeof value === "string" && /^[0-9a-f]{24}$/i.test(value);
 }
 //#endregion
-export { looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };
+export { looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyFor, stockKeyOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",