feat(validator): add support for filter type (#20)

We're adding support for the `filter` type of field, which was missing until now.

---------

Co-authored-by: Patrik Simek <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

README.md

@@ -185,6 +185,7 @@ const result = await validateFormanWithDomains(
 - email → string
 - file → string
 - filename → string
+- filter → array
 - folder → string
 - hidden → string
 - hook → number

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@makehq/forman-schema",
-    "version": "1.5.0",
+    "version": "1.6.0",
     "description": "Forman Schema Tools",
     "license": "MIT",
     "author": "Make",

package.json

@@ -1,4 +1,4 @@
-import type { JSONSchema7 } from 'json-schema';
+import type { JSONSchema7, JSONSchema7Definition } from 'json-schema';
 import type {
     FormanSchemaField,
     FormanSchemaValue,
@@ -7,7 +7,16 @@ import type {
     FormanSchemaOption,
     FormanSchemaOptionGroup,
 } from './types';
-import { noEmpty, isObject, isOptionGroup, normalizeFormanFieldType, isVisualType } from './utils';
+import {
+    noEmpty,
+    isObject,
+    isOptionGroup,
+    normalizeFormanFieldType,
+    isVisualType,
+    IML_UNARY_FILTER_OPERATORS,
+    IML_BINARY_FILTER_OPERATORS,
+    IML_FILTER_ENTRY_TYPES,
+} from './utils';
 
 /**
  * Context for schema conversion operations
@@ -93,6 +102,7 @@ const FORMAN_TYPE_MAP: Readonly<Record<string, JSONSchema7['type']>> = {
     email: 'string',
     filename: 'string',
     file: 'string',
+    filter: 'array',
     folder: 'string',
     hidden: undefined,
     integer: 'number',
@@ -198,6 +208,8 @@ export function toJSONSchemaInternal(
         case 'file':
         case 'folder':
             return handleSelectType(normalizedField, result, context);
+        case 'filter':
+            return handleFilterType(normalizedField, result, context);
         default:
             return handlePrimitiveType(normalizedField, result);
     }
@@ -311,6 +323,54 @@ function handleArrayType(field: FormanSchemaField, result: JSONSchema7, context:
     return result;
 }
 
+/**
+ * Handles filter type conversion
+ * @param field The field to convert
+ * @param result The prepared JSON Schema field
+ * @param context The context for the conversion
+ * @returns The converted JSON Schema field
+ */
+function handleFilterType(field: FormanSchemaField, result: JSONSchema7, context: ConversionContext): JSONSchema7 {
+    const filterItems: JSONSchema7Definition = {
+        oneOf: [
+            {
+                type: 'object',
+                properties: {
+                    a: { type: IML_FILTER_ENTRY_TYPES },
+                    o: { enum: IML_UNARY_FILTER_OPERATORS },
+                },
+                required: ['a', 'o'],
+            },
+            {
+                type: 'object',
+                properties: {
+                    a: { type: IML_FILTER_ENTRY_TYPES },
+                    b: { type: IML_FILTER_ENTRY_TYPES },
+                    o: { enum: IML_BINARY_FILTER_OPERATORS },
+                },
+                required: ['a', 'b', 'o'],
+            },
+        ],
+    };
+    const logic = field.logic ?? 'default';
+
+    result.items = ['and', 'or'].includes(logic)
+        ? filterItems
+        : {
+              type: 'array',
+              items: filterItems,
+          };
+    // Store this to the JSON Schema to allow safe conversion back to the Forman Schema
+    Object.defineProperty(result, 'x-filter', {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: logic,
+    });
+
+    return result;
+}
+
 /**
  * Handles select type conversion
  * @param field The field to convert

src/forman.ts

@@ -47,6 +47,17 @@ export function toFormanSchema(field: JSONSchema7): FormanSchemaField {
                 spec,
             };
         case 'array':
+            // If the array is flagged as filter field root, then short-circuit to it
+            const filterLogic = Object.getOwnPropertyDescriptor(field, 'x-filter');
+            if (filterLogic) {
+                return {
+                    type: 'filter',
+                    label: noEmpty(field.title),
+                    help: noEmpty(field.description),
+                    logic: filterLogic.value === 'default' ? undefined : filterLogic.value,
+                };
+            }
+
             // For arrays, create an array type with spec from items
             const items = field.items && isObject<JSONSchema7>(field.items) ? field.items : undefined;
 

src/json.ts

@@ -23,6 +23,7 @@ export type FormanSchemaFieldType =
     | 'email'
     | 'filename'
     | 'file'
+    | 'filter'
     | 'folder'
     | 'hidden'
     | 'integer'
@@ -119,6 +120,8 @@ export type FormanSchemaField = {
     sort?: string;
     /** Adds an extra button to the field which opens an extra form. When the form is submitted, a specified RPC is called and the result is set as a new value of the parameter. */
     rpc?: FormanSchemaRPCButton;
+    /** Definition of boolean logic to apply (filter only) */
+    logic?: 'and' | 'or' | 'reverse';
 } & Record<`x-${string}`, unknown>;
 
 /**

src/types.ts

@@ -226,3 +226,79 @@ export function buildRestoreStructure(
 
     return result;
 }
+
+/**
+ * Constants for IML filter entry types
+ */
+export const IML_FILTER_ENTRY_TYPES = ['null' as const, 'boolean' as const, 'number' as const, 'string' as const];
+
+/**
+ * Constants for unary IML filter operators
+ */
+export const IML_UNARY_FILTER_OPERATORS = ['exist' as const, 'notexist' as const];
+
+/**
+ * Constants for binary IML filter operators
+ */
+export const IML_BINARY_FILTER_OPERATORS = [
+    'text:equal' as const,
+    'text:equal:ci' as const,
+    'text:notequal' as const,
+    'text:notequal:ci' as const,
+    'text:contain' as const,
+    'text:contain:ci' as const,
+    'text:notcontain' as const,
+    'text:notcontain:ci' as const,
+    'text:startwith' as const,
+    'text:startwith:ci' as const,
+    'text:notstartwith' as const,
+    'text:notstartwith:ci' as const,
+    'text:endwith' as const,
+    'text:endwith:ci' as const,
+    'text:notendwith' as const,
+    'text:notendwith:ci' as const,
+    'text:pattern' as const,
+    'text:pattern:ci' as const,
+    'text:notpattern' as const,
+    'text:notpattern:ci' as const,
+    'number:equal' as const,
+    'number:notequal' as const,
+    'number:greater' as const,
+    'number:less' as const,
+    'number:greaterorequal' as const,
+    'number:lessorequal' as const,
+    'date:equal' as const,
+    'date:notequal' as const,
+    'date:greater' as const,
+    'date:less' as const,
+    'date:greaterorequal' as const,
+    'date:lessorequal' as const,
+    'time:equal' as const,
+    'time:notequal' as const,
+    'time:greater' as const,
+    'time:less' as const,
+    'time:greaterorequal' as const,
+    'time:lessorequal' as const,
+    'semver:equal' as const,
+    'semver:notequal' as const,
+    'semver:greater' as const,
+    'semver:less' as const,
+    'semver:greaterorequal' as const,
+    'semver:lessorequal' as const,
+    'array:contain' as const,
+    'array:contain:ci' as const,
+    'array:notcontain' as const,
+    'array:notcontain:ci' as const,
+    'array:equal' as const,
+    'array:notequal' as const,
+    'array:greater' as const,
+    'array:less' as const,
+    'array:greaterorequal' as const,
+    'array:lessorequal' as const,
+    'boolean:equal' as const,
+    'boolean:notequal' as const,
+];
+/**
+ * Constants for all IML filter operators
+ */
+export const IML_FILTER_OPERATORS = [...IML_UNARY_FILTER_OPERATORS, ...IML_BINARY_FILTER_OPERATORS];

src/utils.ts

@@ -17,6 +17,7 @@ import {
     normalizeFormanFieldType,
     isVisualType,
     isReferenceType,
+    IML_FILTER_OPERATORS,
 } from './utils';
 
 /**
@@ -88,6 +89,7 @@ const FORMAN_TYPE_MAP: Readonly<Record<string, string | undefined>> = {
     email: 'string',
     filename: 'string',
     file: 'string',
+    filter: 'array',
     folder: 'string',
     hidden: undefined,
     integer: 'number',
@@ -297,6 +299,8 @@ async function validateFormanValue(
         case 'file':
         case 'folder':
             return handleSelectType(value, normalizedField, context);
+        case 'filter':
+            return handleFilterType(value, normalizedField, context);
         default:
             return handlePrimitiveType(value, normalizedField, context);
     }
@@ -459,6 +463,54 @@ async function handleArrayType(
     };
 }
 
+/**
+ * Handles filter type validation
+ * @param value Value to validate
+ * @param field Forman Field Definition
+ * @param context The context for the validation
+ * @returns Validation result
+ */
+async function handleFilterType(value: unknown, field: FormanSchemaField, context: ValidationContext) {
+    // The filter is technically just an array or arrays, or an array. Craft the inline definition and pass to array validator instead.
+    const filterEntry: FormanSchemaField = {
+        type: 'collection',
+        spec: [
+            {
+                name: 'a',
+                type: 'any',
+                required: true,
+            },
+            {
+                name: 'b',
+                type: 'any',
+            },
+            {
+                name: 'o',
+                type: 'text',
+                validate: {
+                    enum: IML_FILTER_OPERATORS,
+                },
+            },
+        ],
+    };
+
+    const inlineSchema: FormanSchemaField = ['and', 'or'].includes(field.logic ?? 'default')
+        ? {
+              name: field.name,
+              type: 'array',
+              spec: filterEntry,
+          }
+        : {
+              name: field.name,
+              type: 'array',
+              spec: {
+                  type: 'array',
+                  spec: filterEntry,
+              },
+          };
+    return handleArrayType(value as unknown[], inlineSchema, context);
+}
+
 /**
  * Handles select type validation
  * @param field The field to convert

src/validator.ts

@@ -125,5 +125,22 @@
         "name": "dynamicCollection",
         "type": "dynamicCollection",
         "label": "Dynamic Collection"
+    },
+    {
+        "name": "filter",
+        "type": "filter",
+        "label": "Filter"
+    },
+    {
+        "name": "flatFilter",
+        "type": "filter",
+        "logic": "and",
+        "label": "Flat Filter"
+    },
+    {
+        "name": "reversedFilter",
+        "type": "filter",
+        "logic": "reverse",
+        "label": "Reversed Filter"
     }
 ]