@johntalton/http-util 4.1.1 → 5.0.1

package/README.md

@@ -2,9 +2,9 @@
 
 Set of utilities to aid in building from-scratch [node:http2](https://nodejs.org/docs/latest/api/http2.html) stream compatible services.
 
-- Header parsers
-- Stream Response methods
-- Body parser
+- [Header parsers](#header-parsers)
+- [Stream Response methods](#response)
+- [Body parser](#body)
 
 ## Header Parsers
 ### From Client:
@@ -44,24 +44,37 @@ const bestMatchingType = Accept.select(acceptHeader, supportedType)
 
 All responders take in a `stream` as well as a metadata object to hint on servername and origin strings etc.
 
-- `sendAccepted`
-- `sendConflict`
-- `sendCreated`
-- `sendError` - 500
-- `sendJSON_Encoded` - Standard Ok response with encoding
-- `sendNoContent`
-- `sendNotAcceptable`
-- `sendNotAllowed` - Method not supported / allowed
-- `sendNotFound` - 404
-- `sendNotModified`
-- `sendPreflight` - Response to OPTIONS with CORS headers
-- `sendTimeout`
-- `sendTooManyRequests` - Rate limit response (429)
-- `sendTrace`
-- `sendUnauthorized` - Unauthorized
-- `sendUnprocessable`
-- `sendUnsupportedMediaType`
-- `sendSSE` - SSE header (leave the `stream` open)
+- [`sendAccepted`](#responseaccepted)
+- [`sendConflict`](#responseconflict)
+- [`sendContentTooLarge`](#)
+- [`sendCreated`](#responsecreated)
+- [`sendError`](#responseerror) - 500
+- [`sendGone`](#)
+- [`sendImATeapot`](#)
+- [`sendInsufficientStorage`](#)
+- [`sendJSON_Encoded`](#responsejson) - Standard Ok response with encoding
+- [`sendMovedPermanently`](#)
+- [`sendMultipleChoices`](#)
+- [`sendNoContent`](#responsenocontent)
+- [`sendNotAcceptable`](#responsenotacceptable)
+- [`sendNotAllowed`](#responsenotallowed) - Method not supported / allowed
+- [`sendNotFound`](#responsenotfound) - 404
+- [`sendNotImplemented`](#responsenotimplemented)
+- [`sendNotModified`](#responsenotmodified)
+- [`sendPartialContent`](#)
+- [`sendPreconditionFailed`](#responsepreconditionfailed)
+- [`sendPreflight`](#responsepreflight) - Response to OPTIONS with CORS headers
+- [`sendRangeNotSatisfiable`](#)
+- [`sendSeeOther`](#)
+- [`sendTemporaryRedirect`](#)
+- [`sendTimeout`](#responsetimeout)
+- [`sendTooManyRequests`](#responsetoomanyrequests) - Rate limit response (429)
+- [`sendTrace`](#responsetrace)
+- [`sendUnauthorized`](#responseunauthorized) - Unauthorized
+- [`sendUnavailable`](#responseunavailable)
+- [`sendUnprocessable`](#responseunprocessable)
+- [`sendUnsupportedMediaType`](#responseunsupportedmediatype)
+- [`sendSSE`](#responsesse) - SSE header (leave the `stream` open)
 
 Responses allow for optional CORS headers as well as Server Timing meta data.
 
@@ -102,3 +115,201 @@ const futureBody = requestBody(stream, {
 const body = futureBody.json()
 
 ```
+
+## Response method API
+
+All response methods take in the `stream` and a `meta` property.
+
+Additional parameters are specific to each return type.
+
+Each return type semantic may also expose header (in addition to the standard headers) to the calling code as needed.
+
+Some common objects can be passed such as `EtagItem`, `CacheControlOptions` and `Metadata` have their own structure.
+
+Many parameters accept `undefined` to skip/ignore the usage
+
+### Response.accepted
+
+Parameters:
+- stream
+- meta
+
+### Response.conflict
+
+Parameters:
+- stream
+- meta
+
+
+### Response.created
+
+Parameters:
+- stream
+- location
+- etag
+- meta
+
+Additional Exposed Headers:
+- location
+
+### Response.error
+
+Parameters:
+- stream
+- meta
+
+
+### Response.json
+
+Parameters:
+- stream
+- object
+- encoding - undefined | 'identity' | 'br' | 'gzip' | 'deflate' | 'zstd'
+- etag
+- age
+- cacheControl
+- supportedQueryTypes - undefined | Array of supported query types
+- meta
+
+Additional Exposed Headers
+- age
+- accept-query
+
+### Response.noContent
+
+Parameters:
+- stream
+- etag
+- meta
+
+### Response.notAcceptable
+
+Parameters:
+- stream
+- supportedTypes
+- meta
+
+### Response.notAllowed
+
+Parameters:
+- stream
+- methods - Array of allowed methods
+- meta
+
+Additional Exposed Headers:
+- allow
+
+### Response.notFound
+
+Parameters:
+- stream
+- message
+- meta
+
+### Response.notImplemented
+
+Parameters:
+- stream
+- message
+- meta
+
+### Response.notModified
+
+Parameters:
+- stream
+- etag
+- age
+- cacheControl
+- meta
+
+Additional Exposed Headers:
+- age
+
+### Response.preconditionFailed
+
+Parameters:
+- stream
+- meta
+
+### Response.preflight
+
+Parameters:
+- stream
+- methods
+- supportedQueryTypes - undefined | Array of supported types
+- meta
+
+Additional Exposed Headers:
+- accept-query
+
+### Response.sse
+
+Parameters:
+- stream
+- meta
+
+
+### Response.timeout
+
+Parameters:
+- stream
+- meta
+
+
+### Response.tooManyRequests
+
+Parameters:
+- stream
+- limitInfo - `RateLimitInfo`
+- policies - Array of `RateLimitPolicyInfo`
+- meta
+
+Additional Exposed Headers:
+- retry-after
+- rate-limit
+- rate-limit-policy
+
+### Response.trace
+
+Parameters:
+- stream
+- method
+- url
+- headers
+- meta
+
+### Response.unauthorized
+
+Parameters:
+- stream
+- meta
+
+
+### Response.unavailable
+
+Parameters:
+- stream
+- message
+- retryAfter
+- meta
+
+Additional Exposed Headers:
+- retry-after
+
+### Response.unprocessable
+
+Parameters:
+- stream
+- meta
+
+### Response.unsupportedMediaType
+
+Parameters:
+- stream
+- acceptableMediaTypes
+- supportedQueryTypes
+- meta
+
+Additional Exposed Headers:
+- accept-query
+- accept-post

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johntalton/http-util",
-  "version": "4.1.1",
+  "version": "5.0.1",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/accept-encoding.js

@@ -21,7 +21,7 @@ export class AcceptEncoding {
 	 */
 	static select(acceptEncodingHeader, supportedTypes) {
 		const accepts = AcceptEncoding.parse(acceptEncodingHeader)
-		return this.selectFrom(accepts, supportedTypes)
+		return AcceptEncoding.selectFrom(accepts, supportedTypes)
 	}
 
 	/**

package/src/accept-language.js

@@ -23,7 +23,7 @@ export class AcceptLanguage {
 	 */
 	static select(acceptLanguageHeader, supportedTypes) {
 		const accepts = AcceptLanguage.parse(acceptLanguageHeader)
-		return this.selectFrom(accepts, supportedTypes)
+		return AcceptLanguage.selectFrom(accepts, supportedTypes)
 	}
 
 	/**

package/src/accept-util.js

@@ -39,7 +39,7 @@ export function parseAcceptStyleHeader(header, wellKnown) {
 				}))
 
 				if(!parameters.has(QUALITY)) { parameters.set(QUALITY, DEFAULT_QUALITY_STRING) }
-				const quality = parseFloat(parameters.get(QUALITY) ?? DEFAULT_QUALITY_STRING)
+				const quality = Number.parseFloat(parameters.get(QUALITY) ?? DEFAULT_QUALITY_STRING)
 
 				return {
 					name,

package/src/accept.js

@@ -54,7 +54,6 @@ export class Accept {
 				const qualityB = entryB.quality ?? 0
 				const qualityA = entryA.quality ?? 0
 				return qualityB - qualityA
-				// return entryB.quality - entryA.quality
 			})
 	}
 
@@ -64,7 +63,7 @@ export class Accept {
 	 */
 	static select(acceptHeader, supportedTypes) {
 		const accepts = Accept.parse(acceptHeader)
-		return this.selectFrom(accepts, supportedTypes)
+		return Accept.selectFrom(accepts, supportedTypes)
 	}
 
 	/**
@@ -84,9 +83,7 @@ export class Accept {
 				quality
 			}
 		})
-		.filter(best => {
-			return best.supportedTypes.length > 0
-		})
+		.filter(best => best.supportedTypes.length > 0)
 
 		if(bests.length === 0) { return undefined }
 		const [ first ] = bests

package/src/body.js

@@ -1,15 +1,15 @@
-import { CHARSET_UTF8, MIME_TYPE_MULTIPART_FORM_DATA, MIME_TYPE_URL_FORM_DATA } from './content-type.js'
+import {
+	CHARSET_UTF8,
+	MIME_TYPE_MULTIPART_FORM_DATA,
+	MIME_TYPE_URL_FORM_DATA
+} from './content-type.js'
 import { Multipart } from './multipart.js'
 
-export const DEFAULT_BYTE_LIMIT = 1024 * 1024 //
+export const BYTE_PER_K = 1024
+export const DEFAULT_BYTE_LIMIT = BYTE_PER_K * BYTE_PER_K //
 
-/**
- * @import { Readable } from 'node:stream'
- */
-
-/**
- * @import { ContentType } from './content-type.js'
- */
+/** @import { Readable } from 'node:stream' */
+/** @import { ContentType } from './content-type.js' */
 
 /**
  * @typedef {Object} BodyOptions
@@ -32,7 +32,6 @@ export const DEFAULT_BYTE_LIMIT = 1024 * 1024 //
  * @property { () => Promise<any> } json
  */
 
-
 /**
  * @param {Readable} stream
  * @param {BodyOptions} [options]
@@ -45,7 +44,7 @@ export function requestBody(stream, options) {
 	const charset = options?.contentType?.charset ?? CHARSET_UTF8
 	const contentType = options?.contentType
 
-	const invalidContentLength = (contentLength === undefined || isNaN(contentLength))
+	const invalidContentLength = (contentLength === undefined || Number.isNaN(contentLength))
 	// if(contentLength > byteLimit) {
 		// console.log(contentLength, invalidContentLength)
 	// 	throw new Error('contentLength exceeds limit')
@@ -92,7 +91,6 @@ export function requestBody(stream, options) {
 				// return
 			}
 
-
 			const listener = () => {
 				stats.closed = true
 				controller.error(new Error('Abort Signal'))
@@ -281,7 +279,7 @@ export async function bodyJSON(reader, charset) {
  * @param {ReadableStream} reader
  * @param {ContentType} contentType
  */
-async function _bodyFormData_Multipart(reader, contentType) {
+export async function _bodyFormData_Multipart(reader, contentType) {
 	const MULTIPART_FORM_DATA_BOUNDARY_PARAMETER = 'boundary'
 
 	const text = await bodyText(reader, contentType.charset)
@@ -295,7 +293,7 @@ async function _bodyFormData_Multipart(reader, contentType) {
  * @param {ReadableStream} reader
  * @param {ContentType} contentType
  */
-async function _bodyFormData_URL(reader, contentType) {
+export async function _bodyFormData_URL(reader, contentType) {
 	const text = await bodyText(reader, contentType.charset)
 	const sp = new URLSearchParams(text)
 	const formData = new FormData()
@@ -323,4 +321,4 @@ export async function bodyFormData(reader, contentType) {
 	}
 
 	throw new TypeError('unknown mime type for form data')
-}
+}

package/src/cache-control.js

@@ -12,10 +12,12 @@
 
 export class CacheControl {
 	/**
-	 * @param {CacheControlOptions} options
+	 * @param {CacheControlOptions|undefined} options
 	 * @returns {string|undefined}
 	 */
 	static encode(options) {
+		if(options === undefined) { return undefined }
+
 		const {
 			pub,
 			priv,
@@ -46,6 +48,9 @@ export class CacheControl {
 			result.push(`stale-if-error=${staleIfError}`)
 		}
 
+		//
+		if(result.length === 0) { return undefined }
+
 		return result.join(', ')
 	}
 }

package/src/clear-site-data.js

@@ -0,0 +1,59 @@
+
+/** @type {'*'} */
+export const WILDCARD = '*'
+
+export const CSD_DIRECTIVE_SEPARATOR = ','
+export const CSD_QUOTE = '"'
+
+export const CSD_DIRECTIVE_CACHE = 'cache'
+export const CSD_DIRECTIVE_CLIENT_HINTS = 'clientHints'
+export const CSD_DIRECTIVE_COOKIES = 'cookies'
+export const CSD_DIRECTIVE_EXECUTION_CONTEXTS = 'executionContexts'
+export const CSD_DIRECTIVE_PREFETCH_CACHE = 'prefetchCache'
+export const CSD_DIRECTIVE_PRERENDER_CACHE = 'prerenderCache'
+export const CSD_DIRECTIVE_STORAGE = 'storage'
+
+/**
+ * @typedef {Object} ClearOptions
+ * @property {boolean} cache
+ * @property {boolean} clientHints
+ * @property {boolean} cookies
+ * @property {boolean} executionContext
+ * @property {boolean} prefetchCache
+ * @property {boolean} prerenderCache
+ * @property {boolean} storage
+ */
+
+export class SiteData {
+	/**
+	 * @param {Partial<ClearOptions>|true|'*'|undefined} directives
+	 */
+	static encode(directives) {
+		if(directives === undefined) { return undefined }
+		if(directives === true) { return WILDCARD }
+		if(directives === WILDCARD) { return WILDCARD }
+
+		const result = []
+		if(directives.cache === true) { result.push(CSD_DIRECTIVE_CACHE) }
+		if(directives.clientHints === true) { result.push(CSD_DIRECTIVE_CLIENT_HINTS) }
+		if(directives.cookies === true) { result.push(CSD_DIRECTIVE_COOKIES) }
+		if(directives.executionContext === true) { result.push(CSD_DIRECTIVE_EXECUTION_CONTEXTS) }
+		if(directives.prefetchCache === true) { result.push(CSD_DIRECTIVE_PREFETCH_CACHE) }
+		if(directives.prerenderCache === true) { result.push(CSD_DIRECTIVE_PRERENDER_CACHE) }
+		if(directives.storage === true) { result.push(CSD_DIRECTIVE_STORAGE) }
+
+		return result
+			.map(item => `${CSD_QUOTE}${item}${CSD_QUOTE}`)
+			.join(CSD_DIRECTIVE_SEPARATOR)
+	}
+}
+
+// console.log(SiteData.encode())
+// console.log(SiteData.encode({}))
+// console.log(SiteData.encode(false))
+// console.log(SiteData.encode('true'))
+// console.log(SiteData.encode(true))
+// console.log(SiteData.encode('*'))
+// console.log(SiteData.encode({ storage: false }))
+// console.log(SiteData.encode({ storage: true }))
+// console.log(SiteData.encode({ storage: true, cookies: true }))

package/src/conditional.js

@@ -49,6 +49,9 @@ export const DATE_SEPARATOR = ','
 export const DATE_TIME_SEPARATOR = ':'
 export const DATE_ZONE = 'GMT'
 
+export const MINIMUM_YEAR = 1900
+export const MAXIMUM_DAY = 31
+
 /**
  * @param {string} etag
  */
@@ -102,6 +105,31 @@ export class ETag {
 	 * @returns {AnyEtagItem}
 	 */
 	static any() { return ANY_ETAG_ITEM }
+
+	/**
+	 * @param {string|undefined} raw
+	 * @returns {EtagItem|undefined}
+	 */
+	static parse(raw) {
+		if(raw === undefined) { return undefined }
+
+		const rawEtag = raw.trim()
+		const weak = rawEtag.startsWith(CONDITION_ETAG_WEAK_PREFIX)
+		const quotedEtag = weak ? rawEtag.substring(CONDITION_ETAG_WEAK_PREFIX.length) : rawEtag
+
+		if(quotedEtag === CONDITION_ETAG_ANY) { return ANY_ETAG_ITEM }
+
+		if(!isQuoted(quotedEtag)) { return undefined }
+		const etag = stripQuotes(quotedEtag)
+		if(!isValidEtag(etag)) { return undefined }
+		if(etag === CONDITION_ETAG_ANY) { return undefined }
+
+		return {
+			weak,
+			any: false,
+			etag
+		}
+	}
 }
 
 export class Conditional {
@@ -131,40 +159,7 @@ export class Conditional {
 		if(matchHeader === undefined) { return [] }
 
 		return matchHeader.split(CONDITION_ETAG_SEPARATOR)
-			.map(etag => etag.trim())
-			.map(etag => {
-				if(etag.startsWith(CONDITION_ETAG_WEAK_PREFIX)) {
-					// weak
-					return {
-						weak: true,
-						etag: etag.substring(CONDITION_ETAG_WEAK_PREFIX.length)
-					}
-				}
-
-				// strong
-				return {
-					weak: false,
-					etag
-				}
-			})
-			.map(item => {
-				if(item.etag === CONDITION_ETAG_ANY) { return ANY_ETAG_ITEM }
-
-				// validated quoted
-				if(!isQuoted(item.etag)) { return undefined }
-				const etag = stripQuotes(item.etag)
-				if(!isValidEtag(etag)) { return undefined }
-				if(etag === CONDITION_ETAG_ANY) { return undefined }
-
-				/** @type {WeakEtagItem | NotWeakEtagItem} */
-				const result = {
-					weak: item.weak,
-					any: false,
-					etag
-				}
-
-				return result
-			})
+			.map(ETag.parse)
 			.filter(item => item !== undefined)
 	}
 
@@ -209,7 +204,7 @@ export class Conditional {
 		// <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT
 		// day-name "," SP date1 SP time-of-day SP GMT
 
-		if(matchHeader.length != 29) { return undefined }
+		if(matchHeader.length !== 29) { return undefined }
 
 		//
 		const spaces = [
@@ -238,12 +233,12 @@ export class Conditional {
 
 		//
 		const dayName = matchHeader.substring(0, 3)
-		const day = parseInt(matchHeader.substring(5, 7))
+		const day = Number.parseInt(matchHeader.substring(5, 7))
 		const month = matchHeader.substring(8, 11)
-		const year = parseInt(matchHeader.substring(12, 16))
-		const hour = parseInt(matchHeader.substring(17, 19))
-		const minute = parseInt(matchHeader.substring(20, 22))
-		const second = parseInt(matchHeader.substring(23, 25))
+		const year = Number.parseInt(matchHeader.substring(12, 16))
+		const hour = Number.parseInt(matchHeader.substring(17, 19))
+		const minute = Number.parseInt(matchHeader.substring(20, 22))
+		const second = Number.parseInt(matchHeader.substring(23, 25))
 
 		//
 		if(!DATE_DAYS.includes(dayName)) { return undefined }
@@ -255,8 +250,8 @@ export class Conditional {
 		if(!Number.isInteger(second)) { return undefined }
 
 		//
-		if(day > 31 || day <= 0) { return undefined }
-		if(year < 1900) { return undefined }
+		if(day > MAXIMUM_DAY || day <= 0) { return undefined }
+		if(year < MINIMUM_YEAR) { return undefined }
 		if(hour > 24 || hour < 0) { return undefined }
 		if(minute > 60 || minute < 0) { return undefined }
 		if(second > 60 || second < 0) { return undefined }

package/src/content-disposition.js

@@ -1,9 +1,9 @@
 /**
  * @typedef {Object} Disposition
  * @property {string} disposition
- * @property {Map<string, string>} parameters
- * @property {string} [name]
- * @property {string} [filename]
+ * @property {Map<string, string|undefined>} parameters
+ * @property {string|undefined} [name]
+ * @property {string|undefined} [filename]
  */
 
 export const DISPOSITION_SEPARATOR = {
@@ -15,17 +15,22 @@ export const DISPOSITION_PARAM_NAME = 'name'
 export const DISPOSITION_PARAM_FILENAME = 'filename'
 
 /**
- * @param {string} contentDispositionHeader
+ * @param {string|undefined} contentDispositionHeader
  * @returns {Disposition|undefined}
  */
 export function parseContentDisposition(contentDispositionHeader) {
 	if(contentDispositionHeader === undefined) { return undefined }
 
 	const [ disposition, ...parameterSet ] = contentDispositionHeader.trim().split(DISPOSITION_SEPARATOR.PARAMETER).map(entry => entry.trim())
+	if(disposition === undefined) { return undefined }
 	const parameters = new Map(parameterSet.map(parameter => {
-		const [ key, value ] = parameter.split(DISPOSITION_SEPARATOR.KVP).map(p => p.trim())
-		return [ key, value ]
-	}))
+			const [ key, value ] = parameter.split(DISPOSITION_SEPARATOR.KVP).map(p => p.trim())
+			if(key === undefined) { return undefined }
+			return { key, value }
+		})
+		.filter(item => item !== undefined)
+		.map(({ key, value }) => ([ key, value ])))
+
 
 	const name = parameters.get(DISPOSITION_PARAM_NAME)
 	const filename = parameters.get(DISPOSITION_PARAM_FILENAME)