@swarmmachina/swm-core 1.1.4 → 1.2.0

package/README.md

@@ -291,7 +291,7 @@ The `ctx` object passed to the router function:
 
 Get request lowercased method.
 
-```javascriptx
+```javascript
 const method = ctx.method()
 ```
 
@@ -327,6 +327,16 @@ const page = ctx.query('page') // ?page=1
 
 **Returns:** `string`
 
+##### `ctx.fullQuery()`
+
+Get full raw query string.
+
+```javascript
+const q = ctx.fullQuery() // page=1&limit=20
+```
+
+**Returns:** `string`
+
 ##### `ctx.param(indexOrName)`
 
 Get URL parameter by index or name (for pattern matching in native routing).
@@ -398,7 +408,7 @@ ctx.status(201).send({ created: true })
 
 ##### `ctx.setHeader(key, value)`
 
-Set a response header. Returns context for chaining.
+Set or replace a staged response header. Header names are case-insensitive. Repeated `setHeader()` calls replace previously staged values for the same header. Null or undefined values are silently ignored.
 
 ```javascript
 ctx.setHeader('x-header-any', 'string-value').status(201).send({ created: true })
@@ -406,6 +416,37 @@ ctx.setHeader('x-header-any', 'string-value').status(201).send({ created: true }
 
 **Returns:** `HttpContext`
 
+##### `ctx.appendHeader(key, value)`
+
+Append another staged response header line without replacing existing values. Useful for repeated headers such as `Set-Cookie`. Null or undefined values are silently ignored.
+
+```javascript
+ctx.appendHeader('set-cookie', 'access=...; Path=/; HttpOnly')
+ctx.appendHeader('set-cookie', 'refresh=...; Path=/refresh; HttpOnly')
+```
+
+**Returns:** `HttpContext`
+
+##### `ctx.setHeaders(headers)`
+
+Set multiple response headers at once. Equivalent to calling `setHeader()` for each key. Header values may be strings or arrays of strings.
+
+```javascript
+ctx.setHeaders({
+  'x-request-id': '123',
+  'cache-control': 'no-cache',
+  'set-cookie': ['a=1; Path=/', 'b=2; Path=/refresh']
+})
+```
+
+##### `ctx.flushHeaders([headers])`
+
+Flush all staged headers (and optionally stage additional ones) to the underlying response. Called automatically by `reply()` and `startStreaming()` — only needed for advanced use cases.
+
+```javascript
+ctx.flushHeaders({ 'x-extra': 'value' })
+```
+
 ##### `ctx.send(data)`
 
 Send response with automatic content-type detection.
@@ -419,12 +460,59 @@ ctx.send(null) // 204 No Content
 
 **Supported types:** Object, String, Buffer, null, undefined
 
+##### `ctx.sendJson(data, [status])`
+
+Send a JSON response with explicit status code. Defaults to `200`.
+
+```javascript
+ctx.sendJson({ users: [] })
+ctx.sendJson({ error: 'Not found' }, 404)
+```
+
+##### `ctx.sendText(text, [status])`
+
+Send a plain text response with explicit status code. Defaults to `200`.
+
+```javascript
+ctx.sendText('OK')
+ctx.sendText('Created', 201)
+```
+
+##### `ctx.sendBuffer(buffer, [status])`
+
+Send a binary response with explicit status code. Defaults to `200`.
+
+```javascript
+ctx.sendBuffer(Buffer.from('data'))
+ctx.sendBuffer(imageBuffer, 201)
+```
+
+##### `ctx.sendError(error)`
+
+Send an error response. If `error.status` is a finite number, uses that as the HTTP status with `error.message` as the body. Otherwise responds with `500 Internal Server Error`.
+
+```javascript
+ctx.sendError(new Error('Something broke'))
+
+// With custom status
+const err = new Error('Not found')
+err.status = 404
+ctx.sendError(err)
+```
+
 ##### `ctx.reply(status, headers, body)`
 
-Send response with full control over status, headers, and body.
+Send response with full control over status, headers, and body. Header values may be strings or arrays of strings. Array values are written as separate header lines.
 
 ```javascript
-ctx.reply(200, { 'content-type': 'application/json' }, '{"ok":true}')
+ctx.reply(
+  200,
+  {
+    'content-type': 'application/json',
+    'set-cookie': ['a=1; Path=/', 'b=2; Path=/refresh']
+  },
+  '{"ok":true}'
+)
 ```
 
 ##### `ctx.stream(readable, [status], [headers])`
@@ -442,10 +530,13 @@ await ctx.stream(stream, 200, { 'content-type': 'video/mp4' })
 
 ##### `ctx.startStreaming([status], [headers])`
 
-Start streaming response manually (for advanced use cases).
+Start streaming response manually (for advanced use cases). Header values may be strings or arrays of strings.
 
 ```javascript
-ctx.startStreaming(200, { 'content-type': 'text/plain' })
+ctx.startStreaming(200, {
+  'content-type': 'text/plain',
+  'set-cookie': ['a=1; Path=/', 'b=2; Path=/refresh']
+})
 ```
 
 ##### `ctx.write(chunk)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmmachina/swm-core",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "Zero-dependency high-performance HTTP/WebSocket server built on uWebSockets.js",
   "keywords": [
     "http",
@@ -44,6 +44,8 @@
     "test:e2e:ws": "node --test tests/e2e/ws/*.test.js",
     "bench": "node ./benchmark/bench.js --test base --runs 1 --warmup 10 --sample-ms 250 --v8prof true",
     "bench:core": "node ./benchmark/bench.js --test base --runs 1 --warmup 10 --sample-ms 250 --v8prof true --fw core",
+    "bench:headers": "node ./benchmark/bench.js --test headers --runs 1 --warmup 10 --sample-ms 250 --v8prof true",
+    "bench:headers:core": "node ./benchmark/bench.js --test headers --runs 1 --warmup 10 --sample-ms 250 --v8prof true --fw core",
     "prepublishOnly": "npm run fix && npm test",
     "release": "npm run check && npm test && npm publish"
   },

package/src/http-context.js

@@ -8,7 +8,8 @@ export default class HttpContext {
   #url = ''
   #headersCached = false
   #headers = {}
-  #fullQuery = null
+  #fullQuery = ''
+  #fullQueryCached = false
   #fullQueryParsed = false
   #query = {}
   #params = {}
@@ -122,7 +123,8 @@ export default class HttpContext {
     this.#method = ''
     this.#headersCached = false
     this.#headers = {}
-    this.#fullQuery = null
+    this.#fullQuery = ''
+    this.#fullQueryCached = false
     this.#fullQueryParsed = false
     this.#query = {}
     this.#params = {}
@@ -155,7 +157,8 @@ export default class HttpContext {
     this.#method = ''
     this.#headersCached = false
     this.#headers = {}
-    this.#fullQuery = null
+    this.#fullQuery = ''
+    this.#fullQueryCached = false
     this.#fullQueryParsed = false
     this.#query = {}
     this.#params = {}
@@ -200,13 +203,14 @@ export default class HttpContext {
   }
 
   cacheQuery() {
-    if (this.#fullQuery !== null || !this.req) {
+    if (this.#fullQueryCached || !this.req) {
       return
     }
 
     const fullQuery = this.req.getQuery()
 
     this.#fullQuery = typeof fullQuery === 'string' ? fullQuery : ''
+    this.#fullQueryCached = true
     this.#fullQueryParsed = false
   }
 
@@ -291,6 +295,27 @@ export default class HttpContext {
     return this.#url
   }
 
+  /**
+   * @returns {string}
+   */
+  fullQuery() {
+    if (this.#fullQueryCached) {
+      return this.#fullQuery
+    }
+
+    if (!this.req) {
+      return ''
+    }
+
+    const fullQuery = this.req.getQuery()
+
+    this.#fullQuery = typeof fullQuery === 'string' ? fullQuery : ''
+    this.#fullQueryCached = true
+    this.#fullQueryParsed = false
+
+    return this.#fullQuery
+  }
+
   /**
    * @param {string} name
    * @returns {string|undefined}
@@ -300,7 +325,7 @@ export default class HttpContext {
       return this.#query[name]
     }
 
-    if (this.#fullQuery !== null) {
+    if (this.#fullQueryCached) {
       this.#parseFullQuery()
 
       if (name in this.#query) {
@@ -403,12 +428,61 @@ export default class HttpContext {
       return this
     }
 
-    this.#stageHeader(key, value)
+    if (typeof key !== 'string') {
+      throw new TypeError('Header name must be a string')
+    }
+
+    if (value === undefined || value === null) {
+      return this
+    }
+
+    const headerKey = key.toLowerCase()
+
+    this.#pendingHeaders.set(headerKey, [key, `${value}`])
+    return this
+  }
+
+  /**
+   * @param {string} key
+   * @param {string} value
+   * @returns {HttpContext}
+   */
+  appendHeader(key, value) {
+    if (this.replied || this.aborted) {
+      return this
+    }
+
+    if (typeof key !== 'string') {
+      throw new TypeError('Header name must be a string')
+    }
+
+    if (value === undefined || value === null) {
+      return this
+    }
+
+    const headerKey = key.toLowerCase()
+    const headerValue = `${value}`
+    const pendingHeader = this.#pendingHeaders.get(headerKey)
+
+    if (!pendingHeader) {
+      this.#pendingHeaders.set(headerKey, [key, headerValue])
+      return this
+    }
+
+    pendingHeader[0] = key
+    const cur = pendingHeader[1]
+
+    if (typeof cur === 'string') {
+      pendingHeader[1] = [cur, headerValue]
+    } else {
+      cur[cur.length] = headerValue
+    }
+
     return this
   }
 
   /**
-   * @param {Record<string, string> | null | undefined} headers
+   * @param {Record<string, string | string[]> | null | undefined} headers
    */
   setHeaders(headers) {
     if (this.replied || this.aborted) {
@@ -419,7 +493,7 @@ export default class HttpContext {
   }
 
   /**
-   * @param {Record<string, string> | null | undefined} headers
+   * @param {Record<string, string | string[]> | null | undefined} headers
    */
   flushHeaders(headers = null) {
     this.#flushPendingHeaders(headers)
@@ -427,21 +501,83 @@ export default class HttpContext {
 
   /**
    * @param {string} key
-   * @param {string} value
+   * @param {string | string[] | null | undefined} value
+   * @param {boolean} append
    */
-  #stageHeader(key, value) {
+  #stagePendingHeader(key, value, append) {
     if (value === undefined || value === null) {
       return
     }
 
-    const headerName = String(key)
-    const headerValue = String(value)
+    const headerKey = key.toLowerCase()
+
+    if (!Array.isArray(value)) {
+      const headerValue = `${value}`
+
+      if (!append) {
+        this.#pendingHeaders.set(headerKey, [key, headerValue])
+        return
+      }
+
+      const pendingHeader = this.#pendingHeaders.get(headerKey)
+
+      if (!pendingHeader) {
+        this.#pendingHeaders.set(headerKey, [key, headerValue])
+        return
+      }
+
+      pendingHeader[0] = key
+      const cur = pendingHeader[1]
+
+      if (typeof cur === 'string') {
+        pendingHeader[1] = [cur, headerValue]
+      } else {
+        cur[cur.length] = headerValue
+      }
+
+      return
+    }
+
+    this.#stagePendingHeaderArray(key, headerKey, value, append)
+  }
+
+  /**
+   * @param {string} key
+   * @param {string} headerKey
+   * @param {string[]} value
+   * @param {boolean} append
+   */
+  #stagePendingHeaderArray(key, headerKey, value, append) {
+    let pendingHeader = append ? this.#pendingHeaders.get(headerKey) : null
+
+    for (let i = 0, len = value.length; i < len; i++) {
+      const entry = value[i]
+
+      if (entry === undefined || entry === null) {
+        continue
+      }
+
+      const headerValue = `${entry}`
+
+      if (!pendingHeader) {
+        pendingHeader = [key, headerValue]
+        this.#pendingHeaders.set(headerKey, pendingHeader)
+        continue
+      }
+
+      pendingHeader[0] = key
+      const cur = pendingHeader[1]
 
-    this.#pendingHeaders.set(headerName.toLowerCase(), [headerName, headerValue])
+      if (typeof cur === 'string') {
+        pendingHeader[1] = [cur, headerValue]
+      } else {
+        cur[cur.length] = headerValue
+      }
+    }
   }
 
   /**
-   * @param {Record<string, string> | null | undefined} headers
+   * @param {Record<string, string | string[]> | null | undefined} headers
    */
   #stageHeaders(headers) {
     if (!headers) {
@@ -449,29 +585,27 @@ export default class HttpContext {
     }
 
     if (headers === TEXT_PLAIN_HEADER) {
-      this.#stageHeader('content-type', 'text/plain; charset=utf-8')
+      this.#pendingHeaders.set('content-type', ['content-type', 'text/plain; charset=utf-8'])
       return
     }
 
     if (headers === JSON_HEADER) {
-      this.#stageHeader('content-type', 'application/json; charset=utf-8')
+      this.#pendingHeaders.set('content-type', ['content-type', 'application/json; charset=utf-8'])
       return
     }
 
     if (headers === OCTET_STREAM_HEADER) {
-      this.#stageHeader('content-type', 'application/octet-stream')
+      this.#pendingHeaders.set('content-type', ['content-type', 'application/octet-stream'])
       return
     }
 
     for (const key in headers) {
-      const value = headers[key]
-
-      this.#stageHeader(key, value)
+      this.#stagePendingHeader(key, headers[key], false)
     }
   }
 
   /**
-   * @param {Record<string, string> | null | undefined} headers
+   * @param {Record<string, string | string[]> | null | undefined} headers
    */
   #flushPendingHeaders(headers = null) {
     if (!this.res) {
@@ -483,8 +617,19 @@ export default class HttpContext {
       this.#stageHeaders(headers)
     }
 
-    for (const [, [key, value]] of this.#pendingHeaders) {
-      this.res.writeHeader(key, value)
+    for (const [, pendingHeader] of this.#pendingHeaders) {
+      const headerValue = pendingHeader[1]
+
+      if (typeof headerValue === 'string') {
+        this.res.writeHeader(pendingHeader[0], headerValue)
+        continue
+      }
+
+      const name = pendingHeader[0]
+
+      for (let i = 0, len = headerValue.length; i < len; i++) {
+        this.res.writeHeader(name, headerValue[i])
+      }
     }
 
     this.#pendingHeaders.clear()
@@ -557,7 +702,7 @@ export default class HttpContext {
 
   /**
    * @param {number} status
-   * @param {Record<string,string>} headers
+   * @param {Record<string, string | string[]>} headers
    * @param {string|ArrayBuffer|Uint8Array|Buffer|null|undefined} body
    */
   reply(status = 200, headers = null, body = null) {
@@ -585,7 +730,7 @@ export default class HttpContext {
 
   /**
    * @param {number} status
-   * @param {Record<string,string>} headers
+   * @param {Record<string, string | string[]>} headers
    * @returns {HttpContext}
    */
   startStreaming(status = 200, headers = null) {

package/src/res-streamer.js

@@ -82,7 +82,7 @@ export default class ResStreamer {
 
   /**
    * @param {number|string} status
-   * @param {Record<string,string>|null} headers
+   * @param {Record<string, string | string[]>|null} headers
    * @returns {ResStreamer}
    */
   begin(status = 200, headers = null) {