@connexis/testing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connexis Realtime Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,69 @@
+import { Transport, TransportCapabilities, ConnectionState } from '@connexis/core';
+
+declare class MockTransport implements Transport {
+    private caps;
+    readonly type = "mock";
+    private _state;
+    private messageCallback;
+    private stateCallback;
+    published: Array<{
+        topic: string;
+        data: any;
+    }>;
+    subscribed: Array<{
+        topic: string;
+        filter?: Record<string, any>;
+    }>;
+    unsubscribed: Array<{
+        topic: string;
+        filter?: Record<string, any>;
+    }>;
+    private failNextConnect;
+    private failError;
+    private connectDelay;
+    constructor(caps?: TransportCapabilities);
+    get state(): ConnectionState;
+    setFailNextConnect(fail: boolean, error?: Error): void;
+    setConnectDelay(delayMs: number): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    publish(topic: string, data: any): Promise<void>;
+    subscribe(topic: string, filter?: Record<string, any>): Promise<void>;
+    unsubscribe(topic: string, filter?: Record<string, any>): Promise<void>;
+    capabilities(): TransportCapabilities;
+    onMessage(cb: (topic: string, data: any) => void): void;
+    onStateChange(cb: (state: ConnectionState, error?: Error) => void): void;
+    clone(): MockTransport;
+    simulateMessage(topic: string, data: any): void;
+    simulateStateChange(state: ConnectionState, error?: Error): void;
+    private updateState;
+}
+
+/**
+ * Benchmark Results Interface
+ */
+interface BenchmarkReport {
+    operation: string;
+    count: number;
+    durationMs: number;
+    opsPerSecond: number;
+}
+/**
+ * Runs a performance benchmark for core client operations.
+ */
+declare function runBenchmarks(): Promise<BenchmarkReport[]>;
+/**
+ * Scenario: Stress test hybrid policy deduplication with 1,000 subscriptions.
+ */
+declare function runHybridStressTest(): Promise<{
+    connectionsCount: number;
+    subscriptionsCount: number;
+}>;
+/**
+ * Scenario: Simulate 10 tabs and trigger random network online/offline events.
+ */
+declare function runNetworkChaosStressTest(cycles?: number): Promise<{
+    success: boolean;
+}>;
+
+export { type BenchmarkReport, MockTransport, runBenchmarks, runHybridStressTest, runNetworkChaosStressTest };

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import { Transport, TransportCapabilities, ConnectionState } from '@connexis/core';
+
+declare class MockTransport implements Transport {
+    private caps;
+    readonly type = "mock";
+    private _state;
+    private messageCallback;
+    private stateCallback;
+    published: Array<{
+        topic: string;
+        data: any;
+    }>;
+    subscribed: Array<{
+        topic: string;
+        filter?: Record<string, any>;
+    }>;
+    unsubscribed: Array<{
+        topic: string;
+        filter?: Record<string, any>;
+    }>;
+    private failNextConnect;
+    private failError;
+    private connectDelay;
+    constructor(caps?: TransportCapabilities);
+    get state(): ConnectionState;
+    setFailNextConnect(fail: boolean, error?: Error): void;
+    setConnectDelay(delayMs: number): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    publish(topic: string, data: any): Promise<void>;
+    subscribe(topic: string, filter?: Record<string, any>): Promise<void>;
+    unsubscribe(topic: string, filter?: Record<string, any>): Promise<void>;
+    capabilities(): TransportCapabilities;
+    onMessage(cb: (topic: string, data: any) => void): void;
+    onStateChange(cb: (state: ConnectionState, error?: Error) => void): void;
+    clone(): MockTransport;
+    simulateMessage(topic: string, data: any): void;
+    simulateStateChange(state: ConnectionState, error?: Error): void;
+    private updateState;
+}
+
+/**
+ * Benchmark Results Interface
+ */
+interface BenchmarkReport {
+    operation: string;
+    count: number;
+    durationMs: number;
+    opsPerSecond: number;
+}
+/**
+ * Runs a performance benchmark for core client operations.
+ */
+declare function runBenchmarks(): Promise<BenchmarkReport[]>;
+/**
+ * Scenario: Stress test hybrid policy deduplication with 1,000 subscriptions.
+ */
+declare function runHybridStressTest(): Promise<{
+    connectionsCount: number;
+    subscriptionsCount: number;
+}>;
+/**
+ * Scenario: Simulate 10 tabs and trigger random network online/offline events.
+ */
+declare function runNetworkChaosStressTest(cycles?: number): Promise<{
+    success: boolean;
+}>;
+
+export { type BenchmarkReport, MockTransport, runBenchmarks, runHybridStressTest, runNetworkChaosStressTest };

