@wandelbots/nova-js 3.13.0-pr.307.ea0533d → 3.13.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wandelbots/nova-js",
   "type": "module",
-  "version": "3.13.0-pr.307.ea0533d",
+  "version": "3.13.0",
   "description": "Official JS client for the Wandelbots API",
   "sideEffects": false,
   "packageManager": "pnpm@11.9.0+sha512.bd682d5d03fe525ef7c9fd6780c6884d1e756ac4c9c9fe00c538782824310dcf90e3ddc4f53835f06dfaebd5085e41855e0bcbb3b60de2ac5bbab89e5036f03b",
@@ -56,7 +56,6 @@
   "devDependencies": {
     "@asyncapi/parser": "^3.6.0",
     "@biomejs/biome": "^2.4.16",
-    "@types/lodash-es": "^4.17.12",
     "@types/node": "^25.9.1",
     "@types/ws": "^8.18.1",
     "concurrently": "^10.0.3",
@@ -64,7 +63,6 @@
     "jsdom": "^29.1.1",
     "json-schema-to-typescript": "^15.0.4",
     "knip": "^6.15.0",
-    "lodash-es": "^4.18.1",
     "nodemon": "^3.1.14",
     "semantic-release": "^25.0.3",
     "semantic-release-export-data": "^1.2.0",

package/src/experimental/nats/index.ts

@@ -4,13 +4,20 @@
  *
  * This API is experimental and may change without a major version bump.
  */
+export { buildNatsServerUrl } from "../../lib/experimental/nats/buildNatsServerUrl.ts"
 export type {
   NatsOperationParams,
+  NatsPublishPayloads,
+  NatsPublishSubject,
   NatsReplyPayloads,
   NatsRequestPayloads,
   NatsRequestSubject,
   NatsSubscribePayloads,
   NatsSubscribeSubject,
 } from "../../lib/experimental/nats/generated/operations.ts"
+// Message payload types for every schema in src/asyncapi.yaml, e.g. `Cell`,
+// `App`, `ProgramStatus` (see NatsSubscribePayloads/NatsRequestPayloads for
+// which type applies to which subject).
+export type * from "../../lib/experimental/nats/generated/types.ts"
 export { NovaNatsClient } from "../../lib/experimental/nats/NovaNatsClient.ts"
 export type { NovaNatsClientConfig } from "../../lib/experimental/nats/NovaNatsClient.ts"

package/src/lib/experimental/nats/NovaNatsClient.ts

@@ -4,9 +4,13 @@ import {
   type NatsConnection,
   wsconnect,
 } from "@nats-io/nats-core"
+import type { Nova } from "../../Nova.ts"
+import { buildNatsServerUrl } from "./buildNatsServerUrl.ts"
 import { buildSubject } from "./buildSubject.ts"
 import type {
   NatsOperationParams,
+  NatsPublishPayloads,
+  NatsPublishSubject,
   NatsReplyPayloads,
   NatsRequestPayloads,
   NatsRequestSubject,
@@ -16,6 +20,16 @@ import type {
 
 export type NovaNatsClientConfig = ConnectionOptions
 
+type NatsMessageHandler<K extends NatsSubscribeSubject> = (
+  payload: NatsSubscribePayloads[K],
+  msg: Msg,
+) => void | Promise<void>
+
+type SubscribeArgs<K extends NatsSubscribeSubject> =
+  keyof NatsOperationParams[K] extends never
+    ? [handler: NatsMessageHandler<K>]
+    : [params: NatsOperationParams[K], handler: NatsMessageHandler<K>]
+
 /**
  * Typed NATS client for the Wandelbots NOVA messaging API, generated from
  * src/asyncapi.yaml (see scripts/generate-nats-client.ts).
@@ -24,24 +38,46 @@ export type NovaNatsClientConfig = ConnectionOptions
  */
 export class NovaNatsClient {
   readonly config: NovaNatsClientConfig
-  connection: NatsConnection | null = null
+  private connectionPromise: Promise<NatsConnection> | null = null
 
-  constructor(config: NovaNatsClientConfig) {
-    this.config = config
+  constructor(nova: Nova, config: NovaNatsClientConfig = {}) {
+    this.config = {
+      servers: buildNatsServerUrl(nova.instanceUrl.href),
+      // Reuse the Nova instance's access token for NATS auth, if it has one
+      // (e.g. from login or a passed-in config.accessToken). Explicit auth
+      // options in `config` (token/user/pass/authenticator) still win.
+      ...(nova.accessToken ? { token: nova.accessToken } : {}),
+      ...config,
+    }
   }
 
-  /** Connects to NATS if not already connected, and returns the connection. */
-  async connect(): Promise<NatsConnection> {
-    if (!this.connection) {
-      this.connection = await wsconnect(this.config)
+  /**
+   * Connects to NATS if not already connected or connecting, and returns the
+   * connection. Safe to call concurrently: all callers share the same
+   * in-flight connection attempt instead of each starting their own.
+   */
+  connect(): Promise<NatsConnection> {
+    if (!this.connectionPromise) {
+      this.connectionPromise = wsconnect(this.config).catch((err: unknown) => {
+        // Allow a subsequent connect() call to retry after a failed attempt.
+        this.connectionPromise = null
+        throw err
+      })
     }
-    return this.connection
+    return this.connectionPromise
   }
 
-  /** Closes the underlying NATS connection, if open. */
+  /** Closes the underlying NATS connection, if open or connecting. */
   async close(): Promise<void> {
-    await this.connection?.close()
-    this.connection = null
+    const connectionPromise = this.connectionPromise
+    this.connectionPromise = null
+    if (!connectionPromise) return
+    try {
+      const nc = await connectionPromise
+      await nc.close()
+    } catch {
+      // Connection never succeeded; nothing to close.
+    }
   }
 
   /**
@@ -52,24 +88,41 @@ export class NovaNatsClient {
    * `"nova.v2.cells.{cell}"`, with `{param}` placeholders filled in from
    * `params`.
    *
+   * Errors decoding a message or thrown/rejected by `handler` are caught and
+   * logged per-message, so one bad message doesn't stop later messages on
+   * the same subscription from being handled.
+   *
    * Returns a function that unsubscribes when called.
    */
   async subscribe<K extends NatsSubscribeSubject>(
     subject: K,
-    params: NatsOperationParams[K],
-    handler: (payload: NatsSubscribePayloads[K], msg: Msg) => void,
+    ...args: SubscribeArgs<K>
   ): Promise<() => void> {
+    const [params, handler] =
+      args.length === 1
+        ? ([{}, args[0]] as const)
+        : ([args[0], args[1]] as const)
+
     const nc = await this.connect()
     const resolvedSubject = buildSubject(subject, params)
     const sub = nc.subscribe(resolvedSubject)
 
     ;(async () => {
       for await (const msg of sub) {
-        handler(msg.json<NatsSubscribePayloads[K]>(), msg)
+        // Handled per-message: a bad payload or a throwing/rejecting handler
+        // should not stop the subscription from processing later messages.
+        try {
+          await handler(msg.json<NatsSubscribePayloads[K]>(), msg)
+        } catch (err) {
+          console.error(
+            `Error handling NATS message on subject "${resolvedSubject}"`,
+            err,
+          )
+        }
       }
     })().catch((err: unknown) => {
       console.error(
-        `Error handling NATS subscription for "${resolvedSubject}"`,
+        `NATS subscription iterator failed for "${resolvedSubject}"`,
         err,
       )
     })
@@ -98,4 +151,22 @@ export class NovaNatsClient {
     })
     return msg.json<NatsReplyPayloads[K]>()
   }
+
+  /**
+   * Publishes a JSON payload to any NATS subject defined in the spec,
+   * without waiting for a reply.
+   *
+   * `subject` is the subject template as it appears on the wire, e.g.
+   * `"nova.v2.cells.{cell}.bus-ios.ios.set"`, with `{param}` placeholders
+   * filled in from `params`.
+   */
+  async publish<K extends NatsPublishSubject>(
+    subject: K,
+    params: NatsOperationParams[K],
+    payload: NatsPublishPayloads[K],
+  ): Promise<void> {
+    const nc = await this.connect()
+    const resolvedSubject = buildSubject(subject, params)
+    nc.publish(resolvedSubject, JSON.stringify(payload))
+  }
 }

package/src/lib/experimental/nats/buildNatsServerUrl.ts

@@ -0,0 +1,15 @@
+import { parseNovaInstanceUrl } from "../../converters.ts"
+
+/**
+ * Builds the WebSocket URL for a NOVA instance's NATS gateway from its
+ * instance URL, e.g. `https://foo.instance.wandelbots.io` becomes
+ * `wss://foo.instance.wandelbots.io/api/nats`.
+ *
+ * Pass the result as `servers` in the `NovaNatsClientConfig` passed to
+ * `NovaNatsClient`.
+ */
+export function buildNatsServerUrl(instanceUrl: string): string {
+  const url = parseNovaInstanceUrl(instanceUrl)
+  const protocol = url.protocol === "https:" ? "wss:" : "ws:"
+  return `${protocol}//${url.host}/api/nats`
+}

package/src/lib/experimental/nats/buildSubject.ts

@@ -3,22 +3,70 @@
  * (e.g. `"{instance}.v2.cells.{cell}"`) by substituting each `{param}`
  * placeholder with the corresponding value from `params`.
  */
+
+function isValidSubjectChar(char: string): boolean {
+  const code = char.charCodeAt(0)
+  return (
+    (code >= 48 && code <= 57) || // 0-9
+    (code >= 65 && code <= 90) || // A-Z
+    (code >= 97 && code <= 122) || // a-z
+    char === "-" ||
+    char === "_"
+  )
+}
+
+function isValidSubjectValue(value: string): boolean {
+  // A bare "*" is the NATS single-token wildcard, allowed on its own (e.g.
+  // subscribing to all cells with `{ cell: "*" }") but not as part of a
+  // larger value, since it wouldn't act as a wildcard there anyway.
+  if (value === "*") return true
+  if (value.length === 0) return false
+  for (const char of value) {
+    if (!isValidSubjectChar(char)) return false
+  }
+  return true
+}
+
 export function buildSubject(
   template: string,
   params: Record<string, string>,
 ): string {
-  return template.replace(/\{([^}]+)\}/g, (match, paramName: string) => {
+  // Scanned manually (rather than with a regex like /\{([^}]+)\}/g) to avoid
+  // a polynomial-time backtracking blowup on pathological input, e.g. a
+  // template consisting of many "{" characters with no closing "}".
+  let result = ""
+  let cursor = 0
+
+  while (cursor < template.length) {
+    const openIndex = template.indexOf("{", cursor)
+    if (openIndex === -1) {
+      result += template.slice(cursor)
+      break
+    }
+
+    const closeIndex = template.indexOf("}", openIndex + 1)
+    if (closeIndex === -1) {
+      result += template.slice(cursor)
+      break
+    }
+
+    result += template.slice(cursor, openIndex)
+    const paramName = template.slice(openIndex + 1, closeIndex)
     const value = params[paramName]
     if (value === undefined) {
       throw new Error(
         `Missing value for subject parameter "${paramName}" in template "${template}"`,
       )
     }
-    if (value === "" || /[\s.>*]/.test(value)) {
+    if (!isValidSubjectValue(value)) {
       throw new Error(
-        `Invalid value for subject parameter "${paramName}": "${value}" (must be non-empty and must not contain whitespace or the NATS special characters ".", ">", "*")`,
+        `Invalid value for subject parameter "${paramName}": "${value}" (must be non-empty and contain only letters, digits, "-", and "_")`,
       )
     }
-    return value
-  })
+    result += value
+
+    cursor = closeIndex + 1
+  }
+
+  return result
 }