@jskit-ai/crud-core 0.1.63 → 0.1.65

package/test/routeContracts.test.js

@@ -0,0 +1,146 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createSchema } from "json-rest-schema";
+import {
+  validateSchemaPayload
+} from "@jskit-ai/kernel/shared/validators";
+import { createCrudJsonApiRouteContracts } from "../src/server/routeContracts.js";
+
+function createSchemaDefinition(structure = {}, mode = "patch") {
+  return Object.freeze({
+    schema: createSchema(structure),
+    mode
+  });
+}
+
+function createCrudResource() {
+  return Object.freeze({
+    namespace: "contacts",
+    defaultSort: Object.freeze(["-createdAt"]),
+    operations: Object.freeze({
+      view: Object.freeze({
+        output: createSchemaDefinition({
+          id: {
+            type: "string",
+            required: true
+          },
+          contactId: {
+            type: "string",
+            required: false,
+            relation: {
+              kind: "lookup",
+              apiPath: "/contacts",
+              valueKey: "id"
+            }
+          },
+          name: {
+            type: "string",
+            required: true
+          }
+        }, "replace")
+      }),
+      create: Object.freeze({
+        body: createSchemaDefinition({
+          contactId: {
+            type: "string",
+            required: false,
+            relation: {
+              kind: "lookup",
+              apiPath: "/contacts",
+              valueKey: "id"
+            }
+          },
+          name: {
+            type: "string",
+            required: true
+          }
+        }, "create"),
+        output: createSchemaDefinition({
+          id: {
+            type: "string",
+            required: true
+          },
+          name: {
+            type: "string",
+            required: true
+          }
+        }, "replace")
+      }),
+      patch: Object.freeze({
+        body: createSchemaDefinition({
+          name: {
+            type: "string",
+            required: false
+          }
+        }, "patch"),
+        output: createSchemaDefinition({
+          id: {
+            type: "string",
+            required: true
+          },
+          name: {
+            type: "string",
+            required: true
+          }
+        }, "replace")
+      })
+    })
+  });
+}
+
+test("createCrudJsonApiRouteContracts builds default CRUD JSON:API contracts", async () => {
+  const resource = createCrudResource();
+  const routeParamsValidator = createSchemaDefinition({
+    workspaceSlug: {
+      type: "string",
+      required: true
+    }
+  });
+
+  const contracts = createCrudJsonApiRouteContracts({
+    resource,
+    routeParamsValidator
+  });
+
+  assert.equal(contracts.listRouteContract.transport.contentType, "application/vnd.api+json");
+  assert.equal(contracts.viewRouteContract.transport.contentType, "application/vnd.api+json");
+  assert.equal(contracts.createRouteContract.transport.contentType, "application/vnd.api+json");
+  assert.equal(contracts.updateRouteContract.transport.contentType, "application/vnd.api+json");
+  assert.equal(contracts.listRouteContract.responses[200].transportSchema.type, "object");
+  assert.equal(contracts.createRouteContract.responses[201].transportSchema.type, "object");
+  assert.equal(contracts.updateRouteContract.responses[200].transportSchema.type, "object");
+  assert.equal(Object.hasOwn(contracts.deleteRouteContract.responses, "204"), false);
+  assert.equal(contracts.createRouteContract.body, resource.operations.create.body);
+  assert.equal(contracts.updateRouteContract.body, resource.operations.patch.body);
+  assert.deepEqual(
+    Object.keys(contracts.recordRouteParamsValidator.schema.getFieldDefinitions()).sort(),
+    ["recordId", "workspaceSlug"]
+  );
+
+  const normalizedListQuery = await validateSchemaPayload(contracts.listRouteContract.query, {
+    q: "  hello  ",
+    include: "  ownerId  ",
+    contactId: "  42  ",
+    cursor: "  offset:2  ",
+    limit: "25"
+  }, { phase: "input" });
+
+  assert.deepEqual(normalizedListQuery, {
+    q: "hello",
+    include: "ownerId",
+    contactId: "42",
+    cursor: "offset:2",
+    limit: 25
+  });
+});
+
+test("createCrudJsonApiRouteContracts falls back to recordId params when no route params validator is provided", () => {
+  const contracts = createCrudJsonApiRouteContracts({
+    resource: createCrudResource()
+  });
+
+  assert.deepEqual(
+    Object.keys(contracts.recordRouteParamsValidator.schema.getFieldDefinitions()),
+    ["recordId"]
+  );
+});

