cap-domain 3.0.0

package/tests/db/data-model.cds

@@ -0,0 +1,37 @@
+namespace my.bookshop;
+
+entity Books {
+  key ID            : UUID;
+      title         : String;
+      enableDetails : Boolean;
+      description   : String;
+      stock         : Integer;
+      reorderPoint  : Integer;
+      releaseDate   : Date;
+      previewDate   : Date;
+      statusCode    : String;
+      price         : Integer;
+      Author        : Association to Authors;
+}
+
+entity Authors {
+  key ID    : UUID;
+      name  : String;
+      Books : Composition of many Books
+                on Books.Author = $self;
+}
+
+
+entity Request {
+  key ID            : UUID;
+      title         : String;
+      archived      : Boolean;
+      internalNotes : String;
+      note          : String;
+      Detail        : Composition of one Details;
+}
+
+entity Details {
+  key ID    : UUID;
+      title  : String;
+}

package/tests/eslint.config.js

@@ -0,0 +1,6 @@
+const cds = require("@sap/eslint-plugin-cds");
+
+module.exports = [
+  { ignores: ["coverage/**"] },
+  cds.configs.recommended,
+];

package/tests/jest.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  testEnvironment: 'node',
+  collectCoverage: true,
+  coverageDirectory: 'coverage',
+  testMatch: ['**/test/**/*.test.js'],
+  coveragePathIgnorePatterns: ['/test'],
+  silent: true,
+  setupFilesAfterEnv: ['./test/setup.js']
+};

package/tests/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "cap-domain-showcase",
+  "version": "1.0.0",
+  "description": "A simple CAP project.",
+  "repository": "<Add your repository here>",
+  "license": "UNLICENSED",
+  "private": true,
+  "dependencies": {
+    "@sap/cds": "^10.1.1",
+    "cap-domain": "file:..",
+    "express": "^4"
+  },
+  "devDependencies": {
+    "@cap-js/cds-test": "^1.0.2",
+    "@cap-js/sqlite": "^3.1.1",
+    "@sap/eslint-plugin-cds": "^4.2.5",
+    "axios": "^1.8.2",
+    "eslint": "^9",
+    "jest": "^30.0.0"
+  },
+  "scripts": {
+    "start": "cds-serve",
+    "test": "jest --silent=true"
+  },
+  "cds": {
+    "enable:capdomain:plugin": true,
+    "requires": {},
+    "log": {
+      "levels": {
+        "sql": "debug",
+        "cds": "debug"
+      }
+    }
+  }
+}

package/tests/srv/@FCDefinitions/Authors.js

@@ -0,0 +1,24 @@
+const { fieldControlDictionary } = require('cap-domain');
+
+const fieldControlConfigurations = {
+    name: {
+        fc: () => fieldControlDictionary.Mandatory,
+        validator(value, { i18n }) {
+            if (!value || value.length < 10) {
+                return i18n.getText(
+                    'book.validation.title.minLength'
+                );
+            }
+        }
+    }
+};
+
+// addOnHAndler(fieldControlConfigurations, (req, next) => {
+//     this.srvFn();
+// })
+
+// addOnBeforeAll(fieldControlConfigurations, (req) => {
+//     this.fetchS4Data
+// })
+
+module.exports = fieldControlConfigurations;

package/tests/srv/@FCDefinitions/Books.js

@@ -0,0 +1,23 @@
+const { fieldControlDictionary } = require('cap-domain');
+
+const fieldControlConfigurations = {
+    title: {
+        fc: () => fieldControlDictionary.Mandatory,
+        validator(value, { i18n }) {
+            if (!value || value.length < 10) {
+                return i18n.getText(
+                    'book.validation.title.minLength'
+                );
+            }
+        },
+        onBeforeSave(entity, entityChanges) { },
+    },
+    description: {
+        fc: (book) => book.enableDetails ? fieldControlDictionary.Mandatory : fieldControlDictionary.Hidden,
+    },
+    enableDetails: {
+        fc: () => fieldControlDictionary.Optional,
+    }
+};
+
+module.exports = fieldControlConfigurations;

package/tests/srv/@FCDefinitions/Details.js

