@aikotools/datafilter 1.0.4 → 1.1.0

package/dist/aikotools-datafilter.cjs

@@ -1 +1,937 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const E=require("luxon");function x(i){return"matchAny"in i}function b(i){return"match"in i&&"expected"in i}function y(i,s){const t=[];if(s.length===0)return{value:i,found:!0,validPath:[]};let e=i;for(let n=0;n<s.length;n++){const r=s[n];if(e==null)return{value:void 0,found:!1,error:`Cannot read property '${r}' of ${e}`,validPath:t};if(Array.isArray(e)){const a=typeof r=="number"?r:parseInt(String(r),10);if(isNaN(a))return{value:void 0,found:!1,error:`Array index must be a number, got '${r}'`,validPath:t};if(a<0||a>=e.length)return{value:void 0,found:!1,error:`Array index ${a} out of bounds (length: ${e.length})`,validPath:t};t.push(a),e=e[a];continue}if(typeof e=="object"){const a=String(r);if(!(a in e))return{value:void 0,found:!1,error:`Property '${a}' does not exist`,validPath:t};t.push(a),e=e[a];continue}return{value:void 0,found:!1,error:`Cannot access property '${r}' of primitive type ${typeof e}`,validPath:t}}return{value:e,found:!0,validPath:t}}function P(i,s){const t=y(i,s);return t.found&&t.value!==void 0}function V(i,s,t){const e=y(i,s);return e.found&&e.value!==void 0?e.value:t}class w{constructor(s){this.context=s}evaluateCriterion(s,t){const e=t.check;return"value"in e?this.checkValue(s,t.path,e):"exists"in e?this.checkExists(s,t.path,e):"itemExists"in e&&"item"in e?this.checkArrayElement(s,t.path,e):"type"in e&&"size"in e?this.checkArraySize(s,t.path,e):"min"in e&&"max"in e?typeof e.min=="number"&&typeof e.max=="number"?this.checkNumericRange(s,t.path,e):this.checkTimeRange(s,t.path,e):{status:!1,checkType:"unknown",reason:`Unknown check type: ${JSON.stringify(e)}`}}checkValue(s,t,e){const n=y(s,t);if(!n.found)return{status:!1,checkType:"checkValue",reason:{message:n.error||"Path not found",path:t}};const r=n.value,a=e.value;return this.deepEqual(r,a)?{status:!0,checkType:"checkValue"}:{status:!1,checkType:"checkValue",reason:{message:"Value mismatch",path:t,expected:a,actual:r}}}checkExists(s,t,e){const n=y(s,t),r=n.found&&n.value!==void 0;return e.exists===r?{status:!0,checkType:"checkExists"}:{status:!1,checkType:"checkExists",reason:{message:e.exists?`Path should exist but doesn't: ${n.error}`:"Path should not exist but does",path:t}}}checkArrayElement(s,t,e){const n=y(s,t);if(!n.found)return{status:!1,checkType:"checkArrayElement",reason:{message:n.error||"Path not found",path:t}};const r=n.value;if(!Array.isArray(r))return{status:!1,checkType:"checkArrayElement",reason:{message:"Value is not an array",path:t,actualType:typeof r}};const a=r.some(u=>this.deepEqual(u,e.item));return e.itemExists===a?{status:!0,checkType:"checkArrayElement"}:{status:!1,checkType:"checkArrayElement",reason:{message:e.itemExists?"Item should exist in array but doesn't":"Item should not exist in array but does",path:t,item:e.item}}}checkArraySize(s,t,e){const n=y(s,t);if(!n.found)return{status:!1,checkType:"checkArraySize",reason:{message:n.error||"Path not found",path:t}};const r=n.value;if(!Array.isArray(r))return{status:!1,checkType:"checkArraySize",reason:{message:"Value is not an array",path:t,actualType:typeof r}};const a=r.length,u=e.size;let o=!1,h="";switch(e.type){case"equal":o=a===u,h=`Array length should be ${u} but is ${a}`;break;case"lessThan":o=a<u,h=`Array length should be less than ${u} but is ${a}`;break;case"greaterThan":o=a>u,h=`Array length should be greater than ${u} but is ${a}`;break}return o?{status:!0,checkType:"checkArraySize"}:{status:!1,checkType:"checkArraySize",reason:{message:h,path:t,expected:u,actual:a}}}checkTimeRange(s,t,e){const n=y(s,t);if(!n.found)return{status:!1,checkType:"checkTimeRange",reason:{message:n.error||"Path not found",path:t}};const r=n.value;if(typeof r=="number"){const a=parseInt(e.min),u=parseInt(e.max);return isNaN(a)||isNaN(u)?{status:!1,checkType:"checkTimeRange",reason:{message:"Min or max is not a valid number",min:e.min,max:e.max}}:r>=a&&r<=u?{status:!0,checkType:"checkTimeRange"}:{status:!1,checkType:"checkTimeRange",reason:{message:`Timestamp ${r} is outside range [${a}, ${u}]`,path:t,actual:r,min:a,max:u}}}if(typeof r=="string"){const a=E.DateTime.fromISO(r),u=E.DateTime.fromISO(e.min),o=E.DateTime.fromISO(e.max);return a.isValid?!u.isValid||!o.isValid?{status:!1,checkType:"checkTimeRange",reason:{message:"Invalid min or max time",min:e.min,max:e.max}}:a>=u&&a<=o?{status:!0,checkType:"checkTimeRange"}:{status:!1,checkType:"checkTimeRange",reason:{message:`Timestamp ${r} is outside range [${e.min}, ${e.max}]`,path:t,actual:r,min:e.min,max:e.max}}:{status:!1,checkType:"checkTimeRange",reason:{message:`Invalid timestamp: ${r}`,path:t}}}return{status:!1,checkType:"checkTimeRange",reason:{message:`Timestamp must be a string or number, got ${typeof r}`,path:t}}}checkNumericRange(s,t,e){const n=y(s,t);if(!n.found)return{status:!1,checkType:"checkNumericRange",reason:{message:n.error||"Path not found",path:t}};const r=n.value;return typeof r!="number"?{status:!1,checkType:"checkNumericRange",reason:{message:`Value must be a number, got ${typeof r}`,path:t,actual:r}}:r>=e.min&&r<=e.max?{status:!0,checkType:"checkNumericRange"}:{status:!1,checkType:"checkNumericRange",reason:{message:`Value ${r} is outside range [${e.min}, ${e.max}]`,path:t,actual:r,min:e.min,max:e.max}}}deepEqual(s,t){if(s===t)return!0;if(s===null||t===null||s===void 0||t===void 0)return s===t;if(typeof s!=typeof t)return!1;if(s instanceof Date&&t instanceof Date)return s.getTime()===t.getTime();if(Array.isArray(s)&&Array.isArray(t))return s.length!==t.length?!1:s.every((e,n)=>this.deepEqual(e,t[n]));if(typeof s=="object"&&typeof t=="object"){const e=Object.keys(s),n=Object.keys(t);return e.length!==n.length?!1:e.every(r=>this.deepEqual(s[r],t[r]))}return s===t}}class M{constructor(s){this.engine=new w(s)}matchFile(s,t){const n=(x(t)?t.matchAny:t.match).map(a=>this.engine.evaluateCriterion(s.data,a));return{matched:n.every(a=>a.status),checks:n,rule:t}}applyPreFilter(s,t){const e=[],n=[];for(const r of s){const a=t.map(u=>this.engine.evaluateCriterion(r.data,u));a.every(u=>u.status)?e.push(r):n.push({file:r,failedChecks:a.filter(u=>!u.status)})}return{matched:e,excluded:n}}filterFiles(s,t,e,n){let r,a=[];if(n){const f=this.applyPreFilter(s,n);r=f.matched,a=f.excluded}else r=s;const u=e?[...r].sort(e):[...r],o=[],h=[],g=[],k=new Set,R=new Map;let l=0,c=0;for(;l<u.length;){const f=u[l];if(c>=t.length){k.has(l)||g.push({file:f,attemptedRules:[]}),l++;continue}const m=t[c],F=[];let T=!1;if(Array.isArray(m)){for(let p=0;p<m.length;p++){if(R.get(c)?.has(p))continue;const v=m[p],$=this.matchFile(f,v);if(F.push($),$.matched&&b(v)){R.has(c)||R.set(c,new Set);const S=R.get(c);S&&S.add(p),o.push({expected:v.expected,file:f,matchResult:$,optional:v.optional||!1,info:v.info}),k.add(l),T=!0;break}}R.get(c)?.size===m.length&&c++,l++}else{const d=m,p=this.matchFile(f,d);F.push(p),p.matched?b(d)?(o.push({expected:d.expected,file:f,matchResult:p,optional:d.optional||!1,info:d.info}),k.add(l),c++,l++):x(d)&&(h.push({file:f,matchResult:p,info:d.info}),k.add(l),d.greedy||c++,l++):d.optional||x(d)?c++:(g.push({file:f,attemptedRules:F}),l++)}}const A={totalFiles:s.length,mappedFiles:o.length,wildcardMatchedFiles:h.length,unmappedFiles:g.length,preFilteredFiles:a.length,totalRules:this.countRules(t),mandatoryRules:this.countMandatoryRules(t),optionalRules:this.countOptionalRules(t)};return{mapped:o,wildcardMatched:h,unmapped:g,preFiltered:a,stats:A}}countRules(s){return s.reduce((t,e)=>Array.isArray(e)?t+e.length:t+1,0)}countMandatoryRules(s){return s.reduce((t,e)=>Array.isArray(e)?t+e.filter(n=>!n.optional&&!x(n)).length:t+(e.optional||x(e)?0:1),0)}countOptionalRules(s){return s.reduce((t,e)=>Array.isArray(e)?t+e.filter(n=>n.optional||x(n)).length:t+(e.optional||x(e)?1:0),0)}filterFilesWithGroups(s,t,e,n){let r,a=[];if(n){const l=this.applyPreFilter(s,n);r=l.matched,a=l.excluded}else r=s;const u=e?[...r].sort(e):[...r],o=[],h=[],g=[];for(const l of t){const c=u.filter(m=>l.groupFilter.map(T=>this.engine.evaluateCriterion(m.data,T)).every(T=>T.status));if(c.length===0)continue;const A=l.rules.map(m=>(Array.isArray(m),m)),f=this.filterFiles(c,A);o.push(...f.mapped),h.push(...f.wildcardMatched),g.push(...f.unmapped)}const k=t.flatMap(l=>l.rules),R={totalFiles:s.length,mappedFiles:o.length,wildcardMatchedFiles:h.length,unmappedFiles:g.length,preFilteredFiles:a.length,totalRules:this.countRules(k),mandatoryRules:this.countMandatoryRules(k),optionalRules:this.countOptionalRules(k)};return{mapped:o,wildcardMatched:h,unmapped:g,preFiltered:a,stats:R}}}function I(i){const s=new M(i.context);if(i.rules&&i.groups)throw new Error('FilterRequest: Provide either "rules" or "groups", not both');if(!i.rules&&!i.groups)throw new Error('FilterRequest: Must provide either "rules" or "groups"');if(i.groups)return s.filterFilesWithGroups(i.files,i.groups,i.sortFn,i.preFilter);if(!i.rules)throw new Error("FilterRequest: Rules are required");return s.filterFiles(i.files,i.rules,i.sortFn,i.preFilter)}exports.FilterEngine=w;exports.Matcher=M;exports.filterFiles=I;exports.getValueFromPath=y;exports.getValueOr=V;exports.isSingleMatchRule=b;exports.isWildcardRule=x;exports.pathExists=P;
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const luxon = require("luxon");
+function isWildcardRule(rule) {
+  return "matchAny" in rule;
+}
+function isSingleMatchRule(rule) {
+  return "match" in rule && "expected" in rule;
+}
+function getValueFromPath(object, path) {
+  const validPath = [];
+  if (path.length === 0) {
+    return {
+      value: object,
+      found: true,
+      validPath: []
+    };
+  }
+  let current = object;
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i];
+    if (current === null || current === void 0) {
+      return {
+        value: void 0,
+        found: false,
+        error: `Cannot read property '${segment}' of ${current}`,
+        validPath
+      };
+    }
+    if (Array.isArray(current)) {
+      const index = typeof segment === "number" ? segment : parseInt(String(segment), 10);
+      if (isNaN(index)) {
+        return {
+          value: void 0,
+          found: false,
+          error: `Array index must be a number, got '${segment}'`,
+          validPath
+        };
+      }
+      if (index < 0 || index >= current.length) {
+        return {
+          value: void 0,
+          found: false,
+          error: `Array index ${index} out of bounds (length: ${current.length})`,
+          validPath
+        };
+      }
+      validPath.push(index);
+      current = current[index];
+      continue;
+    }
+    if (typeof current === "object") {
+      const key = String(segment);
+      if (!(key in current)) {
+        return {
+          value: void 0,
+          found: false,
+          error: `Property '${key}' does not exist`,
+          validPath
+        };
+      }
+      validPath.push(key);
+      current = current[key];
+      continue;
+    }
+    return {
+      value: void 0,
+      found: false,
+      error: `Cannot access property '${segment}' of primitive type ${typeof current}`,
+      validPath
+    };
+  }
+  return {
+    value: current,
+    found: true,
+    validPath
+  };
+}
+function pathExists(object, path) {
+  const result = getValueFromPath(object, path);
+  return result.found && result.value !== void 0;
+}
+function getValueOr(object, path, defaultValue) {
+  const result = getValueFromPath(object, path);
+  return result.found && result.value !== void 0 ? result.value : defaultValue;
+}
+class FilterEngine {
+  constructor(context) {
+    this.context = context;
+  }
+  /**
+   * Evaluates a single filter criterion against a data object.
+   *
+   * @param data - The data object to check
+   * @param criterion - The filter criterion to evaluate
+   * @returns FilterCheckResult indicating success or failure
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  evaluateCriterion(data, criterion) {
+    const check = criterion.check;
+    if ("value" in check) {
+      return this.checkValue(data, criterion.path, check);
+    }
+    if ("exists" in check) {
+      return this.checkExists(data, criterion.path, check);
+    }
+    if ("itemExists" in check && "item" in check) {
+      return this.checkArrayElement(data, criterion.path, check);
+    }
+    if ("type" in check && "size" in check) {
+      return this.checkArraySize(data, criterion.path, check);
+    }
+    if ("min" in check && "max" in check) {
+      if (typeof check.min === "number" && typeof check.max === "number") {
+        return this.checkNumericRange(data, criterion.path, check);
+      } else {
+        return this.checkTimeRange(data, criterion.path, check);
+      }
+    }
+    return {
+      status: false,
+      checkType: "unknown",
+      reason: `Unknown check type: ${JSON.stringify(check)}`
+    };
+  }
+  /**
+   * Checks if a value matches an expected value using deep equality.
+   *
+   * @param data - The data object
+   * @param path - Path to the value
+   * @param check - The value check specification
+   * @returns FilterCheckResult
+   */
+  checkValue(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    if (!accessResult.found) {
+      return {
+        status: false,
+        checkType: "checkValue",
+        reason: {
+          message: accessResult.error || "Path not found",
+          path
+        }
+      };
+    }
+    const actual = accessResult.value;
+    const expected = check.value;
+    if (this.deepEqual(actual, expected)) {
+      return {
+        status: true,
+        checkType: "checkValue"
+      };
+    }
+    return {
+      status: false,
+      checkType: "checkValue",
+      reason: {
+        message: "Value mismatch",
+        path,
+        expected,
+        actual
+      }
+    };
+  }
+  /**
+   * Checks if a path exists in the data object.
+   *
+   * @param data - The data object
+   * @param path - Path to check
+   * @param check - The exists check specification
+   * @returns FilterCheckResult
+   */
+  checkExists(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    const exists = accessResult.found && accessResult.value !== void 0;
+    if (check.exists === exists) {
+      return {
+        status: true,
+        checkType: "checkExists"
+      };
+    }
+    return {
+      status: false,
+      checkType: "checkExists",
+      reason: {
+        message: check.exists ? `Path should exist but doesn't: ${accessResult.error}` : "Path should not exist but does",
+        path
+      }
+    };
+  }
+  /**
+   * Checks if an array contains (or doesn't contain) a specific element.
+   *
+   * @param data - The data object
+   * @param path - Path to the array
+   * @param check - The array element check specification
+   * @returns FilterCheckResult
+   */
+  checkArrayElement(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    if (!accessResult.found) {
+      return {
+        status: false,
+        checkType: "checkArrayElement",
+        reason: {
+          message: accessResult.error || "Path not found",
+          path
+        }
+      };
+    }
+    const array = accessResult.value;
+    if (!Array.isArray(array)) {
+      return {
+        status: false,
+        checkType: "checkArrayElement",
+        reason: {
+          message: "Value is not an array",
+          path,
+          actualType: typeof array
+        }
+      };
+    }
+    const found = array.some((elem) => this.deepEqual(elem, check.item));
+    if (check.itemExists === found) {
+      return {
+        status: true,
+        checkType: "checkArrayElement"
+      };
+    }
+    return {
+      status: false,
+      checkType: "checkArrayElement",
+      reason: {
+        message: check.itemExists ? "Item should exist in array but doesn't" : "Item should not exist in array but does",
+        path,
+        item: check.item
+      }
+    };
+  }
+  /**
+   * Checks if an array has the expected size.
+   *
+   * @param data - The data object
+   * @param path - Path to the array
+   * @param check - The array size check specification
+   * @returns FilterCheckResult
+   */
+  checkArraySize(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    if (!accessResult.found) {
+      return {
+        status: false,
+        checkType: "checkArraySize",
+        reason: {
+          message: accessResult.error || "Path not found",
+          path
+        }
+      };
+    }
+    const array = accessResult.value;
+    if (!Array.isArray(array)) {
+      return {
+        status: false,
+        checkType: "checkArraySize",
+        reason: {
+          message: "Value is not an array",
+          path,
+          actualType: typeof array
+        }
+      };
+    }
+    const actualSize = array.length;
+    const expectedSize = check.size;
+    let passes = false;
+    let message = "";
+    switch (check.type) {
+      case "equal":
+        passes = actualSize === expectedSize;
+        message = `Array length should be ${expectedSize} but is ${actualSize}`;
+        break;
+      case "lessThan":
+        passes = actualSize < expectedSize;
+        message = `Array length should be less than ${expectedSize} but is ${actualSize}`;
+        break;
+      case "greaterThan":
+        passes = actualSize > expectedSize;
+        message = `Array length should be greater than ${expectedSize} but is ${actualSize}`;
+        break;
+    }
+    if (passes) {
+      return {
+        status: true,
+        checkType: "checkArraySize"
+      };
+    }
+    return {
+      status: false,
+      checkType: "checkArraySize",
+      reason: {
+        message,
+        path,
+        expected: expectedSize,
+        actual: actualSize
+      }
+    };
+  }
+  /**
+   * Checks if a timestamp is within the expected time range.
+   *
+   * @param data - The data object
+   * @param path - Path to the timestamp
+   * @param check - The time range check specification
+   * @returns FilterCheckResult
+   */
+  checkTimeRange(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    if (!accessResult.found) {
+      return {
+        status: false,
+        checkType: "checkTimeRange",
+        reason: {
+          message: accessResult.error || "Path not found",
+          path
+        }
+      };
+    }
+    const value = accessResult.value;
+    if (typeof value === "number") {
+      const min = parseInt(check.min);
+      const max = parseInt(check.max);
+      if (isNaN(min) || isNaN(max)) {
+        return {
+          status: false,
+          checkType: "checkTimeRange",
+          reason: {
+            message: "Min or max is not a valid number",
+            min: check.min,
+            max: check.max
+          }
+        };
+      }
+      if (value >= min && value <= max) {
+        return {
+          status: true,
+          checkType: "checkTimeRange"
+        };
+      }
+      return {
+        status: false,
+        checkType: "checkTimeRange",
+        reason: {
+          message: `Timestamp ${value} is outside range [${min}, ${max}]`,
+          path,
+          actual: value,
+          min,
+          max
+        }
+      };
+    }
+    if (typeof value === "string") {
+      const timestamp = luxon.DateTime.fromISO(value);
+      const minTime = luxon.DateTime.fromISO(check.min);
+      const maxTime = luxon.DateTime.fromISO(check.max);
+      if (!timestamp.isValid) {
+        return {
+          status: false,
+          checkType: "checkTimeRange",
+          reason: {
+            message: `Invalid timestamp: ${value}`,
+            path
+          }
+        };
+      }
+      if (!minTime.isValid || !maxTime.isValid) {
+        return {
+          status: false,
+          checkType: "checkTimeRange",
+          reason: {
+            message: "Invalid min or max time",
+            min: check.min,
+            max: check.max
+          }
+        };
+      }
+      if (timestamp >= minTime && timestamp <= maxTime) {
+        return {
+          status: true,
+          checkType: "checkTimeRange"
+        };
+      }
+      return {
+        status: false,
+        checkType: "checkTimeRange",
+        reason: {
+          message: `Timestamp ${value} is outside range [${check.min}, ${check.max}]`,
+          path,
+          actual: value,
+          min: check.min,
+          max: check.max
+        }
+      };
+    }
+    return {
+      status: false,
+      checkType: "checkTimeRange",
+      reason: {
+        message: `Timestamp must be a string or number, got ${typeof value}`,
+        path
+      }
+    };
+  }
+  /**
+   * Checks if a numeric value is within the expected range.
+   *
+   * @param data - The data object
+   * @param path - Path to the numeric value
+   * @param check - The numeric range check specification
+   * @returns FilterCheckResult
+   */
+  checkNumericRange(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    if (!accessResult.found) {
+      return {
+        status: false,
+        checkType: "checkNumericRange",
+        reason: {
+          message: accessResult.error || "Path not found",
+          path
+        }
+      };
+    }
+    const value = accessResult.value;
+    if (typeof value !== "number") {
+      return {
+        status: false,
+        checkType: "checkNumericRange",
+        reason: {
+          message: `Value must be a number, got ${typeof value}`,
+          path,
+          actual: value
+        }
+      };
+    }
+    if (value >= check.min && value <= check.max) {
+      return {
+        status: true,
+        checkType: "checkNumericRange"
+      };
+    }
+    return {
+      status: false,
+      checkType: "checkNumericRange",
+      reason: {
+        message: `Value ${value} is outside range [${check.min}, ${check.max}]`,
+        path,
+        actual: value,
+        min: check.min,
+        max: check.max
+      }
+    };
+  }
+  /**
+   * Deep equality comparison.
+   * Compares two values recursively for equality.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  deepEqual(a, b) {
+    if (a === b) return true;
+    if (a === null || b === null) return a === b;
+    if (a === void 0 || b === void 0) return a === b;
+    if (typeof a !== typeof b) return false;
+    if (a instanceof Date && b instanceof Date) {
+      return a.getTime() === b.getTime();
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+      if (a.length !== b.length) return false;
+      return a.every((val, idx) => this.deepEqual(val, b[idx]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+      const keysA = Object.keys(a);
+      const keysB = Object.keys(b);
+      if (keysA.length !== keysB.length) return false;
+      return keysA.every((key) => this.deepEqual(a[key], b[key]));
+    }
+    return a === b;
+  }
+}
+class Matcher {
+  constructor(context) {
+    this.engine = new FilterEngine(context);
+  }
+  /**
+   * Matches a single file against a rule.
+   *
+   * @param file - The file to match
+   * @param rule - The rule to match against
+   * @returns MatchResult indicating if all criteria matched
+   */
+  matchFile(file, rule) {
+    const criteria = isWildcardRule(rule) ? rule.matchAny : rule.match;
+    const checks = criteria.map((criterion) => {
+      return this.engine.evaluateCriterion(file.data, criterion);
+    });
+    const matched = checks.every((check) => check.status);
+    return {
+      matched,
+      checks,
+      rule
+    };
+  }
+  /**
+   * Applies pre-filter criteria to files, separating files that match from those that don't.
+   *
+   * @param files - Files to filter
+   * @param preFilter - Filter criteria that all files must match
+   * @returns Object with matched files and excluded files (with failed checks)
+   */
+  applyPreFilter(files, preFilter) {
+    const matched = [];
+    const excluded = [];
+    for (const file of files) {
+      const checks = preFilter.map((criterion) => {
+        return this.engine.evaluateCriterion(file.data, criterion);
+      });
+      if (checks.every((check) => check.status)) {
+        matched.push(file);
+      } else {
+        excluded.push({
+          file,
+          failedChecks: checks.filter((check) => !check.status)
+        });
+      }
+    }
+    return { matched, excluded };
+  }
+  /**
+   * Main filtering function that processes files according to rules.
+   *
+   * @param files - Files to filter
+   * @param rules - Matching rules (can include arrays for flexible ordering)
+   * @param sortFn - Optional sort function for file ordering
+   * @param preFilter - Optional pre-filter criteria (files not matching are excluded)
+   * @param mode - Matching mode ('strict', 'optional', or 'strict-optional')
+   * @returns FilterResult with mapped, wildcardMatched, optionalFiles and unmapped files
+   */
+  filterFiles(files, rules, sortFn, preFilter, mode = "strict") {
+    let filteredFiles;
+    let preFiltered = [];
+    if (preFilter) {
+      const preFilterResult = this.applyPreFilter(files, preFilter);
+      filteredFiles = preFilterResult.matched;
+      preFiltered = preFilterResult.excluded;
+    } else {
+      filteredFiles = files;
+    }
+    const sortedFiles = sortFn ? [...filteredFiles].sort(sortFn) : [...filteredFiles];
+    const mapped = [];
+    const wildcardMatched = [];
+    const unmapped = [];
+    const optionalFiles = [];
+    const matchedFileIndices = /* @__PURE__ */ new Set();
+    if (mode === "optional" || mode === "strict-optional") {
+      return this.filterFilesOptionalMode(sortedFiles, rules, preFiltered, files.length, mode);
+    }
+    const usedFlexibleRules = /* @__PURE__ */ new Map();
+    let fileIndex = 0;
+    let ruleIndex = 0;
+    while (fileIndex < sortedFiles.length) {
+      const file = sortedFiles[fileIndex];
+      if (ruleIndex >= rules.length) {
+        if (!matchedFileIndices.has(fileIndex)) {
+          unmapped.push({
+            file,
+            attemptedRules: []
+          });
+        }
+        fileIndex++;
+        continue;
+      }
+      const ruleOrRules = rules[ruleIndex];
+      const attemptedMatches = [];
+      let fileMatched = false;
+      if (Array.isArray(ruleOrRules)) {
+        for (let subIndex = 0; subIndex < ruleOrRules.length; subIndex++) {
+          const used = usedFlexibleRules.get(ruleIndex)?.has(subIndex);
+          if (used) {
+            continue;
+          }
+          const rule = ruleOrRules[subIndex];
+          const matchResult = this.matchFile(file, rule);
+          attemptedMatches.push(matchResult);
+          if (matchResult.matched && isSingleMatchRule(rule)) {
+            if (!usedFlexibleRules.has(ruleIndex)) {
+              usedFlexibleRules.set(ruleIndex, /* @__PURE__ */ new Set());
+            }
+            const usedSet = usedFlexibleRules.get(ruleIndex);
+            if (usedSet) {
+              usedSet.add(subIndex);
+            }
+            mapped.push({
+              expected: rule.expected,
+              file,
+              matchResult,
+              optional: rule.optional || false,
+              info: rule.info
+            });
+            matchedFileIndices.add(fileIndex);
+            fileMatched = true;
+            break;
+          }
+        }
+        const allUsed = usedFlexibleRules.get(ruleIndex)?.size === ruleOrRules.length;
+        if (allUsed) {
+          ruleIndex++;
+        }
+        if (fileMatched) {
+          fileIndex++;
+        } else {
+          fileIndex++;
+        }
+      } else {
+        const rule = ruleOrRules;
+        const matchResult = this.matchFile(file, rule);
+        attemptedMatches.push(matchResult);
+        if (matchResult.matched) {
+          if (isSingleMatchRule(rule)) {
+            mapped.push({
+              expected: rule.expected,
+              file,
+              matchResult,
+              optional: rule.optional || false,
+              info: rule.info
+            });
+            matchedFileIndices.add(fileIndex);
+            ruleIndex++;
+            fileIndex++;
+          } else if (isWildcardRule(rule)) {
+            wildcardMatched.push({
+              file,
+              matchResult,
+              info: rule.info
+            });
+            matchedFileIndices.add(fileIndex);
+            if (rule.greedy) {
+              fileIndex++;
+            } else {
+              ruleIndex++;
+              fileIndex++;
+            }
+          }
+        } else {
+          if (rule.optional) {
+            ruleIndex++;
+          } else if (isWildcardRule(rule)) {
+            ruleIndex++;
+          } else {
+            unmapped.push({
+              file,
+              attemptedRules: attemptedMatches
+            });
+            fileIndex++;
+          }
+        }
+      }
+    }
+    const stats = {
+      totalFiles: files.length,
+      mappedFiles: mapped.length,
+      wildcardMatchedFiles: wildcardMatched.length,
+      unmappedFiles: unmapped.length,
+      optionalFiles: optionalFiles.length,
+      preFilteredFiles: preFiltered.length,
+      totalRules: this.countRules(rules),
+      mandatoryRules: this.countMandatoryRules(rules),
+      optionalRules: this.countOptionalRules(rules)
+    };
+    return {
+      mapped,
+      wildcardMatched,
+      optionalFiles,
+      unmapped,
+      preFiltered,
+      stats
+    };
+  }
+  /**
+   * Filtering with optional mode - uses scan-forward algorithm
+   */
+  filterFilesOptionalMode(sortedFiles, rules, preFiltered, totalFiles, mode) {
+    const mapped = [];
+    const wildcardMatched = [];
+    const optionalFiles = [];
+    let currentFileIndex = 0;
+    let lastMatchedIndex = -1;
+    let lastMatchedRule = null;
+    for (let ruleIndex = 0; ruleIndex < rules.length; ruleIndex++) {
+      const ruleOrRules = rules[ruleIndex];
+      let found = false;
+      for (let fileIndex = currentFileIndex; fileIndex < sortedFiles.length; fileIndex++) {
+        const file = sortedFiles[fileIndex];
+        let matchResult = null;
+        let matchedRule = null;
+        if (Array.isArray(ruleOrRules)) {
+          for (const rule of ruleOrRules) {
+            const result = this.matchFile(file, rule);
+            if (result.matched) {
+              matchResult = result;
+              matchedRule = rule;
+              break;
+            }
+          }
+        } else {
+          matchResult = this.matchFile(file, ruleOrRules);
+          if (matchResult.matched) {
+            matchedRule = ruleOrRules;
+          }
+        }
+        if (matchResult && matchResult.matched && matchedRule) {
+          for (let i = lastMatchedIndex + 1; i < fileIndex; i++) {
+            const optionalFile = sortedFiles[i];
+            optionalFiles.push({
+              fileName: optionalFile.fileName,
+              position: i,
+              between: {
+                afterRule: lastMatchedRule || "(start)",
+                beforeRule: isSingleMatchRule(matchedRule) ? matchedRule.expected : "(wildcard)"
+              },
+              failedMatches: []
+              // TODO: collect actual failed matches
+            });
+          }
+          if (isSingleMatchRule(matchedRule)) {
+            mapped.push({
+              expected: matchedRule.expected,
+              file,
+              matchResult,
+              optional: matchedRule.optional || false,
+              info: matchedRule.info
+            });
+            lastMatchedRule = matchedRule.expected;
+          } else if (isWildcardRule(matchedRule)) {
+            wildcardMatched.push({
+              file,
+              matchResult,
+              info: matchedRule.info
+            });
+            lastMatchedRule = "(wildcard)";
+          }
+          lastMatchedIndex = fileIndex;
+          currentFileIndex = fileIndex + 1;
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        const isMandatory = Array.isArray(ruleOrRules) ? ruleOrRules.some((r) => !r.optional && !isWildcardRule(r)) : !ruleOrRules.optional && !isWildcardRule(ruleOrRules);
+        if (isMandatory && mode === "strict-optional") {
+          break;
+        }
+      }
+    }
+    for (let i = lastMatchedIndex + 1; i < sortedFiles.length; i++) {
+      const optionalFile = sortedFiles[i];
+      optionalFiles.push({
+        fileName: optionalFile.fileName,
+        position: i,
+        between: {
+          afterRule: lastMatchedRule || "(start)",
+          beforeRule: "(end)"
+        },
+        failedMatches: []
+        // TODO: collect actual failed matches
+      });
+    }
+    const stats = {
+      totalFiles,
+      mappedFiles: mapped.length,
+      wildcardMatchedFiles: wildcardMatched.length,
+      unmappedFiles: 0,
+      // Always 0 in optional modes
+      optionalFiles: optionalFiles.length,
+      preFilteredFiles: preFiltered.length,
+      totalRules: this.countRules(rules),
+      mandatoryRules: this.countMandatoryRules(rules),
+      optionalRules: this.countOptionalRules(rules)
+    };
+    return {
+      mapped,
+      wildcardMatched,
+      optionalFiles,
+      unmapped: [],
+      // Always empty in optional modes
+      preFiltered,
+      stats
+    };
+  }
+  /**
+   * Counts total number of rules (flattening arrays)
+   */
+  countRules(rules) {
+    return rules.reduce((count, rule) => {
+      if (Array.isArray(rule)) {
+        return count + rule.length;
+      }
+      return count + 1;
+    }, 0);
+  }
+  /**
+   * Counts mandatory rules
+   */
+  countMandatoryRules(rules) {
+    return rules.reduce((count, rule) => {
+      if (Array.isArray(rule)) {
+        return count + rule.filter((r) => !r.optional && !isWildcardRule(r)).length;
+      }
+      return count + (rule.optional || isWildcardRule(rule) ? 0 : 1);
+    }, 0);
+  }
+  /**
+   * Counts optional rules
+   */
+  countOptionalRules(rules) {
+    return rules.reduce((count, rule) => {
+      if (Array.isArray(rule)) {
+        return count + rule.filter((r) => r.optional || isWildcardRule(r)).length;
+      }
+      return count + (rule.optional || isWildcardRule(rule) ? 1 : 0);
+    }, 0);
+  }
+  /**
+   * Filtering function for grouped rules with common filter criteria.
+   * Files are first filtered by preFilter (if provided), then matched against
+   * group filters, and finally processed by the group's rules.
+   *
+   * @param files - Files to filter
+   * @param groups - Filter groups with common criteria and rules
+   * @param sortFn - Optional sort function for file ordering
+   * @param preFilter - Optional pre-filter criteria (files not matching are excluded)
+   * @param mode - Matching mode ('strict', 'optional', or 'strict-optional')
+   * @returns FilterResult with mapped, wildcardMatched, optionalFiles and unmapped files
+   */
+  filterFilesWithGroups(files, groups, sortFn, preFilter, mode = "strict") {
+    let filteredFiles;
+    let preFiltered = [];
+    if (preFilter) {
+      const preFilterResult = this.applyPreFilter(files, preFilter);
+      filteredFiles = preFilterResult.matched;
+      preFiltered = preFilterResult.excluded;
+    } else {
+      filteredFiles = files;
+    }
+    const sortedFiles = sortFn ? [...filteredFiles].sort(sortFn) : [...filteredFiles];
+    const mapped = [];
+    const wildcardMatched = [];
+    const unmapped = [];
+    const optionalFiles = [];
+    for (const group of groups) {
+      const groupFiles = sortedFiles.filter((file) => {
+        const checks = group.groupFilter.map((criterion) => {
+          return this.engine.evaluateCriterion(file.data, criterion);
+        });
+        return checks.every((check) => check.status);
+      });
+      if (groupFiles.length === 0) {
+        continue;
+      }
+      const rulesArray = group.rules.map((rule) => {
+        if (Array.isArray(rule)) {
+          return rule;
+        }
+        return rule;
+      });
+      const groupResult = this.filterFiles(groupFiles, rulesArray, void 0, void 0, mode);
+      mapped.push(...groupResult.mapped);
+      wildcardMatched.push(...groupResult.wildcardMatched);
+      unmapped.push(...groupResult.unmapped);
+      optionalFiles.push(...groupResult.optionalFiles);
+    }
+    const allRules = groups.flatMap((g) => g.rules);
+    const stats = {
+      totalFiles: files.length,
+      mappedFiles: mapped.length,
+      wildcardMatchedFiles: wildcardMatched.length,
+      unmappedFiles: unmapped.length,
+      optionalFiles: optionalFiles.length,
+      preFilteredFiles: preFiltered.length,
+      totalRules: this.countRules(allRules),
+      mandatoryRules: this.countMandatoryRules(allRules),
+      optionalRules: this.countOptionalRules(allRules)
+    };
+    return {
+      mapped,
+      wildcardMatched,
+      optionalFiles,
+      unmapped,
+      preFiltered,
+      stats
+    };
+  }
+}
+function filterFiles(request) {
+  const matcher = new Matcher(request.context);
+  if (request.rules && request.groups) {
+    throw new Error('FilterRequest: Provide either "rules" or "groups", not both');
+  }
+  if (!request.rules && !request.groups) {
+    throw new Error('FilterRequest: Must provide either "rules" or "groups"');
+  }
+  if (request.groups) {
+    return matcher.filterFilesWithGroups(
+      request.files,
+      request.groups,
+      request.sortFn,
+      request.preFilter,
+      request.mode
+    );
+  }
+  if (!request.rules) {
+    throw new Error("FilterRequest: Rules are required");
+  }
+  return matcher.filterFiles(
+    request.files,
+    request.rules,
+    request.sortFn,
+    request.preFilter,
+    request.mode
+  );
+}
+exports.FilterEngine = FilterEngine;
+exports.Matcher = Matcher;
+exports.filterFiles = filterFiles;
+exports.getValueFromPath = getValueFromPath;
+exports.getValueOr = getValueOr;
+exports.isSingleMatchRule = isSingleMatchRule;
+exports.isWildcardRule = isWildcardRule;
+exports.pathExists = pathExists;
+//# sourceMappingURL=aikotools-datafilter.cjs.map