@narrative.io/jsonforms-provider-protocols 1.2.0-beta.1 → 1.2.0-beta.3

package/README.md

@@ -141,6 +141,94 @@ const CustomProtocol: Protocol = {
 }
 ```
 
+### Data Transforms
+Transform API response data before mapping to form items using a pipeline of transforms:
+
+```json
+{
+  "provider": {
+    "protocol": "rest_api",
+    "config": {
+      "url": "https://api.example.com/data",
+      "items": "$.data[*]",
+      "transforms": [
+        {
+          "name": "flatten",
+          "key": "children",
+          "labelFormat": "{parent.name} → {name}"
+        },
+        {
+          "name": "filter",
+          "key": "active",
+          "values": [true]
+        }
+      ],
+      "map": {
+        "label": "$.name",
+        "value": "$.id"
+      }
+    }
+  }
+}
+```
+
+#### Built-in Transforms
+
+**Flatten Transform**
+Recursively flattens nested tree structures into a single-level array:
+
+```json
+{
+  "name": "flatten",
+  "key": "children",
+  "labelFormat": "{parent.name} → {name}"
+}
+```
+
+- `key`: The property containing nested children arrays
+- `labelFormat` (optional): Template for formatting labels using parent and child properties
+- Adds `_depth`, `_parent`, and `_formattedLabel` metadata to items
+
+**Filter Transform**
+Filters items based on property values:
+
+```json
+{
+  "name": "filter",
+  "key": "category",
+  "values": ["A", "B"]
+}
+```
+
+- `key`: The property to check
+- `values` (optional): Array of values to match. If omitted, filters by key existence
+
+**Combining Transforms**
+Transforms are applied sequentially in pipeline order:
+
+```json
+{
+  "transforms": [
+    { "name": "flatten", "key": "children" },
+    { "name": "filter", "key": "type", "values": ["product"] }
+  ]
+}
+```
+
+**Custom Transforms**
+Register custom transforms for your specific needs:
+
+```typescript
+import { registerTransform } from '@narrative.io/jsonforms-provider-protocols'
+
+registerTransform('uppercase', (items, config) => {
+  return items.map(item => ({
+    ...item,
+    name: item.name.toUpperCase()
+  }))
+})
+```
+
 ### Template Variables
 Create dynamic URLs using form data:
 

package/dist/core/transforms.d.ts

@@ -11,7 +11,12 @@ export interface FlattenTransform extends Transform {
     key: string;
     labelFormat?: string;
 }
-export type TransformStep = FlattenTransform;
+export interface FilterTransform extends Transform {
+    name: "filter";
+    key: string;
+    values?: unknown[];
+}
+export type TransformStep = FlattenTransform | FilterTransform;
 export type TransformPipeline = TransformStep[];
 /**
  * Registry of transform functions

package/dist/core/transforms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transforms.d.ts","sourceRoot":"","sources":["../../src/core/transforms.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAE7C,MAAM,MAAM,iBAAiB,GAAG,aAAa,EAAE,CAAC;AAEhD;;GAEG;AACH,KAAK,iBAAiB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,EAAE,CAAC;AAI5E;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,iBAAiB,GAAG,IAAI,CAE3E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EAAE,EAChB,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,EAAE,CAYX"}
+{"version":3,"file":"transforms.d.ts","sourceRoot":"","sources":["../../src/core/transforms.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAE/D,MAAM,MAAM,iBAAiB,GAAG,aAAa,EAAE,CAAC;AAEhD;;GAEG;AACH,KAAK,iBAAiB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,EAAE,CAAC;AAI5E;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,iBAAiB,GAAG,IAAI,CAE3E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EAAE,EAChB,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,EAAE,CAYX"}

package/dist/core/transforms.js

@@ -17,40 +17,63 @@ function flattenTransform(items, config) {
   const flattenConfig = config;
   const { key, labelFormat } = flattenConfig;
   const flattened = [];
-  for (const item of items) {
-    if (typeof item !== "object" || item === null) continue;
+  function flattenRecursive(item, parent = null, depth = 0) {
+    if (typeof item !== "object" || item === null) return;
     const itemObj = item;
+    if (labelFormat && parent) {
+      const formattedItem = { ...itemObj };
+      let formattedLabel = labelFormat;
+      formattedLabel = formattedLabel.replace(
+        /\{parent\.(\w+)\}/g,
+        (_, prop) => String(parent[prop] ?? "")
+      );
+      formattedLabel = formattedLabel.replace(
+        /\{(\w+)\}/g,
+        (_, prop) => String(itemObj[prop] ?? "")
+      );
+      formattedItem._formattedLabel = formattedLabel;
+      formattedItem._parent = parent;
+      formattedItem._depth = depth;
+      flattened.push(formattedItem);
+    } else if (parent) {
+      flattened.push({
+        ...itemObj,
+        _parent: parent,
+        _depth: depth
+      });
+    } else {
+      flattened.push({
+        ...itemObj,
+        _depth: depth
+      });
+    }
     const children = itemObj[key];
     if (Array.isArray(children)) {
       for (const child of children) {
-        if (typeof child !== "object" || child === null) continue;
-        const childObj = child;
-        if (labelFormat) {
-          const formattedChild = { ...childObj };
-          let formattedLabel = labelFormat;
-          formattedLabel = formattedLabel.replace(
-            /\{parent\.(\w+)\}/g,
-            (_, prop) => String(itemObj[prop] ?? "")
-          );
-          formattedLabel = formattedLabel.replace(
-            /\{(\w+)\}/g,
-            (_, prop) => String(childObj[prop] ?? "")
-          );
-          formattedChild._formattedLabel = formattedLabel;
-          formattedChild._parent = itemObj;
-          flattened.push(formattedChild);
-        } else {
-          flattened.push({
-            ...childObj,
-            _parent: itemObj
-          });
-        }
+        flattenRecursive(child, itemObj, depth + 1);
       }
     }
   }
+  for (const item of items) {
+    flattenRecursive(item, null, 0);
+  }
   return flattened;
 }
+function filterTransform(items, config) {
+  const filterConfig = config;
+  const { key, values } = filterConfig;
+  return items.filter((item) => {
+    if (typeof item !== "object" || item === null) return false;
+    const itemObj = item;
+    if (!values || values.length === 0) {
+      return key in itemObj;
+    }
+    const itemValue = itemObj[key];
+    return values.includes(itemValue);
+  });
+}
 registerTransform("flatten", flattenTransform);
+registerTransform("filter", filterTransform);
 export {
   applyTransformPipeline,
   registerTransform

package/dist/core/transforms.js.map

@@ -1 +1 @@
-{"version":3,"file":"transforms.js","sources":["../../src/core/transforms.ts"],"sourcesContent":["/**\n * Transform pipeline system for manipulating API response data\n * Transforms are applied sequentially in the order they appear in the pipeline\n */\n\nexport interface Transform {\n  name: string;\n  [key: string]: unknown;\n}\n\nexport interface FlattenTransform extends Transform {\n  name: \"flatten\";\n  key: string; // The key containing the nested array to flatten\n  labelFormat?: string; // Optional format string like \"{parent.name} → {name}\"\n}\n\nexport type TransformStep = FlattenTransform;\n\nexport type TransformPipeline = TransformStep[];\n\n/**\n * Registry of transform functions\n */\ntype TransformFunction = (items: unknown[], config: Transform) => unknown[];\n\nconst transformRegistry: Record<string, TransformFunction> = {};\n\n/**\n * Register a transform function\n */\nexport function registerTransform(name: string, fn: TransformFunction): void {\n  transformRegistry[name] = fn;\n}\n\n/**\n * Apply a pipeline of transforms to data\n */\nexport function applyTransformPipeline(\n  items: unknown[],\n  pipeline: TransformPipeline,\n): unknown[] {\n  let result = items;\n\n  for (const transform of pipeline) {\n    const fn = transformRegistry[transform.name];\n    if (!fn) {\n      throw new Error(`Unknown transform: ${transform.name}`);\n    }\n    result = fn(result, transform);\n  }\n\n  return result;\n}\n\n/**\n * Flatten transform - flattens nested arrays into a single level\n */\nfunction flattenTransform(items: unknown[], config: Transform): unknown[] {\n  const flattenConfig = config as FlattenTransform;\n  const { key, labelFormat } = flattenConfig;\n  const flattened: unknown[] = [];\n\n  for (const item of items) {\n    if (typeof item !== \"object\" || item === null) continue;\n\n    const itemObj = item as Record<string, unknown>;\n    const children = itemObj[key];\n\n    if (Array.isArray(children)) {\n      for (const child of children) {\n        if (typeof child !== \"object\" || child === null) continue;\n\n        const childObj = child as Record<string, unknown>;\n\n        // If labelFormat is provided, use it to format the label\n        if (labelFormat) {\n          const formattedChild = { ...childObj };\n\n          // Replace placeholders like {parent.name} and {name}\n          let formattedLabel = labelFormat;\n          formattedLabel = formattedLabel.replace(\n            /\\{parent\\.(\\w+)\\}/g,\n            (_, prop) => String(itemObj[prop] ?? \"\"),\n          );\n          formattedLabel = formattedLabel.replace(/\\{(\\w+)\\}/g, (_, prop) =>\n            String(childObj[prop] ?? \"\"),\n          );\n\n          formattedChild._formattedLabel = formattedLabel;\n          formattedChild._parent = itemObj;\n          flattened.push(formattedChild);\n        } else {\n          // Just add parent reference\n          flattened.push({\n            ...childObj,\n            _parent: itemObj,\n          });\n        }\n      }\n    }\n  }\n\n  return flattened;\n}\n\n// Register built-in transforms\nregisterTransform(\"flatten\", flattenTransform);\n"],"names":[],"mappings":"AAyBA,MAAM,oBAAuD,CAAA;AAKtD,SAAS,kBAAkB,MAAc,IAA6B;AAC3E,oBAAkB,IAAI,IAAI;AAC5B;AAKO,SAAS,uBACd,OACA,UACW;AACX,MAAI,SAAS;AAEb,aAAW,aAAa,UAAU;AAChC,UAAM,KAAK,kBAAkB,UAAU,IAAI;AAC3C,QAAI,CAAC,IAAI;AACP,YAAM,IAAI,MAAM,sBAAsB,UAAU,IAAI,EAAE;AAAA,IACxD;AACA,aAAS,GAAG,QAAQ,SAAS;AAAA,EAC/B;AAEA,SAAO;AACT;AAKA,SAAS,iBAAiB,OAAkB,QAA8B;AACxE,QAAM,gBAAgB;AACtB,QAAM,EAAE,KAAK,YAAA,IAAgB;AAC7B,QAAM,YAAuB,CAAA;AAE7B,aAAW,QAAQ,OAAO;AACxB,QAAI,OAAO,SAAS,YAAY,SAAS,KAAM;AAE/C,UAAM,UAAU;AAChB,UAAM,WAAW,QAAQ,GAAG;AAE5B,QAAI,MAAM,QAAQ,QAAQ,GAAG;AAC3B,iBAAW,SAAS,UAAU;AAC5B,YAAI,OAAO,UAAU,YAAY,UAAU,KAAM;AAEjD,cAAM,WAAW;AAGjB,YAAI,aAAa;AACf,gBAAM,iBAAiB,EAAE,GAAG,SAAA;AAG5B,cAAI,iBAAiB;AACrB,2BAAiB,eAAe;AAAA,YAC9B;AAAA,YACA,CAAC,GAAG,SAAS,OAAO,QAAQ,IAAI,KAAK,EAAE;AAAA,UAAA;AAEzC,2BAAiB,eAAe;AAAA,YAAQ;AAAA,YAAc,CAAC,GAAG,SACxD,OAAO,SAAS,IAAI,KAAK,EAAE;AAAA,UAAA;AAG7B,yBAAe,kBAAkB;AACjC,yBAAe,UAAU;AACzB,oBAAU,KAAK,cAAc;AAAA,QAC/B,OAAO;AAEL,oBAAU,KAAK;AAAA,YACb,GAAG;AAAA,YACH,SAAS;AAAA,UAAA,CACV;AAAA,QACH;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAGA,kBAAkB,WAAW,gBAAgB;"}
+{"version":3,"file":"transforms.js","sources":["../../src/core/transforms.ts"],"sourcesContent":["/**\n * Transform pipeline system for manipulating API response data\n * Transforms are applied sequentially in the order they appear in the pipeline\n */\n\nexport interface Transform {\n  name: string;\n  [key: string]: unknown;\n}\n\nexport interface FlattenTransform extends Transform {\n  name: \"flatten\";\n  key: string; // The key containing the nested array to flatten\n  labelFormat?: string; // Optional format string like \"{parent.name} → {name}\"\n}\n\nexport interface FilterTransform extends Transform {\n  name: \"filter\";\n  key: string; // The key to check\n  values?: unknown[]; // Optional array of values to match against\n}\n\nexport type TransformStep = FlattenTransform | FilterTransform;\n\nexport type TransformPipeline = TransformStep[];\n\n/**\n * Registry of transform functions\n */\ntype TransformFunction = (items: unknown[], config: Transform) => unknown[];\n\nconst transformRegistry: Record<string, TransformFunction> = {};\n\n/**\n * Register a transform function\n */\nexport function registerTransform(name: string, fn: TransformFunction): void {\n  transformRegistry[name] = fn;\n}\n\n/**\n * Apply a pipeline of transforms to data\n */\nexport function applyTransformPipeline(\n  items: unknown[],\n  pipeline: TransformPipeline,\n): unknown[] {\n  let result = items;\n\n  for (const transform of pipeline) {\n    const fn = transformRegistry[transform.name];\n    if (!fn) {\n      throw new Error(`Unknown transform: ${transform.name}`);\n    }\n    result = fn(result, transform);\n  }\n\n  return result;\n}\n\n/**\n * Flatten transform - recursively flattens nested arrays into a single level\n */\nfunction flattenTransform(items: unknown[], config: Transform): unknown[] {\n  const flattenConfig = config as FlattenTransform;\n  const { key, labelFormat } = flattenConfig;\n  const flattened: unknown[] = [];\n\n  function flattenRecursive(\n    item: unknown,\n    parent: Record<string, unknown> | null = null,\n    depth: number = 0,\n  ): void {\n    if (typeof item !== \"object\" || item === null) return;\n\n    const itemObj = item as Record<string, unknown>;\n\n    // Add the current item\n    if (labelFormat && parent) {\n      const formattedItem = { ...itemObj };\n\n      // Replace placeholders like {parent.name} and {name}\n      let formattedLabel = labelFormat;\n      formattedLabel = formattedLabel.replace(/\\{parent\\.(\\w+)\\}/g, (_, prop) =>\n        String(parent[prop] ?? \"\"),\n      );\n      formattedLabel = formattedLabel.replace(/\\{(\\w+)\\}/g, (_, prop) =>\n        String(itemObj[prop] ?? \"\"),\n      );\n\n      formattedItem._formattedLabel = formattedLabel;\n      formattedItem._parent = parent;\n      formattedItem._depth = depth;\n      flattened.push(formattedItem);\n    } else if (parent) {\n      // Child node with parent reference\n      flattened.push({\n        ...itemObj,\n        _parent: parent,\n        _depth: depth,\n      });\n    } else {\n      // Root node\n      flattened.push({\n        ...itemObj,\n        _depth: depth,\n      });\n    }\n\n    // Recursively flatten children\n    const children = itemObj[key];\n    if (Array.isArray(children)) {\n      for (const child of children) {\n        flattenRecursive(child, itemObj, depth + 1);\n      }\n    }\n  }\n\n  // Start flattening from root items\n  for (const item of items) {\n    flattenRecursive(item, null, 0);\n  }\n\n  return flattened;\n}\n\n/**\n * Filter transform - filters items based on a key and optional values\n */\nfunction filterTransform(items: unknown[], config: Transform): unknown[] {\n  const filterConfig = config as FilterTransform;\n  const { key, values } = filterConfig;\n\n  return items.filter((item) => {\n    if (typeof item !== \"object\" || item === null) return false;\n\n    const itemObj = item as Record<string, unknown>;\n\n    // If no values array provided, just check if the key exists\n    if (!values || values.length === 0) {\n      return key in itemObj;\n    }\n\n    // If values array provided, check if item[key] matches any of the values\n    const itemValue = itemObj[key];\n    return values.includes(itemValue);\n  });\n}\n\n// Register built-in transforms\nregisterTransform(\"flatten\", flattenTransform);\nregisterTransform(\"filter\", filterTransform);\n"],"names":[],"mappings":"AA+BA,MAAM,oBAAuD,CAAA;AAKtD,SAAS,kBAAkB,MAAc,IAA6B;AAC3E,oBAAkB,IAAI,IAAI;AAC5B;AAKO,SAAS,uBACd,OACA,UACW;AACX,MAAI,SAAS;AAEb,aAAW,aAAa,UAAU;AAChC,UAAM,KAAK,kBAAkB,UAAU,IAAI;AAC3C,QAAI,CAAC,IAAI;AACP,YAAM,IAAI,MAAM,sBAAsB,UAAU,IAAI,EAAE;AAAA,IACxD;AACA,aAAS,GAAG,QAAQ,SAAS;AAAA,EAC/B;AAEA,SAAO;AACT;AAKA,SAAS,iBAAiB,OAAkB,QAA8B;AACxE,QAAM,gBAAgB;AACtB,QAAM,EAAE,KAAK,YAAA,IAAgB;AAC7B,QAAM,YAAuB,CAAA;AAE7B,WAAS,iBACP,MACA,SAAyC,MACzC,QAAgB,GACV;AACN,QAAI,OAAO,SAAS,YAAY,SAAS,KAAM;AAE/C,UAAM,UAAU;AAGhB,QAAI,eAAe,QAAQ;AACzB,YAAM,gBAAgB,EAAE,GAAG,QAAA;AAG3B,UAAI,iBAAiB;AACrB,uBAAiB,eAAe;AAAA,QAAQ;AAAA,QAAsB,CAAC,GAAG,SAChE,OAAO,OAAO,IAAI,KAAK,EAAE;AAAA,MAAA;AAE3B,uBAAiB,eAAe;AAAA,QAAQ;AAAA,QAAc,CAAC,GAAG,SACxD,OAAO,QAAQ,IAAI,KAAK,EAAE;AAAA,MAAA;AAG5B,oBAAc,kBAAkB;AAChC,oBAAc,UAAU;AACxB,oBAAc,SAAS;AACvB,gBAAU,KAAK,aAAa;AAAA,IAC9B,WAAW,QAAQ;AAEjB,gBAAU,KAAK;AAAA,QACb,GAAG;AAAA,QACH,SAAS;AAAA,QACT,QAAQ;AAAA,MAAA,CACT;AAAA,IACH,OAAO;AAEL,gBAAU,KAAK;AAAA,QACb,GAAG;AAAA,QACH,QAAQ;AAAA,MAAA,CACT;AAAA,IACH;AAGA,UAAM,WAAW,QAAQ,GAAG;AAC5B,QAAI,MAAM,QAAQ,QAAQ,GAAG;AAC3B,iBAAW,SAAS,UAAU;AAC5B,yBAAiB,OAAO,SAAS,QAAQ,CAAC;AAAA,MAC5C;AAAA,IACF;AAAA,EACF;AAGA,aAAW,QAAQ,OAAO;AACxB,qBAAiB,MAAM,MAAM,CAAC;AAAA,EAChC;AAEA,SAAO;AACT;AAKA,SAAS,gBAAgB,OAAkB,QAA8B;AACvE,QAAM,eAAe;AACrB,QAAM,EAAE,KAAK,OAAA,IAAW;AAExB,SAAO,MAAM,OAAO,CAAC,SAAS;AAC5B,QAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AAEtD,UAAM,UAAU;AAGhB,QAAI,CAAC,UAAU,OAAO,WAAW,GAAG;AAClC,aAAO,OAAO;AAAA,IAChB;AAGA,UAAM,YAAY,QAAQ,GAAG;AAC7B,WAAO,OAAO,SAAS,SAAS;AAAA,EAClC,CAAC;AACH;AAGA,kBAAkB,WAAW,gBAAgB;AAC7C,kBAAkB,UAAU,eAAe;"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/jsonforms-provider-protocols",
-	"version": "1.2.0-beta.1",
+	"version": "1.2.0-beta.3",
 	"description": "Dynamic data provider capabilities for JSONForms with Vue 3 integration",
 	"type": "module",
 	"author": "Narrative I/O",

package/src/core/transforms.ts

@@ -14,7 +14,13 @@ export interface FlattenTransform extends Transform {
   labelFormat?: string; // Optional format string like "{parent.name} → {name}"
 }
 
-export type TransformStep = FlattenTransform;
+export interface FilterTransform extends Transform {
+  name: "filter";
+  key: string; // The key to check
+  values?: unknown[]; // Optional array of values to match against
+}
+
+export type TransformStep = FlattenTransform | FilterTransform;
 
 export type TransformPipeline = TransformStep[];
 
@@ -53,55 +59,94 @@ export function applyTransformPipeline(
 }
 
 /**
- * Flatten transform - flattens nested arrays into a single level
+ * Flatten transform - recursively flattens nested arrays into a single level
  */
 function flattenTransform(items: unknown[], config: Transform): unknown[] {
   const flattenConfig = config as FlattenTransform;
   const { key, labelFormat } = flattenConfig;
   const flattened: unknown[] = [];
 
-  for (const item of items) {
-    if (typeof item !== "object" || item === null) continue;
+  function flattenRecursive(
+    item: unknown,
+    parent: Record<string, unknown> | null = null,
+    depth: number = 0,
+  ): void {
+    if (typeof item !== "object" || item === null) return;
 
     const itemObj = item as Record<string, unknown>;
-    const children = itemObj[key];
 
+    // Add the current item
+    if (labelFormat && parent) {
+      const formattedItem = { ...itemObj };
+
+      // Replace placeholders like {parent.name} and {name}
+      let formattedLabel = labelFormat;
+      formattedLabel = formattedLabel.replace(/\{parent\.(\w+)\}/g, (_, prop) =>
+        String(parent[prop] ?? ""),
+      );
+      formattedLabel = formattedLabel.replace(/\{(\w+)\}/g, (_, prop) =>
+        String(itemObj[prop] ?? ""),
+      );
+
+      formattedItem._formattedLabel = formattedLabel;
+      formattedItem._parent = parent;
+      formattedItem._depth = depth;
+      flattened.push(formattedItem);
+    } else if (parent) {
+      // Child node with parent reference
+      flattened.push({
+        ...itemObj,
+        _parent: parent,
+        _depth: depth,
+      });
+    } else {
+      // Root node
+      flattened.push({
+        ...itemObj,
+        _depth: depth,
+      });
+    }
+
+    // Recursively flatten children
+    const children = itemObj[key];
     if (Array.isArray(children)) {
       for (const child of children) {
-        if (typeof child !== "object" || child === null) continue;
-
-        const childObj = child as Record<string, unknown>;
-
-        // If labelFormat is provided, use it to format the label
-        if (labelFormat) {
-          const formattedChild = { ...childObj };
-
-          // Replace placeholders like {parent.name} and {name}
-          let formattedLabel = labelFormat;
-          formattedLabel = formattedLabel.replace(
-            /\{parent\.(\w+)\}/g,
-            (_, prop) => String(itemObj[prop] ?? ""),
-          );
-          formattedLabel = formattedLabel.replace(/\{(\w+)\}/g, (_, prop) =>
-            String(childObj[prop] ?? ""),
-          );
-
-          formattedChild._formattedLabel = formattedLabel;
-          formattedChild._parent = itemObj;
-          flattened.push(formattedChild);
-        } else {
-          // Just add parent reference
-          flattened.push({
-            ...childObj,
-            _parent: itemObj,
-          });
-        }
+        flattenRecursive(child, itemObj, depth + 1);
       }
     }
   }
 
+  // Start flattening from root items
+  for (const item of items) {
+    flattenRecursive(item, null, 0);
+  }
+
   return flattened;
 }
 
+/**
+ * Filter transform - filters items based on a key and optional values
+ */
+function filterTransform(items: unknown[], config: Transform): unknown[] {
+  const filterConfig = config as FilterTransform;
+  const { key, values } = filterConfig;
+
+  return items.filter((item) => {
+    if (typeof item !== "object" || item === null) return false;
+
+    const itemObj = item as Record<string, unknown>;
+
+    // If no values array provided, just check if the key exists
+    if (!values || values.length === 0) {
+      return key in itemObj;
+    }
+
+    // If values array provided, check if item[key] matches any of the values
+    const itemValue = itemObj[key];
+    return values.includes(itemValue);
+  });
+}
+
 // Register built-in transforms
 registerTransform("flatten", flattenTransform);
+registerTransform("filter", filterTransform);