@jskit-ai/crud-core 0.1.27 → 0.1.29

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-core",
-  version: "0.1.27",
+  version: "0.1.29",
   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.27"
+        "@jskit-ai/crud-core": "0.1.29"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -10,15 +10,25 @@
     "./client/composables/createCrudClientSupport": "./src/client/composables/createCrudClientSupport.js",
     "./client/composables/crudClientSupportHelpers": "./src/client/composables/crudClientSupportHelpers.js",
     "./client/composables/useCrudRealtimeInvalidation": "./src/client/composables/useCrudRealtimeInvalidation.js",
+    "./shared/crudFieldMetaSupport": "./src/shared/crudFieldMetaSupport.js",
+    "./shared/crudNamespaceSupport": "./src/shared/crudNamespaceSupport.js",
     "./server/repositorySupport": "./src/server/repositorySupport.js",
-    "./server/crudModuleConfig": "./src/server/crudModuleConfig.js"
+    "./server/repositoryMethods": "./src/server/repositoryMethods.js",
+    "./server/createCrudRepositoryFromResource": "./src/server/createCrudRepositoryFromResource.js",
+    "./server/lookupProviders": "./src/server/lookupProviders.js",
+    "./server/serviceEvents": "./src/server/serviceEvents.js",
+    "./server/fieldAccess": "./src/server/fieldAccess.js",
+    "./server/createCrudServiceFromResource": "./src/server/createCrudServiceFromResource.js",
+    "./server/crudModuleConfig": "./src/server/crudModuleConfig.js",
+    "./server/listQueryValidators": "./src/server/listQueryValidators.js"
   },
   "dependencies": {
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/kernel": "0.1.19",
-    "@jskit-ai/realtime": "0.1.18",
-    "@jskit-ai/shell-web": "0.1.18",
-    "@jskit-ai/users-core": "0.1.28",
-    "@jskit-ai/users-web": "0.1.33"
+    "@jskit-ai/kernel": "0.1.21",
+    "@jskit-ai/realtime": "0.1.20",
+    "@jskit-ai/shell-web": "0.1.20",
+    "@jskit-ai/users-core": "0.1.30",
+    "@jskit-ai/users-web": "0.1.35",
+    "typebox": "^1.0.81"
   }
 }

package/src/client/composables/crudClientSupportHelpers.js

@@ -1,19 +1,14 @@
-import { normalizeLowerText, normalizeText, normalizeQueryToken } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeText, normalizeQueryToken } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeRouteVisibilityToken } from "@jskit-ai/kernel/shared/support/visibility";
 import { formatDateTime } from "@jskit-ai/kernel/shared/support";
+import {
+  requireCrudNamespace,
+  resolveCrudRecordChangedEvent
+} from "../../shared/crudNamespaceSupport.js";
 
 const DEFAULT_CRUD_OWNERSHIP_FILTER = "workspace";
 const ROUTE_PARAM_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
 
