@jskit-ai/crud-core 0.1.25 → 0.1.27

package/package.descriptor.mjs

@@ -1,12 +1,14 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-core",
-  version: "0.1.25",
+  version: "0.1.27",
+  kind: "runtime",
   description: "Shared CRUD helpers used by CRUD modules.",
   dependsOn: [
     "@jskit-ai/kernel",
     "@jskit-ai/realtime",
     "@jskit-ai/shell-web",
+    "@jskit-ai/users-core",
     "@jskit-ai/users-web"
   ],
   capabilities: {
@@ -24,7 +26,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/crud-core": "0.1.25"
+        "@jskit-ai/crud-core": "0.1.27"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -10,13 +10,15 @@
     "./client/composables/createCrudClientSupport": "./src/client/composables/createCrudClientSupport.js",
     "./client/composables/crudClientSupportHelpers": "./src/client/composables/crudClientSupportHelpers.js",
     "./client/composables/useCrudRealtimeInvalidation": "./src/client/composables/useCrudRealtimeInvalidation.js",
-    "./server/repositorySupport": "./src/server/repositorySupport.js"
+    "./server/repositorySupport": "./src/server/repositorySupport.js",
+    "./server/crudModuleConfig": "./src/server/crudModuleConfig.js"
   },
   "dependencies": {
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/kernel": "0.1.17",
-    "@jskit-ai/realtime": "0.1.16",
-    "@jskit-ai/shell-web": "0.1.16",
-    "@jskit-ai/users-web": "0.1.27"
+    "@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"
   }
 }

package/src/client/composables/createCrudClientSupport.js

@@ -8,44 +8,123 @@ import {
   invalidateCrudQueries,
   crudListQueryKey,
   crudViewQueryKey,
-  toRouteRecordId
+  toRouteRecordId,
+  normalizeCrudRouteParamName,
+  resolveCrudRecordPathTemplates,
+  resolveCrudRecordPathParams
 } from "./crudClientSupportHelpers.js";
 import { useCrudRealtimeInvalidation } from "./useCrudRealtimeInvalidation.js";
 
