@jskit-ai/json-rest-api-core 0.1.78 → 0.1.80

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/json-rest-api-core",
-  version: "0.1.78",
+  version: "0.1.80",
   kind: "runtime",
   description: "Shared internal json-rest-api host runtime with autofilter, query-projection, and row-policy support.",
   dependsOn: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/json-rest-api-core",
-  "version": "0.1.78",
+  "version": "0.1.80",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -11,6 +11,6 @@
   "dependencies": {
     "hooked-api": "1.x.x",
     "json-rest-api": "^1.0.26",
-    "@jskit-ai/kernel": "0.1.134"
+    "@jskit-ai/kernel": "0.1.136"
   }
 }

package/src/server/jsonRestApiHost.js

@@ -6,8 +6,16 @@ import {
   RestApiPlugin,
   RowPolicyPlugin
 } from "json-rest-api";
-import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  normalizeRecordId,
+  normalizeUniqueTextList
+} from "@jskit-ai/kernel/shared/support/normalize";
 import { resolveCrudResourceScopeName } from "@jskit-ai/kernel/shared/support/crudLookup";
+import {
+  normalizeJsonApiFieldList,
+  normalizeJsonApiFieldsets
+} from "@jskit-ai/kernel/shared/support/jsonApiFieldsets";
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 
 const INTERNAL_JSON_REST_API = "internal.json-rest-api";
 
@@ -321,6 +329,51 @@ function applyJsonRestQueryFields(scopeOptions = {}, extraQueryFields = {}) {
   }
 }
 
