@johntalton/http-util 5.1.6 → 6.1.0

package/README.md

@@ -6,7 +6,7 @@ Set of utilities to aid in building from-scratch [node:http2](https://nodejs.org
 - [Stream Response methods](#response)
 - [Body parser](#body)
 
-## Header Parsers
+## Header Parsers / Encoders
 ### From Client:
 - Accept Encoding - `parse` and `select` based on server/client values
 - Accept Language - `parse` and `select`
@@ -17,10 +17,21 @@ Set of utilities to aid in building from-scratch [node:http2](https://nodejs.org
 - Multipart - parse into `FormData`
 - Content Disposition - for use inside of Multipart
 - Conditionals - Etag / FixDate for IfMatch, IfModifiedSince etc
+- Client Hints
+- Forwarded
+- Applied Preferences
 
 ### Server Sent:
 - Rate Limit
 - Server Timing
+- Cache Control
+- Clear Site Data
+- Conditional (Etag / IMF Date)
+- Content Range
+- Preferences
+- WWW Auth
+- STS
+
 
 
 ```javascript
@@ -49,11 +60,12 @@ All responders take in a `stream` as well as a metadata object to hint on server
 - [`sendContentTooLarge`](#)
 - [`sendCreated`](#responsecreated)
 - [`sendError`](#responseerror) - 500
-- [`sendGone`](#)
+- [`sendForbidden`](#responseforbidden)
+- [`sendGone`](#responsegone)
 - [`sendImATeapot`](#)
 - [`sendInsufficientStorage`](#)
 - [`sendJSON_Encoded`](#responsejson) - Standard Ok response with encoding
-- [`sendMovedPermanently`](#)
+- [`sendMovedPermanently`](#responsemovedpermanently)
 - [`sendMultipleChoices`](#)
 - [`sendNoContent`](#responsenocontent)
 - [`sendNotAcceptable`](#responsenotacceptable)
@@ -62,9 +74,10 @@ All responders take in a `stream` as well as a metadata object to hint on server
 - [`sendNotImplemented`](#responsenotimplemented)
 - [`sendNotModified`](#responsenotmodified)
 - [`sendPartialContent`](#)
+- [`sendPermanentRedirect`](#)
 - [`sendPreconditionFailed`](#responsepreconditionfailed)
 - [`sendPreflight`](#responsepreflight) - Response to OPTIONS with CORS headers
-- [`sendRangeNotSatisfiable`](#)
+- [`sendRangeNotSatisfiable`](#responserangenotsatisfiable)
 - [`sendSeeOther`](#)
 - [`sendTemporaryRedirect`](#)
 - [`sendTimeout`](#responsetimeout)
@@ -145,8 +158,8 @@ Parameters:
 
 Parameters:
 - stream
-- location
-- etag
+- location - URL to newly create object
+- etag - etag of the related object
 - meta
 
 Additional Exposed Headers:
@@ -158,6 +171,27 @@ Parameters:
 - stream
 - meta
 
+### Response.forbidden
+
+Parameters:
+- stream
+- meta
+
+### Response.gone
+
+Parameters:
+- stream
+- meta
+
+### Response.movedPermanently
+
+Parameters:
+- steam
+- location
+- meta
+
+Additional Exposed Headers:
+- location
 
 ### Response.json
 
@@ -186,7 +220,7 @@ Parameters:
 
 Parameters:
 - stream
-- supportedTypes
+- supportedTypes - array of supported types (mime/lang/encodings etc)
 - meta
 
 ### Response.notAllowed
@@ -237,10 +271,22 @@ Parameters:
 - stream
 - methods
 - supportedQueryTypes - undefined | Array of supported types
+- acceptRanges
 - meta
 
 Additional Exposed Headers:
 - accept-query
+- accept-ranges
+
+### Response.rangeNotSatisfiable
+
+Parameters:
+- stream
+- directive - specify size of acceptable range of bytes
+- meta
+
+Additional Exposed Headers:
+- content-range
 
 ### Response.sse
 
@@ -282,6 +328,7 @@ Parameters:
 
 Parameters:
 - stream
+- challenge
 - meta
 
 

package/package.json

@@ -1,23 +1,43 @@
 {
   "name": "@johntalton/http-util",
-  "version": "5.1.6",
+  "version": "6.1.0",
   "license": "MIT",
   "type": "module",
+  "imports": {
+    "#util": "./src/headers/util/index.js"
+  },
   "exports": {
-    ".": "./src/index.js",
-    "./headers": "./src/index.js",
+    ".": "./src/headers/index.js",
+    "./headers": "./src/headers/index.js",
     "./body": "./src/body.js",
     "./response": "./src/response/index.js",
-    "./response/object": "./src/response/response.js"
+    "./response/object": "./src/response/response.js",
+    "./util": "./src/headers/util/index.js"
   },
   "files": [
     "src/*.js",
-    "src/response/*.js"
+    "src/response/**/*.js",
+    "src/headers/*.js",
+    "src/headers/util/*.js"
   ],
+  "scripts": {
+    "lint": "biome check",
+    "test": "node --test test/**/*.test.js",
+    "coverage": "c8 --src src --check-coverage --statements 90 --branches 90 --functions 90 --lines 90 -r lcovonly -r text node --test   test/**/*.test.js"
+  },
   "repository": {
     "url": "https://github.com/johntalton/http-util"
   },
   "dependencies": {
     "@johntalton/sse-util": "^1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.15",
+    "c8": "^11.0.0"
+  },
+  "overrides": {
+    "c8": {
+      "yargs": "^18.0.0"
+    }
   }
-}
+}

package/src/body.js

@@ -2,28 +2,28 @@ import {
 	CHARSET_UTF8,
 	MIME_TYPE_MULTIPART_FORM_DATA,
 	MIME_TYPE_URL_FORM_DATA
-} from './content-type.js'
-import { Multipart } from './multipart.js'
+} from './headers/content-type.js'
+import { Multipart } from './headers/multipart.js'
 
 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 { ContentTypeItem } from './headers/content-type.js' */
 
 /**
  * @typedef {Object} BodyOptions
  * @property {AbortSignal|undefined} [signal]
  * @property {number|undefined} [byteLimit]
  * @property {number|undefined} [contentLength]
- * @property {ContentType|undefined} [contentType]
+ * @property {ContentTypeItem|undefined} [contentType]
  */
 
 /**
  * @typedef {Object} BodyFuture
  * @property {number} duration
  * @property {ReadableStream} body
- * @property {ContentType|undefined} contentType
+ * @property {ContentTypeItem|undefined} contentType
  * @property { (mimetype: string) => Promise<Blob> } blob
  * @property { () => Promise<ArrayBufferLike> } arrayBuffer
  * @property { () => Promise<Uint8Array> } bytes
@@ -277,7 +277,7 @@ export async function bodyJSON(reader, charset) {
 
 /**
  * @param {ReadableStream} reader
- * @param {ContentType} contentType
+ * @param {ContentTypeItem} contentType
  */
 export async function _bodyFormData_Multipart(reader, contentType) {
 	const MULTIPART_FORM_DATA_BOUNDARY_PARAMETER = 'boundary'
@@ -291,7 +291,7 @@ export async function _bodyFormData_Multipart(reader, contentType) {
 
 /**
  * @param {ReadableStream} reader
- * @param {ContentType} contentType
+ * @param {ContentTypeItem} contentType
  */
 export async function _bodyFormData_URL(reader, contentType) {
 	const text = await bodyText(reader, contentType.charset)
@@ -307,7 +307,7 @@ export async function _bodyFormData_URL(reader, contentType) {
 
 /**
  * @param {ReadableStream} reader
- * @param {ContentType|undefined} contentType
+ * @param {ContentTypeItem|undefined} contentType
  */
 export async function bodyFormData(reader, contentType) {
 	if(contentType === undefined) { throw new Error('undefined content type for form data') }

package/src/{response/defs.js → defs.js}

@@ -26,7 +26,14 @@ export const RANGE_UNITS_BYTES = 'bytes'
 /** @type {'none'} */
 export const RANGE_UNITS_NONE = 'none'
 
-/** @import { TimingsInfo } from '../server-timing.js' */
+
+/** @import { TimingsInfo } from './headers/server-timing.js' */
+/** @import { EtagItem, IMFFixDateInput,  } from './headers/conditional.js' */
+/** @import { CacheControlOptions } from './headers/cache-control.js' */
+/** @import { ContentRangeDirective } from './headers/content-range.js' */
+/** @import { RateLimitPolicyInfo, RateLimitInfo } from './headers/rate-limit.js' */
+
+/** @typedef {RANGE_UNITS_BYTES | RANGE_UNITS_NONE} AcceptRangeUnits */
 
 /**
  * @typedef {`X-${string}`} CustomHeaderKey
@@ -46,3 +53,30 @@ export const RANGE_UNITS_NONE = 'none'
  * @property {boolean} [bom]
  */
 
+/** @typedef {ArrayBufferLike|ArrayBufferView|ReadableStream|string} SendBody */
+
+/**
+ * @typedef {Object} SendContent
+ * @property {string|undefined} contentType
+ * @property {number|undefined} contentLength
+ * @property {string|undefined} encoding
+ * @property {EtagItem|undefined} etag
+ * @property {IMFFixDateInput|string|undefined} lastModified
+ * @property {number|undefined} age
+ * @property {CacheControlOptions} cacheControl
+ * @property {ContentRangeDirective} rangeDirective
+ */
+
+/**
+ * @typedef {Object} SendInfo
+ * @property {Array<string>} supportedMethods
+ * @property {Array<string>|string} supportedTypes
+ * @property {Array<string>|string} acceptableMediaType
+ * @property {AcceptRangeUnits|undefined} acceptRanges
+ * @property {Array<string>|undefined} supportedQueryTypes
+ * @property {RateLimitInfo} limitInfo
+ * @property {Array<RateLimitPolicyInfo>} policies
+ * @property {number|undefined} retryAfter
+ */
+
+

package/src/{accept-encoding.js → headers/accept-encoding.js}

@@ -1,6 +1,8 @@
-import { parseAcceptStyleHeader } from './accept-util.js'
+import { parseAcceptStyleHeader } from './util/accept-util.js'
 
-/** @import { AcceptStyleItem } from './accept-util.js' */
+/** @import { AcceptStyleItem } from './util/accept-util.js' */
+
+export const ENCODING_ANY = '*'
 
 export const WELL_KNOWN_ENCODINGS = new Map([
 	[ 'gzip, deflate, br, zstd', [ { name: 'gzip' }, { name: 'deflate' }, { name: 'br' }, { name: 'zstd' } ] ],
@@ -29,6 +31,8 @@ export class AcceptEncoding {
 	 * @param {Array<string>} supportedTypes
 	 */
 	static selectFrom(acceptEncodings, supportedTypes) {
+		if(supportedTypes === undefined) { return undefined }
+
 		for(const acceptEncoding of acceptEncodings) {
 			const { name } = acceptEncoding
 			if(supportedTypes.includes(name)) {
@@ -36,18 +40,11 @@ export class AcceptEncoding {
 			 }
 		}
 
+		//
+		if(acceptEncodings.some(item => item.name === ENCODING_ANY)) {
+			return supportedTypes.at(0)
+		}
+
 		return undefined
 	}
 }
-
-
-// console.log(AcceptEncoding.parse(''))
-// console.log(AcceptEncoding.parse(' '))
-// console.log(AcceptEncoding.parse('zstd'))
-// console.log(AcceptEncoding.parse('identity'))
-// console.log(AcceptEncoding.parse('*'))
-// console.log(AcceptEncoding.parse('gzip, deflate, br, zstd'))
-// console.log(AcceptEncoding.parse('br;q=1.0, gzip;q=0.8, *;q=0.1'))
-// console.log(AcceptEncoding.parse('deflate, gzip;q=1.0, *;q=0.5'))
-// console.log(AcceptEncoding.parse('identity;q=0'))
-// console.log(AcceptEncoding.parse('*;q=0'))

package/src/{accept-language.js → headers/accept-language.js}

@@ -1,12 +1,13 @@
-import { parseAcceptStyleHeader } from './accept-util.js'
+import { parseAcceptStyleHeader } from './util/accept-util.js'
 
-/**
- * @import { AcceptStyleItem } from './accept-util.js'
- */
+/** @import { AcceptStyleItem } from './util/accept-util.js' */
+
+export const LANGUAGE_ANY = '*'
 
 export const WELL_KNOWN_LANGUAGES = new Map([
 	[ 'en-US,en;q=0.5', [ { name: 'en-US', quality: 1 }, { name: 'en', quality: 0.5 } ] ],
-	[ 'en-US,en;q=0.9', [ { name: 'en-US', quality: 1 }, { name: 'en', quality: 0.9 } ] ]
+	[ 'en-US,en;q=0.9', [ { name: 'en-US', quality: 1 }, { name: 'en', quality: 0.9 } ] ],
+	// [ '*', [ { name: '*', quality: 1 } ]]
 ])
 
 export class AcceptLanguage {
@@ -31,16 +32,20 @@ export class AcceptLanguage {
 	 * @param {Array<string>} supportedTypes
 	 */
 	static selectFrom(acceptLanguages, supportedTypes) {
+		if(supportedTypes === undefined) { return undefined }
+
 		for(const acceptLanguage of acceptLanguages) {
 			const { name } = acceptLanguage
 			if(supportedTypes.includes(name)) {
 				return name
-				}
+			}
+		}
+
+		//
+		if(acceptLanguages.some(item => item.name === LANGUAGE_ANY)) {
+			return supportedTypes.at(0)
 		}
 
 		return undefined
 	}
 }
-
-// console.log(AcceptLanguage.parse('en-US,en;q=0.9'))
-// console.log(AcceptLanguage.select('foo;q=0.2, bar-BZ', [ 'bang', 'foo' ]))

package/src/headers/accept.js

@@ -0,0 +1,86 @@
+import { parseAcceptStyleHeader } from './util/accept-util.js'
+import { MIME_ANY, Mime } from './util/mime.js'
+
+/** @import { AcceptStyleItem } from './util/accept-util.js' */
+/** @import { MimeItem } from './util/mime.js' */
+
+/** @typedef {AcceptStyleItem & MimeItem} AcceptItem */
+
+export const WELL_KNOWN = new Map([
+	[ '*/*', [ { name: '*/*', quality: 1 } ] ],
+	[ 'application/json', [ { name: 'application/json', quality: 1 } ] ]
+])
+
+export class Accept {
+	/**
+	 * @param {string|undefined} acceptHeader
+	 * @returns {Array<AcceptItem>}
+	 */
+	static parse(acceptHeader) {
+		return parseAcceptStyleHeader(acceptHeader, WELL_KNOWN)
+			.map(({ name, quality, parameters }) => {
+
+				const mime = Mime.parse(name)
+				if(mime === undefined) { return undefined }
+
+				return {
+					name,
+					...mime,
+					quality,
+					parameters
+				}
+			})
+			.filter(entry => entry !== undefined)
+			.sort((entryA, entryB) => {
+				if(entryA.quality === entryB.quality) {
+					// prefer things with less ANY
+					const specificityA = (entryA.type === MIME_ANY ? 1 : 0) + (entryA.subtype === MIME_ANY ? 1 : 0)
+					const specificityB = (entryB.type === MIME_ANY ? 1 : 0) + (entryB.subtype === MIME_ANY ? 1 : 0)
+					return specificityA - specificityB
+				}
+
+				// B - A descending order
+				const qualityB = entryB.quality ?? 0
+				const qualityA = entryA.quality ?? 0
+				return qualityB - qualityA
+			})
+	}
+
+	/**
+	 * @param {string|undefined} acceptHeader
+	 * @param {Array<string>} supportedTypes
+	 */
+	static select(acceptHeader, supportedTypes) {
+		const accepts = Accept.parse(acceptHeader)
+		return Accept.selectFrom(accepts, supportedTypes)
+	}
+
+	/**
+	 * @param {Array<AcceptItem>} accepts
+	 * @param {Array<string>} supportedTypes
+	 */
+	static selectFrom(accepts, supportedTypes) {
+		const bests = accepts.map(accept => {
+			const { type, subtype, quality } = accept
+			const st = supportedTypes.filter(supportedType => {
+				const supportedMime = Mime.parse(supportedType)
+				if(supportedMime === undefined) { return false }
+				return ((supportedMime.type === type || type === MIME_ANY) && (supportedMime.subtype === subtype || subtype === MIME_ANY))
+			})
+
+			return {
+				supportedTypes: st,
+				quality
+			}
+		})
+		.filter(best => best.supportedTypes.length > 0)
+
+		if(bests.length === 0) { return undefined }
+		const [ first ] = bests
+		if(first === undefined) { return undefined }
+		const [ firstSt ] = first.supportedTypes
+		return firstSt
+	}
+}
+
+

package/src/{cache-control.js → headers/cache-control.js}

@@ -54,9 +54,3 @@ export class CacheControl {
 		return result.join(', ')
 	}
 }
-
-// console.log(CacheControl.encode({
-// 	priv: true,
-// 	maxAge: 60,
-// 	directives: ['must-revalidate', 'no-transform']
-// }))

package/src/{clear-site-data.js → headers/clear-site-data.js}

@@ -42,18 +42,12 @@ export class SiteData {
 		if(directives.prerenderCache === true) { result.push(CSD_DIRECTIVE_PRERENDER_CACHE) }
 		if(directives.storage === true) { result.push(CSD_DIRECTIVE_STORAGE) }
 
+		if(result.length === 0) {
+			return undefined
+		}
+
 		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/headers/client-hints.js

@@ -0,0 +1,88 @@
+
+
+export const CLIENT_HINT_USER_AGENT = 'Sec-CH-UA'
+export const CLIENT_HINT_ARCHITECTURE = 'Sec-CH-UA-Arch'
+export const CLIENT_HINT_BITNESS = 'Sec-CH-UA-Bitness'
+export const CLIENT_HINT_FORM_FACTORS = 'Sec-CH-UA-Form-Factors'
+// export const CLIENT_HINT_ = 'Sec-CH-UA-Full-Version'
+export const CLIENT_HINT_VERSION_LIST = 'Sec-CH-UA-Full-Version-List'
+export const CLIENT_HINT_MOBILE = 'Sec-CH-UA-Mobile'
+export const CLIENT_HINT_MODEL = 'Sec-CH-UA-Model'
+export const CLIENT_HINT_PLATFORM = 'Sec-CH-UA-Platform'
+export const CLIENT_HINT_PLATFORM_VERSION = 'Sec-CH-UA-Platform-Version'
+export const CLIENT_HINT_WOW64 = 'Sec-CH-UA-WoW64'
+export const CLIENT_HINT_PREFERS_COLOR_SCHEME = 'Sec-CH-Prefers-Color-Scheme'
+export const CLIENT_HINT_PREFERS_REDUCED_MOTION = 'Sec-CH-Prefers-Reduced-Motion'
+export const CLIENT_HINT_PREFERS_REDUCED_TRANSPARENCY = 'Sec-CH-Prefers-Reduced-Transparency'
+export const CLIENT_HINT_DEVICE_MEMORY = 'Sec-CH-Device-Memory'
+export const CLIENT_HINT_DEVICE_PIXEL_RATIO = 'Sec-CH-DPR'
+export const CLIENT_HINT_VIEWPORT_HEIGHT = 'Sec-CH-Viewport-Height'
+export const CLIENT_HINT_VIEWPORT_WIDTH = 'Sec-CH-Viewport-Width'
+export const CLIENT_HINT_IMAGE_WIDTH = 'Sec-CH-Width'
+export const CLIENT_HINT_DOWNLINK = 'Downlink'
+export const CLIENT_HINT_EFFECTIVE_CONNECTION_TYPE = 'ECT'
+export const CLIENT_HINT_ROUND_TRIP_TIME = 'RTT'
+export const CLIENT_HINT_SAVE_DATA = 'Save-Data'
+export const CLIENT_HINT_GLOBAL_PRIVACY_CONTROL = 'Sec-GPC'
+
+export const KNOWN_CLIENT_HINTS = [
+	CLIENT_HINT_USER_AGENT,
+	CLIENT_HINT_ARCHITECTURE,
+	CLIENT_HINT_BITNESS,
+	CLIENT_HINT_FORM_FACTORS,
+	CLIENT_HINT_VERSION_LIST,
+	CLIENT_HINT_MOBILE,
+	CLIENT_HINT_MODEL,
+	CLIENT_HINT_PLATFORM,
+	CLIENT_HINT_PLATFORM_VERSION,
+	CLIENT_HINT_WOW64,
+	CLIENT_HINT_PREFERS_COLOR_SCHEME,
+	CLIENT_HINT_PREFERS_REDUCED_MOTION,
+	CLIENT_HINT_PREFERS_REDUCED_TRANSPARENCY,
+	CLIENT_HINT_DEVICE_MEMORY,
+	CLIENT_HINT_DEVICE_PIXEL_RATIO,
+	CLIENT_HINT_VIEWPORT_HEIGHT,
+	CLIENT_HINT_VIEWPORT_WIDTH,
+	CLIENT_HINT_IMAGE_WIDTH,
+	CLIENT_HINT_DOWNLINK,
+	CLIENT_HINT_EFFECTIVE_CONNECTION_TYPE,
+	CLIENT_HINT_ROUND_TRIP_TIME,
+	CLIENT_HINT_SAVE_DATA,
+	CLIENT_HINT_GLOBAL_PRIVACY_CONTROL
+]
+
+export const KNOWN_FORM_FACTORS = [
+	'Desktop',
+	'Automotive',
+	'Mobile',
+	'Tablet',
+	'XR',
+	'EInk',
+	'Watch'
+]
+
+export const CLIENT_HINT_TRUE = '?1'
+export const CLIENT_HINT_FALSE = '?0'
+
+
+export class ClientHints {
+
+	/**
+	 * @param {Array<String>} hints
+	 */
+	static encode(hints) {
+		if(hints === undefined) { return undefined }
+		if(!Array.isArray(hints)) { return undefined }
+		if(hints.length === 0) { return undefined }
+
+		const remaining = hints
+			.filter(hint => KNOWN_CLIENT_HINTS.includes(hint))
+
+		if(remaining.length === 0) { return undefined }
+
+		return remaining.join(', ')
+	}
+}
+
+
+