natsClient_JS/docs/7-implementation-plan.md

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