package/dist/index.js

@@ -0,0 +1,216 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MockTransport: () => MockTransport,
+  runBenchmarks: () => runBenchmarks,
+  runHybridStressTest: () => runHybridStressTest,
+  runNetworkChaosStressTest: () => runNetworkChaosStressTest
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/mock-transport.ts
+var MockTransport = class _MockTransport {
+  constructor(caps = { publish: true, subscribe: true, latency: "low" }) {
+    this.caps = caps;
+  }
+  caps;
+  type = "mock";
+  _state = "idle";
+  messageCallback = null;
+  stateCallback = null;
+  published = [];
+  subscribed = [];
+  unsubscribed = [];
+  failNextConnect = false;
+  failError = new Error("Mock connection failure");
+  connectDelay = 0;
+  get state() {
+    return this._state;
+  }
+  setFailNextConnect(fail, error) {
+    this.failNextConnect = fail;
+    if (error) this.failError = error;
+  }
+  setConnectDelay(delayMs) {
+    this.connectDelay = delayMs;
+  }
+  async connect() {
+    if (this._state === "connected") return;
+    this.updateState("connecting");
+    if (this.connectDelay > 0) {
+      await new Promise((resolve) => setTimeout(resolve, this.connectDelay));
+    }
+    if (this.failNextConnect) {
+      this.failNextConnect = false;
+      this.updateState("error", this.failError);
+      throw this.failError;
+    }
+    this.updateState("connected");
+  }
+  async disconnect() {
+    this.updateState("closed");
+  }
+  async publish(topic, data) {
+    if (this._state !== "connected") {
+      throw new Error("Transport not connected");
+    }
+    this.published.push({ topic, data });
+  }
+  async subscribe(topic, filter) {
+    this.subscribed.push({ topic, filter });
+  }
+  async unsubscribe(topic, filter) {
+    this.unsubscribed.push({ topic, filter });
+  }
+  capabilities() {
+    return this.caps;
+  }
+  onMessage(cb) {
+    this.messageCallback = cb;
+  }
+  onStateChange(cb) {
+    this.stateCallback = cb;
+  }
+  clone() {
+    const cloned = new _MockTransport(this.caps);
+    cloned.failNextConnect = this.failNextConnect;
+    cloned.failError = this.failError;
+    cloned.connectDelay = this.connectDelay;
+    return cloned;
+  }
+  // Simulator helper methods
+  simulateMessage(topic, data) {
+    if (this.messageCallback) {
+      this.messageCallback(topic, data);
+    }
+  }
+  simulateStateChange(state, error) {
+    this.updateState(state, error);
+  }
+  updateState(state, error) {
+    this._state = state;
+    if (this.stateCallback) {
+      this.stateCallback(state, error);
+    }
+  }
+};
+
+// src/stress-and-bench.ts
+var import_core = require("@connexis/core");
+async function runBenchmarks() {
+  const reports = [];
+  const transport = new MockTransport();
+  {
+    const client = (0, import_core.createRealtimeClient)({ transport });
+    const start = performance.now();
+    const count = 1e4;
+    const unsubs = [];
+    for (let i = 0; i < count; i++) {
+      const unsub = await client.subscribe(`topic_${i}`, () => {
+      });
+      unsubs.push(unsub);
+    }
+    for (const unsub of unsubs) {
+      await unsub();
+    }
+    const duration = performance.now() - start;
+    reports.push({
+      operation: "subscribe + unsubscribe",
+      count,
+      durationMs: duration,
+      opsPerSecond: count * 2 / (duration / 1e3)
+    });
+    await client.destroy();
+  }
+  {
+    const client = (0, import_core.createRealtimeClient)({ transport });
+    await client.subscribe("test", () => {
+    });
+    const count = 5e4;
+    const start = performance.now();
+    for (let i = 0; i < count; i++) {
+      await client.publish("test", { seq: i });
+    }
+    const duration = performance.now() - start;
+    reports.push({
+      operation: "publish message",
+      count,
+      durationMs: duration,
+      opsPerSecond: count / (duration / 1e3)
+    });
+    await client.destroy();
+  }
+  return reports;
+}
+async function runHybridStressTest() {
+  const transport = new MockTransport();
+  const manager = new import_core.ConnectionManager(transport, "hybrid");
+  const count = 1e3;
+  const filters = [
+    { region: "US" },
+    { region: "EU" },
+    { region: "AP" },
+    { region: "US" },
+    // duplicate of 0
+    { region: "EU" }
+    // duplicate of 1
+  ];
+  for (let i = 0; i < count; i++) {
+    const filter = filters[i % filters.length];
+    await manager.subscribe({ id: `sub_${i}`, topic: "orders", filter }, () => {
+    });
+  }
+  const connectionsCount = manager.getConnections().size;
+  const subscriptionsCount = manager.getActiveSubscriptionCount();
+  await manager.destroy();
+  return { connectionsCount, subscriptionsCount };
+}
+async function runNetworkChaosStressTest(cycles = 20) {
+  const transport = new MockTransport();
+  const connections = [];
+  for (let i = 0; i < 10; i++) {
+    const conn = (0, import_core.createRealtimeClient)({ transport });
+    await conn.subscribe("alerts", () => {
+    });
+    connections.push(conn);
+  }
+  for (let i = 0; i < cycles; i++) {
+    const shouldOffline = Math.random() > 0.5;
+    if (shouldOffline) {
+      transport.simulateStateChange("offline");
+    } else {
+      transport.simulateStateChange("connected");
+    }
+  }
+  transport.simulateStateChange("connected");
+  for (const conn of connections) {
+    await conn.destroy();
+  }
+  return { success: true };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MockTransport,
+  runBenchmarks,
+  runHybridStressTest,
+  runNetworkChaosStressTest
+});

