feat: expose headerNameToString (#2525)

docs/api/Util.md

@@ -0,0 +1,25 @@
+# Util
+
+Utility API for third-party implementations of the dispatcher API.
+
+## `parseHeaders(headers, [obj])`
+
+Receives a header object and returns the parsed value.
+
+Arguments:
+
+- **headers** `Record<string, string | string[]> | (Buffer | string | (Buffer | string)[])[]` (required) - Header object.
+
+- **obj** `Record<string, string | string[]>` (optional) - Object to specify a proxy object. The parsed value is assigned to this object. But, if **headers** is an object, it is not used.
+
+Returns: `Record<string, string | string[]>` If **headers** is an object, it is **headers**. Otherwise, if **obj** is specified, it is equivalent to **obj**.
+
+## `headerNameToString(value)`
+
+Retrieves a header name and returns its lowercase value.
+
+Arguments:
+
+- **value** `string | Buffer` (required) - Header name.
+
+Returns: `string`

index.js

@@ -20,7 +20,6 @@ const { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')
 const DecoratorHandler = require('./lib/handler/DecoratorHandler')
 const RedirectHandler = require('./lib/handler/RedirectHandler')
 const createRedirectInterceptor = require('./lib/interceptor/redirectInterceptor')
-const { parseHeaders } = require('./lib/core/util')
 
 let hasCrypto
 try {
@@ -47,7 +46,8 @@ module.exports.createRedirectInterceptor = createRedirectInterceptor
 module.exports.buildConnector = buildConnector
 module.exports.errors = errors
 module.exports.util = {
-  parseHeaders
+  parseHeaders: util.parseHeaders,
+  headerNameToString: util.headerNameToString
 }
 
 function makeDispatcher (fn) {

lib/core/util.js

@@ -221,7 +221,9 @@ function parseKeepAliveTimeout (val) {
 }
 
 /**
- * @param {string | Buffer} value
+ * Retrieves a header name and returns its lowercase value.
+ * @param {string | Buffer} value Header name
+ * @returns {string}
  */
 function headerNameToString (value) {
   return typeof value === 'string'
@@ -230,7 +232,9 @@ function headerNameToString (value) {
 }
 
 /**
- * @param {Buffer} value
+ * Receive the buffer as a string and return its lowercase value.
+ * @param {Buffer} value Header name
+ * @returns {string}
  */
 function bufferToLowerCasedHeaderName (value) {
   return tree.lookup(value) ?? value.toString('latin1').toLowerCase()

test/types/util.test-d.ts

@@ -0,0 +1,38 @@
+import { expectAssignable } from 'tsd';
+import { util } from '../../types/util';
+
+expectAssignable<Record<string, string | string[]>>(
+  util.parseHeaders({ 'content-type': 'text/plain' })
+);
+
+expectAssignable<Record<string, string | string[]>>(
+  //@ts-ignore
+  util.parseHeaders({ 'content-type': 'text/plain' }, {})
+);
+
+expectAssignable<Record<string, string | string[]>>(
+  util.parseHeaders({} as Record<string, string> | string[], {})
+);
+
+expectAssignable<Record<string, string | string[]>>(
+  util.parseHeaders(['content-type', 'text/plain'])
+);
+
+expectAssignable<Record<string, string | string[]>>(
+  util.parseHeaders([Buffer.from('content-type'), Buffer.from('text/plain')])
+);
+
+expectAssignable<Record<string, string | string[]>>(
+  util.parseHeaders(
+    [Buffer.from('content-type'), Buffer.from('text/plain')],
+    {}
+  )
+);
+
+expectAssignable<Record<string, string | string[]>>(
+  util.parseHeaders([Buffer.from('content-type'), [Buffer.from('text/plain')]])
+);
+
+expectAssignable<string>(util.headerNameToString('content-type'));
+
+expectAssignable<string>(util.headerNameToString(Buffer.from('content-type')));

types/index.d.ts

@@ -17,6 +17,7 @@ import ProxyAgent from'./proxy-agent'
 import RetryHandler from'./retry-handler'
 import { request, pipeline, stream, connect, upgrade } from './api'
 
+export * from './util'
 export * from './cookies'
 export * from './fetch'
 export * from './file'

types/util.d.ts

@@ -0,0 +1,31 @@
+export namespace util {
+  /**
+   * Retrieves a header name and returns its lowercase value.
+   * @param value Header name
+   */
+  export function headerNameToString(value: string | Buffer): string;
+
+  /**
+   * Receives a header object and returns the parsed value.
+   * @param headers Header object
+   */
+  export function parseHeaders(
+    headers:
+      | Record<string, string | string[]>
+      | (Buffer | string | (Buffer | string)[])[]
+  ): Record<string, string | string[]>;
+  /**
+   * Receives a header object and returns the parsed value.
+   * @param headers Header object
+   * @param obj Object to specify a proxy object. Used to assign parsed values. But, if `headers` is an object, it is not used.
+   * @returns If `headers` is an object, it is `headers`. Otherwise, if `obj` is specified, it is equivalent to `obj`.
+   */
+  export function parseHeaders<
+    H extends
+      | Record<string, string | string[]>
+      | (Buffer | string | (Buffer | string)[])[]
+  >(
+    headers: H,
+    obj?: H extends any[] ? Record<string, string | string[]> : never
+  ): Record<string, string | string[]>;
+}