@acid-cat/catalog 0.9.0 → 0.10.1

package/README.md

@@ -9,6 +9,8 @@ pnpm add -D @acid-cat/catalog
 ```
 
 ```ts
+import { writeFile } from "node:fs/promises";
+
 import { Catalog } from "@acid-cat/catalog";
 
 const catalog = new Catalog({ title: "Neighbourhood lending library" });
@@ -20,10 +22,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.d.ts

@@ -4,7 +4,5 @@
  */
 /** A catalog in canonical form, as text. */
 export declare function canonicalText(catalog: unknown): string;
-/** Put a catalog's members in canonical order. */
-export declare function canonicalCatalog(catalog: unknown): unknown;
 /** Order strings by Unicode code point, as Python, Go and Rust compare them. */
 export declare function byCodePoint(left: string, right: string): number;

package/dist/canonical.js

@@ -1,4 +1,4 @@
-//#region src/canonical.ts
+// src/canonical.ts
 const isObject = (value) => value !== null && typeof value === "object";
 const CATALOG_ORDER = [
 	"acidcat",
@@ -6,7 +6,8 @@ const CATALOG_ORDER = [
 	"description",
 	"targets",
 	"$defs",
-	"capabilities"
+	"capabilities",
+	"events"
 ];
 const TARGET_ORDER = [
 	"bindings",
@@ -22,30 +23,40 @@ 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`;
 }
-/** Put a catalog's members in canonical order. */
+/**
+* Put a catalog's members in canonical order. Each object becomes a `Map`, not a plain object, because a plain object
+* puts integer-like keys such as "9" and "10" first, in numeric order, whatever order they were added in.
+*/
 function canonicalCatalog(catalog) {
 	return ordered(catalog, CATALOG_ORDER, (key, value) => {
 		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);
 	});
 }
 /** The known members in their order, then every other member sorted by key. A value that is not an object is sorted. */
 function ordered(value, order, each) {
-	if (!isObject(value)) return sorted(value);
-	const known = order.filter((key) => key in value);
+	if (!isObject(value) || Array.isArray(value)) return sorted(value);
+	const known = order.filter((key) => Object.hasOwn(value, key));
 	const others = Object.keys(value).filter((key) => !order.includes(key)).sort(byCodePoint);
-	return Object.fromEntries([...known, ...others].map((key) => [key, each(key, value[key])]));
+	return new Map([...known, ...others].map((key) => [key, each(key, value[key])]));
 }
 /** A map keyed by name or id: its keys sorted, each value shaped by `each`. A value that is not an object is sorted. */
 function byKey(value, each) {
-	if (!isObject(value)) return sorted(value);
-	return Object.fromEntries(Object.keys(value).sort(byCodePoint).map((key) => [key, each(value[key])]));
+	if (!isObject(value) || Array.isArray(value)) return sorted(value);
+	return new Map(Object.keys(value).sort(byCodePoint).map((key) => [key, each(value[key])]));
 }
 function sortedMember(_key, value) {
 	return sorted(value);
@@ -66,21 +77,21 @@ function byCodePoint(left, right) {
 	}
 	return a.length - b.length;
 }
-/** Write a JSON value with two-space indentation, one member or item per line. */
+/** Write a JSON value with two-space indentation, one member or item per line. A `Map` keeps its order. */
 function write(value, indent) {
 	if (Array.isArray(value)) {
 		if (value.length === 0) return "[]";
 		const inner = `${indent}  `;
 		return `[\n${value.map((item) => inner + write(item, inner)).join(",\n")}\n${indent}]`;
 	}
-	if (isObject(value)) {
-		const keys = Object.keys(value);
-		if (keys.length === 0) return "{}";
+	if (value instanceof Map) {
+		const entries = [...value];
+		if (entries.length === 0) return "{}";
 		const inner = `${indent}  `;
-		return `{\n${keys.map((key) => `${inner}${JSON.stringify(key)}: ${write(value[key], inner)}`).join(",\n")}\n${indent}}`;
+		return `{\n${entries.map(([key, member]) => `${inner}${JSON.stringify(key)}: ${write(member, inner)}`).join(",\n")}\n${indent}}`;
 	}
+	if (isObject(value)) return write(sorted(value), indent);
 	if (typeof value === "number" && !Number.isFinite(value)) throw new TypeError("A catalog holds only finite numbers");
 	return JSON.stringify(value);
 }
-//#endregion
-export { byCodePoint, canonicalCatalog, canonicalText };
+export { byCodePoint, canonicalText };

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

@@ -1,5 +1,5 @@
 import { canonicalText } from "./canonical.js";
-//#region src/index.ts
+// src/index.ts
 /**
 * Write an AcidCat catalog in TypeScript, and render it to the JSON document the toolchain checks.
 *
@@ -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
 			})]))
 		});
 	}
@@ -104,7 +129,7 @@ var Catalog = class {
 	#referenceProblems(schema) {
 		const problems = [];
 		visit(schema, (node) => {
-			if ("$defs" in node) problems.push("carries its own $defs; declare shared types with type()");
+			if (Object.hasOwn(node, "$defs")) problems.push("carries its own $defs; declare shared types with type()");
 			if (node.$ref === void 0) return;
 			const name = typeof node.$ref === "string" ? REFERENCE.exec(node.$ref)?.[1] : void 0;
 			if (name === void 0 || !this.#types.has(name)) problems.push(`references ${typeof node.$ref === "string" ? node.$ref : JSON.stringify(node.$ref)}, which is not a type`);
@@ -124,5 +149,4 @@ function visit(value, onObject) {
 		Object.values(value).forEach((item) => visit(item, onObject));
 	}
 }
-//#endregion
 export { Catalog, canonicalText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/catalog",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Write an AcidCat catalog in TypeScript and render it in canonical form.",
   "keywords": [
     "acidcat",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "26.6.5",
+    "@types/node": "26.6.6",
     "typescript": "7.0.2"
   }
 }