package/dist/index.mjs

@@ -0,0 +1,186 @@
+// src/mock-transport.ts
+var MockTransport = class _MockTransport {
+  constructor(caps = { publish: true, subscribe: true, latency: "low" }) {
+    this.caps = caps;
+  }
+  caps;
+  type = "mock";
+  _state = "idle";
+  messageCallback = null;
+  stateCallback = null;
+  published = [];
+  subscribed = [];
+  unsubscribed = [];
+  failNextConnect = false;
+  failError = new Error("Mock connection failure");
+  connectDelay = 0;
+  get state() {
+    return this._state;
+  }
+  setFailNextConnect(fail, error) {
+    this.failNextConnect = fail;
+    if (error) this.failError = error;
+  }
+  setConnectDelay(delayMs) {
+    this.connectDelay = delayMs;
+  }
+  async connect() {
+    if (this._state === "connected") return;
+    this.updateState("connecting");
+    if (this.connectDelay > 0) {
+      await new Promise((resolve) => setTimeout(resolve, this.connectDelay));
+    }
+    if (this.failNextConnect) {
+      this.failNextConnect = false;
+      this.updateState("error", this.failError);
+      throw this.failError;
+    }
+    this.updateState("connected");
+  }
+  async disconnect() {
+    this.updateState("closed");
+  }
+  async publish(topic, data) {
+    if (this._state !== "connected") {
+      throw new Error("Transport not connected");
+    }
+    this.published.push({ topic, data });
+  }
+  async subscribe(topic, filter) {
+    this.subscribed.push({ topic, filter });
+  }
+  async unsubscribe(topic, filter) {
+    this.unsubscribed.push({ topic, filter });
+  }
+  capabilities() {
+    return this.caps;
+  }
+  onMessage(cb) {
+    this.messageCallback = cb;
+  }
+  onStateChange(cb) {
+    this.stateCallback = cb;
+  }
+  clone() {
+    const cloned = new _MockTransport(this.caps);
+    cloned.failNextConnect = this.failNextConnect;
+    cloned.failError = this.failError;
+    cloned.connectDelay = this.connectDelay;
+    return cloned;
+  }
+  // Simulator helper methods
+  simulateMessage(topic, data) {
+    if (this.messageCallback) {
+      this.messageCallback(topic, data);
+    }
+  }
+  simulateStateChange(state, error) {
+    this.updateState(state, error);
+  }
+  updateState(state, error) {
+    this._state = state;
+    if (this.stateCallback) {
+      this.stateCallback(state, error);
+    }
+  }
+};
+
+// src/stress-and-bench.ts
+import { createRealtimeClient, ConnectionManager } from "@connexis/core";
+async function runBenchmarks() {
+  const reports = [];
+  const transport = new MockTransport();
+  {
+    const client = createRealtimeClient({ transport });
+    const start = performance.now();
+    const count = 1e4;
+    const unsubs = [];
+    for (let i = 0; i < count; i++) {
+      const unsub = await client.subscribe(`topic_${i}`, () => {
+      });
+      unsubs.push(unsub);
+    }
+    for (const unsub of unsubs) {
+      await unsub();
+    }
+    const duration = performance.now() - start;
+    reports.push({
+      operation: "subscribe + unsubscribe",
+      count,
+      durationMs: duration,
+      opsPerSecond: count * 2 / (duration / 1e3)
+    });
+    await client.destroy();
+  }
+  {
+    const client = createRealtimeClient({ transport });
+    await client.subscribe("test", () => {
+    });
+    const count = 5e4;
+    const start = performance.now();
+    for (let i = 0; i < count; i++) {
+      await client.publish("test", { seq: i });
+    }
+    const duration = performance.now() - start;
+    reports.push({
+      operation: "publish message",
+      count,
+      durationMs: duration,
+      opsPerSecond: count / (duration / 1e3)
+    });
+    await client.destroy();
+  }
+  return reports;
+}
+async function runHybridStressTest() {
+  const transport = new MockTransport();
+  const manager = new ConnectionManager(transport, "hybrid");
+  const count = 1e3;
+  const filters = [
+    { region: "US" },
+    { region: "EU" },
+    { region: "AP" },
+    { region: "US" },
+    // duplicate of 0
+    { region: "EU" }
+    // duplicate of 1
+  ];
+  for (let i = 0; i < count; i++) {
+    const filter = filters[i % filters.length];
+    await manager.subscribe({ id: `sub_${i}`, topic: "orders", filter }, () => {
+    });
+  }
+  const connectionsCount = manager.getConnections().size;
+  const subscriptionsCount = manager.getActiveSubscriptionCount();
+  await manager.destroy();
+  return { connectionsCount, subscriptionsCount };
+}
+async function runNetworkChaosStressTest(cycles = 20) {
+  const transport = new MockTransport();
+  const connections = [];
+  for (let i = 0; i < 10; i++) {
+    const conn = createRealtimeClient({ transport });
+    await conn.subscribe("alerts", () => {
+    });
+    connections.push(conn);
+  }
+  for (let i = 0; i < cycles; i++) {
+    const shouldOffline = Math.random() > 0.5;
+    if (shouldOffline) {
+      transport.simulateStateChange("offline");
+    } else {
+      transport.simulateStateChange("connected");
+    }
+  }
+  transport.simulateStateChange("connected");
+  for (const conn of connections) {
+    await conn.destroy();
+  }
+  return { success: true };
+}
+export {
+  MockTransport,
+  runBenchmarks,
+  runHybridStressTest,
+  runNetworkChaosStressTest
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@connexis/testing",
+  "version": "1.0.0",
+  "description": "Testing helpers and mocks for @connexis",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@connexis/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean"
+  }
+}

