@jskit-ai/crud-core 0.1.4

package/package.descriptor.mjs

@@ -0,0 +1,37 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/crud-core",
+  version: "0.1.4",
+  description: "Shared CRUD helpers used by CRUD modules.",
+  dependsOn: [
+    "@jskit-ai/kernel",
+    "@jskit-ai/realtime",
+    "@jskit-ai/shell-web",
+    "@jskit-ai/users-web"
+  ],
+  capabilities: {
+    provides: ["crud.core"],
+    requires: []
+  },
+  runtime: {
+    server: {
+      providers: []
+    },
+    client: {
+      providers: []
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/crud-core": "0.1.4"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: []
+  }
+});

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@jskit-ai/crud-core",
+  "version": "0.1.4",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./client": "./src/client/index.js",
+    "./client/composables/*": "./src/client/composables/*.js",
+    "./server/repositorySupport": "./src/server/repositorySupport.js"
+  },
+  "dependencies": {
+    "@tanstack/vue-query": "^5.90.5",
+    "@jskit-ai/kernel": "0.1.4",
+    "@jskit-ai/realtime": "0.1.4",
+    "@jskit-ai/shell-web": "0.1.4",
+    "@jskit-ai/users-web": "0.1.4"
+  }
+}

package/src/client/composables/createCrudClientSupport.js

