@acid-cat/catalog 0.4.0 → 0.5.0

package/README.md

@@ -11,17 +11,19 @@ pnpm add -D @acid-cat/catalog
 ```ts
 import { Catalog } from "@acid-cat/catalog";
 
-const catalog = new Catalog({ title: "Living-room air conditioner" });
-catalog.target("cli", { bindings: ["cli"] });
-const offline = catalog.type("Offline", { type: "object" });
-catalog.capability("aircon.power.set", {
-  description: "Turn the unit on or off.",
-  audience: ["cli"],
-  input: { type: "object", required: ["on"], properties: { on: { type: "boolean" } } },
-  failures: { Offline: offline },
+const catalog = new Catalog({ title: "Neighbourhood lending library" });
+catalog.target("desk", { bindings: ["cli"] });
+const notFound = catalog.type("NotFound", { type: "object" });
+catalog.capability("library.loan.return", {
+  description: "Take a book back from a member.",
+  audience: ["desk"],
+  input: { type: "object", required: ["loan"], properties: { loan: { type: "string" } } },
+  failures: { NotFound: notFound },
 });
 
 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/aircon.ts`](examples/aircon.ts). Test with `moon run catalog-typescript:test`.
+`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

@@ -2,16 +2,9 @@
  * The canonical form of a catalog (spec/catalog.md#canonical-form): the one way to write a catalog as text, so that
  * every tool and every catalog library produces the same bytes for the same catalog.
  */
-type Json = null | boolean | number | string | readonly Json[] | {
-    readonly [key: string]: Json;
-};
-type JsonObject = {
-    readonly [key: string]: Json;
-};
 /** 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: JsonObject): JsonObject;
+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;
-export {};

package/dist/canonical.js

@@ -1,4 +1,5 @@
 //#region src/canonical.ts
+const isObject = (value) => value !== null && typeof value === "object";
 const CATALOG_ORDER = [
 	"acidcat",
 	"title",
@@ -34,33 +35,34 @@ function canonicalCatalog(catalog) {
 		return sortedMember(key, value);
 	});
 }
-/** The known members in their order, then every other member sorted by key. */
+/** 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);
 	const others = Object.keys(value).filter((key) => !order.includes(key)).sort(byCodePoint);
 	return Object.fromEntries([...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 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) {
-	const object = value;
-	return Object.fromEntries(Object.keys(object).sort(byCodePoint).map((key) => [key, each(object[key])]));
+	if (!isObject(value)) return sorted(value);
+	return Object.fromEntries(Object.keys(value).sort(byCodePoint).map((key) => [key, each(value[key])]));
 }
 function sortedMember(_key, value) {
 	return sorted(value);
 }
 /** Every object's keys sorted, at every depth. Arrays keep their order. */
 function sorted(value) {
-	if (Array.isArray(value)) return value.map(sorted);
-	if (value !== null && typeof value === "object") return byKey(value, sorted);
+	if (Array.isArray(value)) return value.map((item) => sorted(item));
+	if (isObject(value)) return byKey(value, sorted);
 	return value;
 }
 /** Order strings by Unicode code point, as Python, Go and Rust compare them. */
 function byCodePoint(left, right) {
-	const a = [...left];
-	const b = [...right];
+	const a = Array.from(left, (character) => character.codePointAt(0));
+	const b = Array.from(right, (character) => character.codePointAt(0));
 	for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
-		const difference = a[i].codePointAt(0) - b[i].codePointAt(0);
-		if (difference !== 0) return difference;
+		const [first, second] = [a[i], b[i]];
+		if (first !== void 0 && second !== void 0 && first !== second) return first - second;
 	}
 	return a.length - b.length;
 }
@@ -71,7 +73,7 @@ function write(value, indent) {
 		const inner = `${indent}  `;
 		return `[\n${value.map((item) => inner + write(item, inner)).join(",\n")}\n${indent}]`;
 	}
-	if (value !== null && typeof value === "object") {
+	if (isObject(value)) {
 		const keys = Object.keys(value);
 		if (keys.length === 0) return "{}";
 		const inner = `${indent}  `;

package/dist/index.js

@@ -107,7 +107,7 @@ var Catalog = class {
 			if ("$defs" in node) 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 ${String(node.$ref)}, which is not a type`);
+			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`);
 		});
 		return problems;
 	}
@@ -115,9 +115,11 @@ var Catalog = class {
 function compact(value) {
 	return Object.fromEntries(Object.entries(value).filter(([, member]) => member !== void 0));
 }
+/** Tell if a value is an object that is not `null`. Each of its members is read as `unknown`. */
+const isRecord = (value) => value !== null && typeof value === "object";
 function visit(value, onObject) {
 	if (Array.isArray(value)) value.forEach((item) => visit(item, onObject));
-	else if (value !== null && typeof value === "object") {
+	else if (isRecord(value)) {
 		onObject(value);
 		Object.values(value).forEach((item) => visit(item, onObject));
 	}

package/package.json

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