nest feat(ws): Support for dynamic path params in websocket, add tests

PR Checklist

Please check if your PR fulfills the following requirements:

[x] The commit message follows our guidelines: https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
[x] Tests for the changes have been added (for bug fixes / features)
[ ] Docs have been added / updated (for bug fixes / features)
The documentation has been completed and the branch is ready, but the PR hasn't been submitted yet. I plan to discuss it here first, and if there are no issues, I'll submit the PR for the documentation.

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Other... Please describe:

What is the current behavior?

Issue Number: #15238

Currently, NestJS WebSocket gateways only support static path matching. Dynamic path parameters (like /chat/:roomId/socket) are not supported, making it difficult to create RESTful WebSocket endpoints with path-based routing.

What is the new behavior?

This PR introduces WebSocket Wildcard URL Support with dynamic path parameter extraction, bringing WebSocket gateways on par with HTTP controllers in terms of routing flexibility.

Key Features Added:

1. Dynamic Path Parameter Support

Supports complex path patterns like /chat/:roomId/socket, /game/:gameId/room/:roomId/socket
Automatic parameter extraction and injection using familiar :param syntax
Compatible with path-to-regexp patterns used throughout NestJS

2. New @WsParam() Decorator

@WebSocketGateway({ path: '/chat/:roomId/socket' })
export class ChatGateway {
  @SubscribeMessage('message')
  handleMessage(
    @ConnectedSocket() client: WebSocket,
    @MessageBody() data: any,
    @WsParam('roomId') roomId: string,  // ✨ New decorator!
  ) {
    return { room: roomId, message: data };
  }
}

3. Performance Optimized Architecture

Smart path detection: Only dynamic paths use regex matching
Static paths continue using fast string comparison (zero performance impact)
Parameters extracted once during handshake, not per message

4. Full TypeScript Integration

Complete type safety with proper type definitions
Support for validation pipes: @WsParam('userId', ParseIntPipe) userId: number
Excellent IntelliSense and autocomplete support

Changes Summary:

9 files modified with 611 additions, 3 deletions
Comprehensive test coverage with 267 lines of e2e tests
Zero breaking changes - fully backward compatible
New dependency: [email protected] (consistent with NestJS HTTP routing)

Technical Implementation:

Enhanced WsAdapter with intelligent path compilation and matching
Extended WsParamtype enum and WsParamsFactory for parameter extraction
Proper integration with existing WebSocket infrastructure
Clean separation of concerns with minimal code footprint

This implementation addresses the exact requirements from Issue #15238 and provides developers with the flexibility to build sophisticated real-time applications with clean, RESTful WebSocket endpoints!

Does this PR introduce a breaking change?

[ ] Yes
[x] No

No breaking changes - All existing WebSocket gateways continue to work exactly as before. This is purely additive functionality that developers can opt into when needed.

Other information

Backward Compatibility: 100% - existing static path WebSocket gateways remain unchanged
Performance Impact: Zero for existing code, optimized for new dynamic paths
Documentation: Ready for docs update (implementation summary available)
Future Extensions: Architecture supports additional WebSocket routing features

This feature has been thoroughly tested and aligns perfectly with NestJS's design philosophy! 🎉

Aug 01 '25 09:08 lifefloating

Hi @team @micalevisk @kamilmysliwiec

I hope you're all doing well! I just wanted to bring this to your attention when you have a moment.

I've been using NestJS for quite a while now and have built numerous backend applications with it - it's been an absolute game-changer for my development workflow. The framework's elegance and powerful features have made backend development so much more enjoyable and productive.

I truly appreciate all the incredible work you've put into this project and the continuous improvements you keep delivering to the community. Your dedication to maintaining such a high-quality framework doesn't go unnoticed.

Please feel free to take a look when your schedule permits. Thank you so much for all your contributions and for making NestJS the amazing framework it is today. I look forward to your feedback!

Aug 01 '25 10:08 lifefloating

Pull Request Test Coverage Report for Build 2de2078d-a099-4a84-a8fa-37e1baf9a5e2

Details

10 of 11 (90.91%) changed or added relevant lines in 4 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage increased (+0.002%) to 88.89%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
packages/websockets/decorators/ws-param.decorator.ts	3	4	75.0%
<!--	Total:	10	11

