Narrow request-shape blocks via id + relax mapNodes mapper return

NarrowBlockItemByItemType now requires `id: string` and accepts an
optional `relationships?` constraint. That picks both the response form
(ItemInNestedResponse, id always present) and the updated request form
(UpdatedBlockInRequest, relationships optional), while excluding bare
string ids and freshly-created New blocks — finding those via item-type
isn't the typical use case anyway.

mapNodes / mapNodesAsync gain a free `R` parameter on the mapper so the
return type isn't constrained to `MapNodesMapperResult<T>`. Callers can
return nodes whose `item` payload is shaped differently from the input
tree (e.g. swapping a nested-response block for a request-shape block
built via buildBlockRecord) without fighting the inference.

Author: stefanoverna

packages/utils/README.md

@@ -237,8 +237,8 @@ await forEachNodeAsync(structuredText, async (node, parent, path) => {
 
 | Function                                                                                                        | Description                                                        |
 | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| [`mapNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L297)      | Transform nodes in the tree synchronously (1:1, splat, or remove)  |
-| [`mapNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L340) | Transform nodes in the tree asynchronously (1:1, splat, or remove) |
+| [`mapNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L309)      | Transform nodes in the tree synchronously (1:1, splat, or remove)  |
+| [`mapNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L355) | Transform nodes in the tree asynchronously (1:1, splat, or remove) |
 
 `mapNodes` walks the tree **bottom-up**: when the mapper sees a node, its
 descendants have already been transformed, and the mapper's return for that
@@ -306,10 +306,10 @@ const processed = await mapNodesAsync(structuredText, async (node) => {
 
 | Function                                                                                                             | Description                                                  |
 | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| [`collectNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L387)       | Collect all nodes that match a predicate function            |
-| [`collectNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L445)  | Collect all nodes that match an async predicate function     |
-| [`findFirstNode`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L484)      | Find the first node that matches a predicate function        |
-| [`findFirstNodeAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L562) | Find the first node that matches an async predicate function |
+| [`collectNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L402)       | Collect all nodes that match a predicate function            |
+| [`collectNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L460)  | Collect all nodes that match an async predicate function     |
+| [`findFirstNode`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L499)      | Find the first node that matches a predicate function        |
+| [`findFirstNodeAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L577) | Find the first node that matches an async predicate function |
 
 Find specific nodes using predicates or type guards:
 
@@ -344,8 +344,8 @@ const strongText = collectNodes(
 
 | Function                                                                                                           | Description                                             |
 | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
-| [`filterNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L611)      | Remove nodes that don't match a predicate synchronously |
-| [`filterNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L694) | Remove nodes that don't match an async predicate        |
+| [`filterNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L626)      | Remove nodes that don't match a predicate synchronously |
+| [`filterNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L709) | Remove nodes that don't match an async predicate        |
 
 Remove nodes that don't match a predicate:
 
@@ -373,8 +373,8 @@ const validated = await filterNodesAsync(structuredText, async (node) => {
 
 | Function                                                                                                           | Description                                                            |
 | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| [`reduceNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L781)      | Reduce the tree to a single value using a synchronous reducer function |
-| [`reduceNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L826) | Reduce the tree to a single value using an async reducer function      |
+| [`reduceNodes`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L796)      | Reduce the tree to a single value using a synchronous reducer function |
+| [`reduceNodesAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L841) | Reduce the tree to a single value using an async reducer function      |
 
 Reduce the entire tree to a single value:
 
@@ -408,10 +408,10 @@ const nodeCounts = reduceNodes(
 
 | Function                                                                                                         | Description                                                                           |
 | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| [`someNode`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L868)       | Check if any node in the tree matches a predicate (short-circuit evaluation)          |
-| [`someNodeAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L910)  | Check if any node in the tree matches an async predicate (short-circuit evaluation)   |
-| [`everyNode`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L952)      | Check if every node in the tree matches a predicate (short-circuit evaluation)        |
-| [`everyNodeAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L983) | Check if every node in the tree matches an async predicate (short-circuit evaluation) |
+| [`someNode`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L883)       | Check if any node in the tree matches a predicate (short-circuit evaluation)          |
+| [`someNodeAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L925)  | Check if any node in the tree matches an async predicate (short-circuit evaluation)   |
+| [`everyNode`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L967)      | Check if every node in the tree matches a predicate (short-circuit evaluation)        |
+| [`everyNodeAsync`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/manipulation.ts#L998) | Check if every node in the tree matches an async predicate (short-circuit evaluation) |
 
 Test if any or all nodes match a condition:
 

packages/utils/__tests__/guards.test.ts

@@ -122,29 +122,28 @@ export function isBlock<BlockItemType = BlockId, InlineBlockItemType = BlockId>(
 
 /**
  * Narrows a union of block item shapes to the member whose model
- * (`item_type`) matches `Id`. Bare string IDs (the unchanged-block form
- * inside request payloads) are filtered out — they have no shape to narrow.
+ * (`item_type`) matches `Id`.
  *
- * Discriminates on the `__itemTypeId` phantom field carried by every
- * object-shaped block variant exposed by `@datocms/cma-client-node`
- * (nested response items and both request-side variants — updated and
- * newly created). It deliberately does NOT key off
- * `relationships.item_type.data.id`: on the request-side "updated" shape
- * `relationships` is declared optional, which would cause an
- * `Extract`-based narrow to silently drop that variant.
+ * Matches existing (persisted) blocks — items that carry an `id` and
+ * whose `relationships.item_type.data.id` matches. That covers both the
+ * `nested: true` response form and the "updated block" variant of
+ * request payloads. Filtered out:
+ *   - bare string IDs (no `id` property to read)
+ *   - newly-created blocks in request payloads (they have no `id` yet —
+ *     the caller already knows the type, so finding them by model is
+ *     not the typical use case)
  *
- * For the per-D narrowing to fully resolve when the input was
- * parameterized over a *union* of item-type definitions, the upstream
- * `BlockInRequest<D>` / `BlockInNestedResponse<D>` types must distribute
- * over `D` (i.e. be defined as `D extends unknown ? ... : never`).
+ * `relationships` is constrained as optional so the updated-block
+ * request shape (where `relationships?` may be omitted when patching an
+ * existing block) is still picked up.
  */
-export type NarrowBlockItemByItemType<T, Id extends string> = T extends string
-  ? never
-  : T extends { __itemTypeId?: infer ItemTypeIds }
-  ? Id extends ItemTypeIds & string
-    ? T
-    : never
-  : never;
+export type NarrowBlockItemByItemType<T, Id extends string> = Extract<
+  T,
+  {
+    id: string;
+    relationships?: { item_type: { data: { type: 'item_type'; id: Id } } };
+  }
+>;
 
 function itemHasItemTypeId(item: unknown, itemTypeId: string): boolean {
   if (typeof item !== 'object' || item === null) return false;