@blamejs/core 0.8.42 → 0.8.49

package/lib/asyncapi.js

@@ -1,62 +1,36 @@
 "use strict";
 /**
- * b.asyncapi — AsyncAPI 3.0 schema-document builder.
+ * @module b.asyncapi
+ * @nav    Other
+ * @title  Asyncapi
  *
- * AsyncAPI is the event-driven sibling to OpenAPI. Operators describe
- * pubsub / websocket / kafka / mqtt surfaces as a single document the
- * framework can serve at /asyncapi.json (or /asyncapi.yaml) for
- * downstream tooling.
+ * @intro
+ *   AsyncAPI 3.0 emitter for pubsub / WebSocket / SSE channels;
+ *   complements `b.openapi`. Operators describe their pubsub /
+ *   websocket / kafka / mqtt surfaces as a single document the
+ *   framework serves at `/asyncapi.json` (or `.yaml`) for downstream
+ *   tooling.
  *
- *   var aapi = b.asyncapi.create({
- *     info: { title: "Acme Events API", version: "1.0.0" },
- *     servers: {
- *       production: { host: "broker.acme.example.com:9092",
- *                     protocol: "kafka",
- *                     description: "Kafka broker" },
- *     },
- *   });
+ *   The builder is FRAMEWORK-FACING: it produces a valid AsyncAPI 3.0
+ *   document, but the operator's hand-written contract is the source
+ *   of truth — it does NOT auto-walk `b.pubsub` topics or
+ *   `b.websocketChannels` subscriptions (operators frequently want a
+ *   smaller / different surface published than what is in-process).
  *
- *   aapi.channel("orders.created", {
- *     address: "orders.created",
- *     messages: {
- *       OrderCreated: {
- *         payload: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
- *         contentType: "application/json",
- *       },
- *     },
- *     bindings: { kafka: b.asyncapi.bindings.kafka({ topic: "orders.created", partitions: 4 }) },
- *   });
+ *   Builder fluent surface: `channel(id, opts)` registers a channel,
+ *   `operation(id, opts)` registers a send/receive operation that
+ *   `$ref`s an already-registered channel (operations referencing
+ *   undeclared channels throw `asyncapi/dangling-channel`),
+ *   `schema()` / `message()` / `parameter()` / `correlationId()` /
+ *   `security.add()` / `security.require()` / `tag()` / `server()`
+ *   register components. Terminal calls are `toJson()` /
+ *   `toJsonString(indent)` / `toYaml()`. Typed binding builders for
+ *   websockets / kafka / amqp / mqtt / http live on
+ *   `b.asyncapi.bindings`; reusable trait builders on
+ *   `b.asyncapi.traits`.
  *
- *   aapi.operation("publishOrderCreated", {
- *     action:  "send",
- *     channel: "orders.created",
- *     summary: "Publish an order-created event",
- *   });
- *
- *   var doc = aapi.toJson();      // AsyncAPI 3.0 JSON document
- *   var yaml = aapi.toYaml();     // YAML serialisation
- *
- * The builder is FRAMEWORK-FACING: it produces a valid AsyncAPI 3.0
- * document, but the operator's hand-written contract is the source of
- * truth — it does NOT auto-walk b.pubsub topics or b.websocketChannels
- * subscriptions (operators frequently want a smaller / different
- * surface published than what is in-process).
- *
- * Public surface (b.asyncapi.*):
- *
- *   .create({ info, servers, defaultContentType, security, externalDocs })
- *     -> builder
- *
- *   builder.channel(channelId, opts)               // register channel
- *   builder.operation(operationId, opts)           // register operation
- *   builder.schema(name, schemaSpec)               // reusable schema
- *   builder.message(name, messageSpec)             // reusable message
- *   builder.security.add(name, scheme)
- *   builder.tag({ name, description })
- *   builder.toJson() / toJsonString() / toYaml()
- *
- *   b.asyncapi.bindings.{websockets, kafka, amqp, mqtt, http}
- *     -> typed binding builders.
+ * @card
+ *   AsyncAPI 3.0 emitter for pubsub / WebSocket / SSE channels; complements `b.openapi`.
  */
 
 var validateOpts        = require("./validate-opts");
@@ -75,6 +49,50 @@ var ASYNCAPI_VERSION = "3.0.0";
 
 var VALID_OPERATION_ACTIONS = ["send", "receive"];
 
