@jskit-ai/resource-crud-core 0.1.194 → 0.1.196

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/resource-crud-core",
-  "version": "0.1.194",
+  "version": "0.1.196",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -13,7 +13,7 @@
     "./shared/crudResource": "./src/shared/crudResource.js"
   },
   "dependencies": {
-    "@jskit-ai/resource-core": "0.1.194"
+    "@jskit-ai/resource-core": "0.1.196"
   },
   "description": "Shared CRUD resource, field, lookup, filter, and namespace contracts.",
   "jskit": {
@@ -34,6 +34,6 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.2.3"
+    "@jskit-ai/kernel": "0.2.5"
   }
 }

package/patterns/resource-contract/PATTERN.md

@@ -44,7 +44,9 @@ not from a JSKIT questionnaire.
 - User ownership is represented by a non-null `user_id` column.
 - The resource's hidden `userId` field maps to that ownership column.
 - `autofilter: "user"` is used only for genuine current-user ownership.
-- Output, create, and patch participation is explicit on each product field.
+- Each product field's output, create, and patch participation is its
+  `operations` block, or the default `defineCrudResource()` gives a field
+  without one (see Field operations and lookups below).
 - Temporal database values use the declared storage serializer.
 - The source-controlled migration and resource contract agree.
 - Server policy tests prove that one user cannot read or mutate another user's
@@ -60,6 +62,57 @@ Higher layers should consume this resource through JSKIT's CRUD service,
 repository, route, and UI APIs. They should not rebuild field validators or
 serialize requests independently.
 
+## Field operations and lookups
+
+A field's `operations` name the operations it takes part in: `output` (the
+record in every response), and `create` and `patch` (the request bodies; an
+enabled `replace` uses the `create` fields unless a field names `replace`). A
+field that leaves `operations` out takes the default:
+
+| Field | Default `operations` |
+| --- | --- |
+| `primary: true` | `{}`: no operation; every record output already carries its `id` |
+| `hidden: true` | `{}`: no operation |
+| `readOnly: true` | `{ output: { required: true } }` |
+| any other field | `{ output: { required: true }, create: { required: <the field's required> }, patch: { required: false } }` |
+
+So a `required: true` field is required on create, and any other field is
+optional there. An `operations` block you write always wins, for example
+`operations: { output: {}, create: {}, patch: {} }` for a field that is
+optional everywhere. Write the block only where it differs from the default:
+
+```js
+schema: {
+  userId: { type: "id", required: true, hidden: true },
+  title: { type: "string", maxLength: 255, required: true, search: true },
+  notes: { type: "string", maxLength: 65535, nullable: true, search: true },
+  createdAt: { type: "dateTime", default: "now()", readOnly: true, storage: { writeSerializer: "datetime-utc" } }
+}
+```
+
+A field that looks up a record of another resource can name that resource's
+namespace with `lookup`:
+
+```js
+shelfId: { type: "id", nullable: true, search: true, lookup: "shelves" }
+```
+
+`defineCrudResource()` expands it, where `lookup` stood, to:
+
+```js
+relation: { kind: "lookup", namespace: "shelves", valueKey: "id" },
+belongsTo: "shelves",  // the namespace's JSON REST resource, camel-cased
+as: "shelf",           // the field key without its Id suffix
+ui: { formControl: "autocomplete" }
+```
+
+Keys you write beside `lookup` win: `belongsTo` and `as` replace the
+filled-in values, and `relation` and `ui` are merged over them, so
+`relation: { labelKey: "name" }` adds a label key and
+`ui: { formControl: "select" }` picks a select. A field whose key has no `Id`
+suffix must write `as`. The built resource equals one that writes the expanded
+keys out.
+
 ## Example files
 
 - `example/bookResource.js` is a complete resource contract for personal book

package/src/shared/crudFieldContract.js

@@ -1,5 +1,6 @@
 import { normalizeSingleSchemaDefinition } from "@jskit-ai/kernel/shared/validators";
 import {
+  isRecord,
   normalizeObject,
   normalizeText
 } from "@jskit-ai/kernel/shared/support/normalize";
