nats-cljc.core — io.github.unisoma/nats-cljc 0.1.1

Portable public facade for nats-cljc (always aliased nats).

A thin .cljc surface over the internal protocol (ADR 0005): it owns codec encode/decode and ergonomics, delegating primitive operations to the platform Connection record. The same consumer code compiles and runs on the JVM, the browser, and Node.

close clj/s

(close conn)

Close conn, returning a platform-native promise that settles once the connection is fully closed. Closing ends all of the connection's subscriptions; a final :closed status reaches :on-status (ADR 0002/0006).

connect clj/s

(connect opts)

Open a connection to the NATS server(s) in :servers, returning a platform-native promise (CompletableFuture on the JVM, js/Promise on ClojureScript) that resolves to a Connection. The connection's default codec is :codec (default :edn). Transport is fixed per platform: TCP on the JVM, WebSocket on ClojureScript (ADR 0001).

drain clj/s

(drain conn-or-sub)

Drain a connection or a single subscription, returning a platform-native promise that settles once draining completes. For a connection, it stops all the connection's subscriptions after their pending messages are delivered, then closes the connection; for a subscription, it ends just that one and leaves the connection open (ADR 0002).

flush clj/s

(flush conn)

Flush conn, returning a platform-native promise that settles once the server has processed everything buffered on the connection (ADR 0002).

publish clj/s

(publish conn subject data)

(publish conn subject data {:keys [headers] :as opts})

Publish data to subject on conn, encoding it with the connection's codec. Fire-and-forget: returns nil (ADR 0002). opts may set :codec to override the connection's default codec for this call (ADR 0011), and :headers, a map of case-sensitive string names to one or more string values; a scalar value is normalized to a one-element vector (CONTEXT: Headers). Header names and values must be strings, and names must be valid header tokens (printable ASCII, no colon); invalid input throws.

reply clj/s

(reply conn msg data)

(reply conn msg data opts)

Reply to a request message msg with data, encoding it with the connection's codec and publishing to the request's :reply subject. Sugar over publish; returns nil (ADR 0002). opts may set :codec to override the connection default, so a polyglot response can match the request's codec (ADR 0011). Throws an ex-info :type :no-reply-subject when msg has no :reply (e.g. a plain pub/sub message), rather than publishing to a nil subject.

request clj/s

(request conn subject data)

(request conn subject data opts)

Send a request to subject on conn, encoding data with the connection's codec, and return a platform-native promise that resolves to the decoded reply message {:subject :data :reply} (ADR 0002). opts may set :codec to override the connection's default codec for both the request encode and the reply decode (ADR 0011), and :timeout-ms (default 5000). The promise rejects with an ex-info whose :type is :no-responders (nobody subscribes subject) or :timeout (responders exist but none answer within :timeout-ms) (ADR 0006).

subject clj/s

(subject & parts)

Compose the canonical dot-delimited Subject string from parts, each stringified and joined with . — e.g. (subject "orders" id "created") => "orders.<id>.created". The string form is canonical; this is just sugar for building one from its tokens (CONTEXT: Subject).

subscribe clj/s

(subscribe conn subject handler)

(subscribe conn subject handler {:keys [queue on-error max-pending] :as opts})

Subscribe to subject, returning a Subscription synchronously. handler is invoked once per message with {:subject :data :reply}, where :data is decoded with the connection's codec and :reply is the message's reply-to subject (nil when absent), which reply answers (ADR 0007). opts may set :codec to override the connection's default codec for decoding (ADR 0011), and :queue: subscriptions sharing a queue-group name compete, so the server load-balances each matching message to exactly one member of the group. A nil or blank :queue is a plain subscription (normalized here so both platforms agree, rather than relying on each native layer's truthiness).

opts may also set the async-failure sink and overflow threshold (ADR 0006): :on-error, a 1-arg fn receiving this subscription's failures as a bare ex-info — a thrown handler value (unchanged, no canonical :type), a decode failure (:codec-error), or :slow-consumer — and :max-pending, a positive message-count threshold above which :slow-consumer fires. With no :on-error, a thrown-handler/decode failure falls back to the connection's :on-status :error event and :slow-consumer is dropped; the override is strict (never both). A decode failure is caught here, so the handler never sees garbage. A non-positive :max-pending throws a :type :invalid-max-pending ex-info.

unsubscribe clj/s

(unsubscribe sub)

(unsubscribe sub max)

End a single subscription sub abruptly, returning nil synchronously: the server is told to stop and any not-yet-delivered messages are dropped — the lower-level sibling of drain, which flushes the backlog first and is awaitable (ADR 0002/0012). Idempotent: unsubscribing an already-ended subscription (a prior unsubscribe, a drain, or the connection closing) is a silent no-op rather than an error (ADR 0012).

With max, the subscription auto-unsubscribes once it has received that many messages over its lifetime — counted from subscription start, so messages already delivered past the limit are never recalled, and if it has already received max it stops now. max must be a positive integer no greater than 2147483647 (the JVM Dispatcher.unsubscribe(sub, int) cap, enforced on both platforms so the contract is portable); anything else throws a :type :invalid-max ex-info.

version clj/s

Current library version.