@stonyx/sockets 0.1.1-alpha.37 → 0.1.1-alpha.39

package/README.md

@@ -15,6 +15,17 @@ WebSocket server and client module for the [Stonyx framework](https://github.com
 * **Encryption by default:** AES-256-GCM with per-session keys, zero external dependencies.
 * **Singleton pattern:** Matches the conventions of `@stonyx/rest-server` and `stonyx-orm`.
 
+## Usage reference
+
+The handlers in [`test/sample/`](https://github.com/abofs/stonyx-sockets/tree/dev/test/sample) are the canonical usage reference for this module; the integration tests run against them. They are not included in the npm package.
+
+Exports:
+
+* `@stonyx/sockets`: named `SocketServer`, `SocketClient` and `Handler`; the default export is the `Sockets` class Stonyx uses for auto-init
+* `@stonyx/sockets/server`: `SocketServer`
+* `@stonyx/sockets/client`: `SocketClient`
+* `@stonyx/sockets/handler`: `Handler`
+
 ## Installation
 
 ```bash
@@ -205,28 +216,15 @@ Configuration is read from `stonyx/config` under `sockets`:
 | Option | Env Var | Default | Description |
 |--------|---------|---------|-------------|
 | `port` | `SOCKET_PORT` | `2667` | WebSocket server port |
-| `address` | `SOCKET_ADDRESS` | `ws://localhost:{port}` | Client connection address |
+| `address` | `SOCKET_ADDRESS` | `ws://localhost:2667` | Client connection address |
 | `authKey` | `SOCKET_AUTH_KEY` | `'AUTH_KEY'` | Shared authentication key |
 | `heartBeatInterval` | `SOCKET_HEARTBEAT_INTERVAL` | `30000` | Heartbeat interval in ms |
 | `handlerDir` | `SOCKET_HANDLER_DIR` | `'./socket-handlers'` | Handler directory path |
-| `log` | `SOCKET_LOG` | `false` | Enable verbose logging |
 | `encryption` | `SOCKET_ENCRYPTION` | `'true'` | Enable AES-256-GCM encryption |
-| `reconnectBaseDelay` | `SOCKET_RECONNECT_BASE_DELAY` | `1000` | Base delay in ms for reconnect backoff |
-| `reconnectMaxDelay` | `SOCKET_RECONNECT_MAX_DELAY` | `60000` | Ceiling in ms for reconnect backoff |
-| `maxReconnectAttempts` | `SOCKET_MAX_RECONNECT_ATTEMPTS` | `Infinity` | Reconnect attempts before giving up |
-
-That is every variable `config/environment.js` reads -- all ten. `authData`
-(`{}`), `logColor` (`'white'`) and `logMethod` (`'socket'`) are also part of the
-resolved config but are not settable from the environment. No environment value
-is coerced: each resolves as the string the shell supplied.
-
-> **If your app consumes this package and runs its own test suite:** pin all ten
-> of these in your own `test/config/environment.js`, and keep `port` and
-> `address` coupled -- `address` is computed from `port` at module-eval time, so
-> pinning `port` alone does not move it. This package reads these variables
-> unconditionally, so a `NODE_ENV=test` run in a shell that exports
-> `SOCKET_ADDRESS` will dial whatever it names and send `authKey` to it. See
-> [docs/configuration.md](docs/configuration.md#why-all-ten-keys-are-pinned).
+| `authData` | — | `{}` | Extra fields sent with `authKey` in the auth request |
+| `reconnectBaseDelay` | `SOCKET_RECONNECT_BASE_DELAY` | `1000` | First reconnect delay in ms (doubles per attempt) |
+| `reconnectMaxDelay` | `SOCKET_RECONNECT_MAX_DELAY` | `60000` | Reconnect delay cap in ms |
+| `maxReconnectAttempts` | `SOCKET_MAX_RECONNECT_ATTEMPTS` | `Infinity` | Attempts before `onReconnectFailed` |
 
 ## API Reference
 
@@ -237,7 +235,9 @@ is coerced: each resolves as the string the shell supplied.
 | `new SocketServer()` | Singleton constructor |
 | `async init()` | Discover handlers, validate auth, start WebSocket server |
 | `sendTo(clientId, request, data)` | Send to one client by ID |
+| `sendToByMeta(key, value, request, data)` | Send to the first authenticated client whose `meta[key] === value`; returns `true`/`false` |
 | `broadcast(request, data)` | Send to all authenticated clients |
+| `onClientDisconnect` | Optional `(client, code, reason)` callback |
 | `clientMap` | `Map<id, client>` of connected clients |
 | `close()` | Terminate all connections and stop the server |
 | `reset()` | Close + clear all state (for testing) |
@@ -250,7 +250,8 @@ is coerced: each resolves as the string the shell supplied.
 | `async init()` | Discover handlers, connect, authenticate |
 | `send(payload)` | Send a message to the server |
 | `close()` | Forcefully tear down the socket (remove listeners, terminate, null) |
-| `reconnect()` | Reconnect (max 5 retries) |
+| `reconnect()` | Reconnect with exponential backoff, up to `maxReconnectAttempts` (unlimited by default) |
+| `onDisconnect`, `onReconnecting`, `onReconnected`, `onReconnectFailed` | Optional lifecycle callbacks |
 | `reset()` | Close + clear all state (for testing) |
 
 ### Handler

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.37",
+  "version": "0.1.1-alpha.39",
   "description": "WebSocket server and client module for the Stonyx framework",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -51,11 +51,11 @@
   },
   "homepage": "https://github.com/abofs/stonyx-sockets#readme",
   "dependencies": {
-    "stonyx": "0.2.3-beta.62",
+    "stonyx": "0.2.3-beta.98",
     "ws": "^8.18.1"
   },
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.23",
+    "@stonyx/utils": "0.2.3-beta.27",
     "@types/node": "^25.5.2",
     "@types/ws": "^8.18.1",
     "qunit": "^2.24.1",