Skip to content

Docs parity - global #1368

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TartanLlama merged 2 commits into from
Mar 24, 2026
Merged

Docs parity - global #1368

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0f60931
TSDoc update for global
case-fastly Mar 12, 2026
f494615
Merge branch 'main' into docs-parity-global
TartanLlama Mar 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 151 additions & 12 deletions types/globals.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -289,9 +289,18 @@ declare class Backend {
* A Fastly Compute specific implementation of [FetchEvent](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent/FetchEvent).
* @group DOM Events
*/
/**
* The event type for `fetch` events dispatched to a Fastly Compute service.
*
* Contains information about the incoming request, the downstream client, and
* the server. Use {@link FetchEvent.respondWith | respondWith} to send a
* response back to the client.
*
* @group DOM Events
*/
declare interface FetchEvent {
/**
* Information about the downstream client that made the request
* Information about the downstream client that made the request.
*/
readonly client: ClientInfo;

Expand Down Expand Up @@ -328,9 +337,23 @@ declare interface FetchEvent {
respondWith(response: Response | PromiseLike<Response>): void;

/**
* Send a 103 Early Hints response back to the client.
* Send a [103 Early Hints](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/103)
* response back to the client.
*
* Must be called before {@link FetchEvent.respondWith | respondWith}.
*
* @example
* ```js
* event.sendEarlyHints({ link: "</style.css>; rel=preload; as=style" });
*
* event.sendEarlyHints([
* ["link", "</style.css>; rel=preload; as=style"],
* ["link", "</script.js>; rel=preload; as=script"],
* ]);
* ```
*
* @param headers - Headers to send back down to the client
* @param headers Headers to send back down to the client.
* @version 3.36.0
*/
sendEarlyHints(headers: HeadersInit): void;

Expand All @@ -343,7 +366,10 @@ declare interface FetchEvent {
* completed, such as sending telemetry data to a separate backend after the response has
* been sent.
*
* @param promise - The `Promise` to wait for
* Must be initially called synchronously within the event callback, but after that it
* can be called multiple times.
*
* @param promise The `Promise` to wait for.
*/
waitUntil(promise: Promise<any>): void;
}
Expand Down Expand Up @@ -428,21 +454,64 @@ declare var CacheOverride: {
*/
declare interface ClientInfo {
/**
* A string representation of the IPv4 or IPv6 address of the downstream client.
*
* While always defined on Fastly compute, on environments where these fields are unavailable,
* such as Viceroy, these fields may return *null*.
* A UUID generated by Fastly Compute for each request.
* @version 3.40.1
*/
readonly requestId: string;
/**
* A string representation of the IPv4 or IPv6 address of the downstream client.
*/
readonly address: string;
/**
* Geolocation data for the client IP address, or `null` if unavailable.
*/
readonly geo: import('fastly:geolocation').Geolocation | null;
/**
* The JA3 hash of the TLS ClientHello message, or `null` if unavailable.
* @version 3.2.1
*/
readonly tlsJA3MD5: string | null;
/**
* The JA4 fingerprint of the TLS ClientHello message, or `null` if unavailable.
* @version 3.37.0
*/
readonly tlsJA4: string | null;
/**
* The HTTP/2 fingerprint for HTTP/2 connections, or `null` for HTTP/1.1
* connections or when unavailable.
* @version 3.37.0
*/
readonly h2Fingerprint: string | null;
/**
* The Original Header fingerprint based on the order and presence of request
* headers, or `null` if unavailable.
* @version 3.37.0
*/
readonly ohFingerprint: string | null;
/**
* The cipher suite used to secure the client TLS connection, or `null` if
* unavailable.
* @version 3.2.1
*/
readonly tlsCipherOpensslName: string | null;
/**
* The TLS protocol version used to secure the client TLS connection, or
* `null` if unavailable.
* @version 3.2.1
*/
readonly tlsProtocol: string | null;
/**
* The raw client certificate from the mutual TLS handshake in PEM format,
* or `null` if unavailable. Returns an empty `ArrayBuffer` if the connection
* is not mTLS.
* @version 3.2.1
*/
readonly tlsClientCertificate: ArrayBuffer | null;
/**
* The raw bytes sent by the client in the TLS ClientHello message, or
* `null` if unavailable.
* @version 3.2.1
*/
readonly tlsClientHello: ArrayBuffer | null;
}

Expand Down Expand Up @@ -1032,7 +1101,7 @@ declare var fastly: Fastly;
* ```js
* async function app(event) {
* const req = event.request;
* const backendResponse = await fetch("https://httpbin.org/html", { backend: "origin_0" });
* const backendResponse = await fetch("https://httpbin.org/html", { backend: "my-backend" });
* if (!backendResponse.body) {
* return backendResponse;
* }
Expand Down Expand Up @@ -1332,15 +1401,28 @@ declare interface RequestInit {

/** The Fastly configured backend name or instance the request should be sent to. */
backend?: string | import('fastly:backend').Backend;
/** Fastly-specific cache override configuration for this request. */
cacheOverride?:
| import('fastly:cache-override').CacheOverride
| import('fastly:cache-override').ICacheOverride
| Exclude<import('fastly:cache-override').CacheOverrideMode, 'override'>;
/** Fastly-specific cache key override for this request. */
cacheKey?: string;
/** Fastly-specific options. */
fastly?: {
/** Whether to automatically gzip decompress the response. */
decompressGzip?: boolean;
};
/**
* Controls how framing headers (`Content-Length`, `Transfer-Encoding`) are
* determined. When `true`, any provided framing headers will be honored
* instead of being automatically set based on the body.
*/
manualFramingHeaders?: boolean;
/**
* Fastly Image Optimizer transformation options to apply to the response.
* @version 3.36.0
*/
imageOptimizerOptions?: import('fastly:image-optimizer').ImageOptimizerOptions;
}

Expand Down Expand Up @@ -1384,13 +1466,32 @@ interface Request extends Body {
clone(): Request;

/**
* The request backend, null for the downstream request itself
* The backend this request was sent to, or `undefined` for the downstream
* request itself.
*/
readonly backend: import('fastly:backend').Backend | undefined;
/**
* Set the cache override for this request.
*
* @param override The cache override configuration to apply.
*/
setCacheOverride(
override: import('fastly:cache-override').CacheOverride,
): void;
/**
* Set a custom cache key for this request.
*
* @param key The cache key to use.
*/
setCacheKey(key: string): void;
/**
* Controls how framing headers (`Content-Length`, `Transfer-Encoding`) are
* determined. In "manual" mode, any provided framing headers will be
* honored. In "automatic" mode (the default), they are set based on the
* body.
*
* @param manual Whether to use manual mode for framing headers.
*/
setManualFramingHeaders(manual: boolean): void;

/**
Expand All @@ -1401,6 +1502,7 @@ interface Request extends Body {
* this function.
*
* This function always returns undefined on hosts not supporting the HTTP Cache API (i.e. Viceroy)
* @version 3.30.0
*/
readonly isCacheable: boolean | undefined;
}
Expand All @@ -1422,6 +1524,11 @@ declare interface ResponseInit {
headers?: HeadersInit;
status?: number;
statusText?: string;
/**
* Controls how framing headers (`Content-Length`, `Transfer-Encoding`) are
* determined. When `true`, any provided framing headers will be honored
* instead of being automatically set based on the body.
*/
manualFramingHeaders?: boolean;
}

Expand All @@ -1437,7 +1544,7 @@ interface Response extends Body {
/**
* The response headers.
*
* May be modified event for upstream responses prior to storage in the cache.
* May be modified even for upstream responses prior to storage in the cache.
*/
readonly headers: Headers;
readonly ok: boolean;
Expand All @@ -1464,9 +1571,18 @@ interface Response extends Body {
*/
readonly port: number | undefined;
// clone(): Response;
/**
* Controls how framing headers (`Content-Length`, `Transfer-Encoding`) are
* determined. In "manual" mode, any provided framing headers will be
* honored. In "automatic" mode (the default), they are set based on the
* body.
*
* @param manual Whether to use manual mode for framing headers.
*/
setManualFramingHeaders(manual: boolean): void;
/**
* The response backend, if an upstream response
* The backend this response was received from, or `undefined` for
* user-created responses.
*/
readonly backend: import('fastly:backend').Backend | undefined;
/**
Expand All @@ -1475,12 +1591,14 @@ interface Response extends Body {
* (that awaited that response) will show as hits.
*
* Undefined if the environment does not support the new HTTP Cache hostcalls.
* @version 3.30.0
*/
readonly cached: boolean | undefined;
/**
* Fastly-specific property - Returns whether the cached `Response` is considered stale.
*
* Undefined if the environment does not support the new HTTP Cache hostcalls.
* @version 3.30.0
*/
readonly stale: boolean | undefined;
/**
Expand All @@ -1490,30 +1608,35 @@ interface Response extends Body {
* after it is inserted into the cache.
*
* Undefined if the response is not cached or the environment does not support the HTTP Cache hostcalls. May be modified prior to injection into the cache.
* @version 3.30.0
*/
ttl: number | undefined;
/**
* Fastly-specific property - The current age of the response in seconds, if it is cached.
*
* Undefined if the response is not cached or the environment does not support the HTTP Cache hostcalls. May be modified prior to injection into the cache.
* @version 3.30.0
*/
readonly age: number | undefined;
/**
* Fastly-specific property - The time in seconds for which the response can safely be used despite being considered stale, if it is cached.
*
* Undefined if the response is not cached or the environment does not support the HTTP Cache hostcalls. May be modified prior to injection into the cache.
* @version 3.30.0
*/
swr: number | undefined;
/**
* Fastly-specific property - The set of request headers for which the response may vary.
*
* Undefined if the response is not cached or the environment does not support the HTTP Cache hostcalls. May be modified prior to injection into the cache.
* @version 3.30.0
*/
vary: Array<string> | undefined;
/**
* Fastly-specific property - The surrogate keys for the cached response.
*
* Undefined if the response is not cached or the environment does not support the HTTP Cache hostcalls. May be modified prior to injection into the cache.
* @version 3.30.0
*/
surrogateKeys: Array<string> | undefined;
/**
Expand All @@ -1523,6 +1646,7 @@ interface Response extends Body {
* for details.
*
* Undefined if the response is not cached or the environment does not support the HTTP Cache hostcalls. May be modified prior to injection into the cache.
* @version 3.30.0
*/
pci: boolean | undefined;
}
Expand Down Expand Up @@ -2095,18 +2219,33 @@ type Transferable = ArrayBuffer;
// type Transferable = ArrayBuffer | MessagePort | ImageBitmap;

/**
* The absolute location of the script executed by the Worker.
*
* Available via the global {@link location} property.
*
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/WorkerLocation | WorkerLocation on MDN}
* @group Web APIs
*/
interface WorkerLocation {
/** The fragment identifier (`#` followed by the fragment) of the worker's URL. */
readonly hash: string;
/** The host (hostname and port) of the worker's URL. */
readonly host: string;
/** The hostname of the worker's URL. */
readonly hostname: string;
/** The serialized URL of the worker's location. */
readonly href: string;
/** Returns the serialized URL. Synonym for {@link WorkerLocation.href}. */
toString(): string;
/** The origin of the worker's URL. */
readonly origin: string;
/** The pathname of the worker's URL. */
readonly pathname: string;
/** The port of the worker's URL. */
readonly port: string;
/** The protocol scheme of the worker's URL. */
readonly protocol: string;
/** The query string (`?` followed by parameters) of the worker's URL. */
readonly search: string;
}

Expand Down
Loading