bridgewire 1.0.2 → 2.0.0

package/README.md

@@ -1,68 +1,463 @@
 # BridgeWire
 
-**BridgeWire** is a transport-agnostic client for HTTP and WebSocket communication.
+Transport-agnostic client for HTTP and WebSocket communication.
 
-> ⚠️ BridgeWire is currently in early development! The public API is not stable yet.
+BridgeWire provides a fluent builder API for creating typed transports over `fetch` and `WebSocket`. It is designed to keep request lifecycle handling, subscriptions, timeouts, parsing, and transport selection in one consistent API.
 
-The goal of the project is to provide a unified interface for sending requests over different transports, such as Fetch and WebSocket, with a clean and extensible architecture.
+[Coverage report](https://kuznetsovlv.github.io/bridgewire/)
 
-## Features
+## Status
 
-Planned features:
+BridgeWire is under active development.
 
-- Unified API for HTTP Fetch and WebSocket
-- Adapter-based architecture
-- Request/response abstraction
-- Error handling
-- Request cancellation
-- Extensible transport layer
-- Optional reactive layer with RxJS in the future
+Current support:
 
-## Getting started
+- Fetch-based transport
+- WebSocket-based transport
+- Typed request and response data
+- Request lifecycle statuses
+- Transport-level subscriptions
+- Request-level message, error, abort, and settled events
+- Timeout handling
+- Content-type based default fetch response parser
+- Explicit payload parser selection through `PayloadDataType`
+- GitHub Actions CI
+- HTML coverage report via GitHub Pages
 
-Install dependencies:
+## Installation
+
+After the package is published:
+
+```bash
+npm install bridgewire
+```
+
+For local development:
 
 ```bash
+git clone https://github.com/kuznetsovlv/bridgewire.git
+cd bridgewire
 npm install
 ```
 
+## Basic usage
+
+```ts
+import getBridgeWireBuilder, {
+    HTTPMethod,
+    PayloadDataType,
+    Protocol,
+    TransportType,
+} from 'bridgewire';
+
+type UserQuery = {
+    id: string;
+};
+
+type UserResponse = {
+    id: string;
+    name: string;
+};
+
+const transport = getBridgeWireBuilder<UserQuery, UserResponse>()
+    .withTransport(TransportType.FETCH)
+    .withProtocol(Protocol.HTTPS)
+    .withHost('api.example.com')
+    .withPath('/users')
+    .withMethod(HTTPMethod.GET)
+    .withDataType(PayloadDataType.JSON)
+    .build();
+
+const unsubscribeMessage = transport.onMessage((id, data) => {
+    console.log('Message from request:', id, data);
+});
+
+const unsubscribeError = transport.onRequestError((id, error) => {
+    console.error('Request error:', id, error);
+});
+
+const request = transport.send({
+    id: '42',
+});
+
+console.log(request?.status);
+```
+
+For `GET`, `HEAD`, `DELETE`, and `OPTIONS`, plain object request data is merged into the URL query string.
+
+```ts
+transport.send({
+    page: '1',
+    search: 'react',
+});
+```
+
+This produces a request URL similar to:
+
+```text
+https://api.example.com/users?page=1&search=react
+```
+
+## Fetch POST example
+
+```ts
+import getBridgeWireBuilder, {
+    HTTPMethod,
+    PayloadDataType,
+    Protocol,
+    TransportType,
+} from 'bridgewire';
+
+type CreateUserRequest = {
+    name: string;
+};
+
+type CreateUserResponse = {
+    id: string;
+    name: string;
+};
+
+const transport = getBridgeWireBuilder<CreateUserRequest, CreateUserResponse>()
+    .withTransport(TransportType.FETCH)
+    .withProtocol(Protocol.HTTPS)
+    .withHost('api.example.com')
+    .withPath('/users')
+    .withMethod(HTTPMethod.POST)
+    .withHeader('Content-Type', 'application/json')
+    .withDataType(PayloadDataType.JSON)
+    .withTimeout(5000)
+    .build();
+
+transport.onMessage((id, data) => {
+    console.log('Created user:', id, data);
+});
+
+transport.onSettled((id, status, error) => {
+    console.log('Request settled:', id, status, error);
+});
+
+transport.send({
+    name: 'Leonid',
+});
+```
+
+For `POST`, `PUT`, and `PATCH`, plain object request data is serialized to JSON.
+
+Native Fetch body values are passed through:
+
+- `string`
+- `FormData`
+- `Blob`
+- `ArrayBuffer`
+- `ArrayBufferView`
+- `URLSearchParams`
+
+## WebSocket example
+
+```ts
+import getBridgeWireBuilder, {
+    PayloadDataType,
+    Protocol,
+    TransportType,
+} from 'bridgewire';
+
+type ClientMessage = {
+    type: 'ping';
+};
+
+type ServerMessage = {
+    type: 'pong';
+};
+
+const transport = getBridgeWireBuilder<ClientMessage, ServerMessage>()
+    .withTransport(TransportType.WEBSOCKET)
+    .withProtocol(Protocol.WSS)
+    .withHost('example.com')
+    .withPath('/socket')
+    .withDataType(PayloadDataType.JSON)
+    .withTimeout(5000)
+    .build();
+
+transport.onMessage((id, data) => {
+    console.log('WebSocket message:', id, data);
+});
+
+transport.onRequestError((id, error) => {
+    console.error('WebSocket request error:', id, error);
+});
+
+transport.onError((error) => {
+    console.error('Transport error:', error);
+});
+
+const request = transport.send({
+    type: 'ping',
+});
+```
+
+The current WebSocket model represents a socket stream. While the socket request is active, multiple incoming messages can be emitted through the same request.
+
+When `PayloadDataType.JSON` is used, incoming messages are parsed with `JSON.parse`.
+
+## Builder API
+
+The main entry point is:
+
+```ts
+getBridgeWireBuilder<RequestData, ResponseData>();
+```
+
+The builder supports fluent configuration:
+
+```ts
+const transport = getBridgeWireBuilder<RequestData, ResponseData>()
+    .withTransport(TransportType.FETCH)
+    .withProtocol(Protocol.HTTPS)
+    .withHost('api.example.com')
+    .withPort(443)
+    .withPath('/api')
+    .withQuery({page: '1'})
+    .withHash('top')
+    .withMethod(HTTPMethod.GET)
+    .withHeader('Accept', 'application/json')
+    .withTimeout(5000)
+    .build();
+```
+
+### Transport configuration
+
+```ts
+.withTransport(TransportType.FETCH)
+.withTransport(TransportType.WEBSOCKET)
+```
+
+If transport is omitted, BridgeWire infers it from the configured or default protocol:
+
+- `http` / `https` -> Fetch
+- `ws` / `wss` -> WebSocket
+
+### URL configuration
+
+```ts
+.withProtocol(Protocol.HTTPS)
+.withHost('api.example.com')
+.withPort(443)
+.withPath('/users')
+.withQuery({ page: '1', tag: ['react', 'typescript'] })
+.withHash('section')
+.withUrl('https://api.example.com/users?page=1#section')
+```
+
+`withUrl` accepts URL-like strings and applies parsed URL parts to the builder.
+
+### Fetch configuration
+
+```ts
+.withMethod(HTTPMethod.POST)
+.withHeaders({ Accept: 'application/json' })
+.withHeader('Content-Type', 'application/json')
+.withReferrer('about:client')
+.withReferrerPolicy('strict-origin-when-cross-origin')
+.withMode(FetchMode.CORS)
+.withCredentials(FetchCredentials.SAME_ORIGIN)
+.withCache(FetchCache.NO_CACHE)
+.withRedirect(FetchRedirect.FOLLOW)
+.withIntegrity('sha256-...')
+.withKeepAlive()
+```
+
+### WebSocket configuration
+
+```ts
+.withSoap()
+.withWamp()
+```
+
+These methods enable the corresponding WebSocket subprotocol flags.
+
+### Payload data type
+
+```ts
+.withDataType(PayloadDataType.JSON)
+.withDataType(PayloadDataType.TEXT)
+.withDataType(PayloadDataType.BLOB)
+.withDataType(PayloadDataType.FORM_DATA)
+.withDataType(PayloadDataType.ARRAY_BUFFER)
+```
+
+For Fetch, the data type selects the response parser.
+
+For WebSocket, `PayloadDataType.JSON` parses incoming messages with `JSON.parse`, and `PayloadDataType.ARRAY_BUFFER` sets socket `binaryType` to `arraybuffer`.
+
+## Request lifecycle
+
+Requests can have the following statuses:
+
+```ts
+RequestStatus.Pending;
+RequestStatus.Completed;
+RequestStatus.Failed;
+RequestStatus.Aborted;
+RequestStatus.TimedOut;
+```
+
+A request is considered settled when it reaches one of these terminal states:
+
+- `Completed`
+- `Failed`
+- `Aborted`
+- `TimedOut`
+
+## Transport lifecycle
+
+Transports can have the following statuses:
+
+```ts
+TransportStatus.Disconnected;
+TransportStatus.Connecting;
+TransportStatus.Connected;
+TransportStatus.Closing;
+TransportStatus.Error;
+```
+
+## Subscriptions
+
+Transport-level subscriptions:
+
+```ts
+transport.onMessage((id, data) => {
+    console.log(id, data);
+});
+
+transport.onRequestError((id, error) => {
+    console.error(id, error);
+});
+
+transport.onAbort((id) => {
+    console.log('Aborted:', id);
+});
+
+transport.onSettled((id, status, error) => {
+    console.log('Settled:', id, status, error);
+});
+
+transport.onError((error) => {
+    console.error('Transport error:', error);
+});
+```
+
+Each subscription returns an unsubscribe function:
+
+```ts
+const unsubscribe = transport.onMessage((id, data) => {
+    console.log(id, data);
+});
+
+unsubscribe();
+```
+
+## Timeouts
+
+Timeouts can be configured at builder level:
+
+```ts
+const transport = getBridgeWireBuilder<RequestData, ResponseData>()
+    .withTimeout(5000)
+    .build();
+```
+
+They can also be overridden per request:
+
+```ts
+transport.send(data, {
+    timeout: 1000,
+});
+```
+
+For Fetch, timeout aborts the underlying fetch request.
+
+For WebSocket, timeout currently applies to the connection opening phase.
+
+## Compatibility rules
+
+BridgeWire validates some incompatible configuration combinations:
+
+- `http` / `https` protocols are compatible with Fetch transport
+- `ws` / `wss` protocols are compatible with WebSocket transport
+- `FormData` payload type is not compatible with WebSocket transport
+- `FormData` payload type is not compatible with `ws` / `wss` protocols
+
+## Public API
+
+Recommended public imports:
+
+```ts
+import getBridgeWireBuilder, {
+    FetchCache,
+    FetchCredentials,
+    FetchMode,
+    FetchRedirect,
+    HTTPMethod,
+    PayloadDataType,
+    Protocol,
+    RequestStatus,
+    TransportStatus,
+    TransportType,
+} from 'bridgewire';
+
+import type {
+    BridgeWireTransportAbortCallback,
+    BridgeWireTransportCallback,
+    BridgeWireTransportSettledCallback,
+    ErrorCallback,
+    Query,
+    RequestId,
+    RequestOptions,
+    UnsubscribeMethod,
+} from 'bridgewire';
+```
+
+Internal implementation details should not be considered stable public API.
+
 ## Development
 
-Run tests in watch mode:
+Install dependencies:
 
 ```bash
-npm run test:watch
+npm install
 ```
 
-Run tests once:
+Run tests:
 
 ```bash
 npm run test
 ```
 
-## Build
-
-Build the library:
+Run tests in watch mode:
 
 ```bash
-npm run build
+npm run test:watch
 ```
 
-This will:
+Run coverage:
 
-- clean the `dist` folder
-- build ESM and CJS bundles using Vite
-- generate TypeScript declaration files
+```bash
+npm run coverage
+```
+
+Open the local HTML coverage report:
 
-## Lint and format
+```bash
+xdg-open coverage/index.html
+```
 
-Run ESLint:
+Run lint:
 
 ```bash
 npm run lint
 ```
 
-Format code:
+Format files:
 
 ```bash
 npm run format
@@ -74,39 +469,98 @@ Check formatting:
 npm run format:check
 ```
 
-## Full check
+Build package:
+
+```bash
+npm run build
+```
 
-Run all checks:
+Run full local check:
 
 ```bash
 npm run check
 ```
 
-Includes:
+## CI
+
+The project uses GitHub Actions for:
+
+- formatting check
+- ESLint
+- unit tests
+- coverage generation
+- package build
+- coverage report deployment to GitHub Pages
+
+Coverage report:
+
+```text
+https://kuznetsovlv.github.io/bridgewire/
+```
+
+## Release workflow
+
+This project uses Changesets.
+
+Create a changeset:
+
+```bash
+npm run changeset
+```
+
+Version packages:
+
+```bash
+npm run version-packages
+```
+
+Release:
+
+```bash
+npm run release
+```
 
-- lint
-- format check
-- tests
-- build
+Before publishing, review the public exports and make sure only stable API is exported.
 
 ## Project structure
 
 ```text
 src/
+  BridgeWireBuilder.ts
   index.ts
-  index.test.ts
-dist/
+  types.ts
+
+  BridgeWireTransport/
+    BridgeWireTransport.ts
+    FetchBridgeWireTransport.ts
+    WebSocketBridgeWireTransport.ts
+
+  Request/
+    Request.ts
+    FetchRequest.ts
+    WebSocketRequest.ts
+
+  utils/
+    compatibilityAsserts.ts
+    isArrayBufferView.ts
+    subscribe.ts
+    url.ts
 ```
 
-## Architecture
+## Notes
 
-BridgeWire is designed around the idea of transport abstraction:
+BridgeWire is still evolving. The current API is usable, but some details may change before the first stable release.
 
-- Fetch transport
-- WebSocket transport
-- Unified client interface
+Important areas to review before publishing:
 
-More details will be added as the implementation evolves.
+- public exports
+- README examples
+- generated declaration files
+- package contents
+- compatibility rules
+- WebSocket transport semantics
+- header normalization
+- coverage and CI status
 
 ## License
 

package/package.json

@@ -1,60 +1,65 @@
 {
-  "name": "bridgewire",
-  "version": "1.0.2",
-  "description": "Transport-agnostic client for HTTP and WebSocket communication",
-  "keywords": [],
-  "author": "Kuznetsov Leonid",
-  "license": "MIT",
-  "type": "module",
-  "main": "./dist/bridgewire.cjs",
-  "module": "./dist/bridgewire.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/bridgewire.js",
-      "require": "./dist/bridgewire.cjs"
+    "name": "bridgewire",
+    "version": "2.0.0",
+    "description": "Transport-agnostic client for HTTP and WebSocket communication",
+    "keywords": [],
+    "author": "Kuznetsov Leonid",
+    "license": "MIT",
+    "type": "module",
+    "main": "./dist/bridgewire.cjs",
+    "module": "./dist/bridgewire.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/bridgewire.js",
+            "require": "./dist/bridgewire.cjs"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/kuznetsovlv/bridgewire.git"
+    },
+    "bugs": {
+        "url": "https://github.com/kuznetsovlv/bridgewire/issues"
+    },
+    "homepage": "https://github.com/kuznetsovlv/bridgewire#readme",
+    "scripts": {
+        "dev": "vite",
+        "prebuild": "npm run clean",
+        "build": "vite build",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "coverage": "vitest run --coverage",
+        "lint": "eslint .",
+        "format": "prettier . --write",
+        "format:check": "prettier . --check",
+        "check": "npm run lint && npm run format:check && npm run test && npm run build",
+        "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+        "changeset": "changeset",
+        "version-packages": "changeset version",
+        "release": "npm run check && changeset publish"
+    },
+    "devDependencies": {
+        "@changesets/cli": "^2.31.0",
+        "@eslint/js": "^10.0.1",
+        "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+        "@types/node": "^25.6.0",
+        "@vitest/coverage-v8": "^4.1.7",
+        "eslint": "^10.3.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-simple-import-sort": "^13.0.0",
+        "prettier": "^3.8.3",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.59.2",
+        "vite": "^8.0.10",
+        "vite-plugin-dts": "^5.0.0",
+        "vitest": "^4.1.5"
+    },
+    "publishConfig": {
+        "access": "public"
     }
-  },
-  "files": [
-    "dist"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kuznetsovlv/bridgewire.git"
-  },
-  "bugs": {
-    "url": "https://github.com/kuznetsovlv/bridgewire/issues"
-  },
-  "homepage": "https://github.com/kuznetsovlv/bridgewire#readme",
-  "scripts": {
-    "dev": "vite",
-    "prebuild": "npm run clean",
-    "build": "vite build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "eslint .",
-    "format": "prettier . --write",
-    "format:check": "prettier . --check",
-    "check": "npm run lint && npm run format:check && npm run test && npm run build",
-    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "npm run check && changeset publish"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.31.0",
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^25.6.0",
-    "eslint": "^10.3.0",
-    "prettier": "^3.8.3",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.2",
-    "vite": "^8.0.10",
-    "vite-plugin-dts": "^5.0.0",
-    "vitest": "^4.1.5"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
 }