@jskit-ai/kernel 0.1.55 → 0.1.57

package/shared/support/crudListFilters.test.js

@@ -2,6 +2,21 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import {
   defineCrudListFilters,
+  CRUD_LIST_FILTER_INVALID_VALUES_REJECT,
+  CRUD_LIST_FILTER_INVALID_VALUES_DISCARD,
+  INVALID_CRUD_LIST_FILTER_QUERY_VALUE,
+  parseCrudListRangeQueryExpression,
+  formatCrudListRangeQueryExpression,
+  createCrudListFilterInitialValue,
+  isCrudListFilterMultiValue,
+  isCrudListFilterStructuredValue,
+  normalizeCrudListFilterUiValue,
+  areCrudListFilterUiValuesEqual,
+  hasCrudListFilterUiValue,
+  listCrudListFilterChipValues,
+  formatCrudListFilterDefaultChipLabel,
+  formatCrudListFilterQueryValue,
+  parseCrudListFilterQueryValue,
   resolveCrudListFilterQueryKeys,
   resolveCrudListFilterOptionLabel
 } from "./crudListFilters.js";
@@ -52,8 +67,7 @@ test("defineCrudListFilters normalizes common filter shapes", () => {
     key: "arrivalDate",
     type: "dateRange",
     label: "Arrival Date",
-    fromKey: "arrivalDateFrom",
-    toKey: "arrivalDateTo",
+    queryKey: "arrivalDate",
     options: [],
     lookup: null,
     chipLabel: null,
@@ -64,8 +78,7 @@ test("defineCrudListFilters normalizes common filter shapes", () => {
     key: "weight",
     type: "numberRange",
     label: "Weight",
-    minKey: "weightMin",
-    maxKey: "weightMax",
+    queryKey: "weight",
     options: [],
     lookup: null,
     chipLabel: null,
@@ -104,12 +117,37 @@ test("defineCrudListFilters rejects duplicate query keys", () => {
         type: "dateRange",
         label: "Arrival Date"
       },
-      arrivalDateFrom: {
+      arrivalDateExact: {
         type: "date",
-        label: "Arrival Date From"
+        label: "Arrival Date From",
+        queryKey: "arrivalDate"
       }
     }),
-    /both use query key "arrivalDateFrom"/
+    /both use query key "arrivalDate"/
+  );
+});
+
+test("defineCrudListFilters rejects split range keys", () => {
+  assert.throws(
+    () => defineCrudListFilters({
+      arrivalDate: {
+        type: "dateRange",
+        label: "Arrival Date",
+        fromKey: "arrivalDateFrom"
+      }
+    }),
+    /unsupported split range keys/
+  );
+
+  assert.throws(
+    () => defineCrudListFilters({
+      weight: {
+        type: "numberRange",
+        label: "Weight",
+        minKey: "weightMin"
+      }
+    }),
+    /unsupported split range keys/
   );
 });
 
@@ -129,7 +167,139 @@ test("resolveCrudListFilter helpers expose query keys and option labels", () =>
   });
 
   assert.deepEqual(resolveCrudListFilterQueryKeys(filters.status), ["status"]);
-  assert.deepEqual(resolveCrudListFilterQueryKeys(filters.arrivalDate), ["arrivalDateFrom", "arrivalDateTo"]);
+  assert.deepEqual(resolveCrudListFilterQueryKeys(filters.arrivalDate), ["arrivalDate"]);
   assert.equal(resolveCrudListFilterOptionLabel(filters.status, "active"), "Active");
   assert.equal(resolveCrudListFilterOptionLabel(filters.status, "missing", { fallback: "Unknown" }), "Unknown");
 });