@@ -10,31 +11,6 @@ const CRUD_FIELD_WRITE_SERIALIZER_DATETIME_UTC = "datetime-utc";
 const CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE = "autocomplete";
 const CRUD_LOOKUP_FORM_CONTROL_SELECT = "select";
 
-function checkCrudLookupFormControl(
-  value,
-  {
-    context = "crud field 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 cloneStructuredFieldMetadata(value = {}) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return null;
@@ -75,10 +51,6 @@ function resolveCrudFieldSchemaProperties(value, { context = "crud resource fiel
     context,
     defaultMode: "patch"
   });
-  if (!normalized) {
-    return {};
-  }
-
   return normalizeObject(normalized.schema.getFieldDefinitions());
 }
 
@@ -91,7 +63,7 @@ function normalizeCrudFieldStorageConfig(
 ) {
   const normalizedFieldKey = normalizeText(fieldKey);
   const actualField = normalizeText(fieldDefinition.actualField);
-  const storage = fieldDefinition?.storage;
+  const storage = fieldDefinition.storage;
 
   if (storage === undefined || storage === null) {
     return Object.freeze({
@@ -211,7 +183,7 @@ function mergeFieldContractEntry(target, source, { context = "crud field contrac
   return next;
 }
 
-function buildCrudFieldContractMap(resource = {}, { context = "crud resource field contract" } = {}) {
+function buildCrudFieldContractMap(resource, { context = "crud resource field contract" } = {}) {
   const sections = [
     resolveCrudFieldSchemaProperties(resource?.operations?.view?.output, {
       context: `${context}.operations.view.output`
@@ -276,11 +248,40 @@ function buildCrudFieldContractMap(resource = {}, { context = "crud resource fie
   );
 }
 
+/**
+ * The operations a schema field takes part in. A field's own `operations` always
+ * win. A field without them takes the default: none when it is `primary: true`
+ * (every record output already carries its id) or `hidden: true`, output only
+ * when it is `readOnly: true`, and otherwise output, create (required when the
+ * field is `required: true`) and patch.
+ * @param {Record<string, any>} fieldDefinition
+ * @returns {Record<string, unknown>}
+ */
+function resolveCrudFieldOperations(fieldDefinition) {
+  if (fieldDefinition.operations !== undefined) {
+    return normalizeObject(fieldDefinition.operations);
+  }
+  if (fieldDefinition.primary === true || fieldDefinition.hidden === true) {
+    return {};
+  }
+  if (fieldDefinition.readOnly === true) {
+    return { output: { required: true } };
+  }
+  return {
+    output: { required: true },
+    create: { required: fieldDefinition.required === true },
+    patch: { required: false }
+  };
+}
+
 function buildCrudOperationSchemaFields(fields = {}, operationName = "") {
   const definitions = {};
 
   for (const [fieldKey, fieldDefinition] of Object.entries(fields)) {
-    const operationConfig = fieldDefinition?.operations?.[operationName];
+    if (!isRecord(fieldDefinition)) {
+      continue;
+    }
+    const operationConfig = resolveCrudFieldOperations(fieldDefinition)[operationName];
     if (!operationConfig) {
       continue;
     }
@@ -300,26 +301,14 @@ function buildCrudOperationSchemaFields(fields = {}, operationName = "") {
   return definitions;
 }
 
-function resolveCrudFieldContractEntry(resource = {}, fieldKey = "", options = {}) {
-  const normalizedFieldKey = normalizeText(fieldKey);
-  if (!normalizedFieldKey) {
-    return null;
-  }
-
-  const entries = buildCrudFieldContractMap(resource, options);
-  return entries[normalizedFieldKey] || null;
-}
-
 export {
   CRUD_FIELD_STORAGE_COLUMN,
   CRUD_FIELD_STORAGE_VIRTUAL,
   CRUD_FIELD_WRITE_SERIALIZER_DATETIME_UTC,
   CRUD_LOOKUP_FORM_CONTROL_AUTOCOMPLETE,
   CRUD_LOOKUP_FORM_CONTROL_SELECT,
-  checkCrudLookupFormControl,
   resolveCrudFieldSchemaProperties,
   normalizeCrudFieldStorageConfig,
   buildCrudOperationSchemaFields,
-  buildCrudFieldContractMap,
-  resolveCrudFieldContractEntry
+  buildCrudFieldContractMap
 };