@doswiftly/storefront-operations 5.4.1 → 5.5.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 5.5.0
+
+### Minor Changes
+
+- 9a715e2: `menu(handle:)` query now resolves `MenuItem.url` and `MenuItem.resource` server-side via a batched DataLoader (~1 SQL query per resource type, no N+1).
+
+  **What changed**
+  - `MenuItem.url` for `CATEGORY` / `COLLECTION` / `PAGE` / `PRODUCT` types is now computed from the linked resource's slug/handle and follows the convention `/categories/{slug}`, `/collections/{handle}`, `/pages/{handle}`, `/products/{slug}`. Previously this field returned `null` whenever the menu item only stored a `resourceId` (the common admin-created case), making the menu unusable for navigation rendering.
+  - `MenuItem.resource` is now populated with the actual `Category` / `Collection` / `ShopPage` / `Product` object. Previously it was always `null`. Resolution is batched per resource type — fetching a 50-item menu with mixed types triggers at most 4 service calls.
+  - `Menu.itemsCount` now returns the count of top-level items (equal to `items.length`), matching the Shopify Storefront API. Previously it returned a recursive count of all items across all nesting levels, which produced confusing mismatches with `items.length`.
+  - Static types (`HTTP` / `FRONTPAGE` / `SEARCH` / `CATALOG` / `BLOG`) and orphaned resource references are unchanged in shape but now have clearer field descriptions.
+
+  **Migration**
+
+  If you relied on `Menu.itemsCount` as a recursive total, switch to client-side counting:
+
+  ```ts
+  function countAllItems(items: MenuItem[]): number {
+    return items.reduce((acc, item) => acc + 1 + countAllItems(item.items), 0);
+  }
+  ```
+
+  If you previously worked around the missing `url` / `resource` by fetching each linked resource individually after reading the menu, you can now drop that code path.
+
 ## 5.4.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "5.4.1",
+  "version": "5.5.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {

package/schema.graphql

@@ -2662,7 +2662,7 @@ type Menu {
   """Top-level menu items"""
   items: [MenuItem!]!
 
-  """Total count of items across all levels"""
+  """The count of top-level items on the menu (equal to items.length)"""
   itemsCount: Int!
 
   """Menu title"""
@@ -2680,7 +2680,9 @@ type MenuItem {
   """Child menu items (max 3 levels)"""
   items: [MenuItem!]!
 
-  """Linked resource object (lazy, via DataLoader)"""
+  """
+  Linked resource object resolved server-side via DataLoader (batched per resource type — no N+1). Null when type is HTTP/FRONTPAGE/SEARCH/CATALOG/BLOG, or when resourceId points to a deleted resource.
+  """
   resource: MenuItemResource
 
   """Linked resource ID"""
@@ -2692,7 +2694,9 @@ type MenuItem {
   """Link type"""
   type: MenuItemType!
 
-  """Resolved URL (always computed server-side)"""
+  """
+  Resolved URL path computed server-side (e.g., /categories/funko, /products/toy-1, /pages/about, /collections/sale). Static types resolve to /, /search, /products, /blog. HTTP type returns the manually stored URL. Null only when type is a resource link (CATEGORY/COLLECTION/PAGE/PRODUCT) and the resource was deleted.
+  """
   url: String
 }