+/**
+ * @primitive b.asyncapi.create
+ * @signature b.asyncapi.create(opts)
+ * @since     0.6.30
+ * @related   b.asyncapi.parse, b.openapi.create
+ *
+ * Build a fluent AsyncAPI 3.0 document builder. `opts.info` is
+ * required (`title` + `version`). `opts.servers` is a map keyed by
+ * server id, each entry carrying `host` + `protocol`. Returns a
+ * chainable builder; terminal calls are `toJson()`,
+ * `toJsonString(indent)`, and `toYaml()`. `toJson()` cross-checks
+ * every doc-level and per-operation security requirement against
+ * `components.securitySchemes` and throws
+ * `AsyncApiError("asyncapi/dangling-security")` on a missing scheme.
+ *
+ * @opts
+ *   info:               { title, version, description?, contact?, license? },   // REQUIRED — title + version are non-empty strings
+ *   servers:            { serverId: { host, protocol, description?, ... } },    // map keyed by id; each entry needs host + protocol
+ *   defaultContentType: string,                  // defaults to "application/json"
+ *   security:           array,                   // doc-level security requirements [{ schemeName: ["scope"] }, ...]
+ *   externalDocs:       { url, description? },
+ *   tags:               array,                   // [{ name, description? }, ...] — seed; builder.tag() appends more
+ *   id:                 string,                  // optional document identifier (e.g. "urn:com:acme:events")
+ *
+ * @example
+ *   var aapi = b.asyncapi.create({
+ *     info:    { title: "Acme Events", version: "1.0.0" },
+ *     servers: { production: { host: "broker.acme.example.com:9092", protocol: "kafka" } },
+ *   });
+ *   aapi.channel("orders.created", {
+ *     address:  "orders.created",
+ *     messages: { OrderCreated: { payload: { type: "object", properties: { id: { type: "string" } }, required: ["id"] }, contentType: "application/json" } },
+ *     bindings: { kafka: b.asyncapi.bindings.kafka({ topic: "orders.created", partitions: 4 }) },
+ *   });
+ *   aapi.operation("publishOrderCreated", {
+ *     action:  "send",
+ *     channel: "orders.created",
+ *     summary: "Publish an order-created event",
+ *   });
+ *   var doc = aapi.toJson();
+ *   doc.asyncapi;                                    // → "3.0.0"
+ *   doc.operations.publishOrderCreated.action;       // → "send"
+ *   doc.operations.publishOrderCreated.channel.$ref; // → "#/channels/orders.created"
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
@@ -423,8 +441,34 @@ function _validateServerEntry(entry, label) {
     label + ": protocol", AsyncApiError, "asyncapi/bad-server");
 }
 
-// Parse + validate an external AsyncAPI 3.0 document. Like openapi.parse:
-// returns `{ doc, errors[], valid }`. Throws on invalid JSON.
+/**
+ * @primitive b.asyncapi.parse
+ * @signature b.asyncapi.parse(jsonStringOrObject)
+ * @since     0.6.30
+ * @related   b.asyncapi.create, b.openapi.parse
+ *
+ * Parse + validate an external AsyncAPI 3.0 document. Throws on
+ * invalid JSON or non-object input; otherwise returns
+ * `{ doc, errors, valid }`. `errors` is an array of strings — empty
+ * on a valid document. Operations must declare `action: "send" |
+ * "receive"` and a `channel.$ref` resolving to a declared channel;
+ * server entries need both `host` and `protocol`; doc-level security
+ * must reference declared schemes.
+ *
+ * @example
+ *   var result = b.asyncapi.parse('{"asyncapi":"3.0.0","info":{"title":"x","version":"1.0.0"}}');
+ *   result.valid;       // → true
+ *   result.errors;      // → []
+ *
+ *   var bad = b.asyncapi.parse({
+ *     asyncapi: "3.0.0",
+ *     info:     { title: "x", version: "1.0.0" },
+ *     channels: {},
+ *     operations: { pub: { action: "send", channel: { $ref: "#/channels/missing" } } },
+ *   });
+ *   bad.valid;          // → false
+ *   bad.errors[0];      // → 'operations.pub.channel: $ref "#/channels/missing" does not resolve to a declared channel'
+ */
 function parse(jsonStringOrObject) {
   var doc;
   if (typeof jsonStringOrObject === "string") {