@jskit-ai/crud-core 0.1.52 → 0.1.54

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-core",
-  version: "0.1.52",
+  version: "0.1.54",
   kind: "runtime",
   description: "Shared CRUD helpers used by CRUD modules.",
   dependsOn: [
@@ -26,7 +26,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/crud-core": "0.1.52"
+        "@jskit-ai/crud-core": "0.1.54"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -22,16 +22,17 @@
     "./server/fieldAccess": "./src/server/fieldAccess.js",
     "./server/createCrudServiceFromResource": "./src/server/createCrudServiceFromResource.js",
     "./server/crudModuleConfig": "./src/server/crudModuleConfig.js",
-    "./server/listQueryValidators": "./src/server/listQueryValidators.js"
+    "./server/listQueryValidators": "./src/server/listQueryValidators.js",
+    "./server/listFilters": "./src/server/listFilters.js"
   },
   "dependencies": {
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/database-runtime": "0.1.44",
-    "@jskit-ai/kernel": "0.1.44",
-    "@jskit-ai/realtime": "0.1.43",
-    "@jskit-ai/shell-web": "0.1.43",
-    "@jskit-ai/users-core": "0.1.54",
-    "@jskit-ai/users-web": "0.1.59",
+    "@jskit-ai/database-runtime": "0.1.46",
+    "@jskit-ai/kernel": "0.1.46",
+    "@jskit-ai/realtime": "0.1.45",
+    "@jskit-ai/shell-web": "0.1.45",
+    "@jskit-ai/users-core": "0.1.56",
+    "@jskit-ai/users-web": "0.1.61",
     "typebox": "^1.0.81"
   }
 }

package/src/server/listFilters.js