package/test/serviceEvents.test.js

@@ -1,6 +1,12 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { createCrudServiceEvents } from "../src/server/serviceEvents.js";
+import {
+  createCrudJsonApiServiceEvents,
+  createCrudServiceEvents,
+  resolveCrudEntityIdFromArgs,
+  resolveCrudEntityIdFromResult,
+  resolveCrudJsonApiEntityIdFromResult
+} from "../src/server/serviceEvents.js";
 
 test("createCrudServiceEvents builds CRUD realtime events from resource namespace", () => {
   const events = createCrudServiceEvents({
@@ -26,3 +32,37 @@ test("createCrudServiceEvents validates required resource namespace", () => {
     /resource\.namespace/
   );
 });
+
+test("createCrudJsonApiServiceEvents builds JSON:API-aware create/update/delete event defaults", () => {
+  const events = createCrudJsonApiServiceEvents("contacts");
+
+  assert.equal(events.createDocument[0].realtime.event, "contacts.record.changed");
+  assert.equal(events.patchDocumentById[0].realtime.event, "contacts.record.changed");
+  assert.equal(events.deleteDocumentById[0].realtime.event, "contacts.record.changed");
+  assert.equal(events.createDocument[0].entityId({
+    result: {
+      data: {
+        id: "21"
+      }
+    }
+  }), "21");
+  assert.equal(events.patchDocumentById[0].entityId({
+    args: [22]
+  }), "22");
+  assert.equal(events.deleteDocumentById[0].entityId({
+    args: [23]
+  }), "23");
+});
+
+test("service event entity-id helpers normalize ids from args, plain results, and JSON:API results", () => {
+  assert.equal(resolveCrudEntityIdFromArgs({ args: [12] }), "12");
+  assert.equal(resolveCrudEntityIdFromResult({ result: { id: 13 } }), "13");
+  assert.equal(resolveCrudJsonApiEntityIdFromResult({
+    result: {
+      data: {
+        id: 14
+      }
+    }
+  }), "14");
+  assert.equal(resolveCrudEntityIdFromArgs({ args: ["   "] }), "");
+});

package/test/serviceMethods.test.js

@@ -1,5 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { createSchema } from "json-rest-schema";
 import {
   createCrudServiceRuntime,
   crudServiceListRecords,
@@ -9,21 +10,22 @@ import {
   crudServiceDeleteRecord
 } from "../src/server/serviceMethods.js";
 
+function createOperationSchemaDefinition(structure = {}, mode = "replace") {
+  return {
+    schema: createSchema(structure),
+    mode
+  };
+}
+
 function createResourceWithOutputSchema(overrides = {}) {
   return {
     namespace: "contacts",
     operations: {
       view: {
-        outputValidator: {
-          schema: {
-            type: "object",
-            properties: {
-              id: { type: "integer" },
-              name: { type: "string" }
-            },
-            required: ["id", "name"]
-          }
-        }
+        output: createOperationSchemaDefinition({
+          id: { type: "integer", required: true },
+          name: { type: "string", required: true }
+        })
       }
     },
     ...overrides

package/src/shared/crudFieldMetaSupport.js

@@ -1,153 +0,0 @@
-import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import {
-  DEFAULT_CRUD_LOOKUP_CONTAINER_KEY,
-  normalizeCrudLookupContainerKey
-} from "@jskit-ai/kernel/shared/support/crudLookup";
-
-const CRUD_RUNTIME_LOOKUPS_FIELD_KEY = DEFAULT_CRUD_LOOKUP_CONTAINER_KEY;
-const CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE = "autocomplete";
-const CRUD_LOOKUP_FORM_CONTROL_SELECT = "select";
-const CRUD_FIELD_REPOSITORY_STORAGE_COLUMN = "column";
-const CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL = "virtual";
-const CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC = "datetime-utc";
-
-function normalizeCrudFieldRepositoryWriteSerializer(
-  value,
-  {
-    context = "crud fieldMeta repository",
-    fieldKey = ""
-  } = {}
-) {
-  const normalizedFieldKey = normalizeText(fieldKey);
-  const normalizedValue = normalizeText(value).toLowerCase();
-  if (!normalizedValue) {
-    return "";
-  }
-
-  if (normalizedValue === CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC) {
-    return normalizedValue;
-  }
-
-  throw new Error(
-    `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} repository.writeSerializer must be ` +
-      `"${CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC}" when provided.`
-  );
-}
-
-function checkCrudLookupFormControl(
-  value,
-  {
-    context = "crud fieldMeta ui.formControl",
-    defaultValue = CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE
-  } = {}
-) {
-  const resolvedValue = value === undefined || value === null || value === "" ? defaultValue : value;
-  if (resolvedValue === "") {
-    return "";
-  }
-
-  if (
-    resolvedValue === CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE ||
-    resolvedValue === CRUD_LOOKUP_FORM_CONTROL_SELECT
-  ) {
-    return resolvedValue;
-  }
-
-  throw new Error(
-    `${context} must be "${CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE}" or "${CRUD_LOOKUP_FORM_CONTROL_SELECT}". ` +
-      `Received: ${JSON.stringify(resolvedValue)}.`
-  );
-}
-
-function isCrudRuntimeOutputOnlyFieldKey(
-  value = "",
-  {
-    lookupContainerKey = CRUD_RUNTIME_LOOKUPS_FIELD_KEY
-  } = {}
-) {
-  const resolvedLookupContainerKey = normalizeCrudLookupContainerKey(lookupContainerKey, {
-    context: "crud runtime lookup container key"
-  });
-  return normalizeText(value) === resolvedLookupContainerKey;
-}
-
-function normalizeCrudFieldRepositoryConfig(
-  fieldMetaEntry = {},
-  {
-    context = "crud fieldMeta repository",
-    fieldKey = ""
-  } = {}
-) {
-  const normalizedFieldKey = normalizeText(fieldKey || fieldMetaEntry?.key);
-  const repository = fieldMetaEntry?.repository;
-  if (repository === undefined || repository === null) {
-    return Object.freeze({
-      storage: CRUD_FIELD_REPOSITORY_STORAGE_COLUMN,
-      column: ""
-    });
-  }
-  if (!repository || typeof repository !== "object" || Array.isArray(repository)) {
-    throw new TypeError(
-      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} must be an object when provided.`
-    );
-  }
-
-  const repositoryKeys = Object.keys(repository);
-  for (const repositoryKey of repositoryKeys) {
-    if (repositoryKey !== "column" && repositoryKey !== "storage" && repositoryKey !== "writeSerializer") {
-      throw new Error(
-        `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} does not support repository.${repositoryKey}.`
-      );
-    }
-  }
-
-  const column = normalizeText(repository.column);
-  const storage = normalizeText(repository.storage).toLowerCase();
-  const writeSerializer = normalizeCrudFieldRepositoryWriteSerializer(repository.writeSerializer, {
-    context,
-    fieldKey: normalizedFieldKey
-  });
-
-  if (!column && !storage && !writeSerializer) {
-    throw new Error(
-      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} requires repository.column, repository.storage, or repository.writeSerializer.`
-    );
-  }
-
-  if (storage && storage !== CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL) {
-    throw new Error(
-      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} repository.storage must be "virtual" when provided.`
-    );
-  }
-  if (storage === CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL && column) {
-    throw new Error(
-      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} repository.storage "virtual" cannot define repository.column.`
-    );
-  }
-  if (storage === CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL && writeSerializer) {
-    throw new Error(
-      `${context}${normalizedFieldKey ? `["${normalizedFieldKey}"]` : ""} repository.storage "virtual" cannot define repository.writeSerializer.`
-    );
-  }
-
-  return Object.freeze({
-    storage: storage === CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL
-      ? CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL
-      : CRUD_FIELD_REPOSITORY_STORAGE_COLUMN,
-    column,
-    writeSerializer
-  });
-}
-
-export {
-  CRUD_FIELD_REPOSITORY_STORAGE_COLUMN,
-  CRUD_FIELD_REPOSITORY_STORAGE_VIRTUAL,
-  CRUD_FIELD_REPOSITORY_WRITE_SERIALIZER_DATETIME_UTC,
-  CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE,
-  CRUD_LOOKUP_FORM_CONTROL_SELECT,
-  CRUD_RUNTIME_LOOKUPS_FIELD_KEY,
-  checkCrudLookupFormControl,
-  isCrudRuntimeOutputOnlyFieldKey,
-  normalizeCrudFieldRepositoryConfig,
-  normalizeCrudFieldRepositoryWriteSerializer
-};