@jskit-ai/crud 0.1.4

package/templates/src/local-package/server/actions.js

@@ -0,0 +1,151 @@
+import {
+  cursorPaginationQueryValidator,
+  recordIdParamsValidator
+} from "@jskit-ai/kernel/shared/validators";
+import { workspaceSlugParamsValidator } from "@jskit-ai/users-core/server/validators/routeParamsValidator";
+import { crudResource } from "../shared/${option:namespace|singular|camel}Resource.js";
+import { actionIds } from "./actionIds.js";
+
+function requireActionSurface(surface = "") {
+  const normalizedSurface = String(surface || "").trim().toLowerCase();
+  if (!normalizedSurface) {
+    throw new TypeError("createActions requires a non-empty surface.");
+  }
+
+  return normalizedSurface;
+}
+
+function createActions({ surface = "" } = {}) {
+  const actionSurface = requireActionSurface(surface);
+
+  return Object.freeze([
+    {
+      id: actionIds.list,
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: {
+        require: "authenticated"
+      },
+      inputValidator: [workspaceSlugParamsValidator, cursorPaginationQueryValidator],
+      outputValidator: crudResource.operations.list.outputValidator,
+      idempotency: "none",
+      audit: {
+        actionName: actionIds.list
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.${option:namespace|camel}Service.listRecords(input, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    },
+    {
+      id: actionIds.view,
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: {
+        require: "authenticated"
+      },
+      inputValidator: [workspaceSlugParamsValidator, recordIdParamsValidator],
+      outputValidator: crudResource.operations.view.outputValidator,
+      idempotency: "none",
+      audit: {
+        actionName: actionIds.view
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.${option:namespace|camel}Service.getRecord(input.recordId, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    },
+    {
+      id: actionIds.create,
+      version: 1,
+      kind: "command",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: {
+        require: "authenticated"
+      },
+      inputValidator: [
+        workspaceSlugParamsValidator,
+        {
+          payload: crudResource.operations.create.bodyValidator
+        }
+      ],
+      outputValidator: crudResource.operations.create.outputValidator,
+      idempotency: "optional",
+      audit: {
+        actionName: actionIds.create
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.${option:namespace|camel}Service.createRecord(input.payload, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    },
+    {
+      id: actionIds.update,
+      version: 1,
+      kind: "command",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: {
+        require: "authenticated"
+      },
+      inputValidator: [
+        workspaceSlugParamsValidator,
+        recordIdParamsValidator,
+        {
+          patch: crudResource.operations.patch.bodyValidator
+        }
+      ],
+      outputValidator: crudResource.operations.patch.outputValidator,
+      idempotency: "optional",
+      audit: {
+        actionName: actionIds.update
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.${option:namespace|camel}Service.updateRecord(input.recordId, input.patch, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    },
+    {
+      id: actionIds.delete,
+      version: 1,
+      kind: "command",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: {
+        require: "authenticated"
+      },
+      inputValidator: [workspaceSlugParamsValidator, recordIdParamsValidator],
+      outputValidator: crudResource.operations.delete.outputValidator,
+      idempotency: "optional",
+      audit: {
+        actionName: actionIds.delete
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.${option:namespace|camel}Service.deleteRecord(input.recordId, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    }
+  ]);
+}
+
+export { createActions };

package/templates/src/local-package/server/diTokens.js

@@ -0,0 +1,4 @@
+const NAMESPACE_${option:namespace|snake|upper}_SERVICE_TOKEN = "crud.${option:namespace|snake}";
+const NAMESPACE_${option:namespace|snake|upper}_REPOSITORY_TOKEN = "repository.${option:namespace|snake}";
+
+export { NAMESPACE_${option:namespace|snake|upper}_SERVICE_TOKEN, NAMESPACE_${option:namespace|snake|upper}_REPOSITORY_TOKEN };

package/templates/src/local-package/server/registerRoutes.js

@@ -0,0 +1,196 @@
+import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import {
+  cursorPaginationQueryValidator,
+  recordIdParamsValidator
+} from "@jskit-ai/kernel/shared/validators";
+import { routeParamsValidator } from "@jskit-ai/users-core/server/validators/routeParamsValidator";
+import { normalizeScopedRouteVisibility } from "@jskit-ai/users-core/shared/support/usersVisibility";
+import { buildWorkspaceInputFromRouteParams } from "@jskit-ai/users-core/server/support/workspaceRouteInput";
+import { resolveApiBasePath } from "@jskit-ai/users-core/shared/support/usersApiPaths";
+import { actionIds } from "./actionIds.js";
+import { crudResource } from "../shared/${option:namespace|singular|camel}Resource.js";
+import { crudModuleConfig } from "../shared/moduleConfig.js";
+
+function registerRoutes(
+  app,
+  {
+    routeOwnershipFilter = "public",
+    routeSurface = "",
+    routeSurfaceRequiresWorkspace = false,
+    routeRelativePath = crudModuleConfig.relativePath
+  } = {}
+) {
+  if (!app || typeof app.make !== "function") {
+    throw new Error("registerRoutes requires application make().");
+  }
+
+  const router = app.make(KERNEL_TOKENS.HttpRouter);
+  const routeVisibility = normalizeScopedRouteVisibility(routeOwnershipFilter, {
+    fallback: "public"
+  });
+  const normalizedRouteSurface = normalizeSurfaceId(routeSurface);
+  const routeBase = resolveApiBasePath({
+    surfaceRequiresWorkspace: routeSurfaceRequiresWorkspace === true,
+    relativePath: routeRelativePath
+  });
+
+  router.register(
+    "GET",
+    routeBase,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "List records."
+      },
+      paramsValidator: routeParamsValidator,
+      queryValidator: cursorPaginationQueryValidator,
+      responseValidators: withStandardErrorResponses({
+        200: crudResource.operations.list.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const listInput = {
+        ...buildWorkspaceInputFromRouteParams(request.input.params)
+      };
+      if (request.input.query.cursor != null) {
+        listInput.cursor = request.input.query.cursor;
+      }
+      if (request.input.query.limit != null) {
+        listInput.limit = request.input.query.limit;
+      }
+      const response = await request.executeAction({
+        actionId: actionIds.list,
+        input: listInput
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "GET",
+    `${routeBase}/:recordId`,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "View a record."
+      },
+      paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      responseValidators: withStandardErrorResponses({
+        200: crudResource.operations.view.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.view,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          recordId: request.input.params.recordId
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "POST",
+    routeBase,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "Create a record."
+      },
+      paramsValidator: routeParamsValidator,
+      bodyValidator: crudResource.operations.create.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          201: crudResource.operations.create.outputValidator
+        },
+        { includeValidation400: true }
+      )
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.create,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          payload: request.input.body
+        }
+      });
+      reply.code(201).send(response);
+    }
+  );
+
+  router.register(
+    "PATCH",
+    `${routeBase}/:recordId`,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "Update a record."
+      },
+      paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      bodyValidator: crudResource.operations.patch.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          200: crudResource.operations.patch.outputValidator
+        },
+        { includeValidation400: true }
+      )
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.update,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          recordId: request.input.params.recordId,
+          patch: request.input.body
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "DELETE",
+    `${routeBase}/:recordId`,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: routeVisibility,
+      meta: {
+        tags: ["crud"],
+        summary: "Delete a record."
+      },
+      paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      responseValidators: withStandardErrorResponses({
+        200: crudResource.operations.delete.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.delete,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          recordId: request.input.params.recordId
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { registerRoutes };

package/templates/src/local-package/server/repository.js

@@ -0,0 +1 @@
+export { createRepository } from "../../../../src/server/repository.js";

package/templates/src/local-package/server/service.js

@@ -0,0 +1,96 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+
+const serviceEvents = Object.freeze({
+  createRecord: Object.freeze([
+    Object.freeze({
+      type: "entity.changed",
+      source: "crud",
+      entity: "record",
+      operation: "created",
+      entityId: ({ result }) => result?.id,
+      realtime: Object.freeze({
+        event: "${option:namespace|snake}.record.changed",
+        audience: "event_scope"
+      })
+    })
+  ]),
+  updateRecord: Object.freeze([
+    Object.freeze({
+      type: "entity.changed",
+      source: "crud",
+      entity: "record",
+      operation: "updated",
+      entityId: ({ result }) => result?.id,
+      realtime: Object.freeze({
+        event: "${option:namespace|snake}.record.changed",
+        audience: "event_scope"
+      })
+    })
+  ]),
+  deleteRecord: Object.freeze([
+    Object.freeze({
+      type: "entity.changed",
+      source: "crud",
+      entity: "record",
+      operation: "deleted",
+      entityId: ({ result }) => result?.id,
+      realtime: Object.freeze({
+        event: "${option:namespace|snake}.record.changed",
+        audience: "event_scope"
+      })
+    })
+  ])
+});
+
+function createService({ ${option:namespace|camel}Repository } = {}) {
+  if (!${option:namespace|camel}Repository) {
+    throw new Error("${option:namespace|camel}Service requires ${option:namespace|camel}Repository.");
+  }
+
+  async function listRecords(query = {}, options = {}) {
+    return ${option:namespace|camel}Repository.list(query, options);
+  }
+
+  async function getRecord(recordId, options = {}) {
+    const record = await ${option:namespace|camel}Repository.findById(recordId, options);
+    if (!record) {
+      throw new AppError(404, "Record not found.");
+    }
+
+    return record;
+  }
+
+  async function createRecord(payload = {}, options = {}) {
+    const record = await ${option:namespace|camel}Repository.create(payload, options);
+    if (!record) {
+      throw new Error("${option:namespace|camel}Service could not load the created record.");
+    }
+    return record;
+  }
+
+  async function updateRecord(recordId, payload = {}, options = {}) {
+    const record = await ${option:namespace|camel}Repository.updateById(recordId, payload, options);
+    if (!record) {
+      throw new AppError(404, "Record not found.");
+    }
+    return record;
+  }
+
+  async function deleteRecord(recordId, options = {}) {
+    const deleted = await ${option:namespace|camel}Repository.deleteById(recordId, options);
+    if (!deleted) {
+      throw new AppError(404, "Record not found.");
+    }
+    return deleted;
+  }
+
+  return Object.freeze({
+    listRecords,
+    getRecord,
+    createRecord,
+    updateRecord,
+    deleteRecord
+  });
+}
+
+export { createService, serviceEvents };

package/templates/src/local-package/shared/crudResource.js

@@ -0,0 +1 @@
+export { crudResource } from "../../../../src/shared/crud/crudResource.js";

package/templates/src/local-package/shared/index.js

@@ -0,0 +1,8 @@
+export { crudResource } from "./${option:namespace|singular|camel}Resource.js";
+export {
+  CRUD_MODULE_OWNERSHIP_FILTER_AUTO,
+  crudModuleConfig,
+  resolveCrudModulePolicy,
+  resolveCrudModulePolicyFromAppConfig,
+  resolveCrudModulePolicyFromPlacementContext
+} from "./moduleConfig.js";

package/templates/src/local-package/shared/moduleConfig.js

@@ -0,0 +1,169 @@
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  USERS_ROUTE_VISIBILITY_LEVELS,
+  normalizeScopedRouteVisibility,
+  isWorkspaceVisibility
+} from "@jskit-ai/users-core/shared/support/usersVisibility";
+
+const CRUD_MODULE_OWNERSHIP_FILTER_AUTO = "auto";
+const CRUD_MODULE_OWNERSHIP_FILTER_SET = new Set([
+  ...USERS_ROUTE_VISIBILITY_LEVELS,
+  CRUD_MODULE_OWNERSHIP_FILTER_AUTO
+]);
+
+const crudModuleConfig = Object.freeze({
+  namespace: "${option:namespace|snake}",
+  surface: "${option:surface|lower}",
+  ownershipFilter: "${option:ownership-filter}",
+  relativePath: "/${option:directory-prefix|pathprefix}${option:namespace|kebab}"
+});
+
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return value;
+}
+
+function normalizeCrudOwnershipFilter(value, { fallback = CRUD_MODULE_OWNERSHIP_FILTER_AUTO } = {}) {
+  const normalized = normalizeText(value).toLowerCase();
+  if (CRUD_MODULE_OWNERSHIP_FILTER_SET.has(normalized)) {
+    return normalized;
+  }
+
+  const normalizedFallback = normalizeText(fallback).toLowerCase();
+  if (CRUD_MODULE_OWNERSHIP_FILTER_SET.has(normalizedFallback)) {
+    return normalizedFallback;
+  }
+
+  return CRUD_MODULE_OWNERSHIP_FILTER_AUTO;
+}
+
+function normalizeCrudRelativePath(value, { context = "resolveCrudModulePolicy" } = {}) {
+  const normalized = normalizeText(value);
+  if (!normalized) {
+    throw new TypeError(`${context} requires a non-empty relativePath.`);
+  }
+
+  const withLeadingSlash = normalized.startsWith("/") ? normalized : `/${normalized}`;
+  const compacted = withLeadingSlash.replace(/\/{2,}/g, "/");
+  return compacted === "/" ? "/" : compacted.replace(/\/+$/, "") || "/";
+}
+
+function normalizeCrudSurfaceDefinitions(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 resolveOwnershipFilterForSurfaceDefinition(definition = {}) {
+  if (definition.requiresWorkspace === true) {
+    return "workspace";
+  }
+  if (definition.requiresAuth === true) {
+    return "user";
+  }
+  return "public";
+}
+
+function resolveCrudModulePolicy({
+  moduleConfig = crudModuleConfig,
+  surfaceDefinitions = {},
+  defaultSurfaceId = "",
+  context = "resolveCrudModulePolicy"
+} = {}) {
+  const config = asRecord(moduleConfig);
+  const normalizedDefinitions = normalizeCrudSurfaceDefinitions(surfaceDefinitions);
+  const requestedSurfaceId = normalizeSurfaceId(config.surface);
+  const fallbackSurfaceId = normalizeSurfaceId(defaultSurfaceId);
+  const selectedSurfaceId = requestedSurfaceId || fallbackSurfaceId;
+  if (!selectedSurfaceId) {
+    throw new Error(
+      `${context} requires crudModuleConfig.surface or an app default surface id.`
+    );
+  }
+
+  const surfaceDefinition = normalizedDefinitions[selectedSurfaceId];
+  if (!surfaceDefinition) {
+    throw new Error(
+      `${context} cannot resolve surface "${selectedSurfaceId}" from surface definitions.`
+    );
+  }
+  if (surfaceDefinition.enabled === false) {
+    throw new Error(`${context} surface "${selectedSurfaceId}" is disabled.`);
+  }
+
+  const requestedOwnershipFilter = normalizeCrudOwnershipFilter(config.ownershipFilter);
+  const resolvedOwnershipFilter =
+    requestedOwnershipFilter === CRUD_MODULE_OWNERSHIP_FILTER_AUTO
+      ? resolveOwnershipFilterForSurfaceDefinition(surfaceDefinition)
+      : normalizeScopedRouteVisibility(requestedOwnershipFilter, {
+          fallback: "public"
+        });
+
+  if (isWorkspaceVisibility(resolvedOwnershipFilter) && surfaceDefinition.requiresWorkspace !== true) {
+    throw new Error(
+      `${context} ownershipFilter "${resolvedOwnershipFilter}" requires a workspace-enabled surface.`
+    );
+  }
+
+  const relativePath = normalizeCrudRelativePath(config.relativePath, {
+    context
+  });
+
+  return Object.freeze({
+    namespace: normalizeText(config.namespace).toLowerCase(),
+    relativePath,
+    surfaceId: selectedSurfaceId,
+    requestedOwnershipFilter,
+    ownershipFilter: resolvedOwnershipFilter,
+    workspaceScoped: isWorkspaceVisibility(resolvedOwnershipFilter),
+    surfaceDefinition
+  });
+}
+
+function resolveCrudModulePolicyFromAppConfig(appConfig = {}, options = {}) {
+  const config = asRecord(appConfig);
+  return resolveCrudModulePolicy({
+    ...asRecord(options),
+    surfaceDefinitions: config.surfaceDefinitions,
+    defaultSurfaceId: config.surfaceDefaultId
+  });
+}
+
+function resolveCrudModulePolicyFromPlacementContext(placementContext = null, options = {}) {
+  const context = asRecord(placementContext);
+  const surfaceConfig = asRecord(context.surfaceConfig);
+  return resolveCrudModulePolicy({
+    ...asRecord(options),
+    surfaceDefinitions: surfaceConfig.surfacesById,
+    defaultSurfaceId: surfaceConfig.defaultSurfaceId
+  });
+}
+
+export {
+  CRUD_MODULE_OWNERSHIP_FILTER_AUTO,
+  crudModuleConfig,
+  resolveCrudModulePolicy,
+  resolveCrudModulePolicyFromAppConfig,
+  resolveCrudModulePolicyFromPlacementContext
+};

package/templates/src/pages/admin/crud/[recordId]/edit.vue

@@ -0,0 +1,7 @@
+<template>
+  <Edit${option:namespace|singular|pascal}Element />
+</template>
+
+<script setup>
+import Edit${option:namespace|singular|pascal}Element from "@local/${option:namespace|kebab}/client/Edit${option:namespace|singular|pascal}Element";
+</script>

package/templates/src/pages/admin/crud/[recordId]/index.vue

@@ -0,0 +1,7 @@
+<template>
+  <View${option:namespace|singular|pascal}Element />
+</template>
+
+<script setup>
+import View${option:namespace|singular|pascal}Element from "@local/${option:namespace|kebab}/client/View${option:namespace|singular|pascal}Element";
+</script>

package/templates/src/pages/admin/crud/index.vue

@@ -0,0 +1,7 @@
+<template>
+  <List${option:namespace|plural|pascal}Element />
+</template>
+
+<script setup>
+import List${option:namespace|plural|pascal}Element from "@local/${option:namespace|kebab}/client/List${option:namespace|plural|pascal}Element";
+</script>

package/templates/src/pages/admin/crud/new.vue

@@ -0,0 +1,7 @@
+<template>
+  <Create${option:namespace|singular|pascal}Element />
+</template>
+
+<script setup>
+import Create${option:namespace|singular|pascal}Element from "@local/${option:namespace|kebab}/client/Create${option:namespace|singular|pascal}Element";
+</script>