# Implementation Plan: natsClient_JS

## Phases & Timeline

- **Phase 1**: Core transport (connection lifecycle, subscribe, publish, close).
- **Phase 2**: request/reply + reply handler + msghandler integration.
- **Phase 3**: status store + integration tests + CI gates.

## Module Breakdown & Tasks

| Task ID | Module | Responsibility | Effort | Dependencies | Validation Tests Satisfied |
|----------|--------|----------------|--------|--------------|------------------------------|
| IMP-001 | `natsClient.js` | `getNats` — connection + URL resolution | 1d | — | `tests/unit/getNats.test.js` (SP-001), `tests/integration/connect.test.js` (WT-001) |
| IMP-002 | `natsClient.js` | `subscribe` — decode + registry | 1d | IMP-001 | `tests/unit/subscribe.test.js` (SP-002), `tests/integration/publish-flow.test.js` (WT-003) |
| IMP-003 | `natsClient.js` | `publish` — encode + send | 0.5d | IMP-001 | `tests/unit/publish.test.js` (SP-003) |
| IMP-004 | `natsClient.js` | `closeNats` — cleanup | 0.5d | IMP-002 | `tests/unit/closeNats.test.js` (SP-007), `tests/integration/close-flow.test.js` (NFR-501) |
| IMP-005 | `natsClient.js` | `request` / `reply` | 1d | IMP-003 | `tests/unit/request.test.js` (SP-004), `tests/unit/reply.test.js` (SP-005) |
| IMP-006 | msghandler | `sendMsghandlerRequest` | 1d | IMP-005 | `tests/unit/sendMsghandlerRequest.test.js` (SP-006, SP-010/SP-011) |
| IMP-007 | status | `connectionStatus` store + event wiring | 1d | IMP-001 | `tests/unit/connectionStatus.test.js` (SP-008), `tests/integration/status-store.test.js` (NFR-201) |

## Performance & Error Guards

| Task ID | Module | Responsibility | Effort | Validation Tests Satisfied |
|----------|--------|----------------|--------|------------------------------|
| IMP-008 | error handling | per-message decode/parse/handle guard | 0.5d | `tests/unit/subscribe.test.js:decode_error_does_not_crash` (NFR-302) |
| IMP-009 | reconnect | reconnect behavior wired by `nats.ws` + `nc.status()` | 0.5d | `tests/integration/reconnect.test.js` (WT-007, NFR-102) |

## Build & Deployment

| Task ID | Module | Responsibility | Effort |
|----------|--------|----------------|--------|
| IMP-010 | CI | contract + integration gates on every commit/PR | 0.5d |
| IMP-011 | release | publish as a library module (ESM) | 0.5d |

## Risk Mitigation

| Risk | Mitigation | Task |
|------|------------|------|
| Broker unreachable at startup | `getNats` throws; consumer retries | IMP-001 |
| Decode error kills subscription loop | `catch` per message | IMP-008 |
| Reconnect never settles | `nc.status()` + `nc.closed()` monitoring | IMP-009 |