feat: expose content-type parser (nodejs#1895)

* feat: expose content-type parser

* fix: add docs

docs/api/ContentType.md

@@ -0,0 +1,57 @@
+# MIME Type Parsing
+
+## `MIMEType` interface
+
+* **type** `string`
+* **subtype** `string`
+* **parameters** `Map<string, string>`
+* **essence** `string`
+
+## `parseMIMEType(input)`
+
+Implements [parse a MIME type](https://mimesniff.spec.whatwg.org/#parse-a-mime-type).
+
+Parses a MIME type, returning its type, subtype, and any associated parameters. If the parser can't parse an input it returns the string literal `'failure'`.
+
+```js
+import { parseMIMEType } from 'undici'
+
+parseMIMEType('text/html; charset=gbk')
+// {
+//   type: 'text',
+//   subtype: 'html',
+//   parameters: Map(1) { 'charset' => 'gbk' },
+//   essence: 'text/html'
+// }
+```
+
+Arguments:
+
+* **input** `string`
+
+Returns: `MIMEType|'failure'`
+
+## `serializeAMimeType(input)`
+
+Implements [serialize a MIME type](https://mimesniff.spec.whatwg.org/#serialize-a-mime-type).
+
+Serializes a MIMEType object.
+
+```js
+import { serializeAMimeType } from 'undici'
+
+serializeAMimeType({
+  type: 'text',
+  subtype: 'html',
+  parameters: new Map([['charset', 'gbk']]),
+  essence: 'text/html'
+})
+// text/html;charset=gbk
+
+```
+
+Arguments:
+
+* **mimeType** `MIMEType`
+
+Returns: `string`

docsify/sidebar.md

@@ -19,6 +19,7 @@
   * [API Lifecycle](/docs/api/api-lifecycle.md "Undici API - Lifecycle")
   * [Diagnostics Channel Support](/docs/api/DiagnosticsChannel.md "Diagnostics Channel Support")
   * [WebSocket](/docs/api/WebSocket.md "Undici API - WebSocket")
+  * [MIME Type Parsing](/docs/api/ContentType.md "Undici API - MIME Type Parsing")
 * Best Practices
   * [Proxy](/docs/best-practices/proxy.md "Connecting through a proxy")
   * [Client Certificate](/docs/best-practices/client-certificate.md "Connect using a client certificate")

index.d.ts

@@ -23,6 +23,7 @@ export * from './types/filereader'
 export * from './types/formdata'
 export * from './types/diagnostics-channel'
 export * from './types/websocket'
+export * from './types/content-type'
 export { Interceptable } from './types/mock-interceptor'
 
 export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent, RedirectHandler, DecoratorHandler }

index.js

@@ -134,6 +134,11 @@ if (nodeMajor >= 16) {
   module.exports.getCookies = getCookies
   module.exports.getSetCookies = getSetCookies
   module.exports.setCookie = setCookie
+
+  const { parseMIMEType, serializeAMimeType } = require('./lib/fetch/dataURL')
+
+  module.exports.parseMIMEType = parseMIMEType
+  module.exports.serializeAMimeType = serializeAMimeType
 }
 
 if (nodeMajor >= 18 && hasCrypto) {

types/content-type.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="node" />
+
+interface MIMEType {
+  type: string
+  subtype: string
+  parameters: Map<string, string>
+  essence: string
+}
+
+/**
+ * Parse a string to a {@link MIMEType} object. Returns `failure` if the string
+ * couldn't be parsed.
+ * @see https://mimesniff.spec.whatwg.org/#parse-a-mime-type
+ */
+export function parseMIMEType (input: string): 'failure' | MIMEType
+
+/**
+ * Convert a MIMEType object to a string.
+ * @see https://mimesniff.spec.whatwg.org/#serialize-a-mime-type
+ */
+export function serializeAMimeType (mimeType: MIMEType): string