+function resolveJsonRestDefaultExcludedFields(resource = {}) {
+  const defaultExclude = resource?.contract?.response?.defaultExclude;
+  if (defaultExclude == null) {
+    return [];
+  }
+  if (!Array.isArray(defaultExclude)) {
+    throw new TypeError("json-rest-api resource contract.response.defaultExclude must be an array.");
+  }
+
+  return normalizeUniqueTextList(defaultExclude);
+}
+
+function applyJsonRestDefaultExclusions(scopeOptions = {}, resource = {}) {
+  const excludedFields = resolveJsonRestDefaultExcludedFields(resource);
+  if (excludedFields.length < 1) {
+    return;
+  }
+
+  const schema = normalizeJsonRestObject(scopeOptions.schema);
+  const queryFields = normalizeJsonRestObject(scopeOptions.queryFields);
+  const idProperty = normalizeJsonRestText(scopeOptions.idProperty, {
+    fallback: "id"
+  });
+
+  for (const field of excludedFields) {
+    if (field === "id" || field === idProperty) {
+      throw new TypeError(
+        `json-rest-api resource contract.response.defaultExclude cannot exclude identifier field "${field}".`
+      );
+    }
+
+    const definitions = Object.hasOwn(schema, field) ? schema : queryFields;
+    if (!Object.hasOwn(definitions, field)) {
+      throw new TypeError(
+        `json-rest-api resource contract.response.defaultExclude references unknown field "${field}".`
+      );
+    }
+
+    definitions[field] = {
+      ...normalizeJsonRestObject(definitions[field]),
+      normallyHidden: true
+    };
+  }
+}
+
 function buildJsonRestQueryParams(resourceType = "", query = {}, { include = undefined } = {}) {
   const normalizedResourceType = normalizeJsonRestText(resourceType);
   const source = normalizeJsonRestObject(query);
@@ -365,11 +418,27 @@ function buildJsonRestQueryParams(resourceType = "", query = {}, { include = und
     };
   }
 
-  const fields = normalizeJsonRestText(source.fields);
-  if (normalizedResourceType && fields) {
-    queryParams.fields = {
-      [normalizedResourceType]: fields
-    };
+  const fieldsets = normalizeJsonApiFieldsets(source.fields, {
+    primaryType: normalizedResourceType
+  });
+  if (Object.keys(fieldsets).length > 0) {
+    const jsonRestFieldsets = new Map();
+    for (const [type, fields] of Object.entries(fieldsets)) {
+      const scopeName = resolveCrudResourceScopeName(type);
+      if (!scopeName) {
+        continue;
+      }
+      jsonRestFieldsets.set(scopeName, [
+        ...(jsonRestFieldsets.get(scopeName) || []),
+        ...fields
+      ]);
+    }
+    queryParams.fields = Object.fromEntries(
+      [...jsonRestFieldsets.entries()].map(([scopeName, fields]) => [
+        scopeName,
+        normalizeJsonApiFieldList(fields).join(",")
+      ])
+    );
   }
 
   return queryParams;
@@ -485,6 +554,7 @@ function createJsonRestResourceScopeOptions(
     };
   }
   applyJsonRestQueryFields(scopeOptions, queryFields);
+  applyJsonRestDefaultExclusions(scopeOptions, resource);
   const collectionRelationships = resolveJsonRestCollectionRelationships(scopeOptions);
   if (Object.keys(collectionRelationships).length > 0) {
     if (
@@ -576,6 +646,30 @@ async function returnNullWhenJsonRestResourceMissing(run) {
   }
 }
 
+function isJsonRestSparseFieldError(error = null) {
+  return /^Unknown sparse field '.+' requested for '.+'$/u.test(
+    normalizeJsonRestText(error?.message)
+  );
+}
+
+async function returnBadRequestWhenJsonRestFieldsetInvalid(run) {
+  if (typeof run !== "function") {
+    throw new TypeError("returnBadRequestWhenJsonRestFieldsetInvalid requires run function.");
+  }
+
+  try {
+    return await run();
+  } catch (error) {
+    if (!isJsonRestSparseFieldError(error)) {
+      throw error;
+    }
+
+    throw new AppError(400, error.message, {
+      code: "JSON_API_FIELDSET_INVALID"
+    });
+  }
+}
+
 async function createJsonRestApiHost({ knex }) {
   if (typeof knex !== "function") {
     throw new TypeError("createJsonRestApiHost requires knex.");
@@ -640,6 +734,7 @@ export {
   extractJsonRestCollectionRows,
   isJsonRestResourceMissingError,
   returnNullWhenJsonRestResourceMissing,
+  returnBadRequestWhenJsonRestFieldsetInvalid,
   resolveWorkspaceScopeValue,
   resolveUserScopeValue,
   createJsonRestApiHost,

package/test/entrypoints.boundary.test.js

@@ -16,6 +16,7 @@ import {
   isJsonRestResourceMissingError,
   registerJsonRestApiHost,
   returnNullWhenJsonRestResourceMissing,
+  returnBadRequestWhenJsonRestFieldsetInvalid,
   resolveWorkspaceScopeValue,
   resolveUserScopeValue
 } from "../src/server/jsonRestApiHost.js";
@@ -47,6 +48,7 @@ test("server entrypoint exports shared host helpers", () => {
   assert.equal(typeof isJsonRestResourceMissingError, "function");
   assert.equal(typeof registerJsonRestApiHost, "function");
   assert.equal(typeof returnNullWhenJsonRestResourceMissing, "function");
+  assert.equal(typeof returnBadRequestWhenJsonRestFieldsetInvalid, "function");
   assert.equal(typeof resolveWorkspaceScopeValue, "function");
   assert.equal(typeof resolveUserScopeValue, "function");
   assert.equal(typeof JsonRestApiCoreServiceProvider, "function");
@@ -206,7 +208,11 @@ test("shared query/document helpers build json-rest-api request shapes", () => {
       limit: 10,
       include: "workspace,user",
       sort: ["-createdAt", "name"],
-      fields: "name,dob"
+      fields: {
+        contacts: ["name", "dob"],
+        workspaces: ["slug", "id"],
+        "contact-notes": ["body", "id"]
+      }
     }),
     {
       filters: {
@@ -219,7 +225,9 @@ test("shared query/document helpers build json-rest-api request shapes", () => {
         size: "10"
       },
       fields: {
-        contacts: "name,dob"
+        contactNotes: "body,id",
+        contacts: "dob,name",
+        workspaces: "id,slug"
       }
     }
   );
@@ -480,6 +488,84 @@ test("createJsonRestResourceScopeOptions maps server query projections into json
   assert.equal(resource.schema.remainingProcessableWeight.storage.virtual, true);
 });
 
+test("createJsonRestResourceScopeOptions applies resource-owned default response exclusions", () => {
+  const source = Object.freeze({
+    namespace: "contacts",
+    tableName: "contacts",
+    contract: Object.freeze({
+      response: Object.freeze({
+        defaultExclude: Object.freeze([
+          "privateNotes",
+          "searchRank"
+        ])
+      })
+    }),
+    schema: Object.freeze({
+      id: Object.freeze({
+        type: "id",
+        primary: true
+      }),
+      name: Object.freeze({
+        type: "string"
+      }),
+      privateNotes: Object.freeze({
+        type: "string"
+      }),
+      searchRank: Object.freeze({
+        type: "number",
+        storage: Object.freeze({
+          virtual: true,
+          queryProjection: Object.freeze({
+            select() {}
+          })
+        })
+      })
+    })
+  });
+
+  const result = createJsonRestResourceScopeOptions(source);
+
+  assert.equal(result.schema.name.normallyHidden, undefined);
+  assert.equal(result.schema.privateNotes.normallyHidden, true);
+  assert.equal(result.queryFields.searchRank.normallyHidden, true);
+  assert.equal(source.schema.privateNotes.normallyHidden, undefined);
+  assert.equal(source.schema.searchRank.normallyHidden, undefined);
+});
+
+test("createJsonRestResourceScopeOptions rejects invalid default response exclusions", () => {
+  const createResource = (defaultExclude) => ({
+    namespace: "contacts",
+    tableName: "contacts",
+    contract: {
+      response: {
+        defaultExclude
+      }
+    },
+    schema: {
+      id: {
+        type: "id",
+        primary: true
+      },
+      name: {
+        type: "string"
+      }
+    }
+  });
+
+  assert.throws(
+    () => createJsonRestResourceScopeOptions(createResource("name")),
+    /contract\.response\.defaultExclude must be an array/
+  );
+  assert.throws(
+    () => createJsonRestResourceScopeOptions(createResource(["unknown"])),
+    /defaultExclude references unknown field "unknown"/
+  );
+  assert.throws(
+    () => createJsonRestResourceScopeOptions(createResource(["id"])),
+    /defaultExclude cannot exclude identifier field "id"/
+  );
+});
+
 test("createJsonRestResourceScopeOptions rejects query field names for column-backed schema fields", () => {
   assert.throws(
     () => createJsonRestResourceScopeOptions({
@@ -563,6 +649,30 @@ test("returnNullWhenJsonRestResourceMissing only swallows missing-resource error
   );
 });
 
+test("invalid sparse fields become a stable 400 without swallowing unrelated failures", async () => {
+  const sparseFieldError = new Error("Unknown sparse field 'passwordHash' requested for 'contacts'");
+
+  await assert.rejects(
+    () => returnBadRequestWhenJsonRestFieldsetInvalid(async () => {
+      throw sparseFieldError;
+    }),
+    (error) => {
+      assert.equal(error.status, 400);
+      assert.equal(error.code, "JSON_API_FIELDSET_INVALID");
+      assert.equal(error.message, sparseFieldError.message);
+      return true;
+    }
+  );
+
+  const unrelatedError = new Error("database unavailable");
+  await assert.rejects(
+    () => returnBadRequestWhenJsonRestFieldsetInvalid(async () => {
+      throw unrelatedError;
+    }),
+    (error) => error === unrelatedError
+  );
+});
+
 test("scope resolvers understand explicit scopeValues and JSKIT visibilityContext", () => {
   assert.equal(resolveWorkspaceScopeValue({
     scopeValues: {