@nanobpm/urban 0.33.0 → 0.34.0

package/dist/openapi/spec.d.ts

@@ -79,8 +79,10 @@ export interface OperationInfo {
     eject: boolean;
     summary?: string;
 }
-/** Parse an OpenAPI document from text. JSON only in this slice (ADR 0058 open question: YAML).
- *  Throws with a clear message on malformed input. */
+/** Parse an OpenAPI document from text. Accepts both YAML (the sanctioned authoring format for
+ *  the HTTP surface — ADR 0059) and JSON (still accepted, e.g. a generated interchange artifact).
+ *  JSON is a strict subset of YAML 1.2, so JSON is tried first for a precise error + fast path,
+ *  then the text is parsed as YAML. Throws with a clear message on malformed input. */
 export declare function parseSpec(text: string): OpenApiDoc;
 /** The basename of a local `#/components/schemas/Name` ref, else undefined. */
 export declare function refName(ref: string): string | undefined;

package/dist/openapi/spec.js

@@ -2,12 +2,15 @@
 // deriver (`toolkit/derivers/api.ts`, authoring-time type + wrapper emission) and the runtime
 // (`runtime/core/modules/api.ts`, request validation + routing) build on this one module, so the
 // derived types and the runtime routes/validation always agree. No IO, no `node:*`, no `Deno` —
-// it operates on an already-parsed document object.
+// it operates on document text/objects. Its one external dependency is `yaml` (a browser-safe,
+// pure-JS parser with a dedicated browser build) so `parseSpec` accepts YAML — the sanctioned
+// authoring format for the HTTP surface (ADR 0059) — as well as JSON.
 //
 // Scope: the ADR 0058 "supported profile" — JSON bodies, path/query parameters, a JSON
 // requestBody, response codes, and a JSON-Schema subset validator (type/required/enum/numeric &
 // string bounds/pattern/array & object shape/nullable/$ref). Exotic OpenAPI (callbacks, links,
 // XML, discriminated oneOf composition) is intentionally out of scope for this slice.