package/src/__tests__/stress-and-bench.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import {
+  runBenchmarks,
+  runHybridStressTest,
+  runNetworkChaosStressTest
+} from '../stress-and-bench.js';
+
+describe('Performance Benchmarks & Stress Tests', () => {
+  it('should run core performance benchmarks and yield throughput values', async () => {
+    const reports = await runBenchmarks();
+
+    // Print reports to stdout
+    console.table(reports);
+
+    expect(reports.length).toBe(2);
+    expect(reports[0].opsPerSecond).toBeGreaterThan(0);
+    expect(reports[1].opsPerSecond).toBeGreaterThan(0);
+  });
+
+  it('should run hybrid stress test and correctly deduplicate connection count', async () => {
+    // 1,000 subscriptions split across 5 unique filter groups -> should result in exactly 3 unique filter signatures
+    // (since region US, EU, AP are 3 distinct values, and the duplicates group onto them)
+    const { connectionsCount, subscriptionsCount } = await runHybridStressTest();
+
+    expect(subscriptionsCount).toBe(1000);
+    expect(connectionsCount).toBe(3); // 'orders' with region US, EU, AP
+  });
+
+  it('should run network chaos stress test without leaking subscriptions or crashing', async () => {
+    const { success } = await runNetworkChaosStressTest(10);
+    expect(success).toBe(true);
+  });
+});