@@ -0,0 +1,16 @@
+const { fieldControlDictionary } = require('cap-domain');
+
+const fieldControlConfigurations = {
+    title: {
+        fc: () => fieldControlDictionary.Mandatory,
+        validator(value, { i18n }) {
+            if (!value || value.length < 10) {
+                return i18n.getText(
+                    'book.validation.title.minLength'
+                );
+            }
+        }
+    }
+};
+
+module.exports = fieldControlConfigurations;

package/tests/srv/@FCDefinitions/Request.js

@@ -0,0 +1,22 @@
+const { fieldControlDictionary } = require('cap-domain');
+
+const fieldControlConfigurations = {
+    title: {
+        fc: () => fieldControlDictionary.Mandatory,
+        validator(value, { i18n }) {
+            if (!value || value.length < 10) {
+                return i18n.getText(
+                    'book.validation.title.minLength'
+                );
+            }
+        }
+    },
+    archived: {
+        fc: () => fieldControlDictionary.Optional,
+    },
+    internalNotes: {
+        fc: (request) => request.archived ? fieldControlDictionary.Hidden : fieldControlDictionary.Optional,
+    }
+};
+
+module.exports = fieldControlConfigurations;

package/tests/srv/CatalogService-annotations.cds

@@ -0,0 +1,44 @@
+using {CatalogService as srv} from './CatalogService';
+
+annotate srv.Books with {
+  title         @(
+    Common.FieldControl: {$value: title_fc},
+    Common.Label       : '{i18n>title}'
+  );
+  description   @(
+    Common.FieldControl: {$value: description_fc},
+    Common.Label       : '{i18n>description}'
+  );
+  enableDetails @(
+    Common.FieldControl: {$value: enableDetails_fc}
+  );
+};
+
+annotate srv.Request with {
+  title         @(
+    Common.FieldControl: {$value: title_fc},
+    Common.Label       : '{i18n>title}'
+  );
+  archived      @(
+    Common.FieldControl: {$value: archived_fc}
+  );
+  internalNotes @(
+    Common.FieldControl: {$value: internalNotes_fc}
+  );
+};
+
+annotate srv.Details with {
+  title       @(
+    Common.FieldControl: {$value: title_fc},
+    Common.Label       : '{i18n>title}'
+  );
+};
+
+
+annotate srv.Authors with {
+  name       @(
+    Common.FieldControl: {$value: name_fc},
+    Common.Label       : '{i18n>name}'
+  );
+};
+

package/tests/srv/CatalogService.cds

@@ -0,0 +1,46 @@
+using my.bookshop as my from '../db/data-model';
+
+
+service CatalogService {
+    @FCSettings: {
+        path     : 'srv/@FCDefinitions/Authors.js'
+    }
+    entity Authors   as
+        projection on my.Authors {
+            *,
+            virtual null as name_fc       : Integer @odata.Type: 'Edm.Byte',
+        };
+
+    @FCSettings: {
+        path     : 'srv/@FCDefinitions/Books.js'
+    }
+    entity Books   as
+        projection on my.Books {
+            *,
+            virtual null as title_fc         : Integer @odata.Type: 'Edm.Byte',
+            virtual null as description_fc   : Integer @odata.Type: 'Edm.Byte',
+            virtual null as enableDetails_fc : Integer @odata.Type: 'Edm.Byte'
+        };
+
+    @FCSettings: {
+        path                        : 'srv/@FCDefinitions/Request.js',
+        autoErase                   : false,
+        blockUnannotatedValueChanges: false
+    }
+    entity Request as
+        projection on my.Request {
+            *,
+            virtual null as title_fc         : Integer @odata.Type: 'Edm.Byte',
+            virtual null as archived_fc      : Integer @odata.Type: 'Edm.Byte',
+            virtual null as internalNotes_fc : Integer @odata.Type: 'Edm.Byte'
+        };
+
+    @FCSettings: {
+        path     : 'srv/@FCDefinitions/Details.js'
+    }
+    entity Details as
+        projection on my.Details {
+            *,
+            virtual null as title_fc : Integer @odata.Type: 'Edm.Byte',
+        };
+}

package/tests/srv/CatalogService.js