-function requireCrudNamespace(namespace, { context = "resolveCrudClientConfig" } = {}) {
-  const normalizedNamespace = normalizeLowerText(namespace);
-  if (!normalizedNamespace) {
-    throw new TypeError(`${context} requires a non-empty namespace.`);
-  }
-
-  return normalizedNamespace;
-}
-
 function normalizeRelativePath(value, { context = "resolveCrudClientConfig" } = {}) {
   const raw = normalizeText(value);
   if (!raw) {
@@ -77,13 +72,6 @@ function crudScopeQueryKey(namespace = "") {
   return Object.freeze(["crud", normalizeQueryToken(namespace)]);
 }
 
-function resolveCrudRecordChangedEvent(namespace = "") {
-  const normalizedNamespace = requireCrudNamespace(namespace, {
-    context: "resolveCrudRecordChangedEvent"
-  });
-  return `${normalizedNamespace.replace(/-/g, "_")}.record.changed`;
-}
-
 async function invalidateCrudQueries(queryClient, namespace = "") {
   if (!queryClient || typeof queryClient.invalidateQueries !== "function") {
     throw new TypeError("invalidateCrudQueries requires queryClient.invalidateQueries().");

package/src/server/createCrudRepositoryFromResource.js

@@ -0,0 +1,57 @@
+import {
+  createCrudRepositoryRuntime,
+  crudRepositoryList,
+  crudRepositoryFindById,
+  crudRepositoryListByIds,
+  crudRepositoryCreate,
+  crudRepositoryUpdateById,
+  crudRepositoryDeleteById
+} from "./repositoryMethods.js";
+
+function createCrudRepositoryFromResource(resource = {}, { context = "crudRepository", list = {} } = {}) {
+  const runtime = createCrudRepositoryRuntime(resource, {
+    context,
+    list
+  });
+
+  return function createRepository(knex, options = {}) {
+    if (typeof knex !== "function") {
+      throw new TypeError("crudRepository requires knex.");
+    }
+
+    async function listRecords(query = {}, callOptions = {}) {
+      return crudRepositoryList(runtime, knex, query, options, callOptions);
+    }
+
+    async function findById(recordId, callOptions = {}) {
+      return crudRepositoryFindById(runtime, knex, recordId, options, callOptions);
+    }
+
+    async function listByIds(ids = [], callOptions = {}) {
+      return crudRepositoryListByIds(runtime, knex, ids, options, callOptions);
+    }
+
+    async function create(payload = {}, callOptions = {}) {
+      return crudRepositoryCreate(runtime, knex, payload, options, callOptions);
+    }
+
+    async function updateById(recordId, patch = {}, callOptions = {}) {
+      return crudRepositoryUpdateById(runtime, knex, recordId, patch, options, callOptions);
+    }
+
+    async function deleteById(recordId, callOptions = {}) {
+      return crudRepositoryDeleteById(runtime, knex, recordId, options, callOptions);
+    }
+
+    return Object.freeze({
+      list: listRecords,
+      findById,
+      listByIds,
+      create,
+      updateById,
+      deleteById
+    });
+  };
+}
+
+export { createCrudRepositoryFromResource };

package/src/server/createCrudServiceFromResource.js

@@ -0,0 +1,101 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { requireCrudNamespace } from "../shared/crudNamespaceSupport.js";
+import { createCrudFieldAccessRuntime } from "./fieldAccess.js";
+import { createCrudServiceEvents } from "./serviceEvents.js";
+
+function createCrudServiceFromResource(resource = {}, { context = "crudService" } = {}) {
+  const namespace = requireCrudNamespace(resource?.resource, { context: `${context} resource.resource` });
+  const baseServiceEvents = createCrudServiceEvents(resource, { context });
+  const fieldAccessRuntime = createCrudFieldAccessRuntime(resource, { context });
+
+  function createBaseService({ repository, fieldAccess = {} } = {}) {
+    if (!repository) {
+      throw new Error(`${context} requires repository.`);
+    }
+
+    async function listRecords(query = {}, options = {}) {
+      const result = await repository.list(query, options);
+      return fieldAccessRuntime.filterReadableListResult(result, fieldAccess, {
+        action: "list",
+        query,
+        options,
+        context: options?.context
+      });
+    }
+
+    async function getRecord(recordId, options = {}) {
+      const record = await repository.findById(recordId, options);
+      if (!record) {
+        throw new AppError(404, "Record not found.");
+      }
+
+      return fieldAccessRuntime.filterReadableRecord(record, fieldAccess, {
+        action: "view",
+        recordId,
+        options,
+        context: options?.context
+      });
+    }
+
+    async function createRecord(payload = {}, options = {}) {
+      const writablePayload = await fieldAccessRuntime.enforceWritablePayload(payload, fieldAccess, {
+        action: "create",
+        payload,
+        options,
+        context: options?.context
+      });
+      const record = await repository.create(writablePayload, options);
+      if (!record) {
+        throw new Error(`${namespace}Service could not load the created record.`);
+      }
+      return fieldAccessRuntime.filterReadableRecord(record, fieldAccess, {
+        action: "create",
+        options,
+        context: options?.context
+      });
+    }
+
+    async function updateRecord(recordId, payload = {}, options = {}) {
+      const writablePayload = await fieldAccessRuntime.enforceWritablePayload(payload, fieldAccess, {
+        action: "update",
+        recordId,
+        payload,
+        options,
+        context: options?.context
+      });
+      const record = await repository.updateById(recordId, writablePayload, options);
+      if (!record) {
+        throw new AppError(404, "Record not found.");
+      }
+      return fieldAccessRuntime.filterReadableRecord(record, fieldAccess, {
+        action: "update",
+        recordId,
+        options,
+        context: options?.context
+      });
+    }
+
+    async function deleteRecord(recordId, options = {}) {
+      const deleted = await repository.deleteById(recordId, options);
+      if (!deleted) {
+        throw new AppError(404, "Record not found.");
+      }
+      return deleted;
+    }
+
+    return Object.freeze({
+      listRecords,
+      getRecord,
+      createRecord,
+      updateRecord,
+      deleteRecord
+    });
+  }
+
+  return Object.freeze({
+    createBaseService,
+    baseServiceEvents
+  });
+}
+
+export { createCrudServiceFromResource };

package/src/server/crudModuleConfig.js

@@ -1,11 +1,15 @@
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import {
+  normalizeCrudNamespace,
+  requireCrudNamespace
+} from "../shared/crudNamespaceSupport.js";
 import {
   resolveApiBasePath
 } from "@jskit-ai/users-core/shared/support/usersApiPaths";
 import {
   USERS_ROUTE_VISIBILITY_LEVELS,
-  normalizeScopedRouteVisibility,
+  checkRouteVisibility,
   isWorkspaceVisibility
 } from "@jskit-ai/users-core/shared/support/usersVisibility";
 
@@ -25,16 +29,13 @@ function asRecord(value) {
   return value;
 }
 
-function normalizeCrudNamespace(value) {
-  return normalizeText(value)
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-+|-+$/g, "");
-}
-
 function normalizeCrudOwnershipFilter(value, { fallback = DEFAULT_OWNERSHIP_FILTER } = {}) {
-  return normalizeScopedRouteVisibility(value, { fallback });
+  const normalizedValue = normalizeText(value).toLowerCase();
+  const normalizedFallback = normalizeText(fallback).toLowerCase();
+  const resolved = normalizedValue || normalizedFallback;
+  return checkRouteVisibility(resolved, {
+    context: "normalizeCrudOwnershipFilter ownershipFilter"
+  });
 }
 
 function normalizeCrudRequestedOwnershipFilter(value, { fallback = CRUD_REQUESTED_OWNERSHIP_FILTER_AUTO } = {}) {
@@ -51,15 +52,6 @@ function normalizeCrudRequestedOwnershipFilter(value, { fallback = CRUD_REQUESTE
   return CRUD_REQUESTED_OWNERSHIP_FILTER_AUTO;
 }
 
-function requireCrudNamespace(namespace, { context = "CRUD config" } = {}) {
-  const normalizedNamespace = normalizeCrudNamespace(namespace);
-  if (!normalizedNamespace) {
-    throw new TypeError(`${context} requires a non-empty namespace.`);
-  }
-
-  return normalizedNamespace;
-}
-
 function resolveCrudNamespacePath(namespace = "") {
   const normalizedNamespace = requireCrudNamespace(namespace, {
     context: "resolveCrudNamespacePath"
@@ -208,8 +200,8 @@ function resolveCrudSurfacePolicy(
   const ownershipFilter =
     requestedOwnershipFilter === CRUD_REQUESTED_OWNERSHIP_FILTER_AUTO
       ? resolveOwnershipFilterFromSurfaceDefinition(surfaceDefinition)
-      : normalizeScopedRouteVisibility(requestedOwnershipFilter, {
-          fallback: "public"
+      : checkRouteVisibility(requestedOwnershipFilter, {
+          context: `${context} ownershipFilter`
         });
 
   if (isWorkspaceVisibility(ownershipFilter) && surfaceDefinition.requiresWorkspace !== true) {

package/src/server/fieldAccess.js

@@ -0,0 +1,316 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators/inputNormalization";
+
+function isSchemaNullable(schema = {}) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return false;
+  }
+
+  const schemaType = schema.type;
+  if (typeof schemaType === "string" && normalizeText(schemaType).toLowerCase() === "null") {
+    return true;
+  }
+  if (Array.isArray(schemaType)) {
+    const hasNullType = schemaType.some((entry) => normalizeText(entry).toLowerCase() === "null");
+    if (hasNullType) {
+      return true;
+    }
+  }
+
+  const variants = [];
+  if (Array.isArray(schema.anyOf)) {
+    variants.push(...schema.anyOf);
+  }
+  if (Array.isArray(schema.oneOf)) {
+    variants.push(...schema.oneOf);
+  }
+
+  return variants.some((entry) => isSchemaNullable(entry));
+}
+
+function normalizeFieldSet(value, { context = "crudFieldAccess", label = "field list" } = {}) {
+  if (value == null || value === "*") {
+    return null;
+  }
+
+  const rawValues = value instanceof Set
+    ? [...value]
+    : Array.isArray(value)
+      ? value
+      : null;
+  if (!rawValues) {
+    throw new TypeError(`${context} ${label} must be an array, set, or "*".`);
+  }
+
+  const normalizedKeys = rawValues
+    .map((entry) => normalizeText(entry))
+    .filter(Boolean);
+
+  return new Set(normalizedKeys);
+}
+
+async function resolveFieldSet(resolver, input = {}, { context = "crudFieldAccess", label = "field list" } = {}) {
+  const resolvedResolver = resolver;
+  if (resolvedResolver == null) {
+    return null;
+  }
+
+  const resolvedValue = typeof resolvedResolver === "function"
+    ? await resolvedResolver(input)
+    : resolvedResolver;
+
+  return normalizeFieldSet(resolvedValue, { context, label });
+}
+
+function resolveWriteMode(fieldAccess = {}, { context = "crudFieldAccess" } = {}) {
+  const writeMode = normalizeText(fieldAccess?.writeMode || "throw").toLowerCase();
+  if (writeMode === "throw" || writeMode === "strip") {
+    return writeMode;
+  }
+
+  throw new TypeError(`${context} fieldAccess.writeMode must be "throw" or "strip".`);
+}
+
+function buildOutputFieldRules(resource = {}) {
+  const viewOutputSchema = resource?.operations?.view?.outputValidator?.schema;
+  if (!viewOutputSchema || typeof viewOutputSchema !== "object" || Array.isArray(viewOutputSchema)) {
+    return null;
+  }
+
+  const outputProperties = normalizeObject(viewOutputSchema.properties);
+  const requiredFields = new Set(
+    (Array.isArray(viewOutputSchema.required) ? viewOutputSchema.required : [])
+      .map((entry) => normalizeText(entry))
+      .filter(Boolean)
+  );
+  const fieldRules = new Map();
+
+  for (const [fieldKey, fieldSchemaRaw] of Object.entries(outputProperties)) {
+    const normalizedFieldKey = normalizeText(fieldKey);
+    if (!normalizedFieldKey) {
+      continue;
+    }
+
+    const fieldSchema = normalizeObject(fieldSchemaRaw);
+    fieldRules.set(
+      normalizedFieldKey,
+      Object.freeze({
+        required: requiredFields.has(normalizedFieldKey),
+        nullable: isSchemaNullable(fieldSchema),
+        hasDefault: Object.hasOwn(fieldSchema, "default"),
+        defaultValue: fieldSchema.default
+      })
+    );
+  }
+
+  return Object.freeze({
+    fieldRules: new Map(fieldRules)
+  });
+}
+
+function resolveRoleFromFieldAccessInput(input = {}) {
+  const role = normalizeText(input?.context?.auth?.role).toLowerCase();
+  return role || "default";
+}
+
+function resolveActionFromFieldAccessInput(input = {}) {
+  const action = normalizeText(input?.action).toLowerCase();
+  return action || "*";
+}
+
+function resolveOperationPolicyValue(operationPolicy, input = {}, action = "*") {
+  if (typeof operationPolicy === "function") {
+    return operationPolicy(input);
+  }
+  if (
+    operationPolicy == null ||
+    operationPolicy === "*" ||
+    Array.isArray(operationPolicy) ||
+    operationPolicy instanceof Set
+  ) {
+    return operationPolicy;
+  }
+  if (typeof operationPolicy !== "object" || Array.isArray(operationPolicy)) {
+    return null;
+  }
+
+  if (Object.hasOwn(operationPolicy, action)) {
+    return operationPolicy[action];
+  }
+  if (Object.hasOwn(operationPolicy, "*")) {
+    return operationPolicy["*"];
+  }
+  if (Object.hasOwn(operationPolicy, "all")) {
+    return operationPolicy.all;
+  }
+  return null;
+}
+
+function resolveRoleMatrixPolicy(matrix = {}, operation = "readable", input = {}) {
+  const sourceMatrix = normalizeObject(matrix);
+  const role = resolveRoleFromFieldAccessInput(input);
+  const action = resolveActionFromFieldAccessInput(input);
+
+  const rolePolicy = normalizeObject(sourceMatrix[role]);
+  const roleValue = resolveOperationPolicyValue(rolePolicy[operation], input, action);
+  if (roleValue != null) {
+    return roleValue;
+  }
+
+  const defaultPolicy = normalizeObject(sourceMatrix.default);
+  return resolveOperationPolicyValue(defaultPolicy[operation], input, action);
+}
+
+function createFieldAccessForRoleMatrix(matrix = {}, { context = "crudFieldAccess" } = {}) {
+  const sourceMatrix = normalizeObject(matrix);
+  const writeMode = resolveWriteMode(
+    { writeMode: sourceMatrix.writeMode },
+    { context: `${context} createFieldAccessForRoleMatrix` }
+  );
+
+  return Object.freeze({
+    readable(input = {}) {
+      return resolveRoleMatrixPolicy(sourceMatrix, "readable", input);
+    },
+    writable(input = {}) {
+      return resolveRoleMatrixPolicy(sourceMatrix, "writable", input);
+    },
+    writeMode
+  });
+}
+
+function applyReadableFieldPolicyToRecord(record, allowedFields, outputRules = null, { context = "crudFieldAccess" } = {}) {
+  if (!record || typeof record !== "object" || Array.isArray(record) || !allowedFields) {
+    return record;
+  }
+
+  const nextRecord = { ...record };
+  const fieldRules = outputRules?.fieldRules instanceof Map ? outputRules.fieldRules : null;
+
+  for (const fieldKey of Object.keys(nextRecord)) {
+    if (allowedFields.has(fieldKey)) {
+      continue;
+    }
+
+    const fieldRule = fieldRules?.get(fieldKey);
+    if (!fieldRule || fieldRule.required !== true) {
+      delete nextRecord[fieldKey];
+      continue;
+    }
+
+    if (fieldRule.nullable) {
+      nextRecord[fieldKey] = null;
+      continue;
+    }
+
+    if (fieldRule.hasDefault) {
+      nextRecord[fieldKey] = fieldRule.defaultValue;
+      continue;
+    }
+
+    throw new Error(
+      `${context} cannot redact required non-nullable field "${fieldKey}" without schema.default.`
+    );
+  }
+
+  return nextRecord;
+}
+
+function createCrudFieldAccessRuntime(resource = {}, { context = "crudFieldAccess" } = {}) {
+  const outputRules = buildOutputFieldRules(resource);
+
+  async function resolveReadableAllowedFields(fieldAccess = {}, input = {}) {
+    const allowedFields = await resolveFieldSet(
+      fieldAccess?.readable,
+      input,
+      {
+        context,
+        label: "fieldAccess.readable"
+      }
+    );
+    if (!allowedFields) {
+      return null;
+    }
+    if (!outputRules) {
+      throw new TypeError(`${context} requires resource.operations.view.outputValidator.schema for fieldAccess.readable.`);
+    }
+
+    return allowedFields;
+  }
+
+  async function enforceWritablePayload(payload = {}, fieldAccess = {}, input = {}) {
+    const allowedFields = await resolveFieldSet(
+      fieldAccess?.writable,
+      input,
+      {
+        context,
+        label: "fieldAccess.writable"
+      }
+    );
+    if (!allowedFields) {
+      return payload;
+    }
+    const sourcePayload = normalizeObjectInput(payload);
+
+    const writeMode = resolveWriteMode(fieldAccess, { context });
+    const filteredPayload = {};
+    const forbiddenFields = [];
+    for (const [fieldKey, fieldValue] of Object.entries(sourcePayload)) {
+      if (allowedFields.has(fieldKey)) {
+        filteredPayload[fieldKey] = fieldValue;
+      } else {
+        forbiddenFields.push(fieldKey);
+      }
+    }
+
+    if (forbiddenFields.length > 0 && writeMode === "throw") {
+      throw new AppError(403, `Write access denied for fields: ${forbiddenFields.join(", ")}.`);
+    }
+
+    return filteredPayload;
+  }
+
+  async function filterReadableRecord(record = null, fieldAccess = {}, input = {}) {
+    const allowedFields = await resolveReadableAllowedFields(fieldAccess, input);
+    if (!allowedFields) {
+      return record;
+    }
+
+    return applyReadableFieldPolicyToRecord(record, allowedFields, outputRules, {
+      context
+    });
+  }
+
+  async function filterReadableListResult(listResult = {}, fieldAccess = {}, input = {}) {
+    const allowedFields = await resolveReadableAllowedFields(fieldAccess, input);
+    if (!allowedFields) {
+      return listResult;
+    }
+
+    const sourceList = normalizeObject(listResult);
+    const sourceItems = Array.isArray(sourceList.items) ? sourceList.items : [];
+    if (sourceItems.length < 1) {
+      return sourceList;
+    }
+    const filteredItems = sourceItems.map((record) =>
+      applyReadableFieldPolicyToRecord(record, allowedFields, outputRules, {
+        context
+      })
+    );
+
+    return {
+      ...sourceList,
+      items: filteredItems
+    };
+  }
+
+  return Object.freeze({
+    enforceWritablePayload,
+    filterReadableRecord,
+    filterReadableListResult
+  });
+}
+
+export { createCrudFieldAccessRuntime };
+export { createFieldAccessForRoleMatrix };