package/src/index.ts

@@ -0,0 +1,2 @@
+export { MockTransport } from './mock-transport.js';
+export * from './stress-and-bench.js';

package/src/mock-transport.ts

@@ -0,0 +1,107 @@
+import { Transport, ConnectionState, TransportCapabilities } from '@connexis/core';
+
+export class MockTransport implements Transport {
+  public readonly type = 'mock';
+  private _state: ConnectionState = 'idle';
+  private messageCallback: ((topic: string, data: any) => void) | null = null;
+  private stateCallback: ((state: ConnectionState, error?: Error) => void) | null = null;
+
+  public published: Array<{ topic: string; data: any }> = [];
+  public subscribed: Array<{ topic: string; filter?: Record<string, any> }> = [];
+  public unsubscribed: Array<{ topic: string; filter?: Record<string, any> }> = [];
+
+  private failNextConnect = false;
+  private failError: Error = new Error('Mock connection failure');
+  private connectDelay = 0;
+
+  constructor(
+    private caps: TransportCapabilities = { publish: true, subscribe: true, latency: 'low' }
+  ) {}
+
+  get state(): ConnectionState {
+    return this._state;
+  }
+
+  setFailNextConnect(fail: boolean, error?: Error): void {
+    this.failNextConnect = fail;
+    if (error) this.failError = error;
+  }
+
+  setConnectDelay(delayMs: number): void {
+    this.connectDelay = delayMs;
+  }
+
+  async connect(): Promise<void> {
+    if (this._state === 'connected') return;
+    this.updateState('connecting');
+
+    if (this.connectDelay > 0) {
+      await new Promise((resolve) => setTimeout(resolve, this.connectDelay));
+    }
+
+    if (this.failNextConnect) {
+      this.failNextConnect = false; // Reset
+      this.updateState('error', this.failError);
+      throw this.failError;
+    }
+
+    this.updateState('connected');
+  }
+
+  async disconnect(): Promise<void> {
+    this.updateState('closed');
+  }
+
+  async publish(topic: string, data: any): Promise<void> {
+    if (this._state !== 'connected') {
+      throw new Error('Transport not connected');
+    }
+    this.published.push({ topic, data });
+  }
+
+  async subscribe(topic: string, filter?: Record<string, any>): Promise<void> {
+    this.subscribed.push({ topic, filter });
+  }
+
+  async unsubscribe(topic: string, filter?: Record<string, any>): Promise<void> {
+    this.unsubscribed.push({ topic, filter });
+  }
+
+  capabilities(): TransportCapabilities {
+    return this.caps;
+  }
+
+  onMessage(cb: (topic: string, data: any) => void): void {
+    this.messageCallback = cb;
+  }
+
+  onStateChange(cb: (state: ConnectionState, error?: Error) => void): void {
+    this.stateCallback = cb;
+  }
+
+  clone(): MockTransport {
+    const cloned = new MockTransport(this.caps);
+    cloned.failNextConnect = this.failNextConnect;
+    cloned.failError = this.failError;
+    cloned.connectDelay = this.connectDelay;
+    return cloned;
+  }
+
+  // Simulator helper methods
+  simulateMessage(topic: string, data: any): void {
+    if (this.messageCallback) {
+      this.messageCallback(topic, data);
+    }
+  }
+
+  simulateStateChange(state: ConnectionState, error?: Error): void {
+    this.updateState(state, error);
+  }
+
+  private updateState(state: ConnectionState, error?: Error): void {
+    this._state = state;
+    if (this.stateCallback) {
+      this.stateCallback(state, error);
+    }
+  }
+}

