@jskit-ai/crud-core 0.1.99 → 0.1.101

package/package.descriptor.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.99",
+  "version": "0.1.101",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -27,15 +27,15 @@
     "./server/routeContracts": "./src/server/routeContracts.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.91",
-    "@jskit-ai/http-runtime": "0.1.90",
-    "@jskit-ai/kernel": "0.1.91",
+    "@jskit-ai/database-runtime": "0.1.93",
+    "@jskit-ai/http-runtime": "0.1.92",
+    "@jskit-ai/kernel": "0.1.93",
     "json-rest-schema": "1.x.x",
-    "@jskit-ai/realtime": "0.1.90",
-    "@jskit-ai/resource-crud-core": "0.1.36",
-    "@jskit-ai/shell-web": "0.1.90",
-    "@jskit-ai/users-core": "0.1.101",
-    "@jskit-ai/users-web": "0.1.106"
+    "@jskit-ai/realtime": "0.1.92",
+    "@jskit-ai/resource-crud-core": "0.1.38",
+    "@jskit-ai/shell-web": "0.1.92",
+    "@jskit-ai/users-core": "0.1.103",
+    "@jskit-ai/users-web": "0.1.108"
   },
   "peerDependencies": {
     "@tanstack/vue-query": "^5.90.5",

package/src/server/listFilters.js

@@ -21,6 +21,8 @@ import {
   CRUD_LIST_FILTER_TYPE_DATE_RANGE,
   CRUD_LIST_FILTER_TYPE_NUMBER_RANGE,
   CRUD_LIST_FILTER_TYPE_PRESENCE,
+  CRUD_LIST_FILTER_PRESENCE_PRESENT,
+  CRUD_LIST_FILTER_PRESENCE_MISSING,
   INVALID_CRUD_LIST_FILTER_QUERY_VALUE,
   normalizeCrudListFilterInvalidValues,
   parseCrudListFilterQueryValue
@@ -34,6 +36,7 @@ const NUMBER_FILTER_VALUE_PATTERN_SOURCE = "[+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:
 const NUMBER_RANGE_FILTER_PATTERN_SOURCE =
   `^(?:${NUMBER_FILTER_VALUE_PATTERN_SOURCE}(?:\\.\\.(?:${NUMBER_FILTER_VALUE_PATTERN_SOURCE})?)?|\\.\\.${NUMBER_FILTER_VALUE_PATTERN_SOURCE})$`;
 const CRUD_LIST_FILTER_QUERY_TYPE = "crudListFilterQuery";
+const JSON_REST_INTERNAL_FILTER_PREFIX = "__jskit";
 const crudListFilterSchemaFactory = createSchema.createFactory();
 const looseTextTransportSchema = Object.freeze({
   type: "string",
@@ -462,6 +465,276 @@ function normalizeColumnsMap(columns = {}) {
   return Object.freeze(normalized);
 }
 
+function resolveJsonRestFilterActualField(filter = {}, columns = {}) {
+  const meta = isPlainObject(filter.meta?.jsonRest) ? filter.meta.jsonRest : {};
+  return normalizeText(meta.actualField || meta.column || columns[filter.key] || filter.key);
+}
+
+function renderInternalJsonRestFilterKey(filter = {}, suffix = "") {
+  return [
+    JSON_REST_INTERNAL_FILTER_PREFIX,
+    filter.queryKey,
+    suffix
+  ]
+    .map((entry) => normalizeText(entry))
+    .filter(Boolean)
+    .join("_");
+}
+
+function createJsonRestSearchSchemaEntry({
+  type = "string",
+  actualField = "",
+  filterOperator = "=",
+  extra = {}
+} = {}) {
+  return {
+    type,
+    ...(actualField ? { actualField } : {}),
+    ...(filterOperator ? { filterOperator } : {}),
+    ...extra
+  };
+}
+
+function buildJsonRestFilterItemSchema(filter = {}) {
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY) {
+    return {
+      type: "string",
+      enum: (Array.isArray(filter.options) ? filter.options : []).map((entry) => entry.value)
+    };
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+    return cloneTransportSchema(recordIdTransportSchema);
+  }
+
+  return {};
+}
+
+function buildJsonRestSimpleFilterSearchSchemaEntry(filter = {}, { actualField = "" } = {}) {
+  if (filter.type === CRUD_LIST_FILTER_TYPE_FLAG) {
+    return createJsonRestSearchSchemaEntry({
+      type: "boolean",
+      actualField,
+      filterOperator: "="
+    });
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM) {
+    return createJsonRestSearchSchemaEntry({
+      type: "string",
+      actualField,
+      filterOperator: "=",
+      extra: {
+        enum: (Array.isArray(filter.options) ? filter.options : []).map((entry) => entry.value)
+      }
+    });
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_ENUM_MANY || filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY) {
+    return createJsonRestSearchSchemaEntry({
+      type: "array",
+      actualField,
+      filterOperator: "in",
+      extra: {
+        items: buildJsonRestFilterItemSchema(filter)
+      }
+    });
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_RECORD_ID) {
+    return createJsonRestSearchSchemaEntry({
+      type: "id",
+      actualField,
+      filterOperator: "="
+    });
+  }
+
+  return null;
+}
+
+function buildJsonRestRangeFilterSearchSchemaEntries(filter = {}, { actualField = "" } = {}) {
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE) {
+    return {
+      [renderInternalJsonRestFilterKey(filter, "from")]: createJsonRestSearchSchemaEntry({
+        type: "dateTime",
+        actualField,
+        filterOperator: ">="
+      }),
+      [renderInternalJsonRestFilterKey(filter, "toExclusive")]: createJsonRestSearchSchemaEntry({
+        type: "dateTime",
+        actualField,
+        filterOperator: "<"
+      })
+    };
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+    return {
+      [renderInternalJsonRestFilterKey(filter, "from")]: createJsonRestSearchSchemaEntry({
+        type: "dateTime",
+        actualField,
+        filterOperator: ">="
+      }),
+      [renderInternalJsonRestFilterKey(filter, "toExclusive")]: createJsonRestSearchSchemaEntry({
+        type: "dateTime",
+        actualField,
+        filterOperator: "<"
+      })
+    };
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    return {
+      [renderInternalJsonRestFilterKey(filter, "min")]: createJsonRestSearchSchemaEntry({
+        type: "number",
+        actualField,
+        filterOperator: ">="
+      }),
+      [renderInternalJsonRestFilterKey(filter, "max")]: createJsonRestSearchSchemaEntry({
+        type: "number",
+        actualField,
+        filterOperator: "<="
+      })
+    };
+  }
+
+  return {};
+}
+
+function buildJsonRestPresenceFilterSearchSchemaEntry(filter = {}, { actualField = "" } = {}) {
+  return {
+    type: "string",
+    enum: [CRUD_LIST_FILTER_PRESENCE_PRESENT, CRUD_LIST_FILTER_PRESENCE_MISSING],
+    applyFilter(queryBuilder, value) {
+      applyDefaultFilterQuery(queryBuilder, filter, value, actualField);
+    }
+  };
+}
+
+function buildJsonRestCustomFilterSearchSchemaEntry(filter = {}, customApply = null) {
+  return {
+    type: "none",
+    applyFilter(queryBuilder, value) {
+      customApply(queryBuilder, value, {
+        filter,
+        filters: Object.freeze({
+          [filter.key]: value
+        })
+      });
+    }
+  };
+}
+
+function resolveCrudListFilterEntries(value = {}) {
+  if (isPlainObject(value?.filters)) {
+    return Object.values(normalizeObject(value.filters));
+  }
+
+  return Object.values(defineCrudListFilters(value));
+}
+
+function createCrudListFilterJsonRestSearchSchema(runtime = {}, { columns = {}, apply = {} } = {}) {
+  const filterEntries = resolveCrudListFilterEntries(runtime);
+  const normalizedColumns = normalizeColumnsMap(columns);
+  const schema = {};
+
+  for (const filter of filterEntries) {
+    const customApply = typeof apply?.[filter.key] === "function" ? apply[filter.key] : null;
+    if (customApply) {
+      schema[filter.queryKey] = buildJsonRestCustomFilterSearchSchemaEntry(filter, customApply);
+      continue;
+    }
+
+    const actualField = resolveJsonRestFilterActualField(filter, normalizedColumns);
+    if (!actualField) {
+      continue;
+    }
+
+    const simpleEntry = buildJsonRestSimpleFilterSearchSchemaEntry(filter, { actualField });
+    if (simpleEntry) {
+      schema[filter.queryKey] = simpleEntry;
+      continue;
+    }
+
+    if (filter.type === CRUD_LIST_FILTER_TYPE_PRESENCE) {
+      schema[filter.queryKey] = buildJsonRestPresenceFilterSearchSchemaEntry(filter, { actualField });
+      continue;
+    }
+
+    Object.assign(schema, buildJsonRestRangeFilterSearchSchemaEntries(filter, { actualField }));
+  }
+
+  return Object.freeze(schema);
+}
+
+function addJsonRestDateFilterValues(target = {}, filter = {}, value = "") {
+  const nextDate = addDaysToDateFilterValue(value, 1);
+  if (value) {
+    target[renderInternalJsonRestFilterKey(filter, "from")] = `${value} 00:00:00`;
+  }
+  if (nextDate) {
+    target[renderInternalJsonRestFilterKey(filter, "toExclusive")] = `${nextDate} 00:00:00`;
+  }
+}
+
+function addJsonRestFilterValue(target = {}, filter = {}, value) {
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE) {
+    addJsonRestDateFilterValues(target, filter, value);
+    return;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
+    if (value?.from) {
+      target[renderInternalJsonRestFilterKey(filter, "from")] = `${value.from} 00:00:00`;
+    }
+    if (value?.to) {
+      const nextDate = addDaysToDateFilterValue(value.to, 1);
+      if (nextDate) {
+        target[renderInternalJsonRestFilterKey(filter, "toExclusive")] = `${nextDate} 00:00:00`;
+      }
+    }
+    return;
+  }
+
+  if (filter.type === CRUD_LIST_FILTER_TYPE_NUMBER_RANGE) {
+    if (value?.min != null) {
+      target[renderInternalJsonRestFilterKey(filter, "min")] = value.min;
+    }
+    if (value?.max != null) {
+      target[renderInternalJsonRestFilterKey(filter, "max")] = value.max;
+    }
+    return;
+  }
+
+  target[filter.queryKey] = value;
+}
+
+function normalizeCrudListFilterJsonRestQuery(runtime = {}, query = {}) {
+  const source = normalizeObjectInput(query);
+  const filterEntries = Object.values(normalizeObject(runtime?.filters));
+  const filterQueryKeys = new Set(filterEntries.map((filter) => filter.queryKey));
+  const parsedFilters = typeof runtime.parseQuery === "function"
+    ? runtime.parseQuery(source)
+    : {};
+  const normalized = {};
+
+  for (const [key, value] of Object.entries(source)) {
+    if (!filterQueryKeys.has(key)) {
+      normalized[key] = value;
+    }
+  }
+
+  for (const filter of filterEntries) {
+    if (!Object.hasOwn(parsedFilters, filter.key)) {
+      continue;
+    }
+
+    addJsonRestFilterValue(normalized, filter, parsedFilters[filter.key]);
+  }
+
+  return normalized;
+}
+
 function applyDefaultFilterQuery(queryBuilder, filter = {}, value, column = "") {
   const handler = FILTER_TYPE_SERVER_HANDLERS[filter.type];
   return handler
@@ -529,14 +802,46 @@ function createCrudListFilters(definitions = {}, { columns = {}, apply = {} } =
   return Object.freeze({
     filters: normalizedFilters,
     createQueryValidator,
+    parseQuery: parseFilterPayload,
+    toJsonRestQuery(query = {}) {
+      return normalizeCrudListFilterJsonRestQuery({
+        filters: normalizedFilters,
+        parseQuery: parseFilterPayload
+      }, query);
+    },
+    jsonRestSearchSchema: createCrudListFilterJsonRestSearchSchema({
+      filters: normalizedFilters
+    }, {
+      columns: normalizedColumns,
+      apply
+    }),
     applyQuery
   });
 }
 
+function createCrudListFilterContract(definitions = {}, {
+  columns = {},
+  apply = {},
+  invalidValues = CRUD_LIST_FILTER_INVALID_VALUES_REJECT
+} = {}) {
+  const runtime = createCrudListFilters(definitions, { columns, apply });
+  return Object.freeze({
+    filters: runtime.filters,
+    queryValidator: runtime.createQueryValidator({ invalidValues }),
+    createQueryValidator: runtime.createQueryValidator,
+    parseQuery: runtime.parseQuery,
+    toJsonRestQuery: runtime.toJsonRestQuery,
+    jsonRestSearchSchema: runtime.jsonRestSearchSchema,
+    applyQuery: runtime.applyQuery
+  });
+}
+
 export {
   CRUD_LIST_FILTER_INVALID_VALUES_REJECT,
   CRUD_LIST_FILTER_INVALID_VALUES_DISCARD,
   createCrudListFilterQueryField,
   createCrudListFilterQuerySchema,
-  createCrudListFilters
+  createCrudListFilterJsonRestSearchSchema,
+  createCrudListFilters,
+  createCrudListFilterContract
 };

package/src/server/routeContracts.js

@@ -441,16 +441,19 @@ function createCrudJsonApiRouteContracts({
   resource = {},
   routeParamsValidator = null,
   listSearchQueryValidator = defaultListSearchQueryValidator,
-  lookupIncludeQueryValidator = defaultLookupIncludeQueryValidator
+  lookupIncludeQueryValidator = defaultLookupIncludeQueryValidator,
+  listFilterQueryValidator = null
 } = {}) {
   const listCursorPaginationQueryValidator = createCrudCursorPaginationQueryValidator({
     orderBy: resource?.defaultSort
   });
   const listParentFilterQueryValidator = createCrudParentFilterQueryValidator(resource);
+  const resolvedListFilterQueryValidator = listFilterQueryValidator || resource?.contract?.listFilters?.queryValidator || null;
   const listRouteQueryValidator = composeSchemaDefinitions([
     listCursorPaginationQueryValidator,
     listSearchQueryValidator,
     listParentFilterQueryValidator,
+    ...(resolvedListFilterQueryValidator ? [resolvedListFilterQueryValidator] : []),
     lookupIncludeQueryValidator
   ]);
   const recordRouteParamsValidator = routeParamsValidator

package/test/listFilters.test.js

@@ -13,7 +13,9 @@ import {
   CRUD_LIST_FILTER_INVALID_VALUES_DISCARD,
   createCrudListFilterQueryField,
   createCrudListFilterQuerySchema,
-  createCrudListFilters
+  createCrudListFilterJsonRestSearchSchema,
+  createCrudListFilters,
+  createCrudListFilterContract
 } from "../src/server/listFilters.js";
 
 function composeSchemaDefinition(...definitions) {
@@ -28,6 +30,8 @@ test("crud-core exposes createCrudListFilters through the public package export"
   assert.equal(typeof module.createCrudListFilters, "function");
   assert.equal(typeof module.createCrudListFilterQueryField, "function");
   assert.equal(typeof module.createCrudListFilterQuerySchema, "function");
+  assert.equal(typeof module.createCrudListFilterJsonRestSearchSchema, "function");
+  assert.equal(typeof module.createCrudListFilterContract, "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);
 });
@@ -526,6 +530,154 @@ test("createCrudListFilters treats exact range filter values as exact bounds", (
   });
 });
 
+test("createCrudListFilterContract builds route validators and JSON REST search schema from one definition", () => {
+  const contract = createCrudListFilterContract(
+    {
+      status: {
+        type: "enumMany",
+        label: "Status",
+        options: [
+          { value: "active", label: "Active" },
+          { value: "archived", label: "Archived" }
+        ]
+      },
+      supplierContactId: {
+        type: "recordIdMany",
+        label: "Supplier"
+      },
+      arrivalDate: {
+        type: "dateRange",
+        label: "Arrival Date"
+      },
+      weight: {
+        type: "numberRange",
+        label: "Weight"
+      },
+      locationAssignment: {
+        type: "presence",
+        label: "Storage"
+      }
+    },
+    {
+      columns: {
+        status: "status",
+        supplierContactId: "supplier_contact_id",
+        arrivalDate: "arrival_datetime",
+        weight: "weight_received",
+        locationAssignment: "location_id"
+      },
+      invalidValues: CRUD_LIST_FILTER_INVALID_VALUES_REJECT
+    }
+  );
+
+  assert.deepEqual(contract.queryValidator.schema.patch({
+    status: ["active", "archived"],
+    supplierContactId: ["7", "4"],
+    arrivalDate: "2026-04-01..2026-04-30",
+    weight: "12.5..18",
+    locationAssignment: "missing"
+  }), {
+    validatedObject: {
+      status: ["active", "archived"],
+      supplierContactId: ["7", "4"],
+      arrivalDate: {
+        from: "2026-04-01",
+        to: "2026-04-30"
+      },
+      weight: {
+        min: 12.5,
+        max: 18
+      },
+      locationAssignment: "missing"
+    },
+    errors: {}
+  });
+
+  assert.equal(contract.jsonRestSearchSchema.status.filterOperator, "in");
+  assert.equal(contract.jsonRestSearchSchema.status.actualField, "status");
+  assert.equal(contract.jsonRestSearchSchema.supplierContactId.filterOperator, "in");
+  assert.equal(contract.jsonRestSearchSchema.__jskit_arrivalDate_from.filterOperator, ">=");
+  assert.equal(contract.jsonRestSearchSchema.__jskit_arrivalDate_toExclusive.filterOperator, "<");
+  assert.equal(contract.jsonRestSearchSchema.__jskit_weight_min.filterOperator, ">=");
+  assert.equal(contract.jsonRestSearchSchema.__jskit_weight_max.filterOperator, "<=");
+  assert.equal(typeof contract.jsonRestSearchSchema.locationAssignment.applyFilter, "function");
+
+  assert.deepEqual(contract.toJsonRestQuery({
+    q: "Merc",
+    status: ["active", "archived"],
+    supplierContactId: ["7", "4"],
+    arrivalDate: "2026-04-01..2026-04-30",
+    weight: "12.5..",
+    locationAssignment: "missing"
+  }), {
+    q: "Merc",
+    status: ["active", "archived"],
+    supplierContactId: ["7", "4"],
+    locationAssignment: "missing",
+    __jskit_arrivalDate_from: "2026-04-01 00:00:00",
+    __jskit_arrivalDate_toExclusive: "2026-05-01 00:00:00",
+    __jskit_weight_min: 12.5
+  });
+
+  const { query, calls } = createQueryDouble();
+  contract.jsonRestSearchSchema.locationAssignment.applyFilter(query, "missing");
+  assert.deepEqual(calls, [["whereNull", "location_id"]]);
+});
+
+test("createCrudListFilterContract defaults route validation to reject invalid values", () => {
+  const contract = createCrudListFilterContract({
+    status: {
+      type: "enum",
+      label: "Status",
+      options: [
+        { value: "active", label: "Active" }
+      ]
+    }
+  });
+
+  assert.deepEqual(contract.queryValidator.schema.patch({
+    status: "unexpected"
+  }), {
+    validatedObject: {
+      status: "unexpected"
+    },
+    errors: {
+      status: {
+        field: "status",
+        code: "TYPE_CAST_FAILED",
+        message: "Value could not be cast to the required type.",
+        params: {}
+      }
+    }
+  });
+});
+
+test("createCrudListFilterJsonRestSearchSchema accepts normalized filter definitions directly", () => {
+  const filters = defineCrudListFilters({
+    status: {
+      type: "enum",
+      label: "Status",
+      options: [
+        { value: "active", label: "Active" }
+      ],
+      meta: {
+        jsonRest: {
+          actualField: "status_sid"
+        }
+      }
+    }
+  });
+
+  assert.deepEqual(createCrudListFilterJsonRestSearchSchema(filters), {
+    status: {
+      type: "string",
+      actualField: "status_sid",
+      filterOperator: "=",
+      enum: ["active"]
+    }
+  });
+});
+
 test("createCrudListFilters exposes no default query validator alias", () => {
   const runtime = createCrudListFilters({
     arrivalDate: {

package/test/routeContracts.test.js

@@ -5,6 +5,7 @@ import {
   validateSchemaPayload
 } from "@jskit-ai/kernel/shared/validators";
 import { returnJsonApiData } from "@jskit-ai/http-runtime/shared/validators/jsonApiResult";
+import { createCrudListFilterContract } from "../src/server/listFilters.js";
 import { createCrudJsonApiRouteContracts } from "../src/server/routeContracts.js";
 
 function createSchemaDefinition(structure = {}, mode = "patch") {
@@ -304,6 +305,57 @@ test("createCrudJsonApiRouteContracts builds default CRUD JSON:API contracts", a
   ]);
 });
 
+test("createCrudJsonApiRouteContracts includes configured list filter validators", async () => {
+  const listFilterContract = createCrudListFilterContract({
+    status: {
+      type: "enumMany",
+      label: "Status",
+      options: [
+        { value: "active", label: "Active" },
+        { value: "archived", label: "Archived" }
+      ]
+    }
+  });
+
+  const contracts = createCrudJsonApiRouteContracts({
+    resource: createCrudResource(),
+    listFilterQueryValidator: listFilterContract.queryValidator
+  });
+
+  assert.deepEqual(await validateSchemaPayload(contracts.listRouteContract.query, {
+    status: ["active", "archived"]
+  }, { phase: "input" }), {
+    status: ["active", "archived"]
+  });
+});
+
+test("createCrudJsonApiRouteContracts reads list filter validators from the resource contract", async () => {
+  const listFilterContract = createCrudListFilterContract({
+    status: {
+      type: "enum",
+      label: "Status",
+      options: [
+        { value: "active", label: "Active" },
+        { value: "archived", label: "Archived" }
+      ]
+    }
+  });
+  const resource = {
+    ...createCrudResource(),
+    contract: {
+      listFilters: listFilterContract
+    }
+  };
+
+  const contracts = createCrudJsonApiRouteContracts({ resource });
+
+  assert.deepEqual(await validateSchemaPayload(contracts.listRouteContract.query, {
+    status: "archived"
+  }, { phase: "input" }), {
+    status: "archived"
+  });
+});
+
 test("createCrudJsonApiRouteContracts serializes collection relationships from hydrated lookups", () => {
   const output = createSchemaDefinition({
     id: {