@@ -0,0 +1,547 @@
+import { Type } from "typebox";
+import {
+  normalizeObjectInput,
+  mergeObjectSchemas,
+  RECORD_ID_PATTERN
+} from "@jskit-ai/kernel/shared/validators";
+import {
+  normalizeBoolean,
+  normalizeCanonicalRecordIdText,
+  normalizeObject,
+  normalizeText,
+  normalizeUniqueTextList
+} from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  defineCrudListFilters,
+  CRUD_LIST_FILTER_TYPE_FLAG,
+  CRUD_LIST_FILTER_TYPE_ENUM,
+  CRUD_LIST_FILTER_TYPE_ENUM_MANY,
+  CRUD_LIST_FILTER_TYPE_RECORD_ID,
+  CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY,
+  CRUD_LIST_FILTER_TYPE_DATE,
+  CRUD_LIST_FILTER_TYPE_DATE_RANGE,
+  CRUD_LIST_FILTER_TYPE_NUMBER_RANGE,
+  CRUD_LIST_FILTER_TYPE_PRESENCE
+} from "@jskit-ai/kernel/shared/support/crudListFilters";
+
+const DATE_FILTER_PATTERN_SOURCE = "^\\d{4}-\\d{2}-\\d{2}$";
+const DATE_FILTER_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
+const NUMBER_FILTER_PATTERN_SOURCE = "^[+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:[eE][+-]?\\d+)?$";
+const CRUD_LIST_FILTER_INVALID_VALUES_REJECT = "reject";
+const CRUD_LIST_FILTER_INVALID_VALUES_DISCARD = "discard";
+const CRUD_LIST_FILTER_INVALID_VALUES_MODES = Object.freeze([
+  CRUD_LIST_FILTER_INVALID_VALUES_REJECT,
+  CRUD_LIST_FILTER_INVALID_VALUES_DISCARD
+]);
+const looseTextInputSchema = Type.String({ minLength: 0 });
+const strictNumberInputSchema = Type.Union([
+  Type.String({ pattern: NUMBER_FILTER_PATTERN_SOURCE }),
+  Type.Number()
+]);
+const looseStringOrNumberSchema = Type.Union([
+  looseTextInputSchema,
+  Type.Number()
+]);
+const recordIdInputSchema = Type.Union([
+  Type.String({ pattern: RECORD_ID_PATTERN }),
+  Type.Number({ minimum: 1 })
+]);
+const flagInputSchema = Type.Union([
+  Type.String({ minLength: 0 }),
+  Type.Boolean(),
+  Type.Number()
+]);
+
+function normalizeCrudListFilterInvalidValues(value = "") {
+  const normalized = normalizeText(value).toLowerCase();
+  if (CRUD_LIST_FILTER_INVALID_VALUES_MODES.includes(normalized)) {
+    return normalized;
+  }
+
+  throw new TypeError(
+    `Unsupported CRUD list filter invalidValues mode "${value}". Expected one of: ${CRUD_LIST_FILTER_INVALID_VALUES_MODES.join(", ")}.`
+  );
+}
+
+function createSingleOrMultiValueSchema(itemSchema) {
+  return Type.Optional(
+    Type.Union([
+      itemSchema,
+      Type.Array(itemSchema, {
+        minItems: 1
+      })
+    ])
+  );
+}
+
+function firstValue(value) {
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+
+  return value;
+}
+
+function normalizeDateFilterValue(value) {
+  const normalized = normalizeText(firstValue(value));
+  if (!normalized || !DATE_FILTER_PATTERN.test(normalized)) {
+    return "";
+  }
+
+  return normalized;
+}
+
+function normalizeNumberFilterValue(value) {
+  if (value == null || value === "") {
+    return null;
+  }
+
+  const normalized = typeof value === "number"
+    ? value
+    : Number(normalizeText(firstValue(value)));
+  return Number.isFinite(normalized) ? normalized : null;
+}
+
+function normalizeRecordIdFilterValue(value) {
+  return normalizeCanonicalRecordIdText(firstValue(value), {
+    fallback: ""
+  }) || "";
+}
+
+function normalizeRecordIdFilterValues(value) {
+  return normalizeUniqueTextList(value, {
+    acceptSingle: true
+  })
+    .map((entry) => normalizeCanonicalRecordIdText(entry, { fallback: "" }))
+    .filter(Boolean);
+}
+
+function resolveAllowedOptionValues(filter = {}) {
+  return new Set(
+    (Array.isArray(filter.options) ? filter.options : [])
+      .map((entry) => normalizeText(entry?.value))
+      .filter(Boolean)
+  );
+}
+
+function normalizeAllowedTextValue(value, allowedValues = new Set()) {
+  const normalized = normalizeText(firstValue(value));
+  if (!normalized || !allowedValues.has(normalized)) {
+    return "";
+  }
+
+  return normalized;
+}
+
+function normalizeAllowedTextValues(value, allowedValues = new Set()) {
+  return normalizeUniqueTextList(value, {
+    acceptSingle: true
+  }).filter((entry) => allowedValues.has(entry));
+}
+
+function addDaysToDateFilterValue(value = "", days = 0) {
+  const normalizedValue = normalizeDateFilterValue(value);
+  if (!normalizedValue || !Number.isInteger(days)) {
+    return "";
+  }
+
+  const date = new Date(`${normalizedValue}T00:00:00.000Z`);
+  if (Number.isNaN(date.getTime())) {
+    return "";
+  }
+
+  date.setUTCDate(date.getUTCDate() + days);
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function createFilterQuerySchema(filter = {}, { invalidValues = CRUD_LIST_FILTER_INVALID_VALUES_REJECT } = {}) {
+  const invalidValueMode = normalizeCrudListFilterInvalidValues(invalidValues);
+  const discardInvalidValues = invalidValueMode === CRUD_LIST_FILTER_INVALID_VALUES_DISCARD;
+  const allowedValues = (Array.isArray(filter.options) ? filter.options : []).map((entry) => entry.value);
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_FLAG) {
+    return Type.Object(
+      {
+        [filter.queryKey]: Type.Optional(flagInputSchema)
+      },
+      { additionalProperties: false }
+    );
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM || filter.type === CRUD_LIST_FILTER_TYPE_PRESENCE) {
+    return Type.Object(
+      {
+        [filter.queryKey]: Type.Optional(
+          discardInvalidValues
+            ? looseTextInputSchema
+            : Type.String({ enum: allowedValues })
+        )
+      },
+      { additionalProperties: false }
+    );
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY) {
+    return Type.Object(
+      {
+        [filter.queryKey]: createSingleOrMultiValueSchema(
+          discardInvalidValues
+            ? looseTextInputSchema
+            : Type.String({ enum: allowedValues })
+        )
+      },
+      { additionalProperties: false }
+    );
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID) {
+    return Type.Object(
+      {
+        [filter.queryKey]: Type.Optional(
+          discardInvalidValues
+            ? looseStringOrNumberSchema
+            : recordIdInputSchema
+        )
+      },
+      { additionalProperties: false }
+    );
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+    return Type.Object(
+      {
+        [filter.queryKey]: createSingleOrMultiValueSchema(
+          discardInvalidValues
+            ? looseStringOrNumberSchema
+            : recordIdInputSchema
+        )
+      },
+      { additionalProperties: false }
+    );
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE) {
+    return Type.Object(
+      {
+        [filter.queryKey]: Type.Optional(
+          discardInvalidValues
+            ? looseTextInputSchema
+            : Type.String({ pattern: DATE_FILTER_PATTERN_SOURCE })
+        )
+      },
+      { additionalProperties: false }
+    );
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+    return Type.Object(
+      {
+        [filter.fromKey]: Type.Optional(
+          discardInvalidValues
+            ? looseTextInputSchema
+            : Type.String({ pattern: DATE_FILTER_PATTERN_SOURCE })
+        ),
+        [filter.toKey]: Type.Optional(
+          discardInvalidValues
+            ? looseTextInputSchema
+            : Type.String({ pattern: DATE_FILTER_PATTERN_SOURCE })
+        )
+      },
+      { additionalProperties: false }
+    );
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    return Type.Object(
+      {
+        [filter.minKey]: Type.Optional(
+          discardInvalidValues
+            ? looseStringOrNumberSchema
+            : strictNumberInputSchema
+        ),
+        [filter.maxKey]: Type.Optional(
+          discardInvalidValues
+            ? looseStringOrNumberSchema
+            : strictNumberInputSchema
+        )
+      },
+      { additionalProperties: false }
+    );
+  }
+
+  return Type.Object({}, { additionalProperties: false });
+}
+
+function normalizeFilterValue(filter = {}, source = {}) {
+  const allowedValues = resolveAllowedOptionValues(filter);
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_FLAG) {
+    if (!Object.hasOwn(source, filter.queryKey)) {
+      return undefined;
+    }
+
+    const sourceValue = source[filter.queryKey];
+    if (sourceValue === null || sourceValue === "") {
+      return true;
+    }
+
+    try {
+      return normalizeBoolean(firstValue(sourceValue));
+    } catch {
+      return undefined;
+    }
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM || filter.type === CRUD_LIST_FILTER_TYPE_PRESENCE) {
+    if (!Object.hasOwn(source, filter.queryKey)) {
+      return undefined;
+    }
+
+    const normalizedValue = normalizeAllowedTextValue(source[filter.queryKey], allowedValues);
+    return normalizedValue || undefined;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY) {
+    if (!Object.hasOwn(source, filter.queryKey)) {
+      return undefined;
+    }
+
+    const normalizedValues = normalizeAllowedTextValues(source[filter.queryKey], allowedValues);
+    return normalizedValues.length > 0 ? normalizedValues : undefined;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID) {
+    if (!Object.hasOwn(source, filter.queryKey)) {
+      return undefined;
+    }
+
+    const normalizedValue = normalizeRecordIdFilterValue(source[filter.queryKey]);
+    return normalizedValue || undefined;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+    if (!Object.hasOwn(source, filter.queryKey)) {
+      return undefined;
+    }
+
+    const normalizedValues = normalizeRecordIdFilterValues(source[filter.queryKey]);
+    return normalizedValues.length > 0 ? normalizedValues : undefined;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE) {
+    if (!Object.hasOwn(source, filter.queryKey)) {
+      return undefined;
+    }
+
+    const normalizedValue = normalizeDateFilterValue(source[filter.queryKey]);
+    return normalizedValue || undefined;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+    const from = normalizeDateFilterValue(source[filter.fromKey]);
+    const to = normalizeDateFilterValue(source[filter.toKey]);
+    if (!from && !to) {
+      return undefined;
+    }
+
+    return Object.freeze({
+      ...(from ? { from } : {}),
+      ...(to ? { to } : {})
+    });
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    const min = normalizeNumberFilterValue(source[filter.minKey]);
+    const max = normalizeNumberFilterValue(source[filter.maxKey]);
+    if (min == null && max == null) {
+      return undefined;
+    }
+
+    return Object.freeze({
+      ...(min != null ? { min } : {}),
+      ...(max != null ? { max } : {})
+    });
+  }
+
+  return undefined;
+}
+
+function normalizeColumnsMap(columns = {}) {
+  const source = normalizeObject(columns);
+  const normalized = {};
+  for (const [key, value] of Object.entries(source)) {
+    const normalizedKey = normalizeText(key);
+    const normalizedValue = normalizeText(value);
+    if (!normalizedKey || !normalizedValue) {
+      continue;
+    }
+
+    normalized[normalizedKey] = normalizedValue;
+  }
+
+  return Object.freeze(normalized);
+}
+
+function applyDefaultFilterQuery(queryBuilder, filter = {}, value, column = "") {
+  if (!column) {
+    return queryBuilder;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_FLAG) {
+    if (value === true) {
+      queryBuilder.where(column, true);
+    }
+    return queryBuilder;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM || filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID) {
+    if (value !== undefined) {
+      queryBuilder.where(column, value);
+    }
+    return queryBuilder;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY || filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+    if (Array.isArray(value) && value.length > 0) {
+      queryBuilder.whereIn(column, value);
+    }
+    return queryBuilder;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_PRESENCE) {
+    if (value === "present") {
+      queryBuilder.whereNotNull(column);
+    }
+    if (value === "missing") {
+      queryBuilder.whereNull(column);
+    }
+    return queryBuilder;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE) {
+    if (value) {
+      const nextDate = addDaysToDateFilterValue(value, 1);
+      queryBuilder.where(column, ">=", `${value} 00:00:00`);
+      if (nextDate) {
+        queryBuilder.where(column, "<", `${nextDate} 00:00:00`);
+      }
+    }
+    return queryBuilder;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+    if (value?.from) {
+      queryBuilder.where(column, ">=", `${value.from} 00:00:00`);
+    }
+    if (value?.to) {
+      const nextDate = addDaysToDateFilterValue(value.to, 1);
+      if (nextDate) {
+        queryBuilder.where(column, "<", `${nextDate} 00:00:00`);
+      }
+    }
+    return queryBuilder;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    if (value?.min != null) {
+      queryBuilder.where(column, ">=", value.min);
+    }
+    if (value?.max != null) {
+      queryBuilder.where(column, "<=", value.max);
+    }
+    return queryBuilder;
+  }
+
+  return queryBuilder;
+}
+
+function createCrudListFilters(definitions = {}, { columns = {}, apply = {} } = {}) {
+  const normalizedFilters = defineCrudListFilters(definitions);
+  const normalizedColumns = normalizeColumnsMap(columns);
+  const filterEntries = Object.values(normalizedFilters);
+
+  function normalize(payload = {}) {
+    const source = normalizeObjectInput(payload);
+    const normalized = {};
+
+    for (const filter of filterEntries) {
+      const value = normalizeFilterValue(filter, source);
+      if (value === undefined) {
+        continue;
+      }
+
+      normalized[filter.key] = value;
+    }
+
+    return Object.freeze(normalized);
+  }
+
+  const queryValidators = Object.freeze({
+    [CRUD_LIST_FILTER_INVALID_VALUES_REJECT]: Object.freeze({
+      schema: mergeObjectSchemas(
+        filterEntries.map((filter) => createFilterQuerySchema(filter, {
+          invalidValues: CRUD_LIST_FILTER_INVALID_VALUES_REJECT
+        }))
+      ),
+      normalize
+    }),
+    [CRUD_LIST_FILTER_INVALID_VALUES_DISCARD]: Object.freeze({
+      schema: mergeObjectSchemas(
+        filterEntries.map((filter) => createFilterQuerySchema(filter, {
+          invalidValues: CRUD_LIST_FILTER_INVALID_VALUES_DISCARD
+        }))
+      ),
+      normalize
+    })
+  });
+
+  function applyQuery(queryBuilder, payload = {}) {
+    if (!queryBuilder || typeof queryBuilder.where !== "function") {
+      throw new TypeError("createCrudListFilters.applyQuery requires query builder.");
+    }
+
+    const normalized = normalize(payload);
+    for (const filter of filterEntries) {
+      if (!Object.hasOwn(normalized, filter.key)) {
+        continue;
+      }
+
+      const value = normalized[filter.key];
+      const customApply = typeof apply?.[filter.key] === "function"
+        ? apply[filter.key]
+        : null;
+      if (customApply) {
+        customApply(queryBuilder, value, {
+          filter,
+          filters: normalized
+        });
+        continue;
+      }
+
+      applyDefaultFilterQuery(queryBuilder, filter, value, normalizedColumns[filter.key] || "");
+    }
+
+    return queryBuilder;
+  }
+
+  function createQueryValidator({ invalidValues } = {}) {
+    const invalidValueMode = normalizeCrudListFilterInvalidValues(invalidValues);
+    return queryValidators[invalidValueMode];
+  }
+
+  return Object.freeze({
+    filters: normalizedFilters,
+    createQueryValidator,
+    normalize,
+    applyQuery
+  });
+}
+
+export {
+  CRUD_LIST_FILTER_INVALID_VALUES_REJECT,
+  CRUD_LIST_FILTER_INVALID_VALUES_DISCARD,
+  createCrudListFilters
+};

