@jskit-ai/crud 0.1.4

package/src/shared/crud/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/shared/crud/crudResource.js

@@ -0,0 +1,191 @@
+import { Type } from "typebox";
+import {
+  toIsoString,
+  toDatabaseDateTimeUtc
+} from "@jskit-ai/database-runtime/shared";
+import {
+  normalizeObjectInput,
+  createCursorListValidator
+} from "@jskit-ai/kernel/shared/validators";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+function normalizeNumberField(value, { fieldLabel = "Number field" } = {}) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized)) {
+    throw new TypeError(`${fieldLabel} must be a valid number.`);
+  }
+
+  return normalized;
+}
+
+function normalizeDateTimeField(value, { fieldLabel = "Date field" } = {}) {
+  try {
+    return toIsoString(value);
+  } catch {
+    throw new TypeError(`${fieldLabel} must be a valid date/time.`);
+  }
+}
+
+function normalizeDatabaseDateTimeField(value, { fieldLabel = "Date field" } = {}) {
+  try {
+    return toDatabaseDateTimeUtc(value);
+  } catch {
+    throw new TypeError(`${fieldLabel} must be a valid date/time.`);
+  }
+}
+
+function normalizeRecordInput(payload = {}) {
+  const source = normalizeObjectInput(payload);
+  const normalized = {};
+
+  if (Object.hasOwn(source, "textField")) {
+    normalized.textField = normalizeText(source.textField);
+  }
+
+  if (Object.hasOwn(source, "dateField")) {
+    normalized.dateField = normalizeDatabaseDateTimeField(source.dateField, {
+      fieldLabel: "Date field"
+    });
+  }
+
+  if (Object.hasOwn(source, "numberField")) {
+    normalized.numberField = normalizeNumberField(source.numberField, {
+      fieldLabel: "Number field"
+    });
+  }
+
+  return normalized;
+}
+
+function normalizeRecordOutput(payload = {}) {
+  const source = normalizeObjectInput(payload);
+
+  return {
+    id: Number(source.id),
+    textField: normalizeText(source.textField),
+    dateField: normalizeDateTimeField(source.dateField, {
+      fieldLabel: "Date field"
+    }),
+    numberField: normalizeNumberField(source.numberField, {
+      fieldLabel: "Number field"
+    }),
+    createdAt: normalizeDateTimeField(source.createdAt, {
+      fieldLabel: "Created at"
+    }),
+    updatedAt: normalizeDateTimeField(source.updatedAt, {
+      fieldLabel: "Updated at"
+    })
+  };
+}
+
+const recordOutputSchema = Type.Object(
+  {
+    id: Type.Integer({ minimum: 1 }),
+    textField: Type.String({ minLength: 1, maxLength: 160 }),
+    dateField: Type.String({ minLength: 1 }),
+    numberField: Type.Number(),
+    createdAt: Type.String({ minLength: 1 }),
+    updatedAt: Type.String({ minLength: 1 })
+  },
+  { additionalProperties: false }
+);
+
+const recordBodySchema = Type.Object(
+  {
+    textField: Type.String({
+      minLength: 1,
+      maxLength: 160,
+      messages: {
+        required: "Text field is required.",
+        minLength: "Text field is required.",
+        maxLength: "Text field must be at most 160 characters.",
+        default: "Text field is required."
+      }
+    }),
+    dateField: Type.String({
+      minLength: 1,
+      messages: {
+        required: "Date field is required.",
+        minLength: "Date field is required.",
+        default: "Date field is required."
+      }
+    }),
+    numberField: Type.Number({
+      messages: {
+        required: "Number field is required.",
+        default: "Number field must be a valid number."
+      }
+    })
+  },
+  {
+    additionalProperties: false,
+    messages: {
+      additionalProperties: "Unexpected field.",
+      default: "Invalid value."
+    }
+  }
+);
+
+const recordOutputValidator = Object.freeze({
+  schema: recordOutputSchema,
+  normalize: normalizeRecordOutput
+});
+
+const crudResource = {
+  resource: "crud",
+  messages: {
+    validation: "Fix invalid CRUD values and try again.",
+    saveSuccess: "Record saved.",
+    saveError: "Unable to save record.",
+    deleteSuccess: "Record deleted.",
+    deleteError: "Unable to delete record."
+  },
+  operations: {
+    list: {
+      method: "GET",
+      outputValidator: createCursorListValidator(recordOutputValidator)
+    },
+    view: {
+      method: "GET",
+      outputValidator: recordOutputValidator
+    },
+    create: {
+      method: "POST",
+      bodyValidator: {
+        schema: recordBodySchema,
+        normalize: normalizeRecordInput
+      },
+      outputValidator: recordOutputValidator
+    },
+    patch: {
+      method: "PATCH",
+      bodyValidator: {
+        schema: Type.Partial(recordBodySchema, { additionalProperties: false }),
+        normalize: normalizeRecordInput
+      },
+      outputValidator: recordOutputValidator
+    },
+    delete: {
+      method: "DELETE",
+      outputValidator: {
+        schema: Type.Object(
+          {
+            id: Type.Integer({ minimum: 1 }),
+            deleted: Type.Literal(true)
+          },
+          { additionalProperties: false }
+        ),
+        normalize(payload = {}) {
+          const source = normalizeObjectInput(payload);
+
+          return {
+            id: Number(source.id),
+            deleted: true
+          };
+        }
+      }
+    }
+  }
+};
+
+export { crudResource };

