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

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

@@ -59,7 +59,21 @@ function flattenTransform(items, config) {
   }
   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 - 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// 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,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;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.2",
+	"version": "1.2.0",
 	"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[];
 
@@ -118,5 +124,29 @@ function flattenTransform(items: unknown[], config: Transform): unknown[] {
   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);