@tabbr/module-cli 0.4.0 → 0.4.1

package/README.md

@@ -131,20 +131,35 @@ Tabbr repository for the field types, access rules and what the club gets; `tabb
 
 ## Contracts
 
-What a module uses of Tabbr (or, later, of another module) is a **contract** - never its code. Declare the ones you use
-with a version range, and the module API level that has contracts:
+What a module uses of Tabbr or of another module is a **contract** - never its code. Declare the ones you use with a
+version range, and the module API level that has contracts:
 
 ```json
 {
-  "engines": { "tabbr": "^1.1" },
-  "uses": { "sys.access": "^1" }
+  "engines": { "tabbr": "^1.3" },
+  "uses": { "sys.access": "^1" },
+  "optionalUses": { "tabbr.consent": "^1" }
 }
 ```
 
-`publish` puts `uses` in the manifest (also for a module without backend code); Tabbr only installs the module where
-the club has those contracts, and its server-side part gets them as `tabbr.uses['sys.access']`. The frontend gets a
-contract with the SDK's `MODULE_CONTRACTS` (`await inject(MODULE_CONTRACTS).get('sys.access')`). Their types come from
-`fetch-types --contracts` (below). See `docs/module-contracts.md` in the Tabbr repository.
+`publish` puts `uses` and `optionalUses` in the manifest (also for a module without backend code); Tabbr only installs
+the module where the club has the contracts in `uses` (`optionalUses`: it works without them), and its server-side part
+gets them as `tabbr.uses['sys.access']`. The frontend gets a contract with the SDK's `MODULE_CONTRACTS` (`await
+inject(MODULE_CONTRACTS).get('sys.access')`, `null` when the club doesn't have it). Their types come from
+`fetch-types --contracts` (below).
+
+A module can **provide** a contract too (module API 1.3), named after its publisher:
+
+```json
+{
+  "provides": { "acme.groups": { "version": "1.0.0", "types": "contracts/acme.groups.d.ts" } }
+}
+```
+
+The `.d.ts` stands on its own (no imports) and exports `interface Frontend` and/or `interface Backend`; `publish` puts
+it in the build (`backend/contracts/acme.groups.d.ts`), where Tabbr serves it to the modules that use the contract. Your
+module class offers the frontend part as `provides = { 'acme.groups': ... }`, your server-side part exports the backend
+part as `export const provides = { 'acme.groups': { ... } }`. See `docs/module-contracts.md` in the Tabbr repository.
 
 ## Usage: publish
 
@@ -260,8 +275,9 @@ points) to your workspace's `.gitignore` rather than committing them.
 npx tabbr-module fetch-types --contracts [--cwd .] [--api-host https://api.tabbr.be]
 ```
 
-**With `--contracts`**: fetches `GET /api/contracts/{name}/types` for every contract in `uses` into
-`contracts/<name>.d.ts`. Unlike the entity types these don't depend on a club - **commit them**: the store builds your
+**With `--contracts`**: fetches `GET /api/contracts/{name}/types` for every contract in `uses` and `optionalUses` into
+`contracts/<name>.d.ts`. Tabbr's own don't depend on a club; one a module provides comes from your club (`club` in
+tabbr.config.json) when a module there provides it, else from the module store - **commit them**: the store builds your
 module with them. Add `contracts/*.d.ts` to your tsconfig(s); it types `MODULE_CONTRACTS.get(name)` and
 `tabbr.uses[name]`, and its own types can be imported from `@tabbr/contracts/<name>`.
 

package/bin/tabbr-module.js

@@ -106,10 +106,12 @@ publishing it - what the store's builder runs.
 
 Usage: tabbr-module fetch-types --contracts [--cwd <path>] [--api-host <url>]
 
-Fetches the contracts the module uses ("uses" in ${CONFIG_FILE}, e.g. { "sys.access": "^1" }) into
-contracts/<name>.d.ts - commit them: the store builds your module with them. Include contracts/ in your
-tsconfig(s); then MODULE_CONTRACTS.get('<name>') (frontend) and tabbr.uses['<name>'] (backend) are typed,
-and the contract's own types can be imported from '@tabbr/contracts/<name>'. No --club needed.
+Fetches the contracts the module uses ("uses" and "optionalUses" in ${CONFIG_FILE}, e.g.
+{ "sys.access": "^1" }) into contracts/<name>.d.ts - commit them: the store builds your module with them.
+Include contracts/ in your tsconfig(s); then MODULE_CONTRACTS.get('<name>') (frontend) and
+tabbr.uses['<name>'] (backend) are typed, and the contract's own types can be imported from
+'@tabbr/contracts/<name>'. Tabbr's own contracts need no --club; one a module provides comes from your club
+(${CONFIG_FILE} "club") when a module there provides it, else from the module store.
 
 Usage: tabbr-module fetch-types [--club <CODE>] [--entity <name>] [options]
 
@@ -260,9 +262,10 @@ ${dts}
   console.log(`Wrote ${outPath}`);
 }
 