@@ -0,0 +1,21 @@
+const cds = require('@sap/cds');
+const { execAfterREADHandler, execUPDATEHandler, validateAndThowErrorsIfExists } = require('cap-domain');
+
+class CatalogService extends cds.ApplicationService {
+    init() {
+        const { Books, Authors, Request, Details } = this.entities;
+
+        for (const entity of [ Books, Authors, Request, Details ]) {
+            this.on('CREATE', entity, async (req, next) => {
+                await validateAndThowErrorsIfExists(req, req.data, 'in');
+                return await next();
+            });
+            this.after('READ', entity, execAfterREADHandler);
+            this.on('UPDATE', entity, execUPDATEHandler);
+        }
+
+        return super.init();
+    }
+}
+
+module.exports = CatalogService;

package/tests/srv/_i18n/i18n_de.properties

@@ -0,0 +1,6 @@
+title=Titel
+description=Beschreibung
+name=Name X
+book.validation.title.minLength=Der Titel darf nicht kürzer als 10 Zeichen sein
+capdomain.validation.message.readOnly={0} ist ein schreibgeschütztes Feld
+capdomain.validation.message.required={0} ist ein Pflichtfeld

package/tests/srv/_i18n/i18n_en.properties

@@ -0,0 +1,6 @@
+title=Title
+description=Description
+name=Name X
+book.validation.title.minLength=Title cannot be less than 10 characters
+capdomain.validation.message.readOnly={0} is Read-only field
+capdomain.validation.message.required={0} is Required field

package/tests/srv/cat-fiori-service.cds

@@ -0,0 +1,7 @@
+using my.bookshop as my from '../db/data-model';
+
+
+service CatalogFioriService {
+    @odata.draft.enabled
+    entity Books as projection on my.Books;
+}

package/tests/test/UsersApi.js

@@ -0,0 +1,97 @@
+const cds = require('@sap/cds');
+const { GET, PATCH, POST, DELETE } = cds.test(__dirname + '/..');
+
+// should be in sync with mock users in package.json
+const users = {
+  admin: {
+    username: 'admin',
+    password: 'password',
+    email: 'admin@example.com',
+  }
+};
+
+const services = {
+  catalog: '/odata/v4/catalog'
+};
+
+const STATUS_BY_METHOD = {
+  GET: 200,
+  POST: 201,
+  PATCH: 200,
+  PUT: 200,
+  DELETE: 204,
+};
+
+class ServiceAPI {
+  constructor(servicePath, authConfig) {
+    this.servicePath = servicePath;
+    this.authConfig = authConfig;
+  }
+
+  async GET(url, config = {}) {
+    return await GET(`${this.servicePath}${url}`, Object.assign(config, this.authConfig));
+  }
+
+  async PATCH(url, data = {}, config = {}) {
+    try {
+      return await PATCH(`${this.servicePath}${url}`, data, Object.assign(config, this.authConfig));
+    } catch (err) {
+      return { err };
+    }
+  }
+
+  async POST(url, data = {}, config = {}) {
+    try {
+      return await POST(`${this.servicePath}${url}`, data, Object.assign(config, this.authConfig));
+    } catch (err) {
+      return { err };
+    }
+  }
+
+  async DELETE(url, config = {}) {
+    try {
+      return await DELETE(`${this.servicePath}${url}`, Object.assign(config, this.authConfig));
+    } catch (err) {
+      return { err };
+    }
+  }
+
+  async assertRequest(method, url, bodyOrCheck, check) {
+    let body, checkFn;
+    if (typeof bodyOrCheck === 'function') {
+      checkFn = bodyOrCheck;
+    } else {
+      body = bodyOrCheck;
+      checkFn = check;
+    }
+
+    const res = await this[method](url, ...(body ? [body] : []));
+
+    // expect(res.status).toEqual(STATUS_BY_METHOD[method] ?? 200);
+    checkFn?.(res);
+    return res;
+  }
+
+  assertGet(url, check) { return this.assertRequest('GET', url, check); }
+  assertPost(url, body, check) { return this.assertRequest('POST', url, body, check); }
+  assertPatch(url, body, check) { return this.assertRequest('PATCH', url, body, check); }
+  assertDelete(url, check) { return this.assertRequest('DELETE', url, check); }
+}
+
+class UserAPI {
+  constructor(config) {
+    this.email = config.email;
+    this.authConfig = {
+      auth: config,
+    };
+
+    for (const serviceName in services) {
+      this[serviceName] = new ServiceAPI(services[serviceName], this.authConfig);
+    }
+  }
+}
+
+module.exports = {
+  users,
+  admin: new UserAPI(users.admin)
+};

