@jskit-ai/kernel 0.1.135 → 0.1.136

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.135",
+  "version": "0.1.136",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "1.x.x"
@@ -47,6 +47,7 @@
     "./shared/support/crudListFilters": "./shared/support/crudListFilters.js",
     "./shared/support/crudFieldContract": "./shared/support/crudFieldContract.js",
     "./shared/support/crudLookup": "./shared/support/crudLookup.js",
+    "./shared/support/jsonApiFieldsets": "./shared/support/jsonApiFieldsets.js",
     "./shared/support/generatedUiContract": "./shared/support/generatedUiContract.js",
     "./shared/support/deepFreeze": "./shared/support/deepFreeze.js",
     "./shared/support/listenerSet": "./shared/support/listenerSet.js",

package/shared/support/crudListFilters.js

@@ -219,7 +219,7 @@ function normalizeCrudListNumberRangeUiValue(rawValue) {
   };
 }
 
-function createCrudListFilterInitialValue(filter = {}) {
+function createCrudListFilterEmptyValue(filter = {}) {
   if (normalizeCrudListFilterType(filter.type) === CRUD_LIST_FILTER_TYPE_FLAG) {
     return false;
   }
@@ -242,6 +242,14 @@ function createCrudListFilterInitialValue(filter = {}) {
   return "";
 }
 
+function createCrudListFilterInitialValue(filter = {}) {
+  if (!Object.hasOwn(filter, "defaultValue")) {
+    return createCrudListFilterEmptyValue(filter);
+  }
+
+  return normalizeCrudListFilterUiValue(filter, filter.defaultValue);
+}
+
 function isCrudListFilterMultiValue(filter = {}) {
   const type = normalizeCrudListFilterType(filter.type);
   return type === CRUD_LIST_FILTER_TYPE_ENUM_MANY || type === CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY;
@@ -745,6 +753,13 @@ function normalizeCrudListFilterDefinition(rawKey = "", rawDefinition = null) {
   const meta = source.meta && typeof source.meta === "object" && !Array.isArray(source.meta)
     ? deepFreeze({ ...source.meta })
     : null;
+  const hasDefaultValue = Object.hasOwn(source, "defaultValue");
+  const defaultValue = hasDefaultValue
+    ? deepFreeze(normalizeCrudListFilterUiValue({
+        type,
+        options
+      }, source.defaultValue))
+    : undefined;
 
   if (type === CRUD_LIST_FILTER_TYPE_DATE_RANGE) {
     if (normalizeText(source.fromKey) || normalizeText(source.toKey)) {
@@ -767,7 +782,8 @@ function normalizeCrudListFilterDefinition(rawKey = "", rawDefinition = null) {
     lookup,
     chipLabel,
     ui,
-    meta
+    meta,
+    ...(hasDefaultValue ? { defaultValue } : {})
   });
 }
 
@@ -823,6 +839,7 @@ export {
   parseCrudListRangeQueryExpression,
   formatCrudListRangeQueryExpression,
   defineCrudListFilters,
+  createCrudListFilterEmptyValue,
   createCrudListFilterInitialValue,
   isCrudListFilterMultiValue,
   isCrudListFilterStructuredValue,

package/shared/support/crudListFilters.test.js

@@ -7,6 +7,7 @@ import {
   INVALID_CRUD_LIST_FILTER_QUERY_VALUE,
   parseCrudListRangeQueryExpression,
   formatCrudListRangeQueryExpression,
+  createCrudListFilterEmptyValue,
   createCrudListFilterInitialValue,
   isCrudListFilterMultiValue,
   isCrudListFilterStructuredValue,
@@ -110,6 +111,23 @@ test("defineCrudListFilters uses fixed presence semantics with optional label ov
   ]);
 });
 
+test("defineCrudListFilters normalizes declarative defaults without changing the empty state", () => {
+  const filters = defineCrudListFilters({
+    status: {
+      type: "enum",
+      options: [
+        { value: "active", label: "Active" },
+        { value: "archived", label: "Archived" }
+      ],
+      defaultValue: "active"
+    }
+  });
+
+  assert.equal(filters.status.defaultValue, "active");
+  assert.equal(createCrudListFilterInitialValue(filters.status), "active");
+  assert.equal(createCrudListFilterEmptyValue(filters.status), "");
+});
+
 test("defineCrudListFilters rejects duplicate query keys", () => {
   assert.throws(
     () => defineCrudListFilters({

package/shared/support/jsonApiFieldsets.js

@@ -0,0 +1,56 @@
+import { deepFreeze } from "./deepFreeze.js";
+import { normalizeText } from "./normalize.js";
+
+function normalizeJsonApiFieldList(value = []) {
+  const values = Array.isArray(value) ? value : [value];
+  const fields = new Set();
+
+  for (const entry of values) {
+    const parts = typeof entry === "string" ? entry.split(",") : [entry];
+    for (const part of parts) {
+      const field = normalizeText(part);
+      if (field) {
+        fields.add(field);
+      }
+    }
+  }
+
+  return Object.freeze([...fields].sort((left, right) => left.localeCompare(right)));
+}
+
+function normalizeJsonApiFieldsets(value = {}, { primaryType = "" } = {}) {
+  const normalizedPrimaryType = normalizeText(primaryType);
+  let source = {};
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    source = value;
+  } else if (normalizedPrimaryType) {
+    source = { [normalizedPrimaryType]: value };
+  }
+  const fieldsets = [];
+
+  for (const [rawType, rawFields] of Object.entries(source)) {
+    const type = normalizeText(rawType);
+    const fields = normalizeJsonApiFieldList(rawFields);
+    if (!type || fields.length < 1) {
+      continue;
+    }
+    fieldsets.push([type, fields]);
+  }
+
+  return deepFreeze(
+    Object.fromEntries(
+      fieldsets.sort(([left], [right]) => left.localeCompare(right))
+    )
+  );
+}
+
+function buildJsonApiFieldsetsToken(value = {}) {
+  const fieldsets = normalizeJsonApiFieldsets(value);
+  return Object.keys(fieldsets).length > 0 ? JSON.stringify(fieldsets) : "";
+}
+
+export {
+  normalizeJsonApiFieldList,
+  normalizeJsonApiFieldsets,
+  buildJsonApiFieldsetsToken
+};

package/shared/support/jsonApiFieldsets.test.js

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  normalizeJsonApiFieldList,
+  normalizeJsonApiFieldsets,
+  buildJsonApiFieldsetsToken
+} from "./jsonApiFieldsets.js";
+
+test("JSON:API fieldsets normalize comma lists into a stable typed map", () => {
+  assert.deepEqual(
+    normalizeJsonApiFieldsets({
+      jobs: ["status", "id,status"],
+      contacts: "displayName,id"
+    }),
+    {
+      contacts: ["displayName", "id"],
+      jobs: ["id", "status"]
+    }
+  );
+  assert.deepEqual(normalizeJsonApiFieldList(["name", "", "id,name"]), ["id", "name"]);
+});
+
+test("JSON:API fieldsets produce deterministic query tokens", () => {
+  const fieldsets = {
+    jobs: ["status", "id"],
+    contacts: ["id"]
+  };
+
+  assert.equal(
+    buildJsonApiFieldsetsToken(fieldsets),
+    buildJsonApiFieldsetsToken({
+      contacts: ["id"],
+      jobs: ["id", "status"]
+    })
+  );
+  assert.equal(buildJsonApiFieldsetsToken({}), "");
+});
+
+test("JSON:API fieldset resource types cannot mutate object prototypes", () => {
+  const fieldsets = normalizeJsonApiFieldsets(
+    Object.fromEntries([
+      ["__proto__", ["id", "name"]]
+    ])
+  );
+
+  assert.equal(Object.getPrototypeOf(fieldsets), Object.prototype);
+  assert.equal(Object.hasOwn(fieldsets, "__proto__"), true);
+  assert.deepEqual(fieldsets.__proto__, ["id", "name"]);
+});