natsClient_JS/docs/3-walkthrough.md

Walkthrough: natsClient_JS

One section per system participant. Here the single participant is the consuming app that imports natsClient.js. Each step traces the complete flow and cites the Solution Design decision (SD-XXX) and Requirement (FR/NFR) it implements.

Consuming App

Session Start — Connect

WT-001: App calls getNats() / connectNATS() and the connection goes connecting → connected.

Cross-reference: 1-requirements.md:FR-001, 2-solution_design.md:SD-001, SD-002, SD-004

sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    App->>C: getNats({ servers })
    C->>C: resolve URL (SD-002)
    C->>Nats: connect (SD-001)
    Nats-->>C: connected
    C->>App: connectionStatus = { state: "connected" } (SD-004, SD-007)

WT-002: App subscribes to a subject and receives decoded messages.

Cross-reference: 1-requirements.md:FR-002, 2-solution_design.md:SD-003

Step	Action	System Response	Traceability
WT-002.1	subscribe('subj', onMessage)	nc.subscribe, tracked in Map (SD-005)	FR-002
WT-002.2	Broker sends a message	StringCodec decode, JSON.parse (SD-003)	FR-002
WT-002.3	Payload is valid JSON	onMessage(parsed) called	FR-002
WT-002.4	Payload is not JSON	{ text } fallback, onMessage called	FR-002

WT-003: App publishes a message (object or string).

Cross-reference: 1-requirements.md:FR-003, 2-solution_design.md:SD-001, SD-003

sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    App->>C: publish('subj', {a:1})
    C->>C: JSON.stringify (SD-003)
    C->>C: nc.publish
    C->>Nats: publish

WT-004: App issues a request and awaits the reply.

Cross-reference: 1-requirements.md:FR-004, 2-solution_design.md:SD-003

sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    App->>C: request('subj', payload, { timeout })
    C->>Nats: request + encode
    Nats-->>C: reply
    C->>C: decode + JSON.parse
    C-->>App: responseJson

WT-005: App registers a reply handler to serve requests.

Cross-reference: 1-requirements.md:FR-005, 2-solution_design.md:SD-005

sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    App->>C: reply('subj', handler)
    C->>Nats: subscribe
    Nats->>C: request
    C->>C: handler(parsed, msg)
    C->>Nats: publish(reply, responseMsg)

WT-006: App calls sendMsghandlerRequest to talk to the sommpanion db backend.

Cross-reference: 1-requirements.md:FR-006, 2-solution_design.md:SD-006

sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Msg as msghandler-csr.js
    participant Nats as NATS broker

    App->>C: sendMsghandlerRequest('subj', 'fn', args, config)
    C->>Msg: smartpack([db_request, {functioncall,args}, dictionary])
    C->>Nats: request(envelope)
    Nats-->>C: reply envelope
    C->>Msg: smartunpack
    C-->>App: data (dictionary/jsontable) or throw on text

Error Paths

WT-007: Broker disconnects; status transitions then auto-reconnects.

Cross-reference: 1-requirements.md:FR-007, 2-solution_design.md:SD-004, NFR-102

sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    Nats->>C: disconnect event
    C->>App: connectionStatus = disconnected (SD-004)
    Nats->>C: reconnect event
    C->>App: connectionStatus = connected (SD-004)

WT-008: App closes the connection.

Cross-reference: 1-requirements.md:FR-008, 2-solution_design.md:SD-005, NFR-501

sequenceDiagram
    participant App as Consuming App
    participant C as natsClient.js
    participant Nats as NATS broker

    App->>C: closeNats()
    C->>C: unsubscribe all tracked subs (SD-005)
    C->>Nats: close
    C->>App: connectionStatus = disconnected