@acid-cat/catalog 0.8.0 → 0.10.0

package/README.md

@@ -20,10 +20,17 @@ catalog.capability("library.loan.return", {
   input: { type: "object", required: ["loan"], properties: { loan: { type: "string" } } },
   failures: { NotFound: notFound },
 });
+const book = catalog.type("Book", { type: "object", properties: { isbn: { type: "string" } } });
+catalog.event("library.book.returned", {
+  description: "A member returned a book. The occurrence gives the book.",
+  audience: ["desk"],
+  input: { type: "object", properties: {} },
+  payload: book,
+});
 
 await writeFile("acidcat.catalog.json", catalog.render());
 ```
 
-`validate()` lists the rules a catalog breaks, and `render()` refuses to render one that breaks any. The full example is [`examples/library.ts`](examples/library.ts), a lending library.
+`event()` declares an [event](../../../spec/events.md): clients subscribe to it, and get its payload in each occurrence. A payload is an object, or a reference to a type that is an object. `validate()` lists the rules a catalog breaks, and `render()` refuses to render one that breaks any. The full example is [`examples/library.ts`](examples/library.ts), a lending library.
 
 The tests compare the output of the library with files in this directory: the lending-library catalog [`examples/library.acidcat.json`](examples/library.acidcat.json), and a catalog of values that languages write differently, [`test/fixtures/edge.acidcat.json`](test/fixtures/edge.acidcat.json). A test also compares [`examples/aircon.ts`](examples/aircon.ts) with the air-conditioner catalog of the repository. Each committed catalog file is in [canonical form](../../../spec/catalog.md#canonical-form), and the root `moon run check` checks this. Thus all catalog libraries agree on the canonical form, and they do not share a test file. Test with `moon run catalog-typescript:test`.

package/dist/canonical.js

@@ -6,7 +6,8 @@ const CATALOG_ORDER = [
 	"description",
 	"targets",
 	"$defs",
-	"capabilities"
+	"capabilities",
+	"events"
 ];
 const TARGET_ORDER = [
 	"bindings",
@@ -22,6 +23,12 @@ const CAPABILITY_ORDER = [
 	"readOnly",
 	"state"
 ];
+const EVENT_ORDER = [
+	"description",
+	"audience",
+	"input",
+	"payload"
+];
 /** A catalog in canonical form, as text. */
 function canonicalText(catalog) {
 	return `${write(canonicalCatalog(catalog), "")}\n`;
@@ -32,6 +39,7 @@ function canonicalCatalog(catalog) {
 		if (key === "targets") return byKey(value, (target) => ordered(target, TARGET_ORDER, sortedMember));
 		if (key === "$defs") return byKey(value, sorted);
 		if (key === "capabilities") return byKey(value, (capability) => ordered(capability, CAPABILITY_ORDER, (member, inner) => member === "failures" ? byKey(inner, sorted) : sortedMember(member, inner)));
+		if (key === "events") return byKey(value, (event) => ordered(event, EVENT_ORDER, sortedMember));
 		return sortedMember(key, value);
 	});
 }

package/dist/index.d.ts

@@ -32,6 +32,16 @@ export interface CapabilityOptions {
     /** The schema of a value that clients can observe. */
     readonly state?: Schema;
 }
+export interface EventOptions {
+    /** What happens, and when the provider sends an occurrence, written for people and agents. */
+    readonly description: string;
+    /** The targets the event is offered to. Empty means no target. */
+    readonly audience?: readonly string[];
+    /** The input schema of a subscription, for example a filter. It must describe an object. Absent means an empty object. */
+    readonly input?: Schema;
+    /** The schema of the data of each occurrence. It must describe an object. Absent means an empty object. */
+    readonly payload?: Schema;
+}
 export declare class Catalog {
     #private;
     constructor(options?: {
@@ -44,6 +54,8 @@ export declare class Catalog {
     type(name: string, schema: Schema): Schema;
     /** Declare a capability. */
     capability(id: string, options: CapabilityOptions): this;
+    /** Declare an event (spec/events.md). */
+    event(id: string, options: EventOptions): this;
     /** The catalog rules this catalog breaks. Empty when it conforms. */
     validate(): string[];
     /** The catalog as a JSON value. Throws when the catalog breaks a rule. */

package/dist/index.js

@@ -16,6 +16,7 @@ var Catalog = class {
 	#targets = /* @__PURE__ */ new Map();
 	#types = /* @__PURE__ */ new Map();
 	#capabilities = /* @__PURE__ */ new Map();
+	#events = /* @__PURE__ */ new Map();
 	constructor(options = {}) {
 		this.#title = options.title;
 		this.#description = options.description;
@@ -38,6 +39,12 @@ var Catalog = class {
 		this.#capabilities.set(id, options);
 		return this;
 	}
+	/** Declare an event (spec/events.md). */
+	event(id, options) {
+		if (this.#events.has(id)) throw new Error(`The event ${id} is declared twice`);
+		this.#events.set(id, options);
+		return this;
+	}
 	/** The catalog rules this catalog breaks. Empty when it conforms. */
 	validate() {
 		const problems = [];
@@ -52,12 +59,7 @@ var Catalog = class {
 			problems.push(...this.#referenceProblems(schema).map((problem) => `the type ${name} ${problem}`));
 		}
 		for (const [id, capability] of this.#capabilities) {
-			if (id.length > 128 || !ID.test(id)) problems.push(`the id ${id} is malformed`);
-			if (capability.description.trim() === "") problems.push(`${id} has no description`);
-			const audience = capability.audience ?? [];
-			if (new Set(audience).size !== audience.length) problems.push(`${id} repeats a target in its audience`);
-			for (const target of audience) if (!this.#targets.has(target)) problems.push(`${id} names the undeclared target ${target}`);
-			if (capability.input !== void 0 && this.#resolve(capability.input).type !== "object") problems.push(`${id} input does not describe an object`);
+			problems.push(...this.#entryProblems(id, capability));
 			const schemas = [
 				capability.input,
 				capability.output,
@@ -66,6 +68,23 @@ var Catalog = class {
 			];
 			for (const schema of schemas) if (schema !== void 0) problems.push(...this.#referenceProblems(schema).map((problem) => `${id} ${problem}`));
 		}
+		for (const [id, event] of this.#events) {
+			if (this.#capabilities.has(id)) problems.push(`${id} is both a capability and an event`);
+			problems.push(...this.#entryProblems(id, event));
+			if (event.payload !== void 0 && this.#resolve(event.payload).type !== "object") problems.push(`${id} payload does not describe an object`);
+			for (const schema of [event.input, event.payload]) if (schema !== void 0) problems.push(...this.#referenceProblems(schema).map((problem) => `${id} ${problem}`));
+		}
+		return problems;
+	}
+	/** The problems of the id, the description, the audience and the input of a capability or an event. */
+	#entryProblems(id, entry) {
+		const problems = [];
+		if (id.length > 128 || !ID.test(id)) problems.push(`the id ${id} is malformed`);
+		if (entry.description.trim() === "") problems.push(`${id} has no description`);
+		const audience = entry.audience ?? [];
+		if (new Set(audience).size !== audience.length) problems.push(`${id} repeats a target in its audience`);
+		for (const target of audience) if (!this.#targets.has(target)) problems.push(`${id} names the undeclared target ${target}`);
+		if (entry.input !== void 0 && this.#resolve(entry.input).type !== "object") problems.push(`${id} input does not describe an object`);
 		return problems;
 	}
 	/** The catalog as a JSON value. Throws when the catalog breaks a rule. */
@@ -90,6 +109,12 @@ var Catalog = class {
 				failures: Object.keys(capability.failures ?? {}).length === 0 ? void 0 : capability.failures,
 				readOnly: capability.readOnly,
 				state: capability.state
+			})])),
+			events: this.#events.size === 0 ? void 0 : Object.fromEntries([...this.#events].map(([id, event]) => [id, compact({
+				description: event.description,
+				audience: event.audience ?? [],
+				input: event.input,
+				payload: event.payload
 			})]))
 		});
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/catalog",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Write an AcidCat catalog in TypeScript and render it in canonical form.",
   "keywords": [
     "acidcat",