Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

AMQP client.js is a TypeScript library providing AMQP 0-9-1 client functionality for both Node.js (TCP Socket) and browsers (WebSocket). The library has zero runtime dependencies and is designed for high performance messaging.

• Requires Node.js >= 16.0.0 (verified working with Node.js 20.x)
• Docker and Docker Compose for RabbitMQ testing server
• For browser testing: Playwright (optional, may not work in all environments)

Run these commands in sequence:

1. Install dependencies:

   npm install

   • Takes ~16 seconds
   • Automatically runs the build process via prepare script
   • NEVER CANCEL: Set timeout to 30+ minutes for initial install

2. Manual build (if needed):

   npm run build

   • Takes ~5.4 seconds
   • NEVER CANCEL: Set timeout to 10+ minutes
   • Creates three output formats:
     • ES modules in lib/mjs/
     • CommonJS modules in lib/cjs/
     • TypeScript declarations in types/
     • Browser bundle in dist/

3. Start RabbitMQ services:

   docker compose up -d

   • Takes ~11 seconds for first startup
   • NEVER CANCEL: Set timeout to 15+ minutes for Docker image pulls
   • Starts RabbitMQ server on ports 5671 (TLS) and 5672 (plain)
   • Starts WebSocket TCP relay on port 15670

npm test

• Takes ~15 seconds
• NEVER CANCEL: Set timeout to 30+ minutes
• Runs Node.js tests with coverage using Vitest
• EXPECTED: 2 TLS-related tests may fail if certificates are not set up (normal in development)
• All other tests should pass when RabbitMQ is running

npx playwright install --with-deps chromium
npm run test-browser

• WARNING: Playwright installation often fails in CI environments
• Browser tests require WebSocket functionality
• NEVER CANCEL: Playwright install can take 30+ minutes
• Only attempt browser tests if Playwright installs successfully

npm run lint

• Takes ~1.8 seconds
• Uses ESLint with TypeScript support
• Must pass before committing (CI requirement)

npm run docs

• Takes ~3.4 seconds
• Generates API documentation in docs/ directory
• Uses TypeDoc

After making changes, always run this validation sequence:

1. Build validation: npm run build - ensure TypeScript compilation succeeds
2. Test validation: npm test - run Node.js tests (RabbitMQ must be running)
3. Lint validation: npm run lint - ensure code style compliance
4. Functionality validation: Test actual AMQP operations (see examples below)

Always test functionality manually when making changes to core AMQP logic:

import { AMQPClient } from "./lib/mjs/index.js"

// Basic publish/consume test
const amqp = new AMQPClient("amqp://localhost")
const conn = await amqp.connect()
const ch = await conn.channel()
const q = await ch.queue("test-queue")
await q.publish("test message")
const consumer = await q.subscribe({ noAck: true }, (msg) => {
  console.log("Received:", msg.bodyString())
})
// Clean up: consumer.cancel(), q.delete(), conn.close()

• amqp-socket-client.ts - Node.js TCP client implementation
• amqp-websocket-client.ts - Browser WebSocket client implementation
• amqp-channel.ts - AMQP channel implementation
• amqp-queue.ts - Queue operations
• amqp-message.ts - Message handling
• index.ts - Main exports

• test.ts - Main Node.js test suite
• tls.ts - TLS connection tests (may fail without certificates)

• websocket.ts - WebSocket client tests

• package.json - Build scripts and dependencies
• tsconfig.json - TypeScript configuration
• vitest.config.ts - Node.js test configuration
• vitest.config.browser.ts - Browser test configuration
• docker-compose.yml - RabbitMQ test environment

• lib/mjs/ - ES module builds
• lib/cjs/ - CommonJS builds
• types/ - TypeScript declarations
• dist/ - Browser-ready bundles

• Ensure docker compose up -d has been run
• Check containers are healthy: docker compose ps
• RabbitMQ takes ~20 seconds to fully start

• Run npm run prebuild to clean build directories
• Ensure TypeScript has no compilation errors
• Check Node.js version is >= 16.0.0

• TLS tests failing: Expected if mkcert certificates not installed
• Connection errors: Ensure RabbitMQ is running via Docker
• WebSocket tests failing: Expected if Playwright not installed

• WebSocket client requires browser environment or WebSocket polyfill
• Playwright installation may fail in some CI environments
• Browser bundle available in dist/amqp-websocket-client.mjs

• Library has zero runtime dependencies
• Supports high-throughput messaging (300k+ msgs/sec publish, 512k+ msgs/sec consume)
• Uses DataView for binary protocol parsing (browser compatibility)
• Optimized frame buffering for WebSocket connections

1. Start RabbitMQ: docker compose up -d
2. Install dependencies: npm install
3. Make changes to src/ files
4. Build: npm run build
5. Test: npm test
6. Lint: npm run lint
7. Manual validation with real AMQP operations
8. Clean up: docker compose down

Always run the full validation sequence before committing changes. The CI pipeline (.github/workflows/ci.yml) will run all these steps and must pass for merge approval.