+function normalizeText(value = "") {
+  return String(value || "").trim();
+}
+
+function normalizeRouteParams(params = {}) {
+  const source = params && typeof params === "object" && !Array.isArray(params) ? params : {};
+  const normalized = {};
+
+  for (const [rawKey, rawValue] of Object.entries(source)) {
+    const key = normalizeText(rawKey);
+    if (!key) {
+      continue;
+    }
+
+    const value = Array.isArray(rawValue) ? rawValue[0] : rawValue;
+    const normalizedValue = normalizeText(value);
+    if (!normalizedValue) {
+      continue;
+    }
+
+    normalized[key] = normalizedValue;
+  }
+
+  return normalized;
+}
+
+function normalizePathTemplate(value = "") {
+  const normalized = normalizeText(value)
+    .replace(/\\/g, "/")
+    .replace(/\/{2,}/g, "/")
+    .replace(/^\/+|\/+$/g, "");
+
+  return normalized ? `/${normalized}` : "";
+}
+
+function resolvePathTemplate(pathTemplate = "", { routeParams = {}, params = {}, context = "resolvePathTemplate" } = {}) {
+  const normalizedTemplate = normalizePathTemplate(pathTemplate);
+  if (!normalizedTemplate) {
+    return "";
+  }
+
+  const resolvedParams = {
+    ...normalizeRouteParams(routeParams),
+    ...normalizeRouteParams(params)
+  };
+  const missingParams = [];
+  const resolvedPath = normalizedTemplate.replace(/:([A-Za-z][A-Za-z0-9_]*)/g, (_, key) => {
+    const value = normalizeText(resolvedParams[key]);
+    if (!value) {
+      missingParams.push(key);
+      return `:${key}`;
+    }
+
+    return encodeURIComponent(value);
+  });
+
+  if (missingParams.length > 0) {
+    throw new Error(`${context} missing route parameter(s): ${missingParams.join(", ")}.`);
+  }
+
+  return resolvedPath;
+}
+
 function useCrudClientContext(source = {}) {
   const crudConfig = resolveCrudClientConfig(source);
   const paths = usePaths();
   const route = useRoute();
   const workspaceSlugToken = computed(() => paths.workspaceSlug.value);
-  const listPath = computed(() => paths.page(crudConfig.relativePath));
-  const createPath = computed(() => paths.page(`${crudConfig.relativePath}/new`));
+  const defaultRecordIdParam = "recordId";
+  const listPathTemplate = crudConfig.relativePath;
+  const createPathTemplate = `${crudConfig.relativePath}/new`;
+  const defaultRecordPathTemplates = resolveCrudRecordPathTemplates(listPathTemplate, defaultRecordIdParam);
 
-  function listQueryKey(surfaceId = "") {
-    const normalizedSurfaceId = String(surfaceId || paths.currentSurfaceId.value || "").trim();
-    return crudListQueryKey(normalizedSurfaceId, workspaceSlugToken.value, crudConfig.namespace);
+  function resolvePath(pathTemplate = "", params = {}) {
+    const resolvedPath = resolvePathTemplate(pathTemplate, {
+      routeParams: route.params,
+      params,
+      context: "useCrudClientContext.resolvePath"
+    });
+    return resolvedPath ? paths.page(resolvedPath) : "";
   }
 
-  function viewQueryKey(surfaceId = "", recordId = 0) {
-    const normalizedSurfaceId = String(surfaceId || paths.currentSurfaceId.value || "").trim();
-    return crudViewQueryKey(normalizedSurfaceId, workspaceSlugToken.value, recordId, crudConfig.namespace);
+  function resolveApiPath(pathTemplate = "", params = {}) {
+    const resolvedPath = resolvePathTemplate(pathTemplate, {
+      routeParams: route.params,
+      params,
+      context: "useCrudClientContext.resolveApiPath"
+    });
+    return resolvedPath ? paths.api(resolvedPath) : "";
   }
 
-  function resolveViewPath(recordIdLike) {
-    const recordId = toRouteRecordId(recordIdLike);
-    if (!recordId) {
-      return "";
-    }
+  const listPath = computed(() => resolvePath(listPathTemplate));
+  const createPath = computed(() => resolvePath(createPathTemplate));
 
-    return paths.page(`${crudConfig.relativePath}/${recordId}`);
+  function resolveRecordPathTemplates(recordIdParam = defaultRecordIdParam) {
+    return resolveCrudRecordPathTemplates(listPathTemplate, recordIdParam);
   }
 
-  function resolveEditPath(recordIdLike) {
-    const recordId = toRouteRecordId(recordIdLike);
-    if (!recordId) {
-      return "";
-    }
+  function resolveRecordParams(recordIdLike = 0, { recordIdParam = defaultRecordIdParam } = {}) {
+    return resolveCrudRecordPathParams(recordIdLike, recordIdParam);
+  }
+
+  function listQueryKey(surfaceId = "") {
+    const normalizedSurfaceId = String(surfaceId || paths.currentSurfaceId.value || "").trim();
+    return crudListQueryKey(normalizedSurfaceId, workspaceSlugToken.value, crudConfig.namespace);
+  }
 
-    return paths.page(`${crudConfig.relativePath}/${recordId}/edit`);
+  function viewQueryKey(surfaceId = "", recordId = 0) {
+    const normalizedSurfaceId = String(surfaceId || paths.currentSurfaceId.value || "").trim();
+    return crudViewQueryKey(normalizedSurfaceId, workspaceSlugToken.value, recordId, crudConfig.namespace);
   }
 
   function scopeQueryKey() {
@@ -59,36 +138,47 @@ function useCrudClientContext(source = {}) {
   return Object.freeze({
     route,
     crudConfig,
+    listPathTemplate,
+    createPathTemplate,
+    defaultRecordIdParam,
+    viewPathTemplate: defaultRecordPathTemplates.viewPathTemplate,
+    editPathTemplate: defaultRecordPathTemplates.editPathTemplate,
+    resolveRecordPathTemplates,
+    resolveRecordParams,
+    resolvePath,
+    resolveApiPath,
     listPath,
     createPath,
     listQueryKey,
     viewQueryKey,
     scopeQueryKey,
     invalidateQueries,
-    formatDateTime,
-    resolveViewPath,
-    resolveEditPath
+    formatDateTime
   });
 }
 
-function normalizeRecordIdParam(value) {
-  const normalized = String(value || "").trim();
-  if (!normalized) {
-    throw new TypeError("useCrudRecordRuntime requires a non-empty recordIdParam.");
-  }
-
-  return normalized;
-}
-
 function useCrudRecordRuntime(source = {}, { recordIdParam = "recordId" } = {}) {
-  const normalizedRecordIdParam = normalizeRecordIdParam(recordIdParam);
+  const normalizedRecordIdParam = normalizeCrudRouteParamName(recordIdParam, {
+    context: "useCrudRecordRuntime"
+  });
   const crudContext = useCrudClientContext(source);
   useCrudRealtimeInvalidation(crudContext.crudConfig.namespace);
   const router = useRouter();
+  const recordPathTemplates = crudContext.resolveRecordPathTemplates(normalizedRecordIdParam);
   const recordId = computed(() => toRouteRecordId(crudContext.route.params[normalizedRecordIdParam]));
-  const apiSuffix = computed(() => `${crudContext.crudConfig.relativePath}/${recordId.value}`);
-  const viewPath = computed(() => crudContext.resolveViewPath(recordId.value));
-  const editPath = computed(() => crudContext.resolveEditPath(recordId.value));
+  const apiSuffix = computed(() => `${crudContext.crudConfig.apiRelativePath}/${recordId.value}`);
+  const viewPath = computed(() =>
+    crudContext.resolvePath(
+      recordPathTemplates.viewPathTemplate,
+      crudContext.resolveRecordParams(recordId.value, { recordIdParam: normalizedRecordIdParam })
+    )
+  );
+  const editPath = computed(() =>
+    crudContext.resolvePath(
+      recordPathTemplates.editPathTemplate,
+      crudContext.resolveRecordParams(recordId.value, { recordIdParam: normalizedRecordIdParam })
+    )
+  );
   const listPath = crudContext.listPath;
 
   function viewQueryKey(surfaceId = "") {
@@ -105,8 +195,11 @@ function useCrudRecordRuntime(source = {}, { recordIdParam = "recordId" } = {})
   async function invalidateAndGoView(queryClient, recordIdLike = recordId.value) {
     await crudContext.invalidateQueries(queryClient);
 
-    const targetRecordId = toRouteRecordId(recordIdLike);
-    const targetPath = crudContext.resolveViewPath(targetRecordId || recordId.value);
+    const targetRecordId = toRouteRecordId(recordIdLike) || recordId.value;
+    const targetPath = crudContext.resolvePath(
+      recordPathTemplates.viewPathTemplate,
+      crudContext.resolveRecordParams(targetRecordId, { recordIdParam: normalizedRecordIdParam })
+    );
     if (targetPath) {
       await router.push(targetPath);
     }
@@ -129,8 +222,9 @@ function useCrudCreateRuntime(source = {}) {
   const crudContext = useCrudClientContext(source);
   useCrudRealtimeInvalidation(crudContext.crudConfig.namespace);
   const router = useRouter();
+  const recordPathTemplates = crudContext.resolveRecordPathTemplates();
   const listPath = crudContext.listPath;
-  const apiSuffix = crudContext.crudConfig.relativePath;
+  const apiSuffix = crudContext.crudConfig.apiRelativePath;
 
   function createQueryKey(surfaceId = "") {
     return [...crudContext.listQueryKey(surfaceId), "create"];
@@ -139,7 +233,10 @@ function useCrudCreateRuntime(source = {}) {
   async function invalidateAndGoView(queryClient, recordIdLike) {
     await crudContext.invalidateQueries(queryClient);
 
-    const targetPath = crudContext.resolveViewPath(recordIdLike);
+    const targetPath = crudContext.resolvePath(
+      recordPathTemplates.viewPathTemplate,
+      crudContext.resolveRecordParams(recordIdLike)
+    );
     if (targetPath) {
       await router.push(targetPath);
     }
@@ -158,7 +255,7 @@ function useCrudListRuntime(source = {}) {
   const crudContext = useCrudClientContext(source);
   useCrudRealtimeInvalidation(crudContext.crudConfig.namespace);
   const createPath = crudContext.createPath;
-  const apiSuffix = crudContext.crudConfig.relativePath;
+  const apiSuffix = crudContext.crudConfig.apiRelativePath;
 
   function listQueryKey(surfaceId = "") {
     return crudContext.listQueryKey(surfaceId);

package/src/client/composables/crudClientSupportHelpers.js

@@ -3,6 +3,7 @@ import { normalizeRouteVisibilityToken } from "@jskit-ai/kernel/shared/support/v
 import { formatDateTime } from "@jskit-ai/kernel/shared/support";
 
 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);
@@ -40,11 +41,16 @@ function resolveCrudClientConfig(source = {}) {
     Object.hasOwn(payload, "relativePath") ? payload.relativePath : inferredRelativePath,
     { context: "resolveCrudClientConfig" }
   );
+  const apiRelativePath = normalizeRelativePath(
+    Object.hasOwn(payload, "apiRelativePath") ? payload.apiRelativePath : relativePath,
+    { context: "resolveCrudClientConfig" }
+  );
 
   return Object.freeze({
     namespace,
     ownershipFilter,
-    relativePath
+    relativePath,
+    apiRelativePath
   });
 }
 
@@ -97,6 +103,49 @@ function toRouteRecordId(value) {
   return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
 }
 
+function normalizeCrudRouteParamName(value, { context = "normalizeCrudRouteParamName" } = {}) {
+  const normalizedValue = normalizeText(value);
+  if (!normalizedValue) {
+    throw new TypeError(`${context} requires a non-empty route parameter name.`);
+  }
+  if (!ROUTE_PARAM_NAME_PATTERN.test(normalizedValue)) {
+    throw new TypeError(
+      `${context} route parameter "${normalizedValue}" is invalid. Use letters, numbers, and underscores only.`
+    );
+  }
+
+  return normalizedValue;
+}
+
+function resolveCrudRecordPathTemplates(relativePath = "", recordIdParam = "recordId") {
+  const normalizedRelativePath = normalizeRelativePath(relativePath, {
+    context: "resolveCrudRecordPathTemplates"
+  });
+  const normalizedRecordIdParam = normalizeCrudRouteParamName(recordIdParam, {
+    context: "resolveCrudRecordPathTemplates"
+  });
+  const recordSegment = `:${normalizedRecordIdParam}`;
+
+  return Object.freeze({
+    viewPathTemplate: `${normalizedRelativePath}/${recordSegment}`,
+    editPathTemplate: `${normalizedRelativePath}/${recordSegment}/edit`
+  });
+}
+
+function resolveCrudRecordPathParams(recordIdLike = 0, recordIdParam = "recordId") {
+  const normalizedRecordIdParam = normalizeCrudRouteParamName(recordIdParam, {
+    context: "resolveCrudRecordPathParams"
+  });
+  const normalizedRecordId = toRouteRecordId(recordIdLike);
+  if (!normalizedRecordId) {
+    return Object.freeze({});
+  }
+
+  return Object.freeze({
+    [normalizedRecordIdParam]: String(normalizedRecordId)
+  });
+}
+
 export {
   DEFAULT_CRUD_OWNERSHIP_FILTER,
   requireCrudNamespace,
@@ -107,5 +156,8 @@ export {
   invalidateCrudQueries,
   crudListQueryKey,
   crudViewQueryKey,
-  toRouteRecordId
+  toRouteRecordId,
+  normalizeCrudRouteParamName,
+  resolveCrudRecordPathTemplates,
+  resolveCrudRecordPathParams
 };

package/src/server/crudModuleConfig.js

@@ -0,0 +1,310 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import {
+  resolveApiBasePath
+} from "@jskit-ai/users-core/shared/support/usersApiPaths";
+import {
+  USERS_ROUTE_VISIBILITY_LEVELS,
+  normalizeScopedRouteVisibility,
+  isWorkspaceVisibility
+} from "@jskit-ai/users-core/shared/support/usersVisibility";
+
+const DEFAULT_OWNERSHIP_FILTER = "workspace";
+const CRUD_REQUESTED_OWNERSHIP_FILTER_AUTO = "auto";
+const CRUD_REQUESTED_OWNERSHIP_FILTER_SET = new Set([
+  ...USERS_ROUTE_VISIBILITY_LEVELS,
+  CRUD_REQUESTED_OWNERSHIP_FILTER_AUTO
+]);
+const CRUD_MODULE_ID = "crud";
+
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  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 });
+}
+
+function normalizeCrudRequestedOwnershipFilter(value, { fallback = CRUD_REQUESTED_OWNERSHIP_FILTER_AUTO } = {}) {
+  const normalized = normalizeText(value).toLowerCase();
+  if (CRUD_REQUESTED_OWNERSHIP_FILTER_SET.has(normalized)) {
+    return normalized;
+  }
+
+  const normalizedFallback = normalizeText(fallback).toLowerCase();
+  if (CRUD_REQUESTED_OWNERSHIP_FILTER_SET.has(normalizedFallback)) {
+    return normalizedFallback;
+  }
+
+  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"
+  });
+  return `/${normalizedNamespace}`;
+}
+
+function resolveCrudRelativePath(namespace = "") {
+  return resolveCrudNamespacePath(namespace);
+}
+
+function normalizeCrudRelativePath(relativePath = "", { context = "resolveCrudSurfacePolicy" } = {}) {
+  const normalizedPath = normalizeText(relativePath);
+  if (!normalizedPath) {
+    throw new TypeError(`${context} requires a non-empty relativePath.`);
+  }
+
+  const withLeadingSlash = normalizedPath.startsWith("/") ? normalizedPath : `/${normalizedPath}`;
+  const compacted = withLeadingSlash.replace(/\/{2,}/g, "/");
+  return compacted === "/" ? "/" : compacted.replace(/\/+$/, "") || "/";
+}
+
+function resolveCrudApiBasePath({ namespace = "", surfaceRequiresWorkspace = false } = {}) {
+  const relativePath = resolveCrudRelativePath(namespace);
+  return resolveApiBasePath({
+    surfaceRequiresWorkspace: surfaceRequiresWorkspace === true,
+    relativePath
+  });
+}
+
+function resolveCrudTableName(namespace = "") {
+  const normalizedNamespace = requireCrudNamespace(namespace, {
+    context: "resolveCrudTableName"
+  });
+  return `crud_${normalizedNamespace.replace(/-/g, "_")}`;
+}
+
+function resolveCrudTokenPart(namespace = "") {
+  const normalizedNamespace = requireCrudNamespace(namespace, {
+    context: "resolveCrudTokenPart"
+  });
+  return normalizedNamespace.replace(/-/g, "_");
+}
+
+function resolveCrudActionIdPrefix(namespace = "") {
+  const tokenPart = resolveCrudTokenPart(namespace);
+  return `crud.${tokenPart}`;
+}
+
+function resolveCrudContributorId(namespace = "") {
+  const tokenPart = resolveCrudTokenPart(namespace);
+  return `crud.${tokenPart}`;
+}
+
+function resolveCrudDomain(namespace = "") {
+  return "crud";
+}
+
+function resolveCrudToken(namespace = "", suffix = "") {
+  const contributorId = resolveCrudContributorId(namespace);
+  return suffix ? `${contributorId}.${suffix}` : contributorId;
+}
+
+function resolveCrudConfig(source = {}) {
+  const settings = source && typeof source === "object" && !Array.isArray(source) ? source : {};
+  const namespace = requireCrudNamespace(settings.namespace, {
+    context: "resolveCrudConfig"
+  });
+  const ownershipFilter = normalizeCrudOwnershipFilter(settings.ownershipFilter);
+
+  return Object.freeze({
+    namespace,
+    ownershipFilter,
+    workspaceScoped: isWorkspaceVisibility(ownershipFilter),
+    namespacePath: resolveCrudNamespacePath(namespace),
+    relativePath: resolveCrudRelativePath(namespace),
+    apiBasePath: resolveCrudApiBasePath({ namespace }),
+    tableName: resolveCrudTableName(namespace),
+    actionIdPrefix: resolveCrudActionIdPrefix(namespace),
+    contributorId: resolveCrudContributorId(namespace),
+    domain: resolveCrudDomain(namespace),
+    repositoryToken: resolveCrudToken(namespace, "repository"),
+    serviceToken: resolveCrudToken(namespace, "service")
+  });
+}
+
+function normalizeSurfaceDefinitions(sourceDefinitions = {}) {
+  const definitions = asRecord(sourceDefinitions);
+  const normalized = {};
+
+  for (const [key, value] of Object.entries(definitions)) {
+    const definition = asRecord(value);
+    const surfaceId = normalizeSurfaceId(definition.id || key);
+    if (!surfaceId) {
+      continue;
+    }
+
+    normalized[surfaceId] = Object.freeze({
+      ...definition,
+      id: surfaceId,
+      enabled: definition.enabled !== false,
+      requiresAuth: definition.requiresAuth === true,
+      requiresWorkspace: definition.requiresWorkspace === true
+    });
+  }
+
+  return Object.freeze(normalized);
+}
+
+function resolveOwnershipFilterFromSurfaceDefinition(definition = {}) {
+  if (definition.requiresWorkspace === true) {
+    return "workspace";
+  }
+  if (definition.requiresAuth === true) {
+    return "user";
+  }
+  return "public";
+}
+
+function resolveCrudSurfacePolicy(
+  sourceConfig = {},
+  {
+    surfaceDefinitions = {},
+    defaultSurfaceId = "",
+    context = "resolveCrudSurfacePolicy"
+  } = {}
+) {
+  const config = asRecord(sourceConfig);
+  const normalizedDefinitions = normalizeSurfaceDefinitions(surfaceDefinitions);
+  const requestedSurfaceId = normalizeSurfaceId(config.surface);
+  const fallbackSurfaceId = normalizeSurfaceId(defaultSurfaceId);
+  const surfaceId = requestedSurfaceId || fallbackSurfaceId;
+  if (!surfaceId) {
+    throw new Error(`${context} requires surface or defaultSurfaceId.`);
+  }
+
+  const surfaceDefinition = normalizedDefinitions[surfaceId];
+  if (!surfaceDefinition) {
+    throw new Error(`${context} cannot resolve surface "${surfaceId}".`);
+  }
+  if (surfaceDefinition.enabled === false) {
+    throw new Error(`${context} surface "${surfaceId}" is disabled.`);
+  }
+
+  const requestedOwnershipFilter = normalizeCrudRequestedOwnershipFilter(config.ownershipFilter);
+  const ownershipFilter =
+    requestedOwnershipFilter === CRUD_REQUESTED_OWNERSHIP_FILTER_AUTO
+      ? resolveOwnershipFilterFromSurfaceDefinition(surfaceDefinition)
+      : normalizeScopedRouteVisibility(requestedOwnershipFilter, {
+          fallback: "public"
+        });
+
+  if (isWorkspaceVisibility(ownershipFilter) && surfaceDefinition.requiresWorkspace !== true) {
+    throw new Error(
+      `${context} ownershipFilter "${ownershipFilter}" requires a workspace-enabled surface.`
+    );
+  }
+
+  const relativePath = normalizeCrudRelativePath(config.relativePath || resolveCrudRelativePath(config.namespace), {
+    context
+  });
+
+  return Object.freeze({
+    surfaceId,
+    ownershipFilter,
+    requestedOwnershipFilter,
+    workspaceScoped: isWorkspaceVisibility(ownershipFilter),
+    relativePath,
+    surfaceDefinition
+  });
+}
+
+function resolveCrudSurfacePolicyFromAppConfig(sourceConfig = {}, appConfig = {}, options = {}) {
+  const config = asRecord(appConfig);
+  return resolveCrudSurfacePolicy(sourceConfig, {
+    ...asRecord(options),
+    surfaceDefinitions: config.surfaceDefinitions,
+    defaultSurfaceId: config.surfaceDefaultId
+  });
+}
+
+function resolveCrudConfigsFromModules(modulesSource = {}) {
+  const modules = modulesSource && typeof modulesSource === "object" && !Array.isArray(modulesSource)
+    ? modulesSource
+    : {};
+  const configs = [];
+  const seenContributorIds = new Set();
+
+  for (const moduleConfig of Object.values(modules)) {
+    const source = moduleConfig && typeof moduleConfig === "object" && !Array.isArray(moduleConfig)
+      ? moduleConfig
+      : {};
+
+    if (normalizeText(source.module).toLowerCase() !== CRUD_MODULE_ID) {
+      continue;
+    }
+
+    const resolved = resolveCrudConfig(source);
+    if (seenContributorIds.has(resolved.contributorId)) {
+      throw new Error(`Duplicate CRUD namespace in config.modules: "${resolved.namespace}".`);
+    }
+    seenContributorIds.add(resolved.contributorId);
+    configs.push(resolved);
+  }
+
+  return configs;
+}
+
+function resolveCrudConfigFromModules(modulesSource = {}, options = {}) {
+  const configs = resolveCrudConfigsFromModules(modulesSource);
+  const hasNamespace = Object.hasOwn(options, "namespace");
+  if (hasNamespace) {
+    const normalizedNamespace = requireCrudNamespace(options.namespace, {
+      context: "resolveCrudConfigFromModules"
+    });
+    return configs.find((entry) => entry.namespace === normalizedNamespace) || null;
+  }
+
+  if (configs.length === 1) {
+    return configs[0];
+  }
+
+  return null;
+}
+
+export {
+  CRUD_MODULE_ID,
+  DEFAULT_OWNERSHIP_FILTER,
+  CRUD_REQUESTED_OWNERSHIP_FILTER_AUTO,
+  normalizeCrudNamespace,
+  normalizeCrudOwnershipFilter,
+  normalizeCrudRequestedOwnershipFilter,
+  isWorkspaceVisibility,
+  requireCrudNamespace,
+  resolveCrudNamespacePath,
+  resolveCrudRelativePath,
+  normalizeCrudRelativePath,
+  resolveCrudApiBasePath,
+  resolveCrudTableName,
+  resolveCrudActionIdPrefix,
+  resolveCrudContributorId,
+  resolveCrudDomain,
+  resolveCrudConfig,
+  resolveCrudSurfacePolicy,
+  resolveCrudSurfacePolicyFromAppConfig,
+  resolveCrudConfigsFromModules,
+  resolveCrudConfigFromModules
+};

package/src/server/repositorySupport.js

@@ -1,4 +1,6 @@
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators/inputNormalization";
+import { toSnakeCase } from "@jskit-ai/kernel/shared/support/stringCase";
 
 const DEFAULT_LIST_LIMIT = 20;
 const MAX_LIST_LIMIT = 100;
@@ -21,9 +23,103 @@ function requireCrudTableName(tableName, { context = "crudRepository" } = {}) {
   return normalizedTableName;
 }
 
+function resolveColumnName(fieldKey, overrides = {}) {
+  const normalizedKey = String(fieldKey || "").trim();
+  if (!normalizedKey) {
+    return "";
+  }
+
+  const overrideValue = String(overrides?.[normalizedKey] || "").trim();
+  if (overrideValue) {
+    return overrideValue;
+  }
+
+  return toSnakeCase(normalizedKey);
+}
+
+function buildRepositoryColumnMetadata({
+  outputKeys = [],
+  writeKeys = [],
+  columnOverrides = {}
+} = {}) {
+  const normalizedOutputKeys = (Array.isArray(outputKeys) ? outputKeys : [])
+    .map((key) => String(key || "").trim())
+    .filter(Boolean);
+  const normalizedWriteKeys = (Array.isArray(writeKeys) ? writeKeys : [])
+    .map((key) => String(key || "").trim())
+    .filter(Boolean);
+
+  const deriveMapping = (key) => {
+    const column = resolveColumnName(key, columnOverrides);
+    if (!column) {
+      return null;
+    }
+    return { key, column };
+  };
+
+  const outputMappings = normalizedOutputKeys.map(deriveMapping).filter(Boolean);
+  const writeMappings = normalizedWriteKeys.map(deriveMapping).filter(Boolean);
+  const selectColumns = Object.freeze(
+    [...new Set(outputMappings.map((mapping) => mapping.column))]
+  );
+
+  return Object.freeze({
+    selectColumns,
+    outputMappings: Object.freeze(outputMappings),
+    writeMappings: Object.freeze(writeMappings)
+  });
+}
+
+function mapRecordRow(row, fieldKeys = [], overrides = {}) {
+  if (!row) {
+    return null;
+  }
+
+  const mapped = {};
+  for (const key of fieldKeys) {
+    const normalizedKey = String(key || "").trim();
+    const columnName = resolveColumnName(normalizedKey, overrides);
+    if (!normalizedKey || !columnName) {
+      continue;
+    }
+    mapped[normalizedKey] = row[columnName];
+  }
+  return mapped;
+}
+
+function buildWritePayload(sourcePayload = {}, fieldKeys = [], overrides = {}) {
+  const source = normalizeObjectInput(sourcePayload);
+  const payload = {};
+  for (const key of fieldKeys) {
+    const normalizedKey = String(key || "").trim();
+    const columnName = resolveColumnName(normalizedKey, overrides);
+    if (!normalizedKey || !columnName) {
+      continue;
+    }
+    if (!Object.hasOwn(source, normalizedKey)) {
+      continue;
+    }
+    payload[columnName] = source[normalizedKey];
+  }
+  return payload;
+}
+
+function resolveCrudIdColumn(idColumn, { fallback = "id" } = {}) {
+  const normalized = String(idColumn ?? fallback ?? "").trim();
+  if (!normalized) {
+    throw new TypeError("crudRepository requires idColumn.");
+  }
+  return normalized;
+}
+
 export {
   DEFAULT_LIST_LIMIT,
   MAX_LIST_LIMIT,
   normalizeCrudListLimit,
-  requireCrudTableName
+  requireCrudTableName,
+  mapRecordRow,
+  buildWritePayload,
+  resolveColumnName,
+  resolveCrudIdColumn,
+  buildRepositoryColumnMetadata
 };

package/test/createCrudClientSupport.test.js

@@ -7,20 +7,25 @@ import {
   crudListQueryKey,
   crudViewQueryKey,
   toRouteRecordId,
-  resolveCrudRecordChangedEvent
+  resolveCrudRecordChangedEvent,
+  normalizeCrudRouteParamName,
+  resolveCrudRecordPathTemplates,
+  resolveCrudRecordPathParams
 } from "../src/client/composables/crudClientSupportHelpers.js";
 
-test("resolveCrudClientConfig normalizes namespace, ownership filter, and derives relativePath", () => {
+test("resolveCrudClientConfig normalizes namespace, ownership filter, and resolves route/api paths", () => {
   const config = resolveCrudClientConfig({
     namespace: " Customers ",
     ownershipFilter: "workspace",
-    relativePath: "/crm/customers"
+    relativePath: "/ops/customers-ui",
+    apiRelativePath: "/crud/customers"
   });
 
   assert.deepEqual(config, {
     namespace: "customers",
     ownershipFilter: "workspace",
-    relativePath: "/crm/customers"
+    relativePath: "/ops/customers-ui",
+    apiRelativePath: "/crud/customers"
   });
 });
 
@@ -31,6 +36,7 @@ test("resolveCrudClientConfig infers default relativePath from namespace", () =>
   });
 
   assert.equal(config.relativePath, "/appointments");
+  assert.equal(config.apiRelativePath, "/appointments");
 });
 
 test("resolveCrudClientConfig throws when namespace is missing", () => {
@@ -84,6 +90,35 @@ test("toRouteRecordId parses scalar and array params safely", () => {
   assert.equal(toRouteRecordId("not-a-number"), 0);
 });
 
+test("normalizeCrudRouteParamName validates route parameter names", () => {
+  assert.equal(normalizeCrudRouteParamName("recordId"), "recordId");
+  assert.equal(normalizeCrudRouteParamName("addressId"), "addressId");
+  assert.throws(
+    () => normalizeCrudRouteParamName(""),
+    /requires a non-empty route parameter name/
+  );
+  assert.throws(
+    () => normalizeCrudRouteParamName("address-id"),
+    /route parameter "address-id" is invalid/
+  );
+});
+
+test("resolveCrudRecordPathTemplates supports custom route parameter names", () => {
+  assert.deepEqual(
+    resolveCrudRecordPathTemplates("/users/:userId/addresses", "addressId"),
+    {
+      viewPathTemplate: "/users/:userId/addresses/:addressId",
+      editPathTemplate: "/users/:userId/addresses/:addressId/edit"
+    }
+  );
+});
+
+test("resolveCrudRecordPathParams maps record ids to selected route parameter names", () => {
+  assert.deepEqual(resolveCrudRecordPathParams(42, "addressId"), { addressId: "42" });
+  assert.deepEqual(resolveCrudRecordPathParams("7", "recordId"), { recordId: "7" });
+  assert.deepEqual(resolveCrudRecordPathParams("invalid", "addressId"), {});
+});
+
 test("resolveCrudRecordChangedEvent normalizes namespace into event channel", () => {
   assert.equal(resolveCrudRecordChangedEvent("Customers"), "customers.record.changed");
   assert.equal(resolveCrudRecordChangedEvent("customer-orders"), "customer_orders.record.changed");

package/test/repositorySupport.test.js

@@ -3,7 +3,11 @@ import assert from "node:assert/strict";
 import {
   DEFAULT_LIST_LIMIT,
   normalizeCrudListLimit,
-  requireCrudTableName
+  requireCrudTableName,
+  buildWritePayload,
+  mapRecordRow,
+  resolveCrudIdColumn,
+  buildRepositoryColumnMetadata
 } from "../src/server/repositorySupport.js";
 
 test("normalizeCrudListLimit enforces fallback and max", () => {
@@ -22,3 +26,48 @@ test("requireCrudTableName trims and rejects empty values", () => {
     /requires tableName/
   );
 });
+
+test("mapRecordRow remaps rows by key/column pairs", () => {
+  const row = { some_column: 1, other_column: 2 };
+  const mapped = mapRecordRow(row, ["someKey", "otherKey"], {
+    someKey: "some_column",
+    otherKey: "other_column"
+  });
+  assert.deepEqual(mapped, {
+    someKey: 1,
+    otherKey: 2
+  });
+});
+
+test("buildWritePayload respects defined keys", () => {
+  const payload = buildWritePayload(
+    { foo: "bar", missing: true },
+    ["foo", "notPresent"],
+    {
+      foo: "foo_column",
+      notPresent: "not_present_column"
+    }
+  );
+  assert.deepEqual(payload, {
+    foo_column: "bar"
+  });
+});
+
+test("resolveCrudIdColumn falls back and rejects empties", () => {
+  assert.equal(resolveCrudIdColumn("  custom_id  "), "custom_id");
+  assert.equal(resolveCrudIdColumn(undefined, { fallback: "fallback_id" }), "fallback_id");
+  assert.throws(() => resolveCrudIdColumn("", { fallback: "" }), /requires idColumn/);
+});
+
+test("buildRepositoryColumnMetadata normalizes columns and applies overrides", () => {
+  const metadata = buildRepositoryColumnMetadata({
+    outputKeys: ["firstName", "lastName"],
+    writeKeys: ["firstName"],
+    columnOverrides: { lastName: "surname" }
+  });
+
+  assert.deepEqual(metadata.selectColumns, Object.freeze(["first_name", "surname"]));
+  assert.equal(metadata.outputMappings.length, 2);
+  assert.equal(metadata.writeMappings.length, 1);
+  assert.equal(metadata.outputMappings[1].column, "surname");
+});