@nxtedition/nxt-undici 7.4.1 → 7.4.3

package/lib/index.d.ts

@@ -55,17 +55,25 @@ export interface LoggerLike {
   info(obj: unknown, msg?: string): void
 }
 
+export type BodyFactoryResult =
+  | Readable
+  | Uint8Array
+  | string
+  | Iterable<unknown>
+  | AsyncIterable<unknown>
+
+/** Called with an options object (not a bare signal); the signal aborts when the
+ *  request is destroyed before the factory resolves. May be async. */
+export type BodyFactory = (opts: {
+  signal: AbortSignal
+}) => BodyFactoryResult | Promise<BodyFactoryResult>
+
 export interface DispatchOptions {
   id?: string | null
   origin?: string | null
   path?: string | null
   method?: string | null
-  body?:
-    | Readable
-    | Uint8Array
-    | string
-    | ((signal: AbortSignal) => Readable | Uint8Array | string | Iterable<unknown>)
-    | null
+  body?: Readable | Uint8Array | string | BodyFactory | null
   query?: Record<string, unknown> | null
   headers?: Record<string, string | string[] | null | undefined> | null
   signal?: AbortSignal | null
@@ -80,8 +88,13 @@ export interface DispatchOptions {
   retry?: RetryOptions | number | boolean | RetryFn | null
   proxy?: ProxyOptions | boolean | null
   cache?: CacheOptions | boolean | null
-  upgrade?: boolean | null
+  /** Protocol to upgrade to (e.g. 'websocket'). undici requires a string and the
+   *  dispatch handler must implement onUpgrade — only meaningful with raw
+   *  dispatch()/compose(); request() has no upgrade support (see RequestOptions). */
+  upgrade?: string | null
   follow?: number | FollowFn | boolean | null
+  /** Alias for `follow`; ignored when `follow` is also set. */
+  redirect?: number | FollowFn | boolean | null
   error?: boolean | null
   verify?: VerifyOptions | boolean | null
   logger?: LoggerLike | null
@@ -121,6 +134,15 @@ export interface ProxyOptions {
 export interface CacheOptions {
   store?: CacheStore
   maxEntrySize?: number
+  /** Upper bound on an entry's freshness lifetime AND retention, in seconds
+   *  (default 30 days). */
+  maxEntryTTL?: number
+  /** Opt-in RFC 9111 §4.2.2 heuristic freshness (10% of time since
+   *  Last-Modified) for 200 responses without explicit expiration. */
+  heuristic?: boolean
+  /** Opt-in fallback freshness lifetime in seconds for 200 responses without
+   *  any expiration information. */
+  defaultTTL?: number
 }
 
 export interface VerifyOptions {
@@ -130,7 +152,16 @@ export interface VerifyOptions {
 
 export interface DnsOptions {
   ttl?: number
+  /** How long (ms) a failed lookup is negative-cached; requests inside this
+   *  window fail fast without hitting the resolver again (default 1000). */
+  negativeTTL?: number
   balance?: 'hash'
+  /** Custom resolver, `dns.lookup`-compatible (called with `{ all: true }`). */
+  lookup?: (
+    hostname: string,
+    options: { all: boolean },
+    callback: (err: Error | null, addresses: { address: string; family: number }[]) => void,
+  ) => void
 }
 
 export interface LogInterceptorOptions {
@@ -221,6 +252,8 @@ export interface CacheValue {
   etag?: string
   vary?: Record<string, string | string[]>
   cachedAt: number
+  /** Optional on set(): omitting it defaults to deleteAt (staleAt === deleteAt). */
+  staleAt?: number
   deleteAt?: number
 }
 
@@ -233,6 +266,7 @@ export interface CacheGetResult {
   cacheControlDirectives?: Record<string, unknown>
   vary?: Record<string, string | string[]>
   cachedAt: number
+  staleAt: number
   deleteAt: number
 }
 
@@ -242,15 +276,22 @@ export interface CacheStore {
     key: CacheKey,
     value: CacheValue & { body: null | Buffer | Buffer[]; start: number; end: number },
   ): void
+  /** RFC 9111 §4.4 invalidation — optional; the cache interceptor
+   *  feature-detects it and skips invalidation when absent. */
+  delete?(key: CacheKey): void
   gc(): void
   clear(): void
   close(): void
 }
 
-export interface RequestOptions extends DispatchOptions {
+/** `upgrade` is omitted: request()'s internal handler has no onUpgrade, so any
+ *  upgrade attempt rejects with InvalidArgumentError — use dispatch() instead. */
+export interface RequestOptions extends Omit<DispatchOptions, 'upgrade'> {
   url?: URLLike | null
   dispatch?: DispatchFn | null
   dispatcher?: Dispatcher | null
+  /** highWaterMark for the response body readable (non-negative number). */
+  highWaterMark?: number | null
 }
 
 export interface ResponseData {
@@ -310,6 +351,8 @@ export class SqliteCacheStore implements CacheStore {
     key: CacheKey,
     value: CacheValue & { body: null | Buffer | Buffer[]; start: number; end: number },
   ): void
+  /** RFC 9111 §4.4: invalidates every stored response for the key's URI. */
+  delete(key: CacheKey): void
   gc(): void
   clear(): void
   close(): void

package/lib/index.js

@@ -29,6 +29,7 @@ export const cache = {
 }
 
 export { parseHeaders } from './utils.js'
+export { SqliteCacheStore } from './sqlite-cache-store.js'
 export { Client, Pool, Agent, getGlobalDispatcher, setGlobalDispatcher } from '@nxtedition/undici'
 
 function defaultLookup(origin, opts, callback) {