@aikotools/datafilter 1.0.4 → 1.1.0

package/dist/aikotools-datafilter.mjs

@@ -1,83 +1,90 @@
-import { DateTime as E } from "luxon";
-function R(i) {
-  return "matchAny" in i;
+import { DateTime } from "luxon";
+function isWildcardRule(rule) {
+  return "matchAny" in rule;
 }
-function w(i) {
-  return "match" in i && "expected" in i;
+function isSingleMatchRule(rule) {
+  return "match" in rule && "expected" in rule;
 }
-function k(i, s) {
-  const t = [];
-  if (s.length === 0)
+function getValueFromPath(object, path) {
+  const validPath = [];
+  if (path.length === 0) {
     return {
-      value: i,
-      found: !0,
+      value: object,
+      found: true,
       validPath: []
     };
-  let e = i;
-  for (let n = 0; n < s.length; n++) {
-    const r = s[n];
-    if (e == null)
+  }
+  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: !1,
-        error: `Cannot read property '${r}' of ${e}`,
-        validPath: t
+        found: false,
+        error: `Cannot read property '${segment}' of ${current}`,
+        validPath
       };
-    if (Array.isArray(e)) {
-      const a = typeof r == "number" ? r : parseInt(String(r), 10);
-      if (isNaN(a))
+    }
+    if (Array.isArray(current)) {
+      const index = typeof segment === "number" ? segment : parseInt(String(segment), 10);
+      if (isNaN(index)) {
         return {
           value: void 0,
-          found: !1,
-          error: `Array index must be a number, got '${r}'`,
-          validPath: t
+          found: false,
+          error: `Array index must be a number, got '${segment}'`,
+          validPath
         };
-      if (a < 0 || a >= e.length)
+      }
+      if (index < 0 || index >= current.length) {
         return {
           value: void 0,
-          found: !1,
-          error: `Array index ${a} out of bounds (length: ${e.length})`,
-          validPath: t
+          found: false,
+          error: `Array index ${index} out of bounds (length: ${current.length})`,
+          validPath
         };
-      t.push(a), e = e[a];
+      }
+      validPath.push(index);
+      current = current[index];
       continue;
     }
-    if (typeof e == "object") {
-      const a = String(r);
-      if (!(a in e))
+    if (typeof current === "object") {
+      const key = String(segment);
+      if (!(key in current)) {
         return {
           value: void 0,
-          found: !1,
-          error: `Property '${a}' does not exist`,
-          validPath: t
+          found: false,
+          error: `Property '${key}' does not exist`,
+          validPath
         };
-      t.push(a), e = e[a];
+      }
+      validPath.push(key);
+      current = current[key];
       continue;
     }
     return {
       value: void 0,
-      found: !1,
-      error: `Cannot access property '${r}' of primitive type ${typeof e}`,
-      validPath: t
+      found: false,
+      error: `Cannot access property '${segment}' of primitive type ${typeof current}`,
+      validPath
     };
   }
   return {
-    value: e,
-    found: !0,
-    validPath: t
+    value: current,
+    found: true,
+    validPath
   };
 }
-function I(i, s) {
-  const t = k(i, s);
-  return t.found && t.value !== void 0;
+function pathExists(object, path) {
+  const result = getValueFromPath(object, path);
+  return result.found && result.value !== void 0;
 }
-function N(i, s, t) {
-  const e = k(i, s);
-  return e.found && e.value !== void 0 ? e.value : t;
+function getValueOr(object, path, defaultValue) {
+  const result = getValueFromPath(object, path);
+  return result.found && result.value !== void 0 ? result.value : defaultValue;
 }
-class S {
-  constructor(s) {
-    this.context = s;
+class FilterEngine {
+  constructor(context) {
+    this.context = context;
   }
   /**
    * Evaluates a single filter criterion against a data object.
@@ -87,12 +94,31 @@ class S {
    * @returns FilterCheckResult indicating success or failure
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  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,
+  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(e)}`
+      reason: `Unknown check type: ${JSON.stringify(check)}`
     };
   }
   /**
@@ -103,29 +129,34 @@ class S {
    * @param check - The value check specification
    * @returns FilterCheckResult
    */
-  checkValue(s, t, e) {
-    const n = k(s, t);
-    if (!n.found)
+  checkValue(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    if (!accessResult.found) {
       return {
-        status: !1,
+        status: false,
         checkType: "checkValue",
         reason: {
-          message: n.error || "Path not found",
-          path: t
+          message: accessResult.error || "Path not found",
+          path
         }
       };
-    const r = n.value, a = e.value;
-    return this.deepEqual(r, a) ? {
-      status: !0,
-      checkType: "checkValue"
-    } : {
-      status: !1,
+    }
+    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: t,
-        expected: a,
-        actual: r
+        path,
+        expected,
+        actual
       }
     };
   }
@@ -137,17 +168,21 @@ class S {
    * @param check - The exists check specification
    * @returns FilterCheckResult
    */
-  checkExists(s, t, e) {
-    const n = k(s, t), r = n.found && n.value !== void 0;
-    return e.exists === r ? {
-      status: !0,
-      checkType: "checkExists"
-    } : {
-      status: !1,
+  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: e.exists ? `Path should exist but doesn't: ${n.error}` : "Path should not exist but does",
-        path: t
+        message: check.exists ? `Path should exist but doesn't: ${accessResult.error}` : "Path should not exist but does",
+        path
       }
     };
   }
@@ -159,39 +194,44 @@ class S {
    * @param check - The array element check specification
    * @returns FilterCheckResult
    */
-  checkArrayElement(s, t, e) {
-    const n = k(s, t);
-    if (!n.found)
+  checkArrayElement(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    if (!accessResult.found) {
       return {
-        status: !1,
+        status: false,
         checkType: "checkArrayElement",
         reason: {
-          message: n.error || "Path not found",
-          path: t
+          message: accessResult.error || "Path not found",
+          path
         }
       };
-    const r = n.value;
-    if (!Array.isArray(r))
+    }
+    const array = accessResult.value;
+    if (!Array.isArray(array)) {
       return {
-        status: !1,
+        status: false,
         checkType: "checkArrayElement",
         reason: {
           message: "Value is not an array",
-          path: t,
-          actualType: typeof r
+          path,
+          actualType: typeof array
         }
       };
-    const a = r.some((u) => this.deepEqual(u, e.item));
-    return e.itemExists === a ? {
-      status: !0,
-      checkType: "checkArrayElement"
-    } : {
-      status: !1,
+    }
+    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: e.itemExists ? "Item should exist in array but doesn't" : "Item should not exist in array but does",
-        path: t,
-        item: e.item
+        message: check.itemExists ? "Item should exist in array but doesn't" : "Item should not exist in array but does",
+        path,
+        item: check.item
       }
     };
   }
@@ -203,52 +243,62 @@ class S {
    * @param check - The array size check specification
    * @returns FilterCheckResult
    */
-  checkArraySize(s, t, e) {
-    const n = k(s, t);
-    if (!n.found)
+  checkArraySize(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    if (!accessResult.found) {
       return {
-        status: !1,
+        status: false,
         checkType: "checkArraySize",
         reason: {
-          message: n.error || "Path not found",
-          path: t
+          message: accessResult.error || "Path not found",
+          path
         }
       };
-    const r = n.value;
-    if (!Array.isArray(r))
+    }
+    const array = accessResult.value;
+    if (!Array.isArray(array)) {
       return {
-        status: !1,
+        status: false,
         checkType: "checkArraySize",
         reason: {
           message: "Value is not an array",
-          path: t,
-          actualType: typeof r
+          path,
+          actualType: typeof array
         }
       };
-    const a = r.length, u = e.size;
-    let l = !1, h = "";
-    switch (e.type) {
+    }
+    const actualSize = array.length;
+    const expectedSize = check.size;
+    let passes = false;
+    let message = "";
+    switch (check.type) {
       case "equal":
-        l = a === u, h = `Array length should be ${u} but is ${a}`;
+        passes = actualSize === expectedSize;
+        message = `Array length should be ${expectedSize} but is ${actualSize}`;
         break;
       case "lessThan":
-        l = a < u, h = `Array length should be less than ${u} but is ${a}`;
+        passes = actualSize < expectedSize;
+        message = `Array length should be less than ${expectedSize} but is ${actualSize}`;
         break;
       case "greaterThan":
-        l = a > u, h = `Array length should be greater than ${u} but is ${a}`;
+        passes = actualSize > expectedSize;
+        message = `Array length should be greater than ${expectedSize} but is ${actualSize}`;
         break;
     }
-    return l ? {
-      status: !0,
-      checkType: "checkArraySize"
-    } : {
-      status: !1,
+    if (passes) {
+      return {
+        status: true,
+        checkType: "checkArraySize"
+      };
+    }
+    return {
+      status: false,
       checkType: "checkArraySize",
       reason: {
-        message: h,
-        path: t,
-        expected: u,
-        actual: a
+        message,
+        path,
+        expected: expectedSize,
+        actual: actualSize
       }
     };
   }
@@ -260,81 +310,100 @@ class S {
    * @param check - The time range check specification
    * @returns FilterCheckResult
    */
-  checkTimeRange(s, t, e) {
-    const n = k(s, t);
-    if (!n.found)
+  checkTimeRange(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    if (!accessResult.found) {
       return {
-        status: !1,
+        status: false,
         checkType: "checkTimeRange",
         reason: {
-          message: n.error || "Path not found",
-          path: t
+          message: accessResult.error || "Path not found",
+          path
         }
       };
-    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,
+    }
+    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 ${r} is outside range [${a}, ${u}]`,
-          path: t,
-          actual: r,
-          min: a,
-          max: u
+          message: `Timestamp ${value} is outside range [${min}, ${max}]`,
+          path,
+          actual: value,
+          min,
+          max
         }
       };
     }
-    if (typeof r == "string") {
-      const a = E.fromISO(r), u = E.fromISO(e.min), l = E.fromISO(e.max);
-      return a.isValid ? !u.isValid || !l.isValid ? {
-        status: !1,
-        checkType: "checkTimeRange",
-        reason: {
-          message: "Invalid min or max time",
-          min: e.min,
-          max: e.max
-        }
-      } : a >= u && a <= l ? {
-        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,
+    if (typeof value === "string") {
+      const timestamp = DateTime.fromISO(value);
+      const minTime = DateTime.fromISO(check.min);
+      const maxTime = 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: `Invalid timestamp: ${r}`,
-          path: t
+          message: `Timestamp ${value} is outside range [${check.min}, ${check.max}]`,
+          path,
+          actual: value,
+          min: check.min,
+          max: check.max
         }
       };
     }
     return {
-      status: !1,
+      status: false,
       checkType: "checkTimeRange",
       reason: {
-        message: `Timestamp must be a string or number, got ${typeof r}`,
-        path: t
+        message: `Timestamp must be a string or number, got ${typeof value}`,
+        path
       }
     };
   }
@@ -346,38 +415,45 @@ class S {
    * @param check - The numeric range check specification
    * @returns FilterCheckResult
    */
-  checkNumericRange(s, t, e) {
-    const n = k(s, t);
-    if (!n.found)
+  checkNumericRange(data, path, check) {
+    const accessResult = getValueFromPath(data, path);
+    if (!accessResult.found) {
       return {
-        status: !1,
+        status: false,
         checkType: "checkNumericRange",
         reason: {
-          message: n.error || "Path not found",
-          path: t
+          message: accessResult.error || "Path not found",
+          path
         }
       };
-    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,
+    }
+    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 ${r} is outside range [${e.min}, ${e.max}]`,
-        path: t,
-        actual: r,
-        min: e.min,
-        max: e.max
+        message: `Value ${value} is outside range [${check.min}, ${check.max}]`,
+        path,
+        actual: value,
+        min: check.min,
+        max: check.max
       }
     };
   }
@@ -386,24 +462,30 @@ class S {
    * Compares two values recursively for equality.
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  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;
+  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 M {
-  constructor(s) {
-    this.engine = new S(s);
+class Matcher {
+  constructor(context) {
+    this.engine = new FilterEngine(context);
   }
   /**
    * Matches a single file against a rule.
@@ -412,12 +494,16 @@ class M {
    * @param rule - The rule to match against
    * @returns MatchResult indicating if all criteria matched
    */
-  matchFile(s, t) {
-    const n = (R(t) ? t.matchAny : t.match).map((a) => this.engine.evaluateCriterion(s.data, a));
+  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: n.every((a) => a.status),
-      checks: n,
-      rule: t
+      matched,
+      checks,
+      rule
     };
   }
   /**
@@ -427,16 +513,23 @@ class M {
    * @param preFilter - Filter criteria that all files must match
    * @returns Object with matched files and excluded files (with failed checks)
    */
-  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)
+  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: e, excluded: n };
+    return { matched, excluded };
   }
   /**
    * Main filtering function that processes files according to rules.
@@ -445,100 +538,292 @@ class M {
    * @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)
-   * @returns FilterResult with mapped, wildcardMatched, and unmapped files
+   * @param mode - Matching mode ('strict', 'optional', or 'strict-optional')
+   * @returns FilterResult with mapped, wildcardMatched, optionalFiles and unmapped files
    */
-  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], l = [], h = [], y = [], g = /* @__PURE__ */ new Set(), x = /* @__PURE__ */ new Map();
-    let o = 0, c = 0;
-    for (; o < u.length; ) {
-      const f = u[o];
-      if (c >= t.length) {
-        g.has(o) || y.push({
-          file: f,
-          attemptedRules: []
-        }), o++;
+  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 m = t[c], A = [];
-      let T = !1;
-      if (Array.isArray(m)) {
-        for (let p = 0; p < m.length; p++) {
-          if (x.get(c)?.has(p))
+      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 v = m[p], $ = this.matchFile(f, v);
-          if (A.push($), $.matched && w(v)) {
-            x.has(c) || x.set(c, /* @__PURE__ */ new Set());
-            const b = x.get(c);
-            b && b.add(p), l.push({
-              expected: v.expected,
-              file: f,
-              matchResult: $,
-              optional: v.optional || !1,
-              info: v.info
-            }), g.add(o), T = !0;
+          }
+          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;
           }
         }
-        x.get(c)?.size === m.length && c++, o++;
+        const allUsed = usedFlexibleRules.get(ruleIndex)?.size === ruleOrRules.length;
+        if (allUsed) {
+          ruleIndex++;
+        }
+        if (fileMatched) {
+          fileIndex++;
+        } else {
+          fileIndex++;
+        }
       } else {
-        const d = m, p = this.matchFile(f, d);
-        A.push(p), p.matched ? w(d) ? (l.push({
-          expected: d.expected,
-          file: f,
-          matchResult: p,
-          optional: d.optional || !1,
-          info: d.info
-        }), g.add(o), c++, o++) : R(d) && (h.push({
-          file: f,
-          matchResult: p,
-          info: d.info
-        }), g.add(o), d.greedy || c++, o++) : d.optional || R(d) ? c++ : (y.push({
-          file: f,
-          attemptedRules: A
-        }), o++);
+        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 F = {
-      totalFiles: s.length,
-      mappedFiles: l.length,
-      wildcardMatchedFiles: h.length,
-      unmappedFiles: y.length,
-      preFilteredFiles: a.length,
-      totalRules: this.countRules(t),
-      mandatoryRules: this.countMandatoryRules(t),
-      optionalRules: this.countOptionalRules(t)
+    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: l,
-      wildcardMatched: h,
-      unmapped: y,
-      preFiltered: a,
-      stats: F
+      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(s) {
-    return s.reduce((t, e) => Array.isArray(e) ? t + e.length : t + 1, 0);
+  countRules(rules) {
+    return rules.reduce((count, rule) => {
+      if (Array.isArray(rule)) {
+        return count + rule.length;
+      }
+      return count + 1;
+    }, 0);
   }
   /**
    * Counts mandatory rules
    */
-  countMandatoryRules(s) {
-    return s.reduce((t, e) => Array.isArray(e) ? t + e.filter((n) => !n.optional && !R(n)).length : t + (e.optional || R(e) ? 0 : 1), 0);
+  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(s) {
-    return s.reduce((t, e) => Array.isArray(e) ? t + e.filter((n) => n.optional || R(n)).length : t + (e.optional || R(e) ? 1 : 0), 0);
+  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.
@@ -549,66 +834,104 @@ class M {
    * @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)
-   * @returns FilterResult with mapped, wildcardMatched, and unmapped files
+   * @param mode - Matching mode ('strict', 'optional', or 'strict-optional')
+   * @returns FilterResult with mapped, wildcardMatched, optionalFiles and unmapped files
    */
-  filterFilesWithGroups(s, t, e, n) {
-    let r, a = [];
-    if (n) {
-      const o = this.applyPreFilter(s, n);
-      r = o.matched, a = o.excluded;
-    } else
-      r = s;
-    const u = e ? [...r].sort(e) : [...r], l = [], h = [], y = [];
-    for (const o of t) {
-      const c = u.filter((m) => o.groupFilter.map((T) => this.engine.evaluateCriterion(m.data, T)).every((T) => T.status));
-      if (c.length === 0)
+  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 F = o.rules.map((m) => (Array.isArray(m), m)), f = this.filterFiles(c, F);
-      l.push(...f.mapped), h.push(...f.wildcardMatched), y.push(...f.unmapped);
-    }
-    const g = t.flatMap((o) => o.rules), x = {
-      totalFiles: s.length,
-      mappedFiles: l.length,
-      wildcardMatchedFiles: h.length,
-      unmappedFiles: y.length,
-      preFilteredFiles: a.length,
-      totalRules: this.countRules(g),
-      mandatoryRules: this.countMandatoryRules(g),
-      optionalRules: this.countOptionalRules(g)
+      }
+      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: l,
-      wildcardMatched: h,
-      unmapped: y,
-      preFiltered: a,
-      stats: x
+      mapped,
+      wildcardMatched,
+      optionalFiles,
+      unmapped,
+      preFiltered,
+      stats
     };
   }
 }
-function z(i) {
-  const s = new M(i.context);
-  if (i.rules && i.groups)
+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 (!i.rules && !i.groups)
+  }
+  if (!request.rules && !request.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 (request.groups) {
+    return matcher.filterFilesWithGroups(
+      request.files,
+      request.groups,
+      request.sortFn,
+      request.preFilter,
+      request.mode
     );
-  if (!i.rules)
+  }
+  if (!request.rules) {
     throw new Error("FilterRequest: Rules are required");
-  return s.filterFiles(i.files, i.rules, i.sortFn, i.preFilter);
+  }
+  return matcher.filterFiles(
+    request.files,
+    request.rules,
+    request.sortFn,
+    request.preFilter,
+    request.mode
+  );
 }
 export {
-  S as FilterEngine,
-  M as Matcher,
-  z as filterFiles,
-  k as getValueFromPath,
-  N as getValueOr,
-  w as isSingleMatchRule,
-  R as isWildcardRule,
-  I as pathExists
+  FilterEngine,
+  Matcher,
+  filterFiles,
+  getValueFromPath,
+  getValueOr,
+  isSingleMatchRule,
+  isWildcardRule,
+  pathExists
 };
+//# sourceMappingURL=aikotools-datafilter.mjs.map