package/tests/test/authors.test.js

@@ -0,0 +1,26 @@
+const { admin } = require("./UsersApi");
+
+describe("Authors", () => {
+  it("rejects a name shorter than the configured minimum length", async () => {
+    await admin.catalog.assertPost("/Authors", { name: "Al" }, (res) => {
+      expect(res).toBeFailed();
+      expect(res?.err?.response?.data?.error?.message).toBeTruthy();
+    });
+  });
+
+  it("accepts a name that satisfies the validator", async () => {
+    const payload = { name: "Alexander Pushkin" };
+
+    await admin.catalog.assertPost("/Authors", payload, (res) => {
+      expect(res.data).toMatchSubset(payload);
+      expect(res).toBeSuccessful();
+    });
+  });
+
+  it("computes the mandatory field control for name on READ", async () => {
+    await admin.catalog.assertGet("/Authors", (res) => {
+      expect(res).toBeSuccessful();
+      res.data.value.forEach((author) => expect(author.name_fc).toEqual(7));
+    });
+  });
+});

package/tests/test/books.test.js

@@ -0,0 +1,97 @@
+const { admin } = require("./UsersApi");
+
+describe("Books", () => {
+  it("success flow", async () => {
+    const payload = {
+      title: "12345678901",
+      enableDetails: true,
+      description: "This is a description that should be mandatory when enableDetails is true."
+    };
+    await admin.catalog.assertPost("/Books", payload, (res) => {
+      expect(res.data).toMatchSubset(payload);
+      expect(res).toBeSuccessful();
+    });
+  });
+
+  it("failure flow", async () => {
+    const payload = {
+      title: "1",
+      enableDetails: true
+    };
+    await admin.catalog.assertPost("/Books", payload, (res) => {
+      expect(res).toBeFailed();
+      expect(res).toHaveErrorMessagesCount(2);
+    });
+  });
+
+  it("returns the localized validation message text", async () => {
+    const payload = { title: "1" };
+
+    await admin.catalog.assertPost("/Books", payload, (res) => {
+      expect(res).toBeFailed();
+      expect(res?.err?.response?.data?.error?.message).toEqual("Title cannot be less than 10 characters");
+    });
+  });
+
+  it("computes field controls on READ based on entity state", async () => {
+    await admin.catalog.assertGet("/Books", (res) => {
+      expect(res).toBeSuccessful();
+
+      const withDetails = res.data.value.find((b) => b.title === "Wuthering Heights");
+      const withoutDetails = res.data.value.find((b) => b.title === "Jane Eyre");
+
+      // enableDetails=true -> Mandatory(7), enableDetails=false -> Hidden(0)
+      expect(withDetails.description_fc).toEqual(7);
+      expect(withoutDetails.description_fc).toEqual(0);
+    });
+  });
+
+  it("blocks updates to fields that became read-only/hidden", async () => {
+    const created = await admin.catalog.assertPost("/Books", {
+      title: "A Read Only Field Test",
+      enableDetails: false
+    });
+    const { ID } = created.data;
+
+    await admin.catalog.assertPatch(`/Books(${ID})`, { description: "should not be allowed" }, (res) => {
+      expect(res).toBeFailed();
+      expect(res?.err?.response?.data?.error?.message).toEqual("Description is Read-only field");
+    });
+  });
+
+  it("auto-erases field values once they become hidden", async () => {
+    const created = await admin.catalog.assertPost("/Books", {
+      title: "Auto Erase Field Test",
+      enableDetails: true,
+      description: "A description that is long enough to be considered valid."
+    });
+    const { ID } = created.data;
+
+    await admin.catalog.assertPatch(`/Books(${ID})`, { enableDetails: false }, (res) => {
+      expect(res).toBeSuccessful();
+    });
+
+    await admin.catalog.assertGet(`/Books(${ID})`, (res) => {
+      expect(res).toBeSuccessful();
+      expect(res.data.description).toBeNull();
+    });
+  });
+
+  it("blocks changes to fields without a field control annotation", async () => {
+    const created = await admin.catalog.assertPost("/Books", {
+      title: "Unannotated Field Test",
+      enableDetails: false
+    });
+    const { ID } = created.data;
+
+    await admin.catalog.assertPatch(`/Books(${ID})`, { stock: 999 }, (res) => {
+      expect(res).toBeSuccessful();
+    });
+
+    await admin.catalog.assertGet(`/Books(${ID})`, (res) => {
+      expect(res).toBeSuccessful();
+      expect(res.data.stock).not.toEqual(999);
+    });
+  });
+});
+