@@ -0,0 +1,201 @@
+import { computed } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import { usePaths } from "@jskit-ai/users-web/client/composables/usePaths";
+import {
+  resolveCrudClientConfig,
+  formatDateTime,
+  crudScopeQueryKey,
+  invalidateCrudQueries,
+  crudListQueryKey,
+  crudViewQueryKey,
+  toRouteRecordId
+} from "./crudClientSupportHelpers.js";
+import { useCrudRealtimeInvalidation } from "./useCrudRealtimeInvalidation.js";
+
+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`));
+
+  function listQueryKey(surfaceId = "") {
+    const normalizedSurfaceId = String(surfaceId || paths.currentSurfaceId.value || "").trim();
+    return crudListQueryKey(normalizedSurfaceId, workspaceSlugToken.value, crudConfig.namespace);
+  }
+
+  function viewQueryKey(surfaceId = "", recordId = 0) {
+    const normalizedSurfaceId = String(surfaceId || paths.currentSurfaceId.value || "").trim();
+    return crudViewQueryKey(normalizedSurfaceId, workspaceSlugToken.value, recordId, crudConfig.namespace);
+  }
+
+  function resolveViewPath(recordIdLike) {
+    const recordId = toRouteRecordId(recordIdLike);
+    if (!recordId) {
+      return "";
+    }
+
+    return paths.page(`${crudConfig.relativePath}/${recordId}`);
+  }
+
+  function resolveEditPath(recordIdLike) {
+    const recordId = toRouteRecordId(recordIdLike);
+    if (!recordId) {
+      return "";
+    }
+
+    return paths.page(`${crudConfig.relativePath}/${recordId}/edit`);
+  }
+
+  function scopeQueryKey() {
+    return crudScopeQueryKey(crudConfig.namespace);
+  }
+
+  async function invalidateQueries(queryClient) {
+    return invalidateCrudQueries(queryClient, crudConfig.namespace);
+  }
+
+  return Object.freeze({
+    route,
+    crudConfig,
+    listPath,
+    createPath,
+    listQueryKey,
+    viewQueryKey,
+    scopeQueryKey,
+    invalidateQueries,
+    formatDateTime,
+    resolveViewPath,
+    resolveEditPath
+  });
+}
+
+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 crudContext = useCrudClientContext(source);
+  useCrudRealtimeInvalidation(crudContext.crudConfig.namespace);
+  const router = useRouter();
+  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 listPath = crudContext.listPath;
+
+  function viewQueryKey(surfaceId = "") {
+    return crudContext.viewQueryKey(surfaceId, recordId.value);
+  }
+
+  async function invalidateAndGoList(queryClient) {
+    await crudContext.invalidateQueries(queryClient);
+    if (listPath.value) {
+      await router.push(listPath.value);
+    }
+  }
+
+  async function invalidateAndGoView(queryClient, recordIdLike = recordId.value) {
+    await crudContext.invalidateQueries(queryClient);
+
+    const targetRecordId = toRouteRecordId(recordIdLike);
+    const targetPath = crudContext.resolveViewPath(targetRecordId || recordId.value);
+    if (targetPath) {
+      await router.push(targetPath);
+    }
+  }
+
+  return Object.freeze({
+    crudContext,
+    listPath,
+    recordId,
+    apiSuffix,
+    viewPath,
+    editPath,
+    viewQueryKey,
+    invalidateAndGoList,
+    invalidateAndGoView
+  });
+}
+
+function useCrudCreateRuntime(source = {}) {
+  const crudContext = useCrudClientContext(source);
+  useCrudRealtimeInvalidation(crudContext.crudConfig.namespace);
+  const router = useRouter();
+  const listPath = crudContext.listPath;
+  const apiSuffix = crudContext.crudConfig.relativePath;
+
+  function createQueryKey(surfaceId = "") {
+    return [...crudContext.listQueryKey(surfaceId), "create"];
+  }
+
+  async function invalidateAndGoView(queryClient, recordIdLike) {
+    await crudContext.invalidateQueries(queryClient);
+
+    const targetPath = crudContext.resolveViewPath(recordIdLike);
+    if (targetPath) {
+      await router.push(targetPath);
+    }
+  }
+
+  return Object.freeze({
+    crudContext,
+    listPath,
+    apiSuffix,
+    createQueryKey,
+    invalidateAndGoView
+  });
+}
+
+function useCrudListRuntime(source = {}) {
+  const crudContext = useCrudClientContext(source);
+  useCrudRealtimeInvalidation(crudContext.crudConfig.namespace);
+  const createPath = crudContext.createPath;
+  const apiSuffix = crudContext.crudConfig.relativePath;
+
+  function listQueryKey(surfaceId = "") {
+    return crudContext.listQueryKey(surfaceId);
+  }
+
+  return Object.freeze({
+    crudContext,
+    createPath,
+    apiSuffix,
+    listQueryKey
+  });
+}
+
+function createCrudClientSupport(source = {}) {
+  const crudConfig = resolveCrudClientConfig(source);
+
+  return Object.freeze({
+    useCrudClientContext() {
+      return useCrudClientContext(crudConfig);
+    },
+    useCrudListRuntime() {
+      return useCrudListRuntime(crudConfig);
+    },
+    useCrudCreateRuntime() {
+      return useCrudCreateRuntime(crudConfig);
+    },
+    useCrudRecordRuntime(options = {}) {
+      return useCrudRecordRuntime(crudConfig, options);
+    },
+    toRouteRecordId
+  });
+}
+
+export {
+  useCrudClientContext,
+  useCrudListRuntime,
+  useCrudCreateRuntime,
+  useCrudRecordRuntime,
+  createCrudClientSupport
+};

package/src/client/composables/crudClientSupportHelpers.js

@@ -0,0 +1,111 @@
+import { normalizeLowerText, 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";
+
+const DEFAULT_CRUD_OWNERSHIP_FILTER = "workspace";
+
+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) {
+    throw new TypeError(`${context} requires a non-empty relative path.`);
+  }
+
+  const normalized = `/${raw.replace(/^\/+|\/+$/g, "")}`;
+  if (normalized === "/") {
+    throw new TypeError(`${context} requires a non-empty relative path.`);
+  }
+
+  return normalized;
+}
+
+function resolveCrudClientConfig(source = {}) {
+  const payload = source && typeof source === "object" && !Array.isArray(source) ? source : {};
+  const namespace = requireCrudNamespace(payload.namespace, {
+    context: "resolveCrudClientConfig"
+  });
+  const ownershipFilter = normalizeRouteVisibilityToken(payload.ownershipFilter, {
+    fallback: DEFAULT_CRUD_OWNERSHIP_FILTER
+  });
+  const inferredRelativePath = `/${namespace}`;
+  const relativePath = normalizeRelativePath(
+    Object.hasOwn(payload, "relativePath") ? payload.relativePath : inferredRelativePath,
+    { context: "resolveCrudClientConfig" }
+  );
+
+  return Object.freeze({
+    namespace,
+    ownershipFilter,
+    relativePath
+  });
+}
+
+function crudListQueryKey(surfaceId = "", workspaceSlug = "", namespace = "") {
+  return Object.freeze([
+    ...crudScopeQueryKey(namespace),
+    "list",
+    normalizeQueryToken(surfaceId),
+    normalizeQueryToken(workspaceSlug)
+  ]);
+}
+
+function crudViewQueryKey(surfaceId = "", workspaceSlug = "", recordId = 0, namespace = "") {
+  return Object.freeze([
+    ...crudScopeQueryKey(namespace),
+    "view",
+    normalizeQueryToken(surfaceId),
+    normalizeQueryToken(workspaceSlug),
+    Number(recordId) || 0
+  ]);
+}
+
+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().");
+  }
+
+  return queryClient.invalidateQueries({
+    queryKey: crudScopeQueryKey(namespace)
+  });
+}
+
+function toRouteRecordId(value) {
+  if (Array.isArray(value)) {
+    return toRouteRecordId(value[0]);
+  }
+
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
+}
+
+export {
+  DEFAULT_CRUD_OWNERSHIP_FILTER,
+  requireCrudNamespace,
+  resolveCrudClientConfig,
+  formatDateTime,
+  resolveCrudRecordChangedEvent,
+  crudScopeQueryKey,
+  invalidateCrudQueries,
+  crudListQueryKey,
+  crudViewQueryKey,
+  toRouteRecordId
+};

package/src/client/composables/useCrudRealtimeInvalidation.js

@@ -0,0 +1,37 @@
+import { useQueryClient } from "@tanstack/vue-query";
+import { useRealtimeEvent } from "@jskit-ai/realtime/client/composables/useRealtimeEvent";
+import {
+  crudScopeQueryKey,
+  requireCrudNamespace,
+  resolveCrudRecordChangedEvent
+} from "./crudClientSupportHelpers.js";
+
+function useCrudRealtimeInvalidation(
+  namespace = "",
+  {
+    event = "",
+    enabled = true,
+    matches = null,
+    queryKey = null
+  } = {}
+) {
+  const normalizedNamespace = requireCrudNamespace(namespace, {
+    context: "useCrudRealtimeInvalidation"
+  });
+  const queryClient = useQueryClient();
+  const resolvedEvent = String(event || "").trim() || resolveCrudRecordChangedEvent(normalizedNamespace);
+  const resolvedQueryKey = Array.isArray(queryKey) && queryKey.length > 0 ? queryKey : crudScopeQueryKey(normalizedNamespace);
+
+  return useRealtimeEvent({
+    event: resolvedEvent,
+    enabled,
+    matches,
+    onEvent: async () => {
+      await queryClient.invalidateQueries({
+        queryKey: resolvedQueryKey
+      });
+    }
+  });
+}
+
+export { useCrudRealtimeInvalidation };

package/src/client/index.js

@@ -0,0 +1,24 @@
+export {
+  DEFAULT_CRUD_OWNERSHIP_FILTER,
+  resolveCrudClientConfig,
+  crudListQueryKey,
+  crudViewQueryKey,
+  crudScopeQueryKey,
+  invalidateCrudQueries,
+  formatDateTime,
+  resolveCrudRecordChangedEvent,
+  toRouteRecordId,
+  requireCrudNamespace
+} from "./composables/crudClientSupportHelpers.js";
+
+export {
+  useCrudClientContext,
+  useCrudListRuntime,
+  useCrudCreateRuntime,
+  useCrudRecordRuntime,
+  createCrudClientSupport
+} from "./composables/createCrudClientSupport.js";
+
+export {
+  useCrudRealtimeInvalidation
+} from "./composables/useCrudRealtimeInvalidation.js";

package/src/server/repositorySupport.js

@@ -0,0 +1,29 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+const DEFAULT_LIST_LIMIT = 20;
+const MAX_LIST_LIMIT = 100;
+
+function normalizeCrudListLimit(value, { fallback = DEFAULT_LIST_LIMIT, max = MAX_LIST_LIMIT } = {}) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return fallback;
+  }
+
+  return Math.min(parsed, max);
+}
+
+function requireCrudTableName(tableName, { context = "crudRepository" } = {}) {
+  const normalizedTableName = normalizeText(tableName);
+  if (!normalizedTableName) {
+    throw new TypeError(`${context} requires tableName.`);
+  }
+
+  return normalizedTableName;
+}
+
+export {
+  DEFAULT_LIST_LIMIT,
+  MAX_LIST_LIMIT,
+  normalizeCrudListLimit,
+  requireCrudTableName
+};

package/test/createCrudClientSupport.test.js

@@ -0,0 +1,90 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  resolveCrudClientConfig,
+  crudScopeQueryKey,
+  invalidateCrudQueries,
+  crudListQueryKey,
+  crudViewQueryKey,
+  toRouteRecordId,
+  resolveCrudRecordChangedEvent
+} from "../src/client/composables/crudClientSupportHelpers.js";
+
+test("resolveCrudClientConfig normalizes namespace, ownership filter, and derives relativePath", () => {
+  const config = resolveCrudClientConfig({
+    namespace: " Customers ",
+    ownershipFilter: "workspace",
+    relativePath: "/crm/customers"
+  });
+
+  assert.deepEqual(config, {
+    namespace: "customers",
+    ownershipFilter: "workspace",
+    relativePath: "/crm/customers"
+  });
+});
+
+test("resolveCrudClientConfig infers default relativePath from namespace", () => {
+  const config = resolveCrudClientConfig({
+    namespace: "appointments",
+    ownershipFilter: "public"
+  });
+
+  assert.equal(config.relativePath, "/appointments");
+});
+
+test("resolveCrudClientConfig throws when namespace is missing", () => {
+  assert.throws(
+    () => resolveCrudClientConfig({ ownershipFilter: "workspace" }),
+    /requires a non-empty namespace/
+  );
+});
+
+test("crudListQueryKey and crudViewQueryKey normalize cache keys", () => {
+  assert.deepEqual(crudListQueryKey("Admin", " TonymoBily3 ", "Customers"), [
+    "crud",
+    "customers",
+    "list",
+    "admin",
+    "tonymobily3"
+  ]);
+
+  assert.deepEqual(crudViewQueryKey("Admin", " TonymoBily3 ", "12", "Customers"), [
+    "crud",
+    "customers",
+    "view",
+    "admin",
+    "tonymobily3",
+    12
+  ]);
+});
+
+test("crudScopeQueryKey normalizes namespace", () => {
+  assert.deepEqual(crudScopeQueryKey(" Customers "), ["crud", "customers"]);
+});
+
+test("invalidateCrudQueries invalidates by CRUD namespace scope key", async () => {
+  let payload = null;
+  const queryClient = {
+    async invalidateQueries(input) {
+      payload = input;
+      return true;
+    }
+  };
+
+  await invalidateCrudQueries(queryClient, "Customers");
+  assert.deepEqual(payload, {
+    queryKey: ["crud", "customers"]
+  });
+});
+
+test("toRouteRecordId parses scalar and array params safely", () => {
+  assert.equal(toRouteRecordId("42"), 42);
+  assert.equal(toRouteRecordId(["7"]), 7);
+  assert.equal(toRouteRecordId("not-a-number"), 0);
+});
+
+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

@@ -0,0 +1,24 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  DEFAULT_LIST_LIMIT,
+  normalizeCrudListLimit,
+  requireCrudTableName
+} from "../src/server/repositorySupport.js";
+
+test("normalizeCrudListLimit enforces fallback and max", () => {
+  assert.equal(normalizeCrudListLimit(null), DEFAULT_LIST_LIMIT);
+  assert.equal(normalizeCrudListLimit("abc"), DEFAULT_LIST_LIMIT);
+  assert.equal(normalizeCrudListLimit(0), DEFAULT_LIST_LIMIT);
+  assert.equal(normalizeCrudListLimit(5), 5);
+  assert.equal(normalizeCrudListLimit(200), 100);
+});
+
+test("requireCrudTableName trims and rejects empty values", () => {
+  assert.equal(requireCrudTableName("  crud_customers  "), "crud_customers");
+
+  assert.throws(
+    () => requireCrudTableName("   "),
+    /requires tableName/
+  );
+});