Totals
Change from base Build 3a48f653-e287-441b-b2b2-c3e90f54cf30:	0.002%
Covered Lines:	7329
Relevant Lines:	8245

💛 - Coveralls

Aug 01 '25 10:08 coveralls

Hi @team @micalevisk @kamilmysliwiec

I hope you're all doing well! I just wanted to bring this to your attention when you have a moment.

I've been using NestJS for quite a while now and have built numerous backend applications with it - it's been an absolute game-changer for my development workflow. The framework's elegance and powerful features have made backend development so much more enjoyable and productive.

I truly appreciate all the incredible work you've put into this project and the continuous improvements you keep delivering to the community. Your dedication to maintaining such a high-quality framework doesn't go unnoticed.

Please feel free to take a look when your schedule permits. Thank you so much for all your contributions and for making NestJS the amazing framework it is today. I look forward to your feedback!

Hope you're doing well! Just a gentle ping on this PR when you get a chance. If there's anything that needs adjustment or if you'd like to discuss the implementation approach, please feel free to reach out.

Happy to collaborate and make this better. Thanks as always!

Aug 04 '25 02:08 lifefloating

This commit introduces significant performance optimizations to the WsAdapter

Key Changes

Implemented optimized path matching mechanism with O(1) Map lookup for static paths
Dynamic paths sorted by complexity for priority matching of simpler patterns
Added path matcher cache (pathMatchersCache) to improve repeated matching performance
Refactored linear traversal matching logic into more efficient categorized matching

Performance Optimizations

Core Optimization: Indexed Path Matching

Before (Linear Search):

// O(n) - Iterate through all servers for each connection
for (const wsServer of wsServersCollection) {
  if (pathname === wsServer.path || wsServer.pathRegexp?.test(pathname)) {
    // Match found
  }
}

After (Indexed Lookup):

// O(1) for static paths, optimized O(k) for dynamic paths
interface PathMatcher {
  staticPaths: Map<string, WsServerWithPath[]>;  // O(1) lookup
  dynamicPaths: Array<{                         // Sorted by complexity
    server: WsServerWithPath;
    pathRegexp: RegExp;
    pathKeys: Key[];
  }>;
}

Performance Benchmark Results

Path Type	Test Path	Avg Time (ms)	Ops/Second
Static	`/api/v1/chat`	0.000070	14,259,396
Simple Dynamic	`/chat/:roomId/socket`	0.000238	4,199,401
Complex Dynamic	`/game/:gameId/room/:roomId/socket`	0.000452	2,214,165
Not Found	`/nonexistent/path`	0.000094	10,592,760

This is script origin output:

  WebSocket Path Matching Performance

 WebSocket Path Matching Performance Benchmark
==================================================

 Path Matcher Statistics:
   Static paths: 5
   Dynamic paths: 5

🎯 Match "/api/v1/chat" (found)
   Iterations: 10,000
   Total time: 0.70ms
   Average time: 0.000070ms per operation
   Performance: 14,259,396 operations/second

🎯 Match "/chat/room123/socket" (found)
   Iterations: 10,000
   Total time: 2.38ms
   Average time: 0.000238ms per operation
   Performance: 4,199,401 operations/second

🎯 Match "/game/game456/room/room789/socket" (found)
   Iterations: 10,000
   Total time: 4.52ms
   Average time: 0.000452ms per operation
   Performance: 2,214,165 operations/second

🎯 Match "/user/user123/notifications" (found)
   Iterations: 10,000
   Total time: 2.86ms
   Average time: 0.000286ms per operation
   Performance: 3,494,671 operations/second

🎯 Match "/api/v2/game/game999/player/player888/stream" (found)
   Iterations: 10,000
   Total time: 4.02ms
   Average time: 0.000402ms per operation
   Performance: 2,488,491 operations/second

🎯 Match "/nonexistent/path" (not found)
   Iterations: 10,000
   Total time: 0.94ms
   Average time: 0.000094ms per operation
   Performance: 10,592,760 operations/second

 Performance optimization verified!

Origin performance script

/**
 * Path matching performance benchmark test
 */

import { WsAdapter } from '../../adapters/ws-adapter';
import { Test } from '@nestjs/testing';
import { INestApplicationContext } from '@nestjs/common';

