@digta/network 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @digta/network
+
+Network toolkit for Node: a **TCP / WebSocket** client with **autoreconnect**, plus a tiny **HTTP API** client with retries. Same package, one import.
+
+```bash
+npm install @digta/network
+```
+
+## Connection — TCP / WebSocket + autoreconnect
+
+One API for both transports. Pick it with the URL scheme: `tcp://`, `ws://`, or `wss://`.
+
+```js
+import { createConnection } from "@digta/network";
+// or: const { createConnection } = require("@digta/network");
+
+const conn = createConnection({
+  url: "tcp://192.168.1.10:502",   // or "ws://host:8080/path"
+  reconnect: true,                 // on by default
+  backoff: { min: 500, max: 30000, factor: 2 },
+});
+
+conn.on("connect", () => console.log("connected"));
+conn.on("message", (data) => console.log("in:", data));
+conn.on("reconnecting", (attempt, delay) => console.log(`retry #${attempt} in ${delay}ms`));
+conn.on("close", () => console.log("closed"));
+conn.on("error", (err) => console.error(err));
+
+conn.connect();
+conn.send("hello");
+// conn.close();  // intentional — stops reconnecting
+```
+
+**Autoreconnect** uses exponential backoff with jitter and resets on success. Call `close()` to stop for good.
+
+### Heartbeat & latency (optional)
+
+Set `heartbeat` (ms) to ping and measure round-trip time:
+
+```js
+const conn = createConnection({ url: "ws://host:8080", heartbeat: 5000 });
+conn.on("latency", (ms) => console.log(`${ms}ms`));
+conn.on("timeout", () => console.log("no pong — dropping + reconnecting"));
+```
+
+- **WebSocket**: works out of the box (native ping/pong frames).
+- **Raw TCP**: has no ping frame. Provide your protocol's `ping` bytes and an `isPong(data)` matcher, or rely on OS keepalive (always on) for dead-link detection.
+
+### Events
+
+`connect` · `message(data)` · `close` · `error(err)` · `reconnecting(attempt, delay)` · `reconnect_failed(attempts)` · `latency(ms)` · `timeout`
+
+> TCP is a raw byte stream — it has **no message framing**. `message` fires per chunk; handle your own boundaries. WebSocket messages are framed for you.
+
+## API — HTTP client with retries
+
+```js
+import { createApi } from "@digta/network";
+
+const api = createApi({
+  baseURL: "https://api.example.com",
+  headers: { authorization: "Bearer …" },
+  timeout: 10000,
+  retries: 3,        // retries network errors, timeouts, 429, and 5xx (exp backoff)
+});
+
+const { data, status } = await api.get("/users", { query: { page: 2 } });
+await api.post("/users", { name: "digta" });          // JSON body auto-serialized
+await api.get("/thing", { retries: 0, timeout: 2000 }); // per-request overrides
+```
+
+- JSON bodies are serialized and `Content-Type` set automatically; JSON responses are parsed.
+- `4xx`/`5xx` **reject** with an error carrying `.status` and `.response`.
+- Follows redirects (up to 5 hops).
+- Zero HTTP dependency — built on Node's `http`/`https`, works on Node 14+.
+
+For one-off absolute-URL calls, use the ready `api`:
+
+```js
+import { api } from "@digta/network";
+const res = await api.get("https://example.com/health");
+```
+
+## License
+
+MIT

package/api.js

@@ -0,0 +1,107 @@
+'use strict'
+
+const http = require('http')
+const https = require('https')
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+function buildUrl(base, path, query) {
+  let url = /^https?:\/\//i.test(path)
+    ? path
+    : base
+      ? base.replace(/\/+$/, '') + '/' + String(path).replace(/^\/+/, '')
+      : path
+  if (query && Object.keys(query).length) {
+    const qs = new URLSearchParams(query).toString()
+    url += (url.includes('?') ? '&' : '?') + qs
+  }
+  return url
+}
+
+function retriable(err) {
+  if (err.status) return err.status >= 500 || err.status === 429
+  return true // network error or timeout
+}
+
+// One request, following up to 5 redirects (301/302/303 → GET, 307/308 keep method+body).
+function once(method, url, payload, headers, timeout, hops = 0) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url)
+    const lib = u.protocol === 'https:' ? https : http
+    const req = lib.request(u, { method, headers }, (res) => {
+      const { statusCode: status, headers: resHeaders } = res
+      if (resHeaders.location && status >= 300 && status < 400 && hops < 5) {
+        res.resume()
+        const next = new URL(resHeaders.location, url).toString()
+        let m = method, p = payload, h = headers
+        if (status === 303 || ((status === 301 || status === 302) && method === 'POST')) {
+          m = 'GET'; p = null
+          h = { ...headers }; delete h['content-length']; delete h['content-type']
+        }
+        return resolve(once(m, next, p, h, timeout, hops + 1))
+      }
+      const chunks = []
+      res.on('data', (c) => chunks.push(c))
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8')
+        const ct = resHeaders['content-type'] || ''
+        let data = text
+        if (ct.includes('application/json') && text) { try { data = JSON.parse(text) } catch { /* keep text */ } }
+        const result = { status, headers: resHeaders, data }
+        if (status >= 400) {
+          const e = new Error(`HTTP ${status} ${method} ${url}`)
+          e.status = status; e.response = result
+          return reject(e)
+        }
+        resolve(result)
+      })
+    })
+    req.on('error', reject)
+    req.setTimeout(timeout, () => req.destroy(new Error(`@digta/network: request timed out after ${timeout}ms`)))
+    if (payload != null) req.write(payload)
+    req.end()
+  })
+}
+
+function createApi(opts = {}) {
+  const base = opts.baseURL || opts.baseUrl || ''
+  const cfg = {
+    timeout: opts.timeout ?? 30000,
+    retries: opts.retries ?? 0,
+    retryDelay: opts.retryDelay ?? 500,
+    headers: opts.headers || {},
+  }
+
+  function request(method, path, { body, headers, query, timeout, retries } = {}) {
+    const url = buildUrl(base, path, query)
+    const isJsonBody = body != null && typeof body === 'object' && !Buffer.isBuffer(body)
+    const payload = body == null ? null : isJsonBody ? JSON.stringify(body) : body
+    const finalHeaders = {
+      ...cfg.headers,
+      ...headers,
+      ...(isJsonBody ? { 'content-type': 'application/json' } : {}),
+      ...(payload != null ? { 'content-length': Buffer.byteLength(payload) } : {}),
+    }
+    const maxRetries = retries ?? cfg.retries
+    const to = timeout ?? cfg.timeout
+
+    const attempt = (n) =>
+      once(method, url, payload, finalHeaders, to).catch((err) => {
+        if (n < maxRetries && retriable(err)) return sleep(cfg.retryDelay * 2 ** n).then(() => attempt(n + 1))
+        throw err
+      })
+    return attempt(0)
+  }
+
+  return {
+    request,
+    get: (p, o) => request('GET', p, o),
+    delete: (p, o) => request('DELETE', p, o),
+    head: (p, o) => request('HEAD', p, o),
+    post: (p, body, o) => request('POST', p, { ...o, body }),
+    put: (p, body, o) => request('PUT', p, { ...o, body }),
+    patch: (p, body, o) => request('PATCH', p, { ...o, body }),
+  }
+}
+
+module.exports = { createApi }

package/connection.js

@@ -0,0 +1,154 @@
+'use strict'
+
+const EventEmitter = require('events')
+
+let _WS
+function getWs() {
+  if (_WS) return _WS
+  try { _WS = require('ws') }
+  catch { throw new Error('@digta/network: WebSocket support needs ws — run `npm i ws`') }
+  return _WS
+}
+
+function openTcp(conn) {
+  const net = require('net')
+  const socket = net.connect({ host: conn.host, port: conn.port })
+  socket.setKeepAlive(true, conn.opts.heartbeat || 10000) // OS-level dead-link detection
+  socket.on('connect', () => conn._onOpen())
+  socket.on('data', (d) => conn._onData(d))
+  socket.on('close', () => conn._onClose())
+  socket.on('error', (e) => conn._onError(e))
+  return {
+    supportsPing: false, // raw TCP has no ping frame — see _onData / opts.ping
+    send: (data) => socket.write(data),
+    ping: (payload) => { if (payload) socket.write(payload) },
+    close: () => socket.destroy(),
+  }
+}
+
+function openWs(conn) {
+  const WebSocket = getWs()
+  const ws = new WebSocket(conn.url)
+  ws.on('open', () => conn._onOpen())
+  ws.on('message', (d) => conn._onData(d))
+  ws.on('pong', () => conn._onPong())
+  ws.on('close', () => conn._onClose())
+  ws.on('error', (e) => conn._onError(e))
+  return {
+    supportsPing: true, // native ping/pong frames → heartbeat + latency for free
+    send: (data) => ws.send(data),
+    ping: () => ws.ping(),
+    close: () => ws.close(),
+  }
+}
+
+class Connection extends EventEmitter {
+  constructor(opts = {}) {
+    super()
+    this.opts = { heartbeat: 0, heartbeatTimeout: 10000, reconnect: true, maxRetries: Infinity, ...opts }
+    this.backoff = { min: 500, max: 30000, factor: 2, ...(opts.backoff || {}) }
+
+    if (opts.url) {
+      const u = new URL(opts.url)
+      this.transport = u.protocol === 'tcp:' ? 'tcp' : 'ws'
+      this.host = u.hostname
+      this.port = Number(u.port)
+      this.url = opts.url
+    } else {
+      this.transport = opts.transport || 'tcp'
+      this.host = opts.host
+      this.port = opts.port
+      if (this.transport === 'ws') this.url = opts.url || `ws://${this.host}:${this.port}`
+    }
+
+    this.connected = false
+    this.latency = null
+    this._attempt = 0
+    this._intentional = false
+    this._raw = null
+  }
+
+  connect() {
+    if (this.connected) return this
+    this._intentional = false
+    clearTimeout(this._reconnectTimer)
+    this._raw = this.transport === 'ws' ? openWs(this) : openTcp(this)
+    return this
+  }
+
+  send(data) {
+    if (!this.connected) throw new Error('@digta/network: not connected')
+    this._raw.send(data)
+    return this
+  }
+
+  close() {
+    this._intentional = true
+    clearTimeout(this._reconnectTimer)
+    this._stopHeartbeat()
+    if (this._raw) this._raw.close()
+    this.connected = false
+    return this
+  }
+
+  _onOpen() {
+    this.connected = true
+    this._attempt = 0
+    this.emit('connect')
+    this._startHeartbeat()
+  }
+
+  _onData(data) {
+    // TCP has no ping frame: if the caller taught us to recognize a pong, use it for latency.
+    if (!this._raw.supportsPing && this.opts.isPong && this.opts.isPong(data)) return this._onPong()
+    this.emit('message', data)
+  }
+
+  _onClose() {
+    this._stopHeartbeat()
+    this.connected = false
+    this.emit('close')
+    if (!this._intentional) this._scheduleReconnect()
+  }
+
+  _onError(err) {
+    // Swallow when unheard: reconnect recovers, and an unhandled 'error' would crash the process.
+    if (this.listenerCount('error')) this.emit('error', err)
+  }
+
+  _scheduleReconnect() {
+    if (!this.opts.reconnect) return
+    if (this._attempt >= this.opts.maxRetries) return this.emit('reconnect_failed', this._attempt)
+    const { min, max, factor } = this.backoff
+    const base = Math.min(max, min * Math.pow(factor, this._attempt))
+    const delay = Math.round(base / 2 + Math.random() * (base / 2)) // exponential backoff + full jitter
+    this._attempt++
+    this.emit('reconnecting', this._attempt, delay)
+    this._reconnectTimer = setTimeout(() => this.connect(), delay)
+  }
+
+  _startHeartbeat() {
+    if (!this.opts.heartbeat) return
+    if (!this._raw.supportsPing && !this.opts.ping) return // TCP heartbeat needs a ping payload
+    this._hbTimer = setInterval(() => this._ping(), this.opts.heartbeat)
+  }
+
+  _ping() {
+    if (!this.connected) return
+    this._pingAt = Date.now()
+    try { this._raw.ping(this.opts.ping) } catch { return }
+    this._pongTimer = setTimeout(() => { this.emit('timeout'); this._raw.close() }, this.opts.heartbeatTimeout)
+  }
+
+  _onPong() {
+    clearTimeout(this._pongTimer)
+    if (this._pingAt) { this.latency = Date.now() - this._pingAt; this.emit('latency', this.latency) }
+  }
+
+  _stopHeartbeat() {
+    clearInterval(this._hbTimer)
+    clearTimeout(this._pongTimer)
+  }
+}
+
+module.exports = { Connection, createConnection: (opts) => new Connection(opts) }

