stash: i hate ts

Author: gamemaker1

source/api.ts

@@ -4,7 +4,7 @@
 import type {
 	ResponseObject,
 	HeadersObject,
-	RateLimitInfo,
+	ParsedRateLimit,
 	ParserOptions,
 } from './types'
 import { getHeaderObject, getNonStandardHeaders } from './headers.js'
@@ -18,12 +18,12 @@ import { rateLimitSorter } from './utilities.js'
  * @param input {ResponseObject | HeadersObject} - The node/fetch-style response/headers object.
  * @param passedOptions {Partial<ParserOptions> | undefined} - The configuration for the parser.
  *
- * @returns {RateLimitInfo | undefined} - The rate limit information parsed from the headers.
+ * @returns {ParsedRateLimit | undefined} - The rate limit information parsed from the headers.
  */
 export const getRateLimit = (
 	input: ResponseObject | HeadersObject,
 	passedOptions?: Partial<ParserOptions>,
-): RateLimitInfo | undefined => {
+): ParsedRateLimit | undefined => {
 	const rateLimits = getRateLimits(input, passedOptions)
 	return rateLimits.length === 0 ? undefined : rateLimits[0]
 }
@@ -35,12 +35,12 @@ export const getRateLimit = (
  * @param input {ResponseObject | HeadersObject} - The node/fetch-style response/headers object.
  * @param passedOptions {Partial<ParserOptions> | undefined} - The configuration for the parser.
  *
- * @returns {RateLimitInfo[]} - The rate limit information parsed from the headers.
+ * @returns {ParsedRateLimit[]} - The rate limit information parsed from the headers.
  */
 export const getRateLimits = (
 	input: ResponseObject | HeadersObject,
 	passedOptions?: Partial<ParserOptions>,
-): RateLimitInfo[] => {
+): ParsedRateLimit[] => {
 	// Default to no configuration, and get the headers object from the input.
 	const options = passedOptions ?? {}
 	const headers = getHeaderObject(input)

source/parsers/ietf-draft.ts

@@ -1,103 +1,238 @@
 // /source/parser/ietf-draft.ts
-// The parser for headers following the IETF draft specification (v6+).
+// The parser for headers following the IETF draft specification (v7+).
 
 import { parseList, parseDictionary as parseDict } from 'structured-headers'
-import type { RateLimitInfo, HeadersObject, ParserOptions } from '../types'
+import type {
+	ParsedRateLimit,
+	RateLimitPolicy,
+	HeadersObject,
+	ParserOptions,
+} from '../types'
 import { getHeader } from '../headers.js'
+import { toIntOrUndefined, constructParsedRateLimit } from '../utilities.js'
 import { parse as parseResetTime } from './reset.js'
 
+type QuotaUnit = RateLimitPolicy['quota']['unit']
+
+// Utility type for the parsed structured header policy.
+type ParsedValue = string | number | undefined
+type ParsedParameters = Map<string, ParsedValue[]>
+type ParsedHeaderPolicy = {
+	value: string | number
+	params: ParsedParameters
+}
+
+// Utility type for the parsed structured header entries.
+type ParsedDraft7Header = ParsedParameters
+type ParsedDraft8Header = Array<[string, ParsedParameters]>
+
 /**
- * Parses standard headers as per the IETF draft specification.
+ * Attempts to parse header using the 7th draft of the specification.
  *
- * @param headers {HeadersObject} - The object containing headers to parse.
+ * @param header {string} - The `RateLimit` header's contents.
  * @param options {Partial<ParserOptions>} - The parser's configuration.
- * @param prefix {string} - The vendor-specific prefix that each header contains.
  *
- * @returns {RateLimitInfo | undefined} - The normalized rate limit information, if any header is found.
+ * @returns {ParsedDraft7Header | undefined} - The parsed header, if the contents are valid.
  */
-export const parse = (
-	headers: HeadersObject,
+const tryParsingDraft7 = (
+	header: string,
 	options: Partial<ParserOptions>,
-): RateLimitInfo[] => {
-	const header = getHeader(headers, 'ratelimit')
-	const policyHeader = getHeader(headers, 'ratelimit-policy')
+): ParsedDraft7Header | undefined => {
+	try {
+		return parseDict(header) as ParsedDraft7Header
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Attempts to parse header using the 8th draft of the specification.
+ *
+ * @param header {string} - The `RateLimit` header's contents.
+ * @param options {Partial<ParserOptions>} - The parser's configuration.
+ *
+ * @returns {ParsedDraft8Header | undefined} - The parsed header, if the contents are valid.
+ */
+const tryParsingDraft8 = (
+	header: string,
+	options: Partial<ParserOptions>,
+): ParsedDraft8Header | undefined => {
+	try {
+		return parseList(header) as ParsedDraft8Header
+	} catch {
+		return undefined
+	}
+}
 
-	// The rate limit information is provided in a manner similar to non-standard
-	// headers according to the 6th draft, so we do not need to handle it here
-	// separately.
+/**
+ * Attempts to parse policies from the `RateLimit-Policy` header for either the
+ * 7th or 8th draft of the spec.
+ *
+ * @param header {string} - The `RateLimit-Policy` header's contents.
+ *
+ * @returns {ParsedHeaderPolicy[]} - The list of policies specified in the header.
+ */
+function parsePolicies(header?: string): ParsedHeaderPolicy[] {
+	if (!header) return []
 
-	// The value of the `RateLimit` header in the 7th draft is a dictionary, while
-	// in the 8th draft, it is a list.
-	let draft7, draft8
 	try {
-		draft7 = parseDict(header)
+		return parseList(header).map((policy) => ({
+			value: policy[0],
+			params: policy[1],
+		})) as ParsedHeaderPolicy[]
 	} catch {
-		try {
-			draft8 = parseList(header)
-		} catch (error) {
-			if (options?.strict)
-				throw Error(
-					`Failed to parse 'RateLimit' header as per IETF standard drafts: ${error.message}`,
-				)
-		}
+		return []
 	}
+}
 
-	const rateLimits = []
-	const policies =
-		policyHeader !== undefined
-			? parseList(policyHeader).map((policy) => {
-					return {
-						value: policy[0],
-						params: policy[1],
-					}
-			  })
-			: []
-
-	if (draft7 !== undefined) {
-		const limit = draft7.get('limit')[0]
-		const info = {
-			used: limit - draft7.get('remaining')[0],
-			remaining: draft7.get('remaining')[0],
-			reset: draft7.get('reset')[0],
+/**
+ * Processes rate limit information from the header as per the 7th draft.
+ *
+ * @param draft7 {ParsedDraft7Header} - The parsed `RateLimit` structured header.
+ * @param policies {ParsedHeaderPolicy[]} - The parsed `RateLimit-Policy` structured header.
+ * @param options {Partial<ParserOptions>} - The parser's configuration.
+ *
+ * @return {ParsedRateLimit[]} - The parsed rate limit information.
+ */
+function processDraft7Limits(
+	draft7: ParsedDraft7Header,
+	policies: ParsedHeaderPolicy[],
+	options: Partial<ParserOptions>,
+): ParsedRateLimit[] {
+	const limit = toIntOrUndefined(draft7.get('limit')?.[0])
+	const remaining = toIntOrUndefined(draft7.get('remaining')?.[0])
+	const reset = parseResetTime(draft7.get('reset')?.[0] as ParsedValue, options)
+	const info = { limit, remaining, reset }
+
+	// Make sure limit exists in strict mode, since it is required by the draft.
+	if (limit === undefined && options?.strict) {
+		throw new Error(
+			`Failed to parse 'RateLimit' header: 'limit' is not a number.`,
+		)
+	}
+
+	// If no policies exist, create a single rate limit with the policy straight
+	// from the `RateLimit` header.
+	if (policies.length === 0 && limit !== undefined) {
+		return [constructParsedRateLimit({ info })]
+	}
+
+	// Map policies to rate limits
+	return policies.map((parsedPolicy) => {
+		const policy = {
+			quota: {
+				value: parsedPolicy.value as number,
+				unit: 'requests' as QuotaUnit,
+			},
+			window: toIntOrUndefined(parsedPolicy.params.get('w')),
 		}
 
-		for (const policy of policies)
-			rateLimits.push({
-				info: limit === policy.value ? info : undefined,
-				policy: {
-					quota: { value: policy.value, unit: 'requests' },
-					window: policy.params.get('w'),
+		return constructParsedRateLimit({
+			info: limit === parsedPolicy.value ? info : undefined,
+			policy,
+		})
+	})
+}
+
+/**
+ * Processes rate limit information from the header as per the 8th draft.
+ *
+ * @param draft8 {ParsedDraft8Header} - The parsed `RateLimit` structured header.
+ * @param policies {ParsedHeaderPolicy[]} - The parsed `RateLimit-Policy` structured header.
+ * @param options {Partial<ParserOptions>} - The parser's configuration.
+ *
+ * @return {ParsedRateLimit[]} - The parsed rate limit information.
+ */
+function processDraft8Limits(
+	draft8: ParsedDraft8Header,
+	policies: ParsedHeaderPolicy[],
+	options: Partial<ParserOptions>,
+): ParsedRateLimit[] {
+	// If no policies exist, create rate limits and their policies directly from
+	// the `RateLimit` header.
+	if (policies.length === 0) {
+		return draft8.map(([name, parameters]) => {
+			// There is no `q` in the draft, but if there is no policy header, maybe
+			// the server has sent it along with the `RateLimit` header? If not,
+			// default to the value of `remaining` as the limit.
+			const limit = toIntOrUndefined(parameters.get('q') ?? parameters.get('r'))
+			const remaining = toIntOrUndefined(parameters.get('r'))
+			const reset = parseResetTime(parameters.get('t') as ParsedValue, options)
+
+			const info = { limit, remaining, reset }
+			const policy = {
+				name,
+				quota: {
+					value: limit,
+					unit: 'requests' as QuotaUnit,
 				},
-			})
+			}
+
+			return constructParsedRateLimit({ info, policy })
+		})
 	}
 
-	if (draft8 !== undefined) {
-		for (const header of draft8) {
-			const name = header[0]
-			const info = {
-				remaining: header[1].get('r'),
-				reset: parseResetTime(header[1].get('t'), options),
-			}
+	// If an accompanying policy header was found, map each policy to the
+	// corresponding info.
+	return draft8.flatMap(([name, headerParameters]) => {
+		const reset = parseResetTime(
+			headerParameters.get('t') as ParsedValue,
+			options,
+		)
+
+		return policies.map(({ value, params: policyParameters }) => {
+			// Give precedence to the value of partition key in the `RateLimit` header
+			// over the `RateLimit-Policy` header, even though the both should be same.
+			const partition = (headerParameters.get('pk')?.value ??
+				policyParameters.get('pk')?.value) as string | undefined
+			const remaining = toIntOrUndefined(headerParameters.get('r'))
+			const window = toIntOrUndefined(policyParameters.get('w'))
+			const limit = toIntOrUndefined(policyParameters.get('q'))
+			const unit = (policyParameters.get('qu') ?? 'requests') as QuotaUnit
 
-			for (const policy of policies) {
-				const params = policy.params
-				info.used = policy.params.get('q') - info.remaining
-
-				rateLimits.push({
-					info: name === policy.value ? info : undefined,
-					policy: {
-						name,
-						quota: {
-							value: params.get('q'),
-							unit: params.get('qu') ?? 'requests',
-						},
-						window: params.get('w'),
-						partition: header[1].get('pk')?.value ?? params.get('pk')?.value,
-					},
-				})
+			const info = { limit, remaining, reset }
+			const policy = {
+				name,
+				quota: {
+					value: limit,
+					unit,
+				},
+				window,
+				partition,
 			}
-		}
-	}
 
-	return rateLimits
+			return constructParsedRateLimit({ info, policy })
+		})
+	})
+}
+
+/**
+ * Parses standard headers as per the IETF draft specification.
+ *
+ * @param headers - The object containing headers to parse.
+ * @param options - The parser's configuration.
+ * @returns An array of parsed rate limit information.
+ */
+export const parse = (
+	headers: HeadersObject,
+	options: Partial<ParserOptions> = {},
+): ParsedRateLimit[] => {
+	const header = getHeader(headers, 'ratelimit')
+	const policyHeader = getHeader(headers, 'ratelimit-policy')
+
+	// If no rate limit header is present, return an empty array.
+	if (!header) return []
+
+	// Attempt to parse headers with different draft specifications.
+	const draft7 = tryParsingDraft7(header, options)
+	const draft8 = tryParsingDraft8(header, options)
+
+	// Parse policies if the policy header exists.
+	const policies = parsePolicies(policyHeader)
+
+	// Combine the parsed rate limits with the corresponding policies.
+	return [
+		...(draft7 ? processDraft7Limits(draft7, policies, options) : []),
+		...(draft8 ? processDraft8Limits(draft8, policies, options) : []),
+	]
 }

source/parsers/non-standard.ts

@@ -3,10 +3,10 @@
 
 // @ts-expect-error no type definitions
 import { parseItem } from 'structured-headers'
-import { parse as parseResetTime } from './reset.js'
-import type { HeadersObject, RateLimitInfo, ParserOptions } from '../types'
+import type { HeadersObject, ParsedRateLimit, ParserOptions } from '../types'
 import { getHeader } from '../headers.js'
 import { toInt } from '../utilities.js'
+import { parse as parseResetTime } from './reset.js'
 
 /**
  * Parses non standard headers as per their documentation.
@@ -15,13 +15,13 @@ import { toInt } from '../utilities.js'
  * @param options {Partial<ParserOptions>} - The parser's configuration.
  * @param prefix {string} - The vendor-specific prefix that each header contains.
  *
- * @returns {RateLimitInfo | undefined} - The normalized rate limit information, if any header is found.
+ * @returns {ParsedRateLimit | undefined} - The normalized rate limit information, if any header is found.
  */
 export const parse = (
 	headers: HeadersObject,
 	options: Partial<ParserOptions>,
 	prefix: string,
-): RateLimitInfo | undefined => {
+): ParsedRateLimit | undefined => {
 	// Note that `||` is valid in the following lines because used should always
 	// be at least 1, and `||` handles NaN correctly, whereas `??` doesn't.
 	/* eslint-disable @typescript-eslint/prefer-nullish-coalescing */