queen-mq 0.15.0 → 0.16.0

package/README.md

@@ -22,7 +22,7 @@ Queen MQ is a PostgreSQL-backed message queue system with a powerful feature set
 - **Consumer Groups** - Kafka-style consumer groups for scalability
 - **Flexible Semantics** - Exactly-once, at-least-once, and at-most-once delivery
 - **Transactions** - Atomic operations across push and ack
-- **High Performance** - 200K+ messages/sec with proper batching
+- **High Performance** — 104K msg/s push, 165K msg/s fan-out with consumer groups on a single 32-core node ([benchmarks](https://github.com/queen-mq/queen/tree/master/benchmark-queen/2026-04-26))
 - **Subscription Modes** - Process from beginning, new messages only, or from timestamp
 - **Dead Letter Queue** - Automatic failure handling and monitoring
 - **Message Tracing** - Debug distributed workflows with trace timelines
@@ -179,7 +179,7 @@ const queen = new Queen({
   urls: ['http://server1:6632', 'http://server2:6632'],
   timeoutMillis: 30000,
   retryAttempts: 3,
-  loadBalancingStrategy: 'round-robin',  // or 'session'
+  loadBalancingStrategy: 'affinity',  // or 'round-robin', 'session'
   enableFailover: true
 })
 ```
@@ -564,8 +564,10 @@ await queen.close()  // Flush buffers and close connections
   timeoutMillis: 30000,
   retryAttempts: 3,
   retryDelayMillis: 1000,
-  loadBalancingStrategy: 'round-robin',
-  enableFailover: true
+  loadBalancingStrategy: 'affinity',   // 'affinity' | 'round-robin' | 'session'
+  affinityHashRing: 128,
+  enableFailover: true,
+  healthRetryAfterMillis: 5000
 }
 ```
 
@@ -653,17 +655,18 @@ const messages: Message<OrderData>[] = await queen.queue('orders').pop()
 
 ## Documentation
 
-- **[Complete V2 Guide](client-v2/README.md)** - Full tutorial with all features (94 test examples)
-- **[HTTP API Reference](https://github.com/smartpricing/queen/blob/master/server/API.md)** - Raw HTTP endpoints
-- **[Server Guide](https://github.com/smartpricing/queen/blob/master/server/README.md)** - Server setup and configuration
-- **[Architecture Guide](https://github.com/smartpricing/queen/blob/master/documentation/ARCHITECTURE.md)** - Deep dive into internals
+- **[Complete V2 Guide](client-v2/README.md)** — full tutorial with all features
+- **[HTTP API Reference](https://github.com/queen-mq/queen/blob/master/server/API.md)** — raw HTTP endpoints
+- **[Server Guide](https://github.com/queen-mq/queen/blob/master/server/README.md)** — server setup and configuration
+- **[Architecture & internals](https://queenmq.com/architecture.html)** — published architecture overview
+- **[libqueen design notes](https://github.com/queen-mq/queen/blob/master/cdocs/LIBQUEEN_IMPROVEMENTS.md)** — adaptive engine deep-dive
 
 ---
 
 ## Support
 
-- **GitHub:** [smartpricing/queen](https://github.com/smartpricing/queen)
-- **Issues:** [GitHub Issues](https://github.com/smartpricing/queen/issues)
+- **GitHub:** [queen-mq/queen](https://github.com/queen-mq/queen)
+- **Issues:** [GitHub Issues](https://github.com/queen-mq/queen/issues)
 - **LinkedIn:** [Smartness](https://www.linkedin.com/company/smartness-com/)
 
 ---

package/client-v2/Queen.js

@@ -23,9 +23,12 @@ export class Queen {
   #admin = null
 
   constructor(config = {}) {
-    // Configure custom logger before anything else
+    // Configure custom logger before anything else.
+    // Opt into structured field logging with `structuredLogs: true` (the logger
+    // must accept a leading merge object, e.g. pino/bunyan); defaults to the
+    // backward-compatible single-string format.
     if (config && typeof config === 'object' && !Array.isArray(config) && config.logger) {
-      logger.configure(config.logger)
+      logger.configure(config.logger, { structured: config.structuredLogs === true })
     }
 
     logger.log('Queen.constructor', { config: typeof config === 'object' && !Array.isArray(config) ? { ...config, urls: config.urls?.length || 0 } : { type: typeof config } })

package/client-v2/README.md

@@ -1788,11 +1788,13 @@ await queen.close()
 ### Client Defaults
 ```javascript
 {
-  timeoutMillis: 30000,               // 30 seconds
+  timeoutMillis: 30000,                  // 30 seconds
   retryAttempts: 3,
   retryDelayMillis: 1000,
-  loadBalancingStrategy: 'round-robin',
-  enableFailover: true
+  loadBalancingStrategy: 'affinity',     // 'affinity' | 'round-robin' | 'session'
+  affinityHashRing: 128,
+  enableFailover: true,
+  healthRetryAfterMillis: 5000
 }
 ```
 
@@ -1993,9 +1995,10 @@ process.on('SIGINT', async () => {
 You now know everything about Queen v2! 🎉
 
 **Additional resources:**
-- [API Documentation](../../server/API.md) - Complete API reference
-- [Test Examples](../test-v2/) - 94 working test cases
-- [Architecture Guide](../../docs/) - Deep dive into Queen's internals
+- [API Documentation](../../../server/API.md) — complete HTTP API reference
+- [Test Examples](../test-v2/) — runnable test cases
+- [Architecture overview](https://queenmq.com/architecture.html) — published deep-dive
+- [libqueen design notes](../../../cdocs/LIBQUEEN_IMPROVEMENTS.md) — server internals
 
 **Need help?** Check out the test files in `test-v2/` - they're full of working examples!
 

package/client-v2/utils/logger.js

@@ -1,6 +1,6 @@
 /**
  * Logger utility for Queen Client v2
- * 
+ *
  * Supports pluggable logger backends (pino, winston, bunyan, etc.).
  * When no custom logger is configured, falls back to console-based logging
  * gated by the QUEEN_CLIENT_LOG environment variable (Node.js)
@@ -20,6 +20,9 @@ const LOG_ENABLED = (() => {
 })()
 
 let customLogger = null
+// When true, details are passed to the custom logger as structured fields
+// (pino/bunyan style: `info(fields, message)`). Opt-in for backward compatibility.
+let structuredMode = false
 
 function getTimestamp() {
   return new Date().toISOString()
@@ -36,22 +39,62 @@ function formatLog(operation, details, level = 'INFO') {
 
 /**
  * Configure a custom logger backend.
+ *
  * The logger must implement: info(msg), warn(msg), error(msg).
  * debug(msg) is optional and falls back to info(msg) if missing.
  * When a custom logger is set, it is always active (no env var gating).
+ *
+ * By default (backward compatible) the logger is called with a single formatted
+ * string: `info('[operation] {json}')`.
+ *
+ * Pass `{ structured: true }` to instead call the logger pino/bunyan style —
+ * `info(fields, message)` — so `details` become structured, queryable fields
+ * (the `operation` is also added as a field and used as the message). Use this
+ * only with loggers that accept a leading merge object (e.g. pino, bunyan).
+ *
+ * The built-in console fallback (no custom logger) is unaffected by this option.
+ *
  * @param {object} logger - Logger instance (e.g. pino(), winston.createLogger())
+ * @param {{ structured?: boolean }} [options]
  */
-export function configure(logger) {
+export function configure(logger, options = {}) {
   if (logger && typeof logger.info !== 'function') {
     throw new Error('Custom logger must implement info(), warn(), and error() methods')
   }
   customLogger = logger
+  structuredMode = options != null && options.structured === true
+}
+
+/**
+ * Emit a log through the configured custom logger.
+ * - structuredMode: `details` keys become top-level fields, `operation` is added
+ *   as a field, and the operation is the message (pino/bunyan style).
+ * - default (legacy): a single `[operation] {json}` string is passed.
+ * Missing level methods fall back to info().
+ */
+function emitToCustomLogger(method, operation, details) {
+  const fn = customLogger[method] || customLogger.info
+
+  if (structuredMode) {
+    let fields
+    if (details && typeof details === 'object' && !Array.isArray(details)) {
+      fields = { operation, ...details }
+    } else if (details !== undefined) {
+      fields = { operation, details }
+    } else {
+      fields = { operation }
+    }
+    fn.call(customLogger, fields, operation)
+    return
+  }
+
+  const detailsStr = typeof details === 'object' ? JSON.stringify(details) : details
+  fn.call(customLogger, `[${operation}] ${detailsStr}`)
 }
 
 export function log(operation, details) {
   if (customLogger) {
-    const detailsStr = typeof details === 'object' ? JSON.stringify(details) : details
-    customLogger.info(`[${operation}] ${detailsStr}`)
+    emitToCustomLogger('info', operation, details)
     return
   }
   if (!LOG_ENABLED) return
@@ -60,9 +103,7 @@ export function log(operation, details) {
 
 export function debug(operation, details) {
   if (customLogger) {
-    const detailsStr = typeof details === 'object' ? JSON.stringify(details) : details
-    const fn = customLogger.debug || customLogger.info
-    fn.call(customLogger, `[${operation}] ${detailsStr}`)
+    emitToCustomLogger('debug', operation, details)
     return
   }
   if (!LOG_ENABLED) return
@@ -71,8 +112,7 @@ export function debug(operation, details) {
 
 export function warn(operation, details) {
   if (customLogger) {
-    const detailsStr = typeof details === 'object' ? JSON.stringify(details) : details
-    customLogger.warn(`[${operation}] ${detailsStr}`)
+    emitToCustomLogger('warn', operation, details)
     return
   }
   if (!LOG_ENABLED) return
@@ -81,8 +121,7 @@ export function warn(operation, details) {
 
 export function error(operation, details) {
   if (customLogger) {
-    const detailsStr = typeof details === 'object' ? JSON.stringify(details) : details
-    customLogger.error(`[${operation}] ${detailsStr}`)
+    emitToCustomLogger('error', operation, details)
     return
   }
   if (!LOG_ENABLED) return

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "queen-mq",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "type": "module",
   "description": "Partitioned message queue on PostgreSQL — broker client + fluent streaming SDK (windows, joins, gates) in one package",
   "main": "client-v2/index.js",
   "scripts": {
-    "test":             "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js && node test-v2/run.js human",
-    "test:unit":        "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js",
-    "test:unit:e2e":    "node --test test-v2/streams-unit/e2e.test.js",
+    "test": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js && node test-v2/run.js human",
+    "test:unit": "node --test test-v2/streams-unit/configHash.test.js test-v2/streams-unit/operators.test.js test-v2/streams-unit/cycle.test.js test-v2/streams-unit/eventTime.test.js",
+    "test:unit:e2e": "node --test test-v2/streams-unit/e2e.test.js",
     "test:integration": "node test-v2/run.js human",
-    "test:streams":     "node test-v2/run.js stream",
-    "test:all":         "npm run test:unit && npm run test:integration && npm run test:streams"
+    "test:streams": "node test-v2/run.js stream",
+    "test:all": "npm run test:unit && npm run test:integration && npm run test:streams"
   },
   "files": [
     "client-v2/**/*",
@@ -29,7 +29,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/smartpricing/queen"
+    "url": "https://github.com/queen-mq/queen"
   },
   "keywords": [
     "message-queue",