package/index.d.ts

@@ -0,0 +1,96 @@
+import { EventEmitter } from 'events'
+
+// ── Connection (TCP / WebSocket + autoreconnect) ──────────────────────────
+
+export interface BackoffOptions {
+  /** First retry delay in ms. Default 500. */
+  min?: number
+  /** Cap on retry delay in ms. Default 30000. */
+  max?: number
+  /** Multiplier per attempt. Default 2. */
+  factor?: number
+}
+
+export interface ConnectionOptions {
+  /** `tcp://host:port`, `ws://host:port/path`, or `wss://…`. Sets transport + address. */
+  url?: string
+  /** Used instead of `url`. */
+  transport?: 'tcp' | 'ws'
+  host?: string
+  port?: number
+  /** Auto-reconnect on drop. Default true. */
+  reconnect?: boolean
+  /** Max reconnect attempts. Default Infinity. */
+  maxRetries?: number
+  /** Reconnect backoff schedule. */
+  backoff?: BackoffOptions
+  /** Ping interval in ms (0 = off). WS uses native ping/pong; TCP needs `ping`+`isPong`. */
+  heartbeat?: number
+  /** Drop + reconnect if no pong within this many ms. Default 10000. */
+  heartbeatTimeout?: number
+  /** TCP only: bytes to send as a heartbeat ping. */
+  ping?: string | Buffer
+  /** TCP only: returns true if the received data is the pong to our ping. */
+  isPong?: (data: Buffer) => boolean
+}
+
+/**
+ * Events: `connect`, `message(data)`, `close`, `error(err)`,
+ * `reconnecting(attempt, delayMs)`, `reconnect_failed(attempts)`,
+ * `latency(ms)`, `timeout`.
+ */
+export class Connection extends EventEmitter {
+  constructor(options?: ConnectionOptions)
+  readonly connected: boolean
+  /** Last measured round-trip in ms (heartbeat), or null. */
+  readonly latency: number | null
+  readonly transport: 'tcp' | 'ws'
+  connect(): this
+  send(data: string | Buffer | ArrayBufferView): this
+  /** Close intentionally — no reconnect. */
+  close(): this
+}
+
+export function createConnection(options?: ConnectionOptions): Connection
+
+// ── API (HTTP client with retries) ────────────────────────────────────────
+
+export interface ApiOptions {
+  baseURL?: string
+  headers?: Record<string, string>
+  /** Per-request timeout in ms. Default 30000. */
+  timeout?: number
+  /** Retry count for network errors, timeouts, 429, and 5xx. Default 0. */
+  retries?: number
+  /** Base retry delay in ms (doubles each attempt). Default 500. */
+  retryDelay?: number
+}
+
+export interface RequestOptions {
+  body?: unknown
+  headers?: Record<string, string>
+  query?: Record<string, string | number | boolean>
+  timeout?: number
+  retries?: number
+}
+
+export interface Response<T = any> {
+  status: number
+  headers: Record<string, string | string[] | undefined>
+  data: T
+}
+
+export interface Api {
+  request<T = any>(method: string, path: string, options?: RequestOptions): Promise<Response<T>>
+  get<T = any>(path: string, options?: RequestOptions): Promise<Response<T>>
+  delete<T = any>(path: string, options?: RequestOptions): Promise<Response<T>>
+  head<T = any>(path: string, options?: RequestOptions): Promise<Response<T>>
+  post<T = any>(path: string, body?: unknown, options?: RequestOptions): Promise<Response<T>>
+  put<T = any>(path: string, body?: unknown, options?: RequestOptions): Promise<Response<T>>
+  patch<T = any>(path: string, body?: unknown, options?: RequestOptions): Promise<Response<T>>
+}
+
+export function createApi(options?: ApiOptions): Api
+
+/** Ready-to-use client for absolute URLs. */
+export const api: Api

package/index.js

@@ -0,0 +1,11 @@
+'use strict'
+
+const { Connection, createConnection } = require('./connection')
+const { createApi } = require('./api')
+
+module.exports = {
+  Connection,
+  createConnection, // TCP / WebSocket client with autoreconnect
+  createApi,        // HTTP client with retries
+  api: createApi(), // ready-to-use HTTP client for absolute URLs
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@digta/network",
+  "version": "0.1.0",
+  "description": "TCP + WebSocket client with autoreconnect, plus a tiny HTTP API client with retries. One toolkit.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "connection.js",
+    "api.js",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "tcp",
+    "websocket",
+    "ws",
+    "reconnect",
+    "autoreconnect",
+    "http",
+    "api",
+    "client",
+    "retry"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}