@acid-cat/spec-ts 0.3.1 → 0.5.0

package/README.md

@@ -12,7 +12,8 @@ pnpm add @acid-cat/spec-ts
 
 | Export | Use |
 | --- | --- |
-| `ok`, `fail`, `callFailure`, `isCallFailure` | Make and test [outcomes](../../spec/invocation.md#outcomes) |
+| `ok`, `fail`, `callFailure`, `isCallFailure` | Make and test [outcomes](../../spec/invocation.md#outcomes). `fail` takes the whole failure: `fail({ _tag: "Offline", since })` |
+| `isJsonObject` | Tell if a value is a JSON object: not `null`, and not an array |
 | `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 |

package/dist/index.d.ts

@@ -25,10 +25,10 @@ export type Result<Value, Failure> = {
 /** The end of a call: a value, a failure or a call failure. */
 export type Outcome<Value, Failure> = Result<Value, Failure> | CallFailure;
 export declare const ok: <Value>(value: Value) => Result<Value, never>;
-/** A failure with its tag, as a result. */
-export declare const fail: <Tag extends string, Data extends object = {}>(tag: Tag, data?: Data) => Result<never, {
-    readonly _tag: Tag;
-} & Data>;
+/** A failure, with its tag in `_tag`, as a result: `fail({ _tag: "Offline" })`. */
+export declare const fail: <const Failure extends {
+    readonly _tag: string;
+}>(failure: Failure) => Result<never, Failure>;
 export declare const callFailure: (kind: CallFailureKind, message: string) => CallFailure;
 export declare const isCallFailure: (outcome: Outcome<unknown, unknown>) => outcome is CallFailure;
 /** The JavaScript error for a call failure (spec/bindings/typescript.md#handles). */
@@ -143,6 +143,8 @@ 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 schemas of a capability, each with the member that holds it. */
 export declare function schemasOf(capability: CatalogCapability): readonly (readonly [string, JsonObject])[];
 /** Every object in a JSON value, at all levels. */
@@ -151,6 +153,14 @@ export declare function visitObjects(value: unknown, onObject: (node: JsonObject
 export declare function typesUsedBy(schema: unknown, types: {
     readonly [name: string]: JsonObject;
 }): Map<string, JsonObject>;
+/**
+ * An input schema that is a union of object schemas, with `"type": "object"`, so that it is an object schema
+ * (spec/catalog.md#capabilities). A union is `anyOf` or `oneOf`, directly or in the type that a `$ref` names. Each of
+ * its schemas is an object, or a `$ref` to a type that is an object. Other schemas do not change.
+ */
+export declare function objectInput(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

@@ -19,13 +19,10 @@ const ok = (value) => ({
 	ok: true,
 	value
 });
-/** A failure with its tag, as a result. */
-const fail = (tag, data) => ({
+/** A failure, with its tag in `_tag`, as a result: `fail({ _tag: "Offline" })`. */
+const fail = (failure) => ({
 	ok: false,
-	error: {
-		_tag: tag,
-		...data ?? {}
-	}
+	error: failure
 });
 const callFailure = (kind, message) => ({
 	kind,
@@ -65,15 +62,16 @@ const cliExitCode = (outcome) => isCallFailure(outcome) ? CLI_EXIT_CODES[outcome
 * code point order of the names. `input` is the bundled input schema.
 */
 function cliFlags(input) {
-	const properties = input.properties ?? {};
-	const definitions = input.$defs ?? {};
-	const required = new Set(input.required ?? []);
+	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);
 	return [...names.filter((name) => required.has(name)), ...names.filter((name) => !required.has(name))].map((name) => {
-		const reference = properties[name].$ref;
+		const declared = objectOrEmpty(properties[name]);
+		const reference = declared.$ref;
 		const target = typeof reference === "string" ? REFERENCE.exec(reference)?.[1] : void 0;
-		const property = (target === void 0 ? void 0 : definitions[target]) ?? properties[name];
+		const property = objectOrEmpty((target === void 0 ? void 0 : definitions[target]) ?? declared);
 		const flag = property.type === "boolean" ? `--${name}` : `--${name} <${flagValue(property)}>`;
 		return required.has(name) ? flag : `[${flag}]`;
 	});
@@ -112,7 +110,7 @@ function screenRequest(request, rules) {
 	const origin = request.headers.get("Origin");
 	if (origin !== null && !rules.allowedOrigins.includes(origin)) return "origin";
 	if (request.method === "GET" || request.method === "HEAD") return void 0;
-	if ((request.headers.get("Content-Type") ?? "").split(";")[0].trim().toLowerCase() !== rules.mediaType) return "media-type";
+	if (((request.headers.get("Content-Type") ?? "").split(";")[0] ?? "").trim().toLowerCase() !== rules.mediaType) return "media-type";
 	const declared = Number(request.headers.get("Content-Length") ?? "");
 	if (Number.isFinite(declared) && declared > rules.maximumBytes) return "too-large";
 }
@@ -186,6 +184,12 @@ function mcpToolResult(outcome, hasOutputSchema) {
 	} : { content: text(outcome.value) };
 }
 const REFERENCE = /^#\/\$defs\/([A-Za-z][A-Za-z0-9_]*)$/;
+/** 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);
+/** 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. */
+const stringsOf = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 /** The schemas of a capability, each with the member that holds it. */
 function schemasOf(capability) {
 	return [
@@ -198,7 +202,7 @@ function schemasOf(capability) {
 /** Every object in a JSON value, at all levels. */
 function visitObjects(value, onObject) {
 	if (Array.isArray(value)) value.forEach((item) => visitObjects(item, onObject));
-	else if (value !== null && typeof value === "object") {
+	else if (isJsonObject(value)) {
 		onObject(value);
 		Object.values(value).forEach((item) => visitObjects(item, onObject));
 	}
@@ -217,6 +221,27 @@ function typesUsedBy(schema, types) {
 	collect(schema);
 	return used;
 }
+/**
+* An input schema that is a union of object schemas, with `"type": "object"`, so that it is an object schema
+* (spec/catalog.md#capabilities). A union is `anyOf` or `oneOf`, directly or in the type that a `$ref` names. Each of
+* its schemas is an object, or a `$ref` to a type that is an object. Other schemas do not change.
+*/
+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 target = resolve(schema);
+	if (schema.type !== void 0 || target === void 0 || target.type !== void 0) return schema;
+	const union = target.anyOf ?? target.oneOf;
+	if (!Array.isArray(union) || union.length === 0) return schema;
+	return union.every((member) => resolve(member)?.type === "object") ? {
+		type: "object",
+		...schema
+	} : 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;
@@ -246,4 +271,4 @@ function viewOf(catalog, target) {
 	};
 }
 //#endregion
-export { AVAILABLE, CALL_FAILURE_KINDS, CLI_EXIT_CODES, CallFailureError, HTTP_STATUS, ID_PATTERN, MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, REFERENCE, bundle, callFailure, cliExitCode, cliFlags, cliUsage, commandPath, fail, httpStatus, isCallFailure, isId, mcpToolResult, ok, readBounded, schemasOf, screenRequest, typesUsedBy, unavailable, viewOf, visitObjects };
+export { AVAILABLE, CALL_FAILURE_KINDS, CLI_EXIT_CODES, CallFailureError, HTTP_STATUS, ID_PATTERN, MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, REFERENCE, bundle, callFailure, cliExitCode, cliFlags, cliUsage, commandPath, fail, httpStatus, isCallFailure, isId, isJsonObject, mcpToolResult, objectInput, ok, readBounded, schemasOf, screenRequest, typesUsedBy, unavailable, viewOf, visitObjects };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/spec-ts",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "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",