From 8d8b35f51ffd7aa25d98032d35757c5771ae3500 Mon Sep 17 00:00:00 2001
From: Valentin Laurin <valentin.laurin@quickcase.app>
Date: Tue, 16 Jun 2026 12:18:30 +0100
Subject: [PATCH] Path: Update `buildCollectionItem` helper

To favour widespread adoption of the Path helpers, flexibility is needed when targeting collection items.
---
 src/path/helpers.js      | 13 ++++++++++---
 src/path/helpers.test.js | 18 +++++++++++++++++-
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/src/path/helpers.js b/src/path/helpers.js
index d4f2d3d..540d4e7 100644
--- a/src/path/helpers.js
+++ b/src/path/helpers.js
@@ -22,10 +22,17 @@ export const build = (...parts) => parts.join(SEPARATOR);
  *
  * @param {string} collectionPath - Path to the collection
  * @param {number | string} item - Index or ID of the item; undefined if item is not relevant (e.g. definition path)
- * @returns {string} Path to the item
+ * @param {boolean} targetValue - Whether to target the item value or the item root, defaults to `true` for backward compatibility
+ * @returns {string} Path to the item root or value
  */
-export const buildCollectionItem = (collectionPath, item) => {
-  return build(`${collectionPath}[${Number.isInteger(item) ? item : item ? 'id:' + item : ''}]`, 'value');
+export const buildCollectionItem = (collectionPath, item, targetValue = true) => {
+  const itemPath = `${collectionPath}[${Number.isInteger(item) ? item : item ? 'id:' + item : ''}]`;
+
+  if (targetValue) {
+    return build(itemPath, 'value');
+  }
+
+  return itemPath;
 };
 
 /**
diff --git a/src/path/helpers.test.js b/src/path/helpers.test.js
index 23a3057..8ba1f17 100644
--- a/src/path/helpers.test.js
+++ b/src/path/helpers.test.js
@@ -41,9 +41,25 @@ describe('buildCollectionItem', () => {
     {collection: '$.collection', item: 'some-id', expected: '$.collection[id:some-id].value'},
     {collection: '$.complex.collection', item: 'some-id', expected: '$.complex.collection[id:some-id].value'},
     {collection: '$.complex.collection', item: undefined, expected: '$.complex.collection[].value'},
-  ])('should build path: $expected', ({collection, item, expected}) => {
+  ])('should build path to item value: $expected', ({collection, item, expected}) => {
     expect(buildCollectionItem(collection, item)).toBe(expected);
   });
+
+  test.each([
+    {collection: 'collection', item: 0, expected: 'collection[0]'},
+    {collection: '$.collection', item: 0, expected: '$.collection[0]'},
+    {collection: 'collection', item: '0', expected: 'collection[id:0]'},
+    {collection: '$.collection', item: '0', expected: '$.collection[id:0]'},
+    {collection: '$.collection', item: undefined, expected: '$.collection[]'},
+    {collection: '$.collection', item: null, expected: '$.collection[]'},
+    {collection: '$.complex.collection', item: '0', expected: '$.complex.collection[id:0]'},
+    {collection: 'collection', item: 'some-id', expected: 'collection[id:some-id]'},
+    {collection: '$.collection', item: 'some-id', expected: '$.collection[id:some-id]'},
+    {collection: '$.complex.collection', item: 'some-id', expected: '$.complex.collection[id:some-id]'},
+    {collection: '$.complex.collection', item: undefined, expected: '$.complex.collection[]'},
+  ])('should build path to item root: $expected', ({collection, item, expected}) => {
+    expect(buildCollectionItem(collection, item, false)).toBe(expected);
+  });
 });
 
 describe('relative', () => {