package/test/listFilters.test.js

@@ -0,0 +1,379 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Check } from "typebox/value";
+import { compileRouteValidator } from "@jskit-ai/kernel/_testable";
+import { cursorPaginationQueryValidator } from "@jskit-ai/kernel/shared/validators";
+import { listSearchQueryValidator } from "../src/server/listQueryValidators.js";
+import {
+  CRUD_LIST_FILTER_INVALID_VALUES_REJECT,
+  CRUD_LIST_FILTER_INVALID_VALUES_DISCARD,
+  createCrudListFilters
+} from "../src/server/listFilters.js";
+
+test("crud-core exposes createCrudListFilters through the public package export", async () => {
+  const module = await import("@jskit-ai/crud-core/server/listFilters");
+  assert.equal(typeof module.createCrudListFilters, "function");
+  assert.equal(module.CRUD_LIST_FILTER_INVALID_VALUES_REJECT, CRUD_LIST_FILTER_INVALID_VALUES_REJECT);
+  assert.equal(module.CRUD_LIST_FILTER_INVALID_VALUES_DISCARD, CRUD_LIST_FILTER_INVALID_VALUES_DISCARD);
+});
+
+function createQueryDouble() {
+  const calls = [];
+  const nestedQuery = {
+    where(...args) {
+      calls.push(["innerWhere", ...args]);
+      return nestedQuery;
+    },
+    orWhere(...args) {
+      calls.push(["innerOrWhere", ...args]);
+      return nestedQuery;
+    },
+    whereNull(...args) {
+      calls.push(["innerWhereNull", ...args]);
+      return nestedQuery;
+    },
+    whereNotNull(...args) {
+      calls.push(["innerWhereNotNull", ...args]);
+      return nestedQuery;
+    }
+  };
+
+  const query = {
+    where(...args) {
+      if (args.length === 1 && typeof args[0] === "function") {
+        calls.push(["whereGroup"]);
+        args[0](nestedQuery);
+        return query;
+      }
+
+      calls.push(["where", ...args]);
+      return query;
+    },
+    whereIn(...args) {
+      calls.push(["whereIn", ...args]);
+      return query;
+    },
+    whereNull(...args) {
+      calls.push(["whereNull", ...args]);
+      return query;
+    },
+    whereNotNull(...args) {
+      calls.push(["whereNotNull", ...args]);
+      return query;
+    }
+  };
+
+  return {
+    query,
+    calls
+  };
+}
+
+test("createCrudListFilters normalizes filters into semantic values", () => {
+  const runtime = createCrudListFilters({
+    onlyStaff: {
+      type: "flag",
+      label: "Staff"
+    },
+    status: {
+      type: "enumMany",
+      label: "Status",
+      options: [
+        { value: "active", label: "Active" },
+        { value: "archived", label: "Archived" }
+      ]
+    },
+    arrivalDate: {
+      type: "dateRange",
+      label: "Arrival Date"
+    },
+    supplierContactId: {
+      type: "recordIdMany",
+      label: "Supplier"
+    },
+    weight: {
+      type: "numberRange",
+      label: "Weight"
+    }
+  });
+
+  const normalized = runtime.normalize({
+    onlyStaff: "",
+    status: ["active", "ignored", "archived"],
+    arrivalDateFrom: "2026-04-01",
+    arrivalDateTo: "2026-04-30",
+    supplierContactId: ["7", "bad", "4"],
+    weightMin: "12.5",
+    weightMax: 18
+  });
+
+  assert.deepEqual(normalized, {
+    onlyStaff: true,
+    status: ["active", "archived"],
+    arrivalDate: {
+      from: "2026-04-01",
+      to: "2026-04-30"
+    },
+    supplierContactId: ["7", "4"],
+    weight: {
+      min: 12.5,
+      max: 18
+    }
+  });
+});
+
+test("createCrudListFilters applies default column filters by type", () => {
+  const runtime = createCrudListFilters(
+    {
+      onlyStaff: {
+        type: "flag",
+        label: "Staff"
+      },
+      status: {
+        type: "enumMany",
+        label: "Status",
+        options: [
+          { value: "active", label: "Active" },
+          { value: "archived", label: "Archived" }
+        ]
+      },
+      supplierContactId: {
+        type: "recordId",
+        label: "Supplier"
+      },
+      arrivalDate: {
+        type: "dateRange",
+        label: "Arrival Date"
+      },
+      weight: {
+        type: "numberRange",
+        label: "Weight"
+      },
+      locationAssignment: {
+        type: "presence",
+        label: "Storage"
+      }
+    },
+    {
+      columns: {
+        onlyStaff: "is_staff",
+        status: "status",
+        supplierContactId: "supplier_contact_id",
+        arrivalDate: "arrival_datetime",
+        weight: "weight_received",
+        locationAssignment: "location_id"
+      }
+    }
+  );
+  const { query, calls } = createQueryDouble();
+
+  runtime.applyQuery(query, {
+    onlyStaff: "",
+    status: ["active", "archived"],
+    supplierContactId: "7",
+    arrivalDateFrom: "2026-04-01",
+    arrivalDateTo: "2026-04-30",
+    weightMin: "12.5",
+    weightMax: "18",
+    locationAssignment: "missing"
+  });
+
+  assert.deepEqual(calls, [
+    ["where", "is_staff", true],
+    ["whereIn", "status", ["active", "archived"]],
+    ["where", "supplier_contact_id", "7"],
+    ["where", "arrival_datetime", ">=", "2026-04-01 00:00:00"],
+    ["where", "arrival_datetime", "<", "2026-05-01 00:00:00"],
+    ["where", "weight_received", ">=", 12.5],
+    ["where", "weight_received", "<=", 18],
+    ["whereNull", "location_id"]
+  ]);
+});
+
+test("createCrudListFilters supports custom apply overrides for complex filters", () => {
+  const runtime = createCrudListFilters(
+    {
+      ccp1Status: {
+        type: "enumMany",
+        label: "CCP1",
+        options: [
+          { value: "pending", label: "Pending" },
+          { value: "passed", label: "Passed" },
+          { value: "failed", label: "Failed" }
+        ]
+      }
+    },
+    {
+      apply: {
+        ccp1Status(queryBuilder, values) {
+          queryBuilder.where((statusQuery) => {
+            if (values.includes("pending")) {
+              statusQuery.whereNull("ccp1_passed");
+            }
+            if (values.includes("failed")) {
+              statusQuery.orWhere("ccp1_passed", false);
+            }
+          });
+        }
+      }
+    }
+  );
+  const { query, calls } = createQueryDouble();
+
+  runtime.applyQuery(query, {
+    ccp1Status: ["pending", "failed"]
+  });
+
+  assert.deepEqual(calls, [
+    ["whereGroup"],
+    ["innerWhereNull", "ccp1_passed"],
+    ["innerOrWhere", "ccp1_passed", false]
+  ]);
+});
+
+test("createCrudListFilters query validator stays mergeable with search and cursor validators", () => {
+  const runtime = createCrudListFilters({
+    status: {
+      type: "enum",
+      label: "Status",
+      options: [
+        { value: "active", label: "Active" },
+        { value: "archived", label: "Archived" }
+      ]
+    },
+    arrivalDate: {
+      type: "dateRange",
+      label: "Arrival Date"
+    }
+  });
+
+  const compiled = compileRouteValidator({
+    queryValidator: [
+      cursorPaginationQueryValidator,
+      listSearchQueryValidator,
+      runtime.createQueryValidator({
+        invalidValues: CRUD_LIST_FILTER_INVALID_VALUES_REJECT
+      })
+    ]
+  });
+
+  assert.deepEqual(compiled.schema.querystring.required || [], []);
+});
+
+test("createCrudListFilters requires explicit invalid-value mode for new query validators", () => {
+  const runtime = createCrudListFilters({});
+
+  assert.throws(
+    () => runtime.createQueryValidator(),
+    /invalidValues mode/
+  );
+});
+
+test("createCrudListFilters reject validator keeps strict filter schemas", () => {
+  const runtime = createCrudListFilters({
+    arrivalDate: {
+      type: "dateRange",
+      label: "Arrival Date"
+    },
+    status: {
+      type: "enumMany",
+      label: "Status",
+      options: [
+        { value: "active", label: "Active" },
+        { value: "archived", label: "Archived" }
+      ]
+    },
+    supplierContactId: {
+      type: "recordIdMany",
+      label: "Supplier"
+    },
+    weight: {
+      type: "numberRange",
+      label: "Weight"
+    }
+  });
+
+  const validator = runtime.createQueryValidator({
+    invalidValues: CRUD_LIST_FILTER_INVALID_VALUES_REJECT
+  });
+
+  assert.equal(Check(validator.schema, {
+    arrivalDateFrom: "2026-04-01",
+    status: ["active"],
+    supplierContactId: ["7"],
+    weightMin: "12.5"
+  }), true);
+  assert.equal(Check(validator.schema, {
+    arrivalDateFrom: "bad-date"
+  }), false);
+  assert.equal(Check(validator.schema, {
+    status: ["active", "unexpected"]
+  }), false);
+  assert.equal(Check(validator.schema, {
+    supplierContactId: ["7", "bad"]
+  }), false);
+  assert.equal(Check(validator.schema, {
+    weightMin: "bad"
+  }), false);
+});
+
+test("createCrudListFilters discard validator accepts malformed values and lets normalize drop them", () => {
+  const runtime = createCrudListFilters({
+    arrivalDate: {
+      type: "dateRange",
+      label: "Arrival Date"
+    },
+    status: {
+      type: "enumMany",
+      label: "Status",
+      options: [
+        { value: "active", label: "Active" },
+        { value: "archived", label: "Archived" }
+      ]
+    },
+    supplierContactId: {
+      type: "recordIdMany",
+      label: "Supplier"
+    },
+    weight: {
+      type: "numberRange",
+      label: "Weight"
+    }
+  });
+
+  const validator = runtime.createQueryValidator({
+    invalidValues: CRUD_LIST_FILTER_INVALID_VALUES_DISCARD
+  });
+
+  assert.equal(Check(validator.schema, {
+    arrivalDateFrom: "bad-date",
+    status: ["active", "unexpected"],
+    supplierContactId: ["7", "bad"],
+    weightMin: "bad"
+  }), true);
+  assert.deepEqual(validator.normalize({
+    arrivalDateFrom: "bad-date",
+    arrivalDateTo: "2026-04-30",
+    status: ["active", "unexpected"],
+    supplierContactId: ["7", "bad"],
+    weightMin: "bad"
+  }), {
+    arrivalDate: {
+      to: "2026-04-30"
+    },
+    status: ["active"],
+    supplierContactId: ["7"]
+  });
+});
+
+test("createCrudListFilters exposes no default query validator alias", () => {
+  const runtime = createCrudListFilters({
+    arrivalDate: {
+      type: "dateRange",
+      label: "Arrival Date"
+    }
+  });
+
+  assert.equal(Object.hasOwn(runtime, "queryValidator"), false);
+  assert.equal(runtime.queryValidator, undefined);
+});