interface BenchmarkResult {
  operation: string;
  iterations: number;
  totalTime: number;
  averageTime: number;
  opsPerSecond: number;
}

describe('WebSocket Path Matching Performance', () => {
  let adapter: WsAdapter;
  let app: INestApplicationContext;

  beforeEach(async () => {
    const module = await Test.createTestingModule({}).compile();
    app = module.createNestApplication();
    adapter = new WsAdapter(app);
  });

  afterEach(async () => {
    await adapter.dispose();
    await app.close();
  });

  it('should demonstrate performance improvement with optimized path matcher', async () => {
    const port = 3001;

    // Create multiple WebSocket servers with mixed static and dynamic paths
    const staticPaths = [
      '/api/v1/chat',
      '/api/v1/notifications',
      '/api/v1/status',
      '/api/v2/chat',
      '/api/v2/notifications',
    ];

    const dynamicPaths = [
      '/chat/:roomId/socket',
      '/game/:gameId/room/:roomId/socket',
      '/user/:userId/notifications',
      '/api/v1/room/:roomId/user/:userId',
      '/api/v2/game/:gameId/player/:playerId/stream',
    ];

    // Register static paths
    for (const path of staticPaths) {
      const server = adapter.create(port, { path });
      // Simulate server registration without actually starting
    }

    // Register dynamic paths
    for (const path of dynamicPaths) {
      const server = adapter.create(port, { path });
      // Simulate server registration without actually starting
    }

    // Test paths to match
    const testPaths = [
      '/api/v1/chat', // Static match
      '/chat/room123/socket', // Dynamic match
      '/game/game456/room/room789/socket', // Complex dynamic match
      '/user/user123/notifications', // Dynamic match
      '/api/v2/game/game999/player/player888/stream', // Complex dynamic match
      '/nonexistent/path', // No match
    ];

    console.log('\n WebSocket Path Matching Performance Benchmark');
    console.log('==================================================');

    // Get the path matcher (this will create the optimized index)
    const pathMatcher = (adapter as any).getOrCreatePathMatcher(port);

    console.log(`\n Path Matcher Statistics:`);
    console.log(`   Static paths: ${pathMatcher.staticPaths.size}`);
    console.log(`   Dynamic paths: ${pathMatcher.dynamicPaths.length}`);

    // Benchmark path matching
    const iterations = 10000;

    for (const testPath of testPaths) {
      const result = await benchmarkPathMatching(
        adapter as any,
        pathMatcher,
        testPath,
        iterations,
      );
      printBenchmarkResult(result);
    }

    console.log('\n Performance optimization verified!');
    console.log('Static paths now use O(1) Map lookup');
    console.log('Dynamic paths are sorted by complexity for faster matching');
  });
});

async function benchmarkPathMatching(
  adapter: any,
  pathMatcher: any,
  testPath: string,
  iterations: number,
): Promise<BenchmarkResult> {
  const startTime = process.hrtime.bigint();

  let matchCount = 0;
  for (let i = 0; i < iterations; i++) {
    const result = adapter.matchPath(testPath, pathMatcher);
    if (result) matchCount++;
  }

  const endTime = process.hrtime.bigint();
  const totalTime = Number(endTime - startTime) / 1000000; // Convert to milliseconds

  return {
    operation: `Match "${testPath}" (${matchCount > 0 ? 'found' : 'not found'})`,
    iterations,
    totalTime,
    averageTime: totalTime / iterations,
    opsPerSecond: Math.round(iterations / (totalTime / 1000)),
  };
}

function printBenchmarkResult(result: BenchmarkResult): void {
  console.log(`\n🎯 ${result.operation}`);
  console.log(`   Iterations: ${result.iterations.toLocaleString()}`);
  console.log(`   Total time: ${result.totalTime.toFixed(2)}ms`);
  console.log(
    `   Average time: ${result.averageTime.toFixed(6)}ms per operation`,
  );
  console.log(
    `   Performance: ${result.opsPerSecond.toLocaleString()} operations/second`,
  );
}

Aug 04 '25 08:08 lifefloating

hi @kamilmysliwiec

I just wanted to gently check in on this PR and see if there are any concerns or anything I can do to help move it forward. No rush at all, I know everyone is busy.
Thanks for your time!

Oct 24 '25 02:10 lifefloating