@acid-cat/spec-ts 0.10.0 → 0.10.2

package/README.md

@@ -17,5 +17,8 @@ pnpm add @acid-cat/spec-ts
 | `CALL_FAILURE_KINDS`, `CallFailureError` | The kinds of call failure, and the JavaScript error for one |
 | `AVAILABLE`, `unavailable` | Make [availability](../../spec/invocation.md#availability) values |
 | `viewOf`, `bundle` | The [view](../../spec/catalog.md#views) of a target, and a schema with its shared types |
+| `resolveType` | The type that the `$ref` of a schema refers to, whatever other keys the schema has |
+| `ownMember` | The member of an object with a key, or `undefined`. Inherited names, such as `constructor`, are not members |
+| `byCodePoint` | Order strings by Unicode code point, as the [canonical form](../../spec/catalog.md#canonical-form) sorts keys |
 
 The other exports give the names, flags, exit codes and tool shapes of each [binding](../../spec/bindings/README.md).

package/dist/index.d.ts

@@ -202,6 +202,11 @@ export declare function mcpSubscribeError(failure: CallFailure): {
 export declare function mcpEventEntry(id: string, description: string, input: JsonObject | undefined, payload: JsonObject | undefined, webhook?: boolean): JsonObject;
 /** The params of `notifications/events/event` for an occurrence: the occurrence without `truncated`. */
 export declare function mcpEventParams(occurrence: Occurrence, subscriptionId: string | number): JsonObject;
+/**
+ * Order strings by Unicode code point. The `<` operator compares UTF-16 code units, which put a character after U+FFFF
+ * before a character from U+E000 to U+FFFF.
+ */
+export declare function byCodePoint(left: string, right: string): number;
 /** The canonical JSON of a value (spec/bindings/mcp.md#canonical-json): no spaces, and the keys of each object in code point order. */
 export declare function canonicalJson(value: unknown): string;
 /** The defaults of poll delivery (spec/bindings/mcp.md#poll). */
@@ -304,6 +309,13 @@ export interface CatalogDocument extends JsonObject {
 export declare const REFERENCE: RegExp;
 /** Tell if a value is a JSON object: an object that is not `null` and not an array. */
 export declare const isJsonObject: (value: unknown) => value is JsonObject;
+/**
+ * The member of an object with this key, or `undefined` when the object does not have it. Inherited names, such as
+ * `constructor` or `toString`, are not members.
+ */
+export declare function ownMember<Value>(object: {
+    readonly [key: string]: Value;
+}, key: string): Value | undefined;
 /** The schemas of a capability, each with the member that holds it. */
 export declare function schemasOf(capability: CatalogCapability): readonly (readonly [string, JsonObject])[];
 /** The schemas of an event, each with the member that holds it. */
@@ -322,6 +334,14 @@ export declare function typesUsedBy(schema: unknown, types: {
 export declare function objectInput(schema: JsonObject, types: {
     readonly [name: string]: JsonObject;
 }): JsonObject;
+/**
+ * The type that a schema's `$ref` refers to, whatever other keys the schema has, or the schema itself when it has no
+ * `$ref` to a type in `types`. A catalog uses it to tell if an input or a payload is an object
+ * (spec/catalog.md#capabilities).
+ */
+export declare function resolveType(schema: JsonObject, types: {
+    readonly [name: string]: JsonObject;
+}): JsonObject;
 /** Bundle a schema (spec/catalog.md#bundling). */
 export declare function bundle(schema: JsonObject, types: {
     readonly [name: string]: JsonObject;

package/dist/index.js

@@ -1,4 +1,4 @@
-//#region src/index.ts
+// src/index.ts
 /**
 * The fixed details of the AcidCat specification, as TypeScript data and pure functions, for the TypeScript reference
 * implementation. This package has no dependencies.
@@ -101,8 +101,7 @@ function cliFlags(input) {
 	const properties = objectOrEmpty(input.properties);
 	const definitions = objectOrEmpty(input.$defs);
 	const required = new Set(stringsOf(input.required));
-	const byName = (a, b) => a < b ? -1 : a > b ? 1 : 0;
-	const names = Object.keys(properties).sort(byName);
+	const names = Object.keys(properties).sort(byCodePoint);
 	return [...names.filter((name) => required.has(name)), ...names.filter((name) => !required.has(name))].map((name) => {
 		const property = cliResolve(objectOrEmpty(properties[name]), definitions);
 		const items = cliRepeatedItems(property, definitions);
@@ -112,8 +111,8 @@ function cliFlags(input) {
 }
 /** A property schema, or the type in `definitions` that its `$ref` refers to. */
 function cliResolve(property, definitions) {
-	const target = typeof property.$ref === "string" ? REFERENCE.exec(property.$ref)?.[1] : void 0;
-	return target === void 0 ? property : objectOrEmpty(definitions[target] ?? property);
+	const target = referenceName(property);
+	return target === void 0 ? property : objectOrEmpty(ownMember(definitions, target) ?? property);
 }
 /**
 * The schema of the items of a repeated flag (spec/bindings/cli.md#commands), or `undefined` when the property does
@@ -328,10 +327,23 @@ function mcpEventParams(occurrence, subscriptionId) {
 		_meta: { [MCP_SUBSCRIPTION_ID]: subscriptionId }
 	};
 }
+/**
+* Order strings by Unicode code point. The `<` operator compares UTF-16 code units, which put a character after U+FFFF
+* before a character from U+E000 to U+FFFF.
+*/
+function byCodePoint(left, right) {
+	const a = Array.from(left, (character) => character.codePointAt(0) ?? 0);
+	const b = Array.from(right, (character) => character.codePointAt(0) ?? 0);
+	for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
+		const difference = (a[i] ?? 0) - (b[i] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	return a.length - b.length;
+}
 /** The canonical JSON of a value (spec/bindings/mcp.md#canonical-json): no spaces, and the keys of each object in code point order. */
 function canonicalJson(value) {
 	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-	if (isJsonObject(value)) return `{${Object.keys(value).sort((a, b) => a < b ? -1 : a > b ? 1 : 0).map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+	if (isJsonObject(value)) return `{${Object.keys(value).sort(byCodePoint).map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
 	return JSON.stringify(value) ?? "null";
 }
 /** The defaults of poll delivery (spec/bindings/mcp.md#poll). */
@@ -552,8 +564,17 @@ function mcpToolResult(outcome, hasOutputSchema) {
 	} : { content: text(outcome.value) };
 }
 const REFERENCE = /^#\/\$defs\/([A-Za-z][A-Za-z0-9_]*)$/;
+/** The name of the type that a schema's `$ref` refers to, or `undefined` when it has no `$ref` of that form. */
+const referenceName = (schema) => typeof schema.$ref === "string" ? REFERENCE.exec(schema.$ref)?.[1] : void 0;
 /** Tell if a value is a JSON object: an object that is not `null` and not an array. */
 const isJsonObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* The member of an object with this key, or `undefined` when the object does not have it. Inherited names, such as
+* `constructor` or `toString`, are not members.
+*/
+function ownMember(object, key) {
+	return Object.hasOwn(object, key) ? object[key] : void 0;
+}
 /** A value as a JSON object, or an empty object when it is not one. */
 const objectOrEmpty = (value) => isJsonObject(value) ? value : {};
 /** The strings in a value that is an array, or no strings when it is not an array. */
@@ -583,8 +604,8 @@ function visitObjects(value, onObject) {
 function typesUsedBy(schema, types) {
 	const used = /* @__PURE__ */ new Map();
 	const collect = (node) => visitObjects(node, (inner) => {
-		const name = typeof inner.$ref === "string" ? REFERENCE.exec(inner.$ref)?.[1] : void 0;
-		const type = name === void 0 ? void 0 : types[name];
+		const name = referenceName(inner);
+		const type = name === void 0 ? void 0 : ownMember(types, name);
 		if (name !== void 0 && type !== void 0 && !used.has(name)) {
 			used.set(name, type);
 			collect(type);
@@ -601,9 +622,8 @@ function typesUsedBy(schema, types) {
 function objectInput(schema, types) {
 	const resolve = (node) => {
 		if (!isJsonObject(node)) return void 0;
-		const object = node;
-		const name = typeof object.$ref === "string" ? REFERENCE.exec(object.$ref)?.[1] : void 0;
-		return name === void 0 ? object : types[name];
+		const name = referenceName(node);
+		return name === void 0 ? node : ownMember(types, name);
 	};
 	const target = resolve(schema);
 	if (schema.type !== void 0 || target === void 0 || target.type !== void 0) return schema;
@@ -614,10 +634,18 @@ function objectInput(schema, types) {
 		...schema
 	} : schema;
 }
+/**
+* The type that a schema's `$ref` refers to, whatever other keys the schema has, or the schema itself when it has no
+* `$ref` to a type in `types`. A catalog uses it to tell if an input or a payload is an object
+* (spec/catalog.md#capabilities).
+*/
+function resolveType(schema, types) {
+	const name = referenceName(schema);
+	return (name === void 0 ? void 0 : ownMember(types, name)) ?? schema;
+}
 /** Bundle a schema (spec/catalog.md#bundling). */
 function bundle(schema, types) {
-	const only = Object.keys(schema).length === 1 ? REFERENCE.exec(String(schema.$ref))?.[1] : void 0;
-	const base = only === void 0 ? schema : types[only] ?? schema;
+	const base = Object.keys(schema).length === 1 ? resolveType(schema, types) : schema;
 	const used = typesUsedBy(base, types);
 	return used.size === 0 ? base : {
 		...base,
@@ -639,7 +667,7 @@ function viewOf(catalog, target) {
 	const schemas = [...Object.values(capabilities).flatMap(schemasOf), ...Object.values(events).flatMap(eventSchemasOf)];
 	for (const [, schema] of schemas) for (const [name, type] of typesUsedBy(schema, types)) used.set(name, type);
 	const { $defs: _, events: __, ...rest } = catalog;
-	const declared = catalog.targets[target];
+	const declared = ownMember(catalog.targets, target);
 	return {
 		...rest,
 		targets: declared === void 0 ? {} : { [target]: declared },
@@ -648,5 +676,4 @@ function viewOf(catalog, target) {
 		...Object.keys(events).length > 0 ? { events } : {}
 	};
 }
-//#endregion
-export { AVAILABLE, CALL_FAILURE_KINDS, CLI_EXIT_CODES, CLI_RESUME_FLAGS, CLI_WATCH_EXIT_CODES, CallFailureError, HTTP_STATUS, ID_PATTERN, KEEPALIVE_MS, MCP_EVENTS_EXTENSION, MCP_EVENT_ERRORS, MCP_POLL_DEFAULTS, MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_SUBSCRIPTION_ID, MCP_UNKNOWN_TOOL, MCP_WEBHOOK_DEFAULTS, REFERENCE, SSE_MEDIA_TYPE, SUBSCRIBE_FAILURE_KINDS, WEBHOOK_ERRORS, bundle, callFailure, canonicalJson, cliEventUsage, cliExitCode, cliFlags, cliJsonArray, cliRepeatedItems, cliResolve, cliUsage, commandPath, decodePollCursor, encodePollCursor, eventSchemasOf, fail, httpEventMessage, httpStatus, isCallFailure, isGloballyRoutable, isId, isJsonObject, isOccurrence, mcpEventEntry, mcpEventParams, mcpSubscribeError, mcpToolResult, objectInput, occurrenceOf, ok, readBounded, schemasOf, screenRequest, sseMessage, typesUsedBy, unavailable, viewOf, visitObjects, webhookGrantMs, webhookSecretBytes, webhookSignature, webhookSignedText, webhookSubscriptionId };
+export { AVAILABLE, CALL_FAILURE_KINDS, CLI_EXIT_CODES, CLI_RESUME_FLAGS, CLI_WATCH_EXIT_CODES, CallFailureError, HTTP_STATUS, ID_PATTERN, KEEPALIVE_MS, MCP_EVENTS_EXTENSION, MCP_EVENT_ERRORS, MCP_POLL_DEFAULTS, MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_SUBSCRIPTION_ID, MCP_UNKNOWN_TOOL, MCP_WEBHOOK_DEFAULTS, REFERENCE, SSE_MEDIA_TYPE, SUBSCRIBE_FAILURE_KINDS, WEBHOOK_ERRORS, bundle, byCodePoint, callFailure, canonicalJson, cliEventUsage, cliExitCode, cliFlags, cliJsonArray, cliRepeatedItems, cliResolve, cliUsage, commandPath, decodePollCursor, encodePollCursor, eventSchemasOf, fail, httpEventMessage, httpStatus, isCallFailure, isGloballyRoutable, isId, isJsonObject, isOccurrence, mcpEventEntry, mcpEventParams, mcpSubscribeError, mcpToolResult, objectInput, occurrenceOf, ok, ownMember, readBounded, resolveType, schemasOf, screenRequest, sseMessage, typesUsedBy, unavailable, viewOf, visitObjects, webhookGrantMs, webhookSecretBytes, webhookSignature, webhookSignedText, webhookSubscriptionId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/spec-ts",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "The fixed details of the AcidCat specification as TypeScript data and pure functions, with no dependencies. Part of the TypeScript reference implementation.",
   "keywords": [
     "acidcat",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "26.6.5",
+    "@types/node": "26.6.6",
     "typescript": "7.0.2"
   }
 }