+
+test("crud list range helpers parse and format single-key range expressions", () => {
+  assert.deepEqual(parseCrudListRangeQueryExpression("2026-04-01"), {
+    exact: true,
+    start: "2026-04-01",
+    end: "2026-04-01"
+  });
+  assert.deepEqual(parseCrudListRangeQueryExpression("2026-04-01..2026-04-30"), {
+    exact: false,
+    start: "2026-04-01",
+    end: "2026-04-30"
+  });
+  assert.deepEqual(parseCrudListRangeQueryExpression("..2026-04-30"), {
+    exact: false,
+    start: "",
+    end: "2026-04-30"
+  });
+  assert.equal(parseCrudListRangeQueryExpression(".."), null);
+
+  assert.equal(formatCrudListRangeQueryExpression("2026-04-01", ""), "2026-04-01..");
+  assert.equal(
+    formatCrudListRangeQueryExpression("2026-04-01", "2026-04-01", { collapseExact: true }),
+    "2026-04-01"
+  );
+});
+
+test("crud list filter helpers share canonical UI and query normalization", () => {
+  const filters = defineCrudListFilters({
+    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"
+    }
+  });
+
+  assert.deepEqual(createCrudListFilterInitialValue(filters.status), []);
+  assert.equal(isCrudListFilterMultiValue(filters.status), true);
+  assert.equal(isCrudListFilterMultiValue(filters.arrivalDate), false);
+  assert.equal(isCrudListFilterStructuredValue(filters.arrivalDate), true);
+  assert.equal(isCrudListFilterStructuredValue(filters.status), false);
+  assert.deepEqual(
+    normalizeCrudListFilterUiValue(filters.status, ["active", "unexpected"]),
+    ["active"]
+  );
+  assert.deepEqual(
+    parseCrudListFilterQueryValue(filters.status, ["active", "unexpected"], {
+      invalidValues: CRUD_LIST_FILTER_INVALID_VALUES_DISCARD
+    }),
+    ["active"]
+  );
+  assert.equal(
+    parseCrudListFilterQueryValue(filters.status, ["active", "unexpected"], {
+      invalidValues: CRUD_LIST_FILTER_INVALID_VALUES_REJECT
+    }),
+    INVALID_CRUD_LIST_FILTER_QUERY_VALUE
+  );
+
+  assert.deepEqual(
+    normalizeCrudListFilterUiValue(filters.supplierContactId, ["7", "bad", 4]),
+    ["7", "4"]
+  );
+  assert.deepEqual(
+    parseCrudListFilterQueryValue(filters.supplierContactId, ["7", "bad", 4], {
+      invalidValues: CRUD_LIST_FILTER_INVALID_VALUES_DISCARD
+    }),
+    ["7", "4"]
+  );
+  assert.equal(
+    parseCrudListFilterQueryValue(filters.supplierContactId, { bad: true }, {
+      invalidValues: CRUD_LIST_FILTER_INVALID_VALUES_REJECT
+    }),
+    INVALID_CRUD_LIST_FILTER_QUERY_VALUE
+  );
+
+  assert.deepEqual(
+    normalizeCrudListFilterUiValue(filters.arrivalDate, "..2026-04-30"),
+    {
+      from: "",
+      to: "2026-04-30"
+    }
+  );
+  assert.equal(
+    formatCrudListFilterQueryValue(filters.arrivalDate, {
+      from: "2026-04-30",
+      to: "2026-04-30"
+    }),
+    "2026-04-30"
+  );
+  assert.equal(
+    areCrudListFilterUiValuesEqual(
+      filters.arrivalDate,
+      {
+        from: "2026-04-30",
+        to: "2026-04-30"
+      },
+      "2026-04-30"
+    ),
+    true
+  );
+  assert.equal(hasCrudListFilterUiValue(filters.status, ["active", "unexpected"]), true);
+  assert.equal(hasCrudListFilterUiValue(filters.arrivalDate, { from: "", to: "" }), false);
+  assert.deepEqual(listCrudListFilterChipValues(filters.status, ["active", "unexpected"]), ["active"]);
+  assert.deepEqual(
+    listCrudListFilterChipValues(filters.arrivalDate, {
+      from: "2026-04-30",
+      to: "2026-04-30"
+    }),
+    [{
+      from: "2026-04-30",
+      to: "2026-04-30"
+    }]
+  );
+  assert.equal(
+    formatCrudListFilterDefaultChipLabel(filters.status, "active", {
+      resolveAtomicValue(value) {
+        return resolveCrudListFilterOptionLabel(filters.status, value);
+      }
+    }),
+    "Status: Active"
+  );
+});

package/shared/support/crudLookup.js

@@ -1,5 +1,9 @@
 import { normalizeText } from "./normalize.js";
 import { normalizePathname } from "../surface/paths.js";
+import {
+  buildCrudFieldContractMap,
+  resolveCrudFieldSchemaProperties
+} from "./crudFieldContract.js";
 
 const DEFAULT_CRUD_LOOKUP_CONTAINER_KEY = "lookups";
 