+import { parse as parseYaml } from "yaml";
 /**
  * Whether a schema describes an object shape. OpenAPI/JSON-Schema let the `type`
  * keyword be omitted when `properties`/`required`/`additionalProperties` already imply
@@ -33,18 +36,30 @@ function isRecord(v) {
 function isSchema(v) {
     return isRecord(v);
 }
-/** Parse an OpenAPI document from text. JSON only in this slice (ADR 0058 open question: YAML).
- *  Throws with a clear message on malformed input. */
+/** Parse an OpenAPI document from text. Accepts both YAML (the sanctioned authoring format for
+ *  the HTTP surface — ADR 0059) and JSON (still accepted, e.g. a generated interchange artifact).
+ *  JSON is a strict subset of YAML 1.2, so JSON is tried first for a precise error + fast path,
+ *  then the text is parsed as YAML. Throws with a clear message on malformed input. */
 export function parseSpec(text) {
     let doc;
     try {
+        // Fast path + precise diagnostics for JSON (and the generated `openapi.json` interchange file).
         doc = JSON.parse(text);
     }
-    catch (e) {
-        throw new Error(`OpenAPI spec is not valid JSON (YAML is not yet supported — ADR 0058): ${e instanceof Error ? e.message : String(e)}`);
+    catch (jsonError) {
+        // Not JSON — parse as YAML (which also subsumes JSON, so authored `.yaml`/`.yml` specs load).
+        try {
+            doc = parseYaml(text);
+        }
+        catch (yamlError) {
+            const jsonMessage = jsonError instanceof Error ? jsonError.message : String(jsonError);
+            const yamlMessage = yamlError instanceof Error ? yamlError.message : String(yamlError);
+            throw new Error(`OpenAPI spec is not valid YAML or JSON: JSON parse error: ${jsonMessage}; YAML parse error: ${yamlMessage}`);
+        }
+    }
+    if (!isRecord(doc)) {
+        throw new Error("OpenAPI spec must be an object (a mapping at the document root)");
     }
-    if (!isRecord(doc))
-        throw new Error("OpenAPI spec must be a JSON object");
     return doc;
 }
 /** The basename of a local `#/components/schemas/Name` ref, else undefined. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.33.0",
-  "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
+  "version": "0.34.0",
+  "description": "Urban: build and run code-first apps on Nano \u2014 runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",
   "keywords": [
@@ -66,7 +66,8 @@
     "@nanobpm/nano-sdk": "^1.2.3",
     "@nanobpm/workflow": "^0.8.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
-    "create-urban-app": "^0.9.0"
+    "create-urban-app": "^0.9.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

package/src/openapi/spec.test.ts

@@ -51,9 +51,65 @@ const doc: OpenApiDoc = {
   },
 };
 
-test("parseSpec throws a clear error on non-JSON and non-object", () => {
-  assert.throws(() => parseSpec("not json"), /not valid JSON/);
-  assert.throws(() => parseSpec("42"), /must be a JSON object/);
+test("parseSpec throws a clear error on non-object and unparseable input", () => {
+  // A bare scalar parses (as JSON or YAML) but is not a document object.
+  assert.throws(() => parseSpec("42"), /must be an object/);
+  // Unbalanced/garbage that is neither valid JSON nor valid YAML.
+  assert.throws(() => parseSpec("{ : ]["), /not valid YAML or JSON/);
+});
+
+test("parseSpec includes both JSON and YAML diagnostics when neither parser accepts the input", () => {
+  assert.throws(
+    () => parseSpec("{ : ]["),
+    /JSON parse error:.*YAML parse error:/,
+  );
+});
+
+test("parseSpec parses a YAML OpenAPI document (ADR 0059 authoring format)", () => {
+  const yaml = [
+    "openapi: 3.0.0",
+    "info:",
+    "  title: Demo",
+    "  version: 1.0.0",
+    "paths:",
+    "  /invoices:",
+    "    post:",
+    "      operationId: createInvoice",
+    "      requestBody:",
+    "        required: true",
+    "        content:",
+    "          application/json:",
+    "            schema:",
+    "              $ref: '#/components/schemas/Invoice'",
+    "      responses:",
+    "        '201':",
+    "          description: created",
+    "components:",
+    "  schemas:",
+    "    Invoice:",
+    "      type: object",
+    "      required: [id, amount]",
+    "      properties:",
+    "        id: { type: string }",
+    "        amount: { type: integer, minimum: 1 }",
+    "",
+  ].join("\n");
+  const parsed = parseSpec(yaml);
+  assert.equal(parsed.openapi, "3.0.0");
+  const ops = collectOperations(parsed);
+  assert.deepEqual(
+    ops.map((o) => o.operationId),
+    ["createInvoice"],
+  );
+  // The $ref resolves against the YAML-authored components, same as a JSON spec.
+  const resolved = resolveSchema(parsed, { $ref: "#/components/schemas/Invoice" });
+  assert.equal(resolved?.type, "object");
+  assert.deepEqual(resolved?.required, ["id", "amount"]);
+});
+
+test("parseSpec still parses JSON (accepted interchange format)", () => {
+  const parsed = parseSpec(JSON.stringify(doc));
+  assert.equal(parsed.openapi, "3.0.0");
 });
 
 test("collectOperations returns id-bearing ops in stable (path, method) order", () => {

package/src/openapi/spec.ts

@@ -2,13 +2,17 @@
 // deriver (`toolkit/derivers/api.ts`, authoring-time type + wrapper emission) and the runtime
 // (`runtime/core/modules/api.ts`, request validation + routing) build on this one module, so the
 // derived types and the runtime routes/validation always agree. No IO, no `node:*`, no `Deno` —
-// it operates on an already-parsed document object.
+// it operates on document text/objects. Its one external dependency is `yaml` (a browser-safe,
+// pure-JS parser with a dedicated browser build) so `parseSpec` accepts YAML — the sanctioned
+// authoring format for the HTTP surface (ADR 0059) — as well as JSON.
 //
 // Scope: the ADR 0058 "supported profile" — JSON bodies, path/query parameters, a JSON
 // requestBody, response codes, and a JSON-Schema subset validator (type/required/enum/numeric &
 // string bounds/pattern/array & object shape/nullable/$ref). Exotic OpenAPI (callbacks, links,
 // XML, discriminated oneOf composition) is intentionally out of scope for this slice.
 
+import { parse as parseYaml } from "yaml";
+
 /** A JSON Schema (the OpenAPI subset we read). Kept structural and permissive — unknown keywords
  *  are ignored by the validator and fall back to `unknown` in the type emitter. */
 export interface OpenApiSchema {
@@ -116,20 +120,28 @@ function isSchema(v: unknown): v is OpenApiSchema {
   return isRecord(v);
 }
 
-/** Parse an OpenAPI document from text. JSON only in this slice (ADR 0058 open question: YAML).
- *  Throws with a clear message on malformed input. */
+/** Parse an OpenAPI document from text. Accepts both YAML (the sanctioned authoring format for
+ *  the HTTP surface — ADR 0059) and JSON (still accepted, e.g. a generated interchange artifact).
+ *  JSON is a strict subset of YAML 1.2, so JSON is tried first for a precise error + fast path,
+ *  then the text is parsed as YAML. Throws with a clear message on malformed input. */
 export function parseSpec(text: string): OpenApiDoc {
   let doc: unknown;
   try {
+    // Fast path + precise diagnostics for JSON (and the generated `openapi.json` interchange file).
     doc = JSON.parse(text);
-  } catch (e) {
-    throw new Error(
-      `OpenAPI spec is not valid JSON (YAML is not yet supported — ADR 0058): ${
-        e instanceof Error ? e.message : String(e)
-      }`,
-    );
+  } catch (jsonError) {
+    // Not JSON — parse as YAML (which also subsumes JSON, so authored `.yaml`/`.yml` specs load).
+    try {
+      doc = parseYaml(text);
+    } catch (yamlError) {
+      const jsonMessage = jsonError instanceof Error ? jsonError.message : String(jsonError);
+      const yamlMessage = yamlError instanceof Error ? yamlError.message : String(yamlError);
+      throw new Error(`OpenAPI spec is not valid YAML or JSON: JSON parse error: ${jsonMessage}; YAML parse error: ${yamlMessage}`);
+    }
+  }
+  if (!isRecord(doc)) {
+    throw new Error("OpenAPI spec must be an object (a mapping at the document root)");
   }
-  if (!isRecord(doc)) throw new Error("OpenAPI spec must be a JSON object");
   return doc;
 }