-/** One file per contract the module uses: contracts/<name>.d.ts. */
+/** One file per contract the module uses (also optionally): contracts/<name>.d.ts. */
 async function runFetchContractTypes(args) {
-  const names = Object.keys(usesOf(args));
+  const uses = { ...usesOf(args, 'optionalUses'), ...usesOf(args) };
+  const names = Object.keys(uses);
   if (names.length === 0) {
     throw new Error(`No contracts to fetch: add "uses" to ${CONFIG_FILE}, e.g. "uses": { "sys.access": "^1" }.`);
   }
@@ -270,10 +273,11 @@ async function runFetchContractTypes(args) {
   const dir = path.join(args.cwd, 'contracts');
   fs.mkdirSync(dir, { recursive: true });
   for (const name of names) {
-    const dts = await fetchContractTypes({ apiHost: args.apiHost, name, accessToken });
+    // with a club: a contract one of its modules provides comes from there (else from the store)
+    const dts = await fetchContractTypes({ apiHost: args.apiHost, name, accessToken, club: args.club });
     const outPath = path.join(dir, `${name}.d.ts`);
     fs.writeFileSync(outPath, dts);
-    console.log(`Wrote ${outPath} (${args.uses[name]})`);
+    console.log(`Wrote ${outPath} (${uses[name]})`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabbr/module-cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Set up, build and publish a Native Federation club module to a tabbr club.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "SystemWorks BV",

package/src/backend-build.js

@@ -46,27 +46,67 @@ function entitiesOf(config) {
   return entities;
 }
 
+const CONTRACT_NAME = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+
 /**
- * The contracts the module uses (`"uses"` in tabbr.config.json, e.g. `{ "sys.access": "^1" }`): their names and version
- * ranges, checked just enough to fail here - Tabbr checks them again (a contract it doesn't have, a range it can't
- * satisfy) when the module is published or installed.
+ * The contracts the module uses (`"uses"` in tabbr.config.json, e.g. `{ "sys.access": "^1" }`), or uses when the club
+ * has them (`key` `"optionalUses"`): their names and version ranges, checked just enough to fail here - Tabbr checks
+ * them again (a contract it doesn't have, a range it can't satisfy) when the module is published or installed.
  */
-function usesOf(config) {
-  const uses = config.uses || {};
+function usesOf(config, key = 'uses') {
+  const uses = config[key] || {};
   if (typeof uses !== 'object' || Array.isArray(uses)) {
-    throw new Error('"uses" in tabbr.config.json must be an object: { "<contract>": "<version range>" }, e.g. { "sys.access": "^1" }.');
+    throw new Error(`"${key}" in tabbr.config.json must be an object: { "<contract>": "<version range>" }, e.g. { "sys.access": "^1" }.`);
   }
   for (const [name, range] of Object.entries(uses)) {
-    if (!/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/.test(name)) {
-      throw new Error(`"uses": "${name}" is not a contract name (e.g. "sys.access").`);
+    if (!CONTRACT_NAME.test(name)) {
+      throw new Error(`"${key}": "${name}" is not a contract name (e.g. "sys.access").`);
     }
     if (typeof range !== 'string' || !range.trim()) {
-      throw new Error(`"uses": "${name}" needs a version range, e.g. "^1".`);
+      throw new Error(`"${key}": "${name}" needs a version range, e.g. "^1".`);
     }
   }
   return uses;
 }
 
+/**
+ * The contracts the module provides itself (`"provides"` in tabbr.config.json, e.g.
+ * `{ "acme.groups": { "version": "1.0.0", "types": "contracts/acme.groups.d.ts" } }`): for the manifest their names and
+ * versions, and their TypeScript - which goes into the build as `backend/contracts/<name>.d.ts`, where Tabbr serves it
+ * to the modules that use the contract. The file stands on its own (no imports) and exports `interface Frontend`
+ * and/or `interface Backend`. Tabbr checks the rest (the name is the publisher's, no other module has it).
+ */
+function providesOf(cwd, config) {
+  const provides = config.provides || {};
+  if (typeof provides !== 'object' || Array.isArray(provides)) {
+    throw new Error('"provides" in tabbr.config.json must be an object: { "<contract>": { "version": "1.0.0", "types": "contracts/<contract>.d.ts" } }.');
+  }
+  const versions = {};
+  const files = {};
+  for (const [name, contract] of Object.entries(provides)) {
+    if (!CONTRACT_NAME.test(name) || name.startsWith('sys.')) {
+      throw new Error(`"provides": "${name}" is not a contract name a module can provide (e.g. "acme.groups"; "sys." is Tabbr's).`);
+    }
+    if (!contract || !/^\d+\.\d+\.\d+$/.test(contract.version || '')) {
+      throw new Error(`"provides": "${name}" needs a version, e.g. { "version": "1.0.0" }.`);
+    }
+    const typesPath = path.join(cwd, contract.types || `contracts/${name}.d.ts`);
+    if (!fs.existsSync(typesPath)) {
+      throw new Error(`"provides": the TypeScript of "${name}" is missing: ${typesPath}.`);
+    }
+    const source = fs.readFileSync(typesPath, 'utf8');
+    if (!/\bexport\s+interface\s+(Frontend|Backend)\b/.test(source)) {
+      throw new Error(`"provides": ${typesPath} exports neither interface Frontend nor interface Backend.`);
+    }
+    if (/^\s*import\b/m.test(source)) {
+      throw new Error(`"provides": ${typesPath} may not import anything - a contract stands on its own.`);
+    }
+    versions[name] = contract.version;
+    files[`contracts/${name}.d.ts`] = source;
+  }
+  return { versions, files };
+}
+
 /**
  * Bundles a module workspace's backend part (if configured) into a single, dependency-free
  * `bundle.js`, using esbuild so module authors can write normal TypeScript (types, imports,
@@ -75,18 +115,21 @@ function usesOf(config) {
  * `BackendModuleRuntimeService`).
  *
  * Also writes the manifest the server reads (`manifest.json`): the backend config plus the entities the module declares
- * and the contracts it uses - which a module can do without any backend code, so then only the manifest is produced
- * (`bundleJs` null).
+ * and the contracts it uses and provides - which a module can do without any backend code, so then only the manifest
+ * is produced (`bundleJs` null). `files`: more files for the build's `backend/` (the TypeScript of what it provides).
  *
- * Returns `null` when the workspace has no backend part, no entities and uses no contracts, so `build.js` can skip
- * it entirely for such a frontend-only module.
+ * Returns `null` when the workspace has no backend part, no entities and uses or provides no contracts, so `build.js`
+ * can skip it entirely for such a frontend-only module.
  */
 async function buildBackend(cwd, config) {
   const backendConfig = config.backend;
   const entities = entitiesOf(config);
   const uses = usesOf(config);
+  const optionalUses = usesOf(config, 'optionalUses');
+  const provides = providesOf(cwd, config);
   const bundleJs = backendConfig ? await bundle(cwd, backendConfig) : null;
-  if (bundleJs == null && entities.length === 0 && Object.keys(uses).length === 0) {
+  if (bundleJs == null && entities.length === 0 && Object.keys(uses).length === 0 && Object.keys(optionalUses).length === 0
+    && Object.keys(provides.versions).length === 0) {
     return null;
   }
   const settings = backendConfig || {};
@@ -100,9 +143,12 @@ async function buildBackend(cwd, config) {
     manageRoles: bundleJs != null && settings.manageRoles === true,
     // the contracts it uses - for its frontend part as well, so the manifest is written for a frontend-only module too
     uses,
+    optionalUses,
+    // the contracts it provides, with their version; their TypeScript goes along as backend/contracts/<name>.d.ts
+    provides: provides.versions,
   };
 
-  return { bundleJs, manifestJson: JSON.stringify(manifest, null, 2) };
+  return { bundleJs, manifestJson: JSON.stringify(manifest, null, 2), files: provides.files };
 }
 
 /** The backend entry bundled into one script, or null when there is no entry file (and none was configured explicitly). */
@@ -145,4 +191,4 @@ async function bundle(cwd, backendConfig) {
   return result.outputFiles[0].text;
 }
 
-module.exports = { buildBackend, entitiesOf, usesOf, DEFAULT_ENTRY };
+module.exports = { buildBackend, entitiesOf, usesOf, providesOf, DEFAULT_ENTRY };

package/src/build.js

@@ -82,6 +82,9 @@ function zipModule(frontendDir, backend) {
         archive.append(backend.bundleJs, { name: 'backend/bundle.js' });
       }
       archive.append(backend.manifestJson, { name: 'backend/manifest.json' });
+      for (const [name, content] of Object.entries(backend.files || {})) {
+        archive.append(content, { name: `backend/${name}` });
+      }
     }
     archive.finalize();
   });

package/src/fetch-types.js

@@ -51,10 +51,13 @@ async function fetchAllEntityTypes({ apiHost, club, accessToken }) {
  * `@tabbr/contracts/<name>`, plus its entries in `TabbrUiContracts` (what `MODULE_CONTRACTS.get(name)` returns) and
  * `TabbrContracts` (`tabbr.uses[name]` server-side). See docs/module-contracts.md (tabbr repo).
  */
-async function fetchContractTypes({ apiHost, name, accessToken }) {
+async function fetchContractTypes({ apiHost, name, accessToken, club }) {
   const url = `${apiHost}/api/contracts/${encodeURIComponent(name)}/types`;
   console.log(`Fetching the contract ${name} from ${url} ...`);
-  const response = await fetch(url, { headers: { Authorization: `Bearer ${accessToken}` } });
+  const headers = { Authorization: `Bearer ${accessToken}` };
+  // a contract a module provides: the club's version of it, when the club has that module
+  if (club) headers['X-club'] = club.toUpperCase();
+  const response = await fetch(url, { headers });
   if (!response.ok) {
     throw new Error(`Fetching the contract ${name} failed: ${response.status} ${await response.text()}`);
   }