@@ -66,7 +70,9 @@ function resolveCrudLookupContainerKey(resource = {}, options = {}) {
 
 function resolveCrudLookupFieldEntries(resource = {}, { allowKeys = [] } = {}) {
   const source = resource && typeof resource === "object" && !Array.isArray(resource) ? resource : {};
-  const entries = Array.isArray(source.fieldMeta) ? source.fieldMeta : [];
+  const entries = Object.values(buildCrudFieldContractMap(source, {
+    context: "crud lookup field entries"
+  }));
   const allowedKeySet = new Set(
     (Array.isArray(allowKeys) ? allowKeys : [])
       .map((entry) => normalizeText(entry))
@@ -109,12 +115,13 @@ function resolveCrudLookupFieldEntries(resource = {}, { allowKeys = [] } = {}) {
 }
 
 function resolveCrudLookupCreateSchemaKeys(resource = {}) {
-  const createSchemaProperties = resource?.operations?.create?.bodyValidator?.schema?.properties;
-  if (!createSchemaProperties || typeof createSchemaProperties !== "object" || Array.isArray(createSchemaProperties)) {
-    return Object.freeze([]);
-  }
-
-  return Object.freeze(Object.keys(createSchemaProperties));
+  return Object.freeze(
+    Object.keys(
+      resolveCrudFieldSchemaProperties(resource?.operations?.create?.body, {
+        context: "crud lookup create schema"
+      })
+    )
+  );
 }
 
 function resolveCrudLookupFieldKeys(resource = {}, { allowKeys = [] } = {}) {

package/shared/support/crudLookup.test.js

@@ -1,5 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { createSchema } from "json-rest-schema";
 import {
   DEFAULT_CRUD_LOOKUP_CONTAINER_KEY,
   normalizeCrudLookupApiPath,
@@ -13,6 +14,34 @@ import {
   resolveCrudParentFilterFieldKeyFromRouteParam
 } from "./crudLookup.js";
 
+function createCrudResource({
+  viewFields = {},
+  createFields = {},
+  patchFields = {},
+  contract = {}
+} = {}) {
+  return {
+    ...(Object.keys(contract).length > 0 ? { contract } : {}),
+    operations: {
+      view: {
+        output: {
+          schema: createSchema(viewFields)
+        }
+      },
+      create: {
+        body: {
+          schema: createSchema(createFields)
+        }
+      },
+      patch: {
+        body: {
+          schema: createSchema(patchFields)
+        }
+      }
+    }
+  };
+}
+
 test("normalizeCrudLookupApiPath normalizes and rejects root", () => {
   assert.equal(normalizeCrudLookupApiPath("vets"), "/vets");
   assert.equal(normalizeCrudLookupApiPath("/vets//"), "/vets");
@@ -57,21 +86,21 @@ test("resolveCrudLookupContainerKey throws for invalid contract shape", () => {
 });
 
 test("resolveCrudLookupFieldKeys returns lookup field keys with optional allow-list", () => {
-  const resource = {
-    fieldMeta: [
-      {
-        key: "contactId",
+  const resource = createCrudResource({
+    viewFields: {
+      contactId: {
+        type: "integer",
         relation: {
           kind: "lookup",
           apiPath: "/contacts",
           valueKey: "id"
         }
       },
-      {
-        key: "status"
+      status: {
+        type: "string"
       },
-      {
-        key: "vetId",
+      vetId: {
+        type: "integer",
         parentRouteParamKey: "primaryVetId",
         relation: {
           kind: "lookup",
@@ -79,18 +108,18 @@ test("resolveCrudLookupFieldKeys returns lookup field keys with optional allow-l
           valueKey: "id"
         }
       }
-    ]
-  };
+    }
+  });
 
   assert.deepEqual(resolveCrudLookupFieldKeys(resource), ["contactId", "vetId"]);
   assert.deepEqual(resolveCrudLookupFieldKeys(resource, { allowKeys: ["vetId", "missing"] }), ["vetId"]);
 });
 
 test("resolveCrudLookupFieldKeyFromRouteParam matches parent route param aliases to canonical lookup field keys", () => {
-  const resource = {
-    fieldMeta: [
-      {
-        key: "staffContactId",
+  const resource = createCrudResource({
+    viewFields: {
+      staffContactId: {
+        type: "integer",
         parentRouteParamKey: "contactId",
         relation: {
           kind: "lookup",
@@ -98,16 +127,16 @@ test("resolveCrudLookupFieldKeyFromRouteParam matches parent route param aliases
           valueKey: "id"
         }
       },
-      {
-        key: "serviceId",
+      serviceId: {
+        type: "integer",
         relation: {
           kind: "lookup",
           apiPath: "/services",
           valueKey: "id"
         }
       }
-    ]
-  };
+    }
+  });
 
   assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "contactId"), "staffContactId");
   assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "staffContactId"), "staffContactId");
@@ -120,10 +149,10 @@ test("resolveCrudLookupFieldKeyFromRouteParam matches parent route param aliases
 });
 
 test("resolveCrudLookupFieldKeyFromRouteParam prefers exact field keys before alias matches", () => {
-  const resource = {
-    fieldMeta: [
-      {
-        key: "staffContactId",
+  const resource = createCrudResource({
+    viewFields: {
+      staffContactId: {
+        type: "integer",
         parentRouteParamKey: "contactId",
         relation: {
           kind: "lookup",
@@ -131,37 +160,25 @@ test("resolveCrudLookupFieldKeyFromRouteParam prefers exact field keys before al
           valueKey: "id"
         }
       },
-      {
-        key: "contactId",
+      contactId: {
+        type: "integer",
         relation: {
           kind: "lookup",
           apiPath: "/contacts",
           valueKey: "id"
         }
       }
-    ]
-  };
+    }
+  });
 
   assert.equal(resolveCrudLookupFieldKeyFromRouteParam(resource, "contactId"), "contactId");
 });
 
 test("resolveCrudParentFilterKeys keeps only lookup keys that are writable through create", () => {
-  const resource = {
-    operations: {
-      create: {
-        bodyValidator: {
-          schema: {
-            type: "object",
-            properties: {
-              serviceId: { type: "integer" }
-            }
-          }
-        }
-      }
-    },
-    fieldMeta: [
-      {
-        key: "staffContactId",
+  const resource = createCrudResource({
+    viewFields: {
+      staffContactId: {
+        type: "integer",
         parentRouteParamKey: "contactId",
         relation: {
           kind: "lookup",
@@ -169,37 +186,35 @@ test("resolveCrudParentFilterKeys keeps only lookup keys that are writable throu
           valueKey: "id"
         }
       },
-      {
-        key: "serviceId",
+      serviceId: {
+        type: "integer",
         relation: {
           kind: "lookup",
           apiPath: "/services",
           valueKey: "id"
         }
       }
-    ]
-  };
+    },
+    createFields: {
+      serviceId: {
+        type: "integer",
+        relation: {
+          kind: "lookup",
+          apiPath: "/services",
+          valueKey: "id"
+        }
+      }
+    }
+  });
 
   assert.deepEqual(resolveCrudParentFilterKeys(resource), ["serviceId"]);
 });
 
 test("resolveCrudParentFilterFieldKeyFromRouteParam uses the same allowed keys as server parent filters", () => {
-  const resource = {
-    operations: {
-      create: {
-        bodyValidator: {
-          schema: {
-            type: "object",
-            properties: {
-              serviceId: { type: "integer" }
-            }
-          }
-        }
-      }
-    },
-    fieldMeta: [
-      {
-        key: "staffContactId",
+  const resource = createCrudResource({
+    viewFields: {
+      staffContactId: {
+        type: "integer",
         parentRouteParamKey: "contactId",
         relation: {
           kind: "lookup",
@@ -207,16 +222,26 @@ test("resolveCrudParentFilterFieldKeyFromRouteParam uses the same allowed keys a
           valueKey: "id"
         }
       },
-      {
-        key: "serviceId",
+      serviceId: {
+        type: "integer",
         relation: {
           kind: "lookup",
           apiPath: "/services",
           valueKey: "id"
         }
       }
-    ]
-  };
+    },
+    createFields: {
+      serviceId: {
+        type: "integer",
+        relation: {
+          kind: "lookup",
+          apiPath: "/services",
+          valueKey: "id"
+        }
+      }
+    }
+  });
 
   assert.equal(resolveCrudParentFilterFieldKeyFromRouteParam(resource, "contactId"), "");
   assert.equal(resolveCrudParentFilterFieldKeyFromRouteParam(resource, "serviceId"), "serviceId");

package/shared/support/normalize.js

@@ -198,6 +198,13 @@ function normalizeRecordId(value, { fallback = null } = {}) {
     return normalizeCanonicalRecordIdText(value, { fallback });
   }
 
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      return fallback;
+    }
+    return normalizeCanonicalRecordIdText(value, { fallback });
+  }
+
   if (typeof value === "bigint") {
     if (value < 1n) {
       return fallback;

package/shared/support/normalize.test.js

@@ -174,11 +174,13 @@ test("normalizeOrNull normalizes non-nullish values and coerces nullish to null"
   );
 });
 
-test("normalizeRecordId accepts canonical string and bigint identifiers only", () => {
+test("normalizeRecordId accepts canonical string, safe integer, and bigint identifiers", () => {
   const unsafeNumericId = Number(9007199254740993n);
   assert.equal(normalizeRecordId("  7  "), "7");
+  assert.equal(normalizeRecordId(7), "7");
   assert.equal(normalizeRecordId(10n), "10");
-  assert.equal(normalizeRecordId(7), null);
+  assert.equal(normalizeRecordId(7.5), null);
+  assert.equal(normalizeRecordId(0), null);
   assert.equal(normalizeRecordId(unsafeNumericId), null);
   assert.equal(normalizeRecordId(""), null);
   assert.equal(normalizeRecordId(null), null);

package/shared/support/shellLayoutTargets.test.js

@@ -88,7 +88,7 @@ test("discoverShellOutletTargetsFromVueSource ignores disabled default markers",
   assert.equal(discovered.defaultTargetId, "");
 });
 
-test("discoverShellOutletTargetsFromVueSource rejects legacy split outlet attributes", () => {
+test("discoverShellOutletTargetsFromVueSource rejects split outlet attributes", () => {
   const source = `
     <template>
       <ShellOutlet target="shell-layout:primary-menu" host="other-host" position="primary-menu" />

package/shared/validators/composeSchemaDefinitions.js

@@ -0,0 +1,53 @@
+import { createSchema } from "json-rest-schema";
+import { normalizeText } from "../support/normalize.js";
+import { deepFreeze } from "../support/deepFreeze.js";
+import { normalizeSingleSchemaDefinition } from "./schemaDefinitions.js";
+
+function composeSchemaDefinitions(definitions, {
+  mode,
+  context = "schema definitions"
+} = {}) {
+  if (!Array.isArray(definitions) || definitions.length < 1) {
+    throw new TypeError(`${context} must be a non-empty array of schema definitions.`);
+  }
+
+  const normalizedDefinitions = definitions.map((definition, index) =>
+    normalizeSingleSchemaDefinition(definition, {
+      context: `${context}[${index}]`
+    })
+  );
+
+  const mergedStructure = {};
+  for (const normalizedDefinition of normalizedDefinitions) {
+    for (const [fieldName, fieldDefinition] of Object.entries(normalizedDefinition.schema.getFieldDefinitions())) {
+      if (Object.prototype.hasOwnProperty.call(mergedStructure, fieldName)) {
+        throw new Error(`${context} cannot compose duplicate field "${fieldName}".`);
+      }
+
+      mergedStructure[fieldName] = fieldDefinition;
+    }
+  }
+
+  let resolvedMode = normalizeText(mode).toLowerCase();
+  if (!resolvedMode) {
+    const uniqueModes = Array.from(new Set(
+      normalizedDefinitions.map((definition) => normalizeText(definition.mode).toLowerCase())
+    )).filter(Boolean);
+    if (uniqueModes.length === 1 && uniqueModes[0] === "patch") {
+      resolvedMode = "patch";
+    } else {
+      throw new TypeError(`${context} requires an explicit mode unless all schema definitions use patch mode.`);
+    }
+  }
+
+  const schemaFactory = createSchema.createFactory(
+    normalizedDefinitions.map((definition) => definition.schema)
+  );
+
+  return deepFreeze({
+    schema: schemaFactory(mergedStructure),
+    mode: resolvedMode
+  });
+}
+
+export { composeSchemaDefinitions };