package/src/stress-and-bench.ts

@@ -0,0 +1,132 @@
+import { createRealtimeClient, ConnectionManager } from '@connexis/core';
+import { MockTransport } from './mock-transport.js';
+
+/**
+ * Benchmark Results Interface
+ */
+export interface BenchmarkReport {
+  operation: string;
+  count: number;
+  durationMs: number;
+  opsPerSecond: number;
+}
+
+/**
+ * Runs a performance benchmark for core client operations.
+ */
+export async function runBenchmarks(): Promise<BenchmarkReport[]> {
+  const reports: BenchmarkReport[] = [];
+  const transport = new MockTransport();
+
+  // 1. Subscribe/Unsubscribe Benchmark
+  {
+    const client = createRealtimeClient({ transport });
+    const start = performance.now();
+    const count = 10000;
+    const unsubs: Array<() => Promise<void>> = [];
+
+    for (let i = 0; i < count; i++) {
+      const unsub = await client.subscribe(`topic_${i}`, () => {});
+      unsubs.push(unsub);
+    }
+    for (const unsub of unsubs) {
+      await unsub();
+    }
+    const duration = performance.now() - start;
+    reports.push({
+      operation: 'subscribe + unsubscribe',
+      count,
+      durationMs: duration,
+      opsPerSecond: (count * 2) / (duration / 1000)
+    });
+    await client.destroy();
+  }
+
+  // 2. Publish Throughput & Latency Benchmark
+  {
+    const client = createRealtimeClient({ transport });
+    // Spin up connection
+    await client.subscribe('test', () => {});
+
+    const count = 50000;
+    const start = performance.now();
+    for (let i = 0; i < count; i++) {
+      await client.publish('test', { seq: i });
+    }
+    const duration = performance.now() - start;
+    reports.push({
+      operation: 'publish message',
+      count,
+      durationMs: duration,
+      opsPerSecond: count / (duration / 1000)
+    });
+    await client.destroy();
+  }
+
+  return reports;
+}
+
+/**
+ * Scenario: Stress test hybrid policy deduplication with 1,000 subscriptions.
+ */
+export async function runHybridStressTest(): Promise<{
+  connectionsCount: number;
+  subscriptionsCount: number;
+}> {
+  const transport = new MockTransport();
+  const manager = new ConnectionManager(transport, 'hybrid');
+
+  const count = 1000;
+  // Deduplicate onto 5 unique filters
+  const filters = [
+    { region: 'US' },
+    { region: 'EU' },
+    { region: 'AP' },
+    { region: 'US' }, // duplicate of 0
+    { region: 'EU' } // duplicate of 1
+  ];
+
+  for (let i = 0; i < count; i++) {
+    const filter = filters[i % filters.length];
+    await manager.subscribe({ id: `sub_${i}`, topic: 'orders', filter }, () => {});
+  }
+
+  const connectionsCount = manager.getConnections().size;
+  const subscriptionsCount = manager.getActiveSubscriptionCount();
+
+  await manager.destroy();
+
+  return { connectionsCount, subscriptionsCount };
+}
+
+/**
+ * Scenario: Simulate 10 tabs and trigger random network online/offline events.
+ */
+export async function runNetworkChaosStressTest(cycles = 20): Promise<{ success: boolean }> {
+  const transport = new MockTransport();
+  const connections: any[] = [];
+
+  for (let i = 0; i < 10; i++) {
+    const conn = createRealtimeClient({ transport });
+    await conn.subscribe('alerts', () => {});
+    connections.push(conn);
+  }
+
+  for (let i = 0; i < cycles; i++) {
+    const shouldOffline = Math.random() > 0.5;
+    if (shouldOffline) {
+      transport.simulateStateChange('offline');
+    } else {
+      transport.simulateStateChange('connected');
+    }
+  }
+
+  // Recover everything
+  transport.simulateStateChange('connected');
+
+  for (const conn of connections) {
+    await conn.destroy();
+  }
+
+  return { success: true };
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}