package/src/shared/index.js

@@ -0,0 +1,12 @@
+export { crudResource } from "./crud/crudResource.js";
+export {
+  CRUD_REQUESTED_OWNERSHIP_FILTER_AUTO,
+  resolveCrudConfig,
+  resolveCrudSurfacePolicy,
+  resolveCrudSurfacePolicyFromAppConfig,
+  resolveCrudRelativePath,
+  normalizeCrudNamespace,
+  normalizeCrudRequestedOwnershipFilter,
+  normalizeCrudOwnershipFilter,
+  isWorkspaceVisibility
+} from "./crud/crudModuleConfig.js";

package/templates/migrations/crud_initial.cjs

@@ -0,0 +1,42 @@
+// JSKIT_MIGRATION_ID: crud_initial_${option:namespace}
+
+const RAW_NAMESPACE = "${option:namespace}";
+
+function resolveTableName() {
+  const normalizedNamespace = String(RAW_NAMESPACE || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  if (!normalizedNamespace) {
+    throw new Error("crud_initial migration requires option:namespace.");
+  }
+
+  return "crud_" + normalizedNamespace.replace(/-/g, "_");
+}
+
+const TABLE_NAME = resolveTableName();
+
+exports.up = async function up(knex) {
+  const hasCrudTable = await knex.schema.hasTable(TABLE_NAME);
+  if (hasCrudTable) {
+    return;
+  }
+
+  await knex.schema.createTable(TABLE_NAME, (table) => {
+    table.increments("id").unsigned().primary();
+    table.integer("workspace_owner_id").unsigned().nullable().index();
+    table.integer("user_owner_id").unsigned().nullable().index();
+    table.string("text_field", 160).notNullable();
+    table.timestamp("date_field").notNullable();
+    table.double("number_field").notNullable();
+    table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
+    table.timestamp("updated_at").notNullable().defaultTo(knex.fn.now());
+  });
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists(TABLE_NAME);
+};

package/templates/src/elements/CreateElement.vue

@@ -0,0 +1,115 @@
+<template>
+  <section class="crud-create-element d-flex flex-column ga-4">
+    <v-card rounded="lg" elevation="1" border>
+      <v-card-item>
+        <div class="d-flex align-center ga-3 flex-wrap w-100">
+          <div>
+            <v-card-title class="px-0">New ${option:namespace|singular|pascal|default(Record)}</v-card-title>
+            <v-card-subtitle class="px-0">Create a new ${option:namespace|singular|default(record)}.</v-card-subtitle>
+          </div>
+          <v-spacer />
+          <v-btn variant="text" :to="listPath">Cancel</v-btn>
+          <v-btn
+            color="primary"
+            :loading="addEdit.isSaving"
+            :disabled="addEdit.isInitialLoading || addEdit.isRefetching || !addEdit.canSave"
+            @click="addEdit.submit"
+          >
+            Save ${option:namespace|singular|default(record)}
+          </v-btn>
+        </div>
+      </v-card-item>
+      <v-divider />
+      <v-card-text class="pt-4">
+        <v-form v-if="!addEdit.loadError" @submit.prevent="addEdit.submit" novalidate>
+          <v-row>
+            <v-col cols="12" md="6">
+              <v-text-field
+                v-model="recordForm.textField"
+                label="Text field"
+                variant="outlined"
+                density="comfortable"
+                maxlength="160"
+                :readonly="!addEdit.canSave || addEdit.isSaving || addEdit.isRefetching"
+                :error-messages="addEdit.fieldErrors.textField ? [addEdit.fieldErrors.textField] : []"
+              />
+            </v-col>
+            <v-col cols="12" md="6">
+              <v-text-field
+                v-model="recordForm.dateField"
+                label="Date field"
+                type="date"
+                variant="outlined"
+                density="comfortable"
+                :readonly="!addEdit.canSave || addEdit.isSaving || addEdit.isRefetching"
+                :error-messages="addEdit.fieldErrors.dateField ? [addEdit.fieldErrors.dateField] : []"
+              />
+            </v-col>
+            <v-col cols="12" md="6">
+              <v-text-field
+                v-model="recordForm.numberField"
+                label="Number field"
+                type="number"
+                variant="outlined"
+                density="comfortable"
+                :readonly="!addEdit.canSave || addEdit.isSaving || addEdit.isRefetching"
+                :error-messages="addEdit.fieldErrors.numberField ? [addEdit.fieldErrors.numberField] : []"
+              />
+            </v-col>
+          </v-row>
+        </v-form>
+      </v-card-text>
+    </v-card>
+  </section>
+</template>
+
+<script setup>
+import { reactive } from "vue";
+import { validateOperationSection } from "@jskit-ai/http-runtime/shared/validators/operationValidation";
+import { useAddEdit } from "@jskit-ai/users-web/client/composables/useAddEdit";
+import {
+  crudResource,
+  useCrudCreateRuntime,
+  useCrudModulePolicyRuntime
+} from "./clientSupport.js";
+
+const {
+  listPath,
+  apiSuffix,
+  createQueryKey,
+  invalidateAndGoView
+} = useCrudCreateRuntime();
+const { ownershipFilter, surfaceId } = useCrudModulePolicyRuntime();
+const recordForm = reactive({
+  textField: "",
+  dateField: "",
+  numberField: ""
+});
+
+const addEdit = useAddEdit({
+  ownershipFilter,
+  surfaceId,
+  resource: crudResource,
+  apiSuffix,
+  queryKeyFactory: createQueryKey,
+  readEnabled: false,
+  writeMethod: "POST",
+  fallbackSaveError: "Unable to save record.",
+  fieldErrorKeys: ["textField", "dateField", "numberField"],
+  model: recordForm,
+  parseInput: (rawPayload) =>
+    validateOperationSection({
+      operation: crudResource.operations.create,
+      section: "bodyValidator",
+      value: rawPayload
+    }),
+  buildRawPayload: (model) => ({
+    textField: model.textField,
+    dateField: model.dateField,
+    numberField: model.numberField
+  }),
+  onSaveSuccess: async (payload, { queryClient }) => {
+    await invalidateAndGoView(queryClient, payload?.id);
+  }
+});
+</script>