package/tests/test/request.test.js

@@ -0,0 +1,39 @@
+const { admin } = require("./UsersApi");
+
+// Request entity is configured (via @FCSettings) with autoErase:false and
+// blockUnannotatedValueChanges:false, to demonstrate both flags can be turned off.
+describe("Request (autoErase/blockUnannotatedValueChanges disabled)", () => {
+  it("does not erase a field's value once it becomes hidden when autoErase is false", async () => {
+    const created = await admin.catalog.assertPost("/Request", {
+      title: "Auto Erase Disabled Test",
+      archived: false,
+      internalNotes: "Keep me even after archiving"
+    });
+    const { ID } = created.data;
+
+    await admin.catalog.assertPatch(`/Request(${ID})`, { archived: true }, (res) => {
+      expect(res).toBeSuccessful();
+    });
+
+    await admin.catalog.assertGet(`/Request(${ID})`, (res) => {
+      expect(res).toBeSuccessful();
+      expect(res.data.internalNotes).toEqual("Keep me even after archiving");
+    });
+  });
+
+  it("allows changes to fields without a field control annotation when blockUnannotatedValueChanges is false", async () => {
+    const created = await admin.catalog.assertPost("/Request", {
+      title: "Unannotated Field Allowed Test"
+    });
+    const { ID } = created.data;
+
+    await admin.catalog.assertPatch(`/Request(${ID})`, { note: "freeform note" }, (res) => {
+      expect(res).toBeSuccessful();
+    });
+
+    await admin.catalog.assertGet(`/Request(${ID})`, (res) => {
+      expect(res).toBeSuccessful();
+      expect(res.data.note).toEqual("freeform note");
+    });
+  });
+});

package/tests/test/setup.js

@@ -0,0 +1,54 @@
+expect.extend({
+  toMatchSubset(received, expected) {
+    const isSubset = (A, B) =>
+      Object.entries(B).every(([key, val]) =>
+        val && typeof val === "object"
+          ? isSubset(A[key] ?? {}, val)
+          : A[key] === val
+      );
+
+    const pass = received != null && isSubset(received, expected);
+
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `expected received object NOT to contain all fields of expected, but it did.\nExpected: ${JSON.stringify(expected, null, 2)}\nReceived: ${JSON.stringify(received, null, 2)}`
+          : `expected received object to contain all fields of expected.\nExpected: ${JSON.stringify(expected, null, 2)}\nReceived: ${JSON.stringify(received, null, 2)}\nMissing or mismatched keys: ${Object.entries(expected)
+            .filter(([key, val]) => received[key] !== val)
+            .map(([key]) => key)
+            .join(", ")
+          }`,
+    };
+  },
+
+  toBeSuccessful(res) {
+    const status = res?.status;
+    const pass = status >= 200 && status <= 299;
+    return {
+      pass,
+      message: () =>
+        `expected status ${status} to be in 2xx range, but received ${JSON.stringify(res?.err?.response?.data ?? res?.data)}`,
+    };
+  },
+
+  toBeFailed(res) {
+    const status = res?.err?.status;
+    const pass = status >= 400 && status <= 499;
+    return {
+      pass,
+      message: () =>
+        `expected status ${status} to be in 4xx range, but received ${JSON.stringify(res?.err?.response?.data ?? res?.data)}`,
+    };
+  },
+
+  toHaveErrorMessagesCount(res, expectedCount) {
+    const errors = res?.err?.response?.data?.error?.details || [];
+    const pass = errors.length === expectedCount;
+    return {
+      pass,
+      message: () =>
+        `expected error messages count to be ${expectedCount}, but received ${errors.length}. Errors: ${JSON.stringify(errors)}`,
+    };
+  }
+});