@zerotal/core 1.9.0 → 1.11.0

package/src/health/Health.ts

@@ -149,20 +149,20 @@ export const Health = new HealthRegistry();
 /** The health config, authored under the `health` key of `config/app.ts`. */
 export interface HealthConfigShape {
   /** Serve the endpoint. Default: on outside production, off in production. */
-  enabled?: boolean;
+  enabled?: boolean | undefined;
   /** Route path. Default: `/health`. */
-  path?: string;
+  path?: string | undefined;
   /** Shared secret. Required in production; supplied via `?key=` or `X-Health-Key`. */
-  secret?: string;
+  secret?: string | undefined;
   /** Include per-check details. Set false for a bare `{ status }` body. Default: true. */
-  showDetails?: boolean;
+  showDetails?: boolean | undefined;
 }
 
 /** The health config after defaults and back-compat have been applied. */
 export interface ResolvedHealthConfig {
   enabled: boolean;
   path: string;
-  secret?: string;
+  secret?: string | undefined;
   showDetails: boolean;
 }
 

package/src/helpers/index.ts

@@ -298,5 +298,6 @@ export { markdownPage, type BunMarkdownOptions } from "./markdown.ts";
 // must not carry private copies.
 export { escapeHtml } from "./html.ts";
 export { pluralize, singularize, tableNameFor } from "../support/str.ts";
-export { deepMerge } from "../support/deepMerge.ts";
+export { deepMerge, definedOnly } from "../support/deepMerge.ts";
+export type { Resolved } from "../support/deepMerge.ts";
 export { parseCookieHeader } from "../support/cookie.ts";

package/src/helpers/markdown.ts

@@ -49,6 +49,13 @@ ${body}
  * Options for `Bun.markdown.html()`. bun-types exposes the options type only inside
  * its `markdown` namespace; this is the named, exported equivalent the framework uses.
  *
+ * Its optional properties stay `?: T` rather than `?: T | undefined`, unlike the
+ * framework's own option shapes. This one is not an option shape, it is a *mirror* of
+ * somebody else's signature, and a mirror that is wider than what it reflects stops
+ * being assignable to it — the value built here is handed straight to
+ * `Bun.markdown.html()`.
+ *
+ * @exact-optional-ignore
  * @internal
  */
 export interface BunMarkdownOptions {

package/src/http/UploadedFile.ts

@@ -19,9 +19,9 @@ export type StorageDisk = Pick<StorageDriver, "url"> & {
  */
 export interface FileValidationOptions {
   /** Maximum allowed size in bytes. */
-  maxSize?: number;
+  maxSize?: number | undefined;
   /** Allowed MIME types — e.g. `['image/jpeg', 'image/png', 'application/pdf']`. */
-  mimes?: string[];
+  mimes?: string[] | undefined;
 }
 
 /**

package/src/index.ts

@@ -162,7 +162,8 @@ export {
 export { config } from "./helpers/config.ts";
 export { pluralize, singularize, snakeCase, camelCase, tableNameFor } from "./support/str.ts";
 export { deepMerge } from "./support/deepMerge.ts";
-export type { DeepPartial } from "./support/deepMerge.ts";
+// `definedOnly` is a helper, not kernel surface — it lives on `@zerotal/core/helpers`.
+export type { DeepPartial, Resolved } from "./support/deepMerge.ts";
 // The type every class-keyed registry uses — a class rather than an instance.
 export type { ClassRef } from "./support/classRef.ts";
 export { safeEqual, sha256Hex, hmacHex } from "./support/crypto.ts";

package/src/lock/LockManager.ts

@@ -17,13 +17,13 @@ export interface RefreshOptions {
    * question nobody can answer — and becomes "how long after a crash before
    * someone else may take over", which is a decision rather than a guess.
    */
-  refresh?: boolean;
+  refresh?: boolean | undefined;
 
   /**
    * Seconds between refreshes. Defaults to a third of the TTL, so two
    * consecutive failures still leave a full attempt before the lock lapses.
    */
-  refreshEvery?: number;
+  refreshEvery?: number | undefined;
 }
 
 /**
@@ -44,13 +44,13 @@ export interface BlockOptions extends RefreshOptions {
    * Maximum seconds to wait for the lock before throwing.
    * Defaults to the lock TTL.
    */
-  timeout?: number;
+  timeout?: number | undefined;
 
   /**
    * Milliseconds between polling attempts while waiting.
    * Default: 100 ms.
    */
-  retryDelay?: number;
+  retryDelay?: number | undefined;
 }
 
 /**

package/src/logger/LoggerMiddleware.ts

@@ -42,7 +42,7 @@ const LINE_WIDTH = 60;
 
 export interface LoggerOptions {
   /** Output format. Defaults to LOG_FORMAT env var, then 'text'. */
-  format?: "text" | "json";
+  format?: "text" | "json" | undefined;
 }
 
 /**

package/src/logger/types.ts

@@ -186,11 +186,11 @@ export interface LoggingConfigShape {
   /**
    * The terminal sink, on unless `false`. See {@link ConsoleSinkConfig}.
    */
-  console?: ConsoleSinkConfig;
+  console?: ConsoleSinkConfig | undefined;
   /**
    * The durable file trail, on unless `false`. See {@link FileSinkConfig}.
    */
-  file?: FileSinkConfig;
+  file?: FileSinkConfig | undefined;
   /** Name of the channel used by unqualified `Log.*` calls. */
   default: string;
   /**
@@ -203,10 +203,10 @@ export interface LoggingConfigShape {
    */
   channels: Record<string, ChannelConfig>;
   /** Threshold, in ms, above which ORM queries are logged as slow (default 1000). */
-  slowQueryMs?: number;
+  slowQueryMs?: number | undefined;
   /**
    * Log every HTTP request (method, path, status, duration) via `LoggerMiddleware`.
    * On by default; set `false` to silence the per-request access log.
    */
-  requests?: boolean;
+  requests?: boolean | undefined;
 }

package/src/middleware/CorsMiddleware.ts

@@ -26,17 +26,17 @@ export interface CorsOptions {
    * `new URL(o).hostname.endsWith('.example.com') && o.startsWith('https://')`, or just
    * list the origins.
    */
-  origin?: string | string[] | ((origin: string) => boolean);
+  origin?: string | string[] | ((origin: string) => boolean) | undefined;
   /** Allowed HTTP methods. Default: `['GET','POST','PUT','PATCH','DELETE','OPTIONS']`. */
-  methods?: string[];
+  methods?: string[] | undefined;
   /** Allowed request headers. Default: `['Content-Type','Authorization','X-Requested-With']`. */
-  allowedHeaders?: string[];
+  allowedHeaders?: string[] | undefined;
   /** Headers the browser may expose to JS. Default: `[]`. */
-  exposedHeaders?: string[];
+  exposedHeaders?: string[] | undefined;
   /** Allow cookies / auth headers in cross-origin requests. Default: `false`. */
-  credentials?: boolean;
+  credentials?: boolean | undefined;
   /** Preflight cache duration in seconds. Default: `600`. */
-  maxAge?: number;
+  maxAge?: number | undefined;
 }
 
 /**

package/src/middleware/RateLimiter.ts

@@ -4,7 +4,7 @@
  * later attached to routes or checked manually as `ThrottleMiddleware`.
  */
 import type { HttpContext } from "../pipeline/HttpContext.ts";
-import { ThrottleMiddleware } from "./ThrottleMiddleware.ts";
+import { ThrottleMiddleware, _clientIp, _markIpDerived } from "./ThrottleMiddleware.ts";
 import type { ThrottleOptions } from "./ThrottleMiddleware.ts";
 
 /**
@@ -14,7 +14,19 @@ import type { ThrottleOptions } from "./ThrottleMiddleware.ts";
 export class LimiterDefinition {
   private _max = 60;
   private _window = 60;
-  private _keyFn?: (ctx: HttpContext) => string;
+  private _trustedProxies?: number;
+
+  /**
+   * How this limiter keys its buckets, recorded rather than resolved.
+   *
+   * The built-in strategies all fall back to the client address, and resolving that
+   * needs `trustedProxies` — which the fluent API may not have been told yet when
+   * `.byIp()` runs. Keeping the *decision* here and building the resolver in
+   * {@link toMiddlewareClass} means `.byIp().trustedProxies(1)` and
+   * `.trustedProxies(1).byIp()` mean the same thing, which is the only defensible
+   * answer for a builder.
+   */
+  private _key: KeyStrategy = { kind: "default" };
 
   constructor(private readonly _name: string) {}
 
@@ -30,9 +42,33 @@ export class LimiterDefinition {
     return this;
   }
 
-  /** Custom key resolver — defaults to client IP. */
+  /**
+   * Number of trusted reverse proxies in front of this server.
+   *
+   * Needed by every strategy that can fall back to the client address, which is all
+   * the built-in ones. Without it the address used is the socket's — the *proxy's*,
+   * behind a reverse proxy, so every visitor shares one bucket and the limiter
+   * inverts into the thing it was installed to prevent.
+   *
+   * @param count - How many proxies sit in front; see {@link ThrottleOptions.trustedProxies}.
+   *
+   * @example
+   * RateLimiter.for("login").limit(5).every(60).trustedProxies(1).register();
+   */
+  trustedProxies(count: number): this {
+    this._trustedProxies = count;
+    return this;
+  }
+
+  /**
+   * Custom key resolver — defaults to client IP.
+   *
+   * Whatever this returns is the bucket. If it derives from the client address,
+   * resolve that with `ctx.ip()` plus your own proxy handling, or prefer
+   * {@link byIp}, which honours {@link trustedProxies} for you.
+   */
   by(fn: (ctx: HttpContext) => string): this {
-    this._keyFn = fn;
+    this._key = { kind: "custom", fn };
     return this;
   }
 
@@ -45,10 +81,7 @@ export class LimiterDefinition {
    * RateLimiter.for('api').limit(1000).every(3600).byUser().register();
    */
   byUser(): this {
-    this._keyFn = (ctx) => {
-      const user = (ctx as unknown as Record<string, unknown>).user as { id?: number } | undefined;
-      return user?.id !== undefined ? `user:${user.id}` : `ip:${_resolveIp(ctx)}`;
-    };
+    this._key = { kind: "user" };
     return this;
   }
 
@@ -60,10 +93,7 @@ export class LimiterDefinition {
    * RateLimiter.for('api').limit(500).every(60).byApiKey('x-api-key').register();
    */
   byApiKey(header = "x-api-key"): this {
-    this._keyFn = (ctx) => {
-      const key = ctx.header(header);
-      return key ? `apikey:${key}` : `ip:${_resolveIp(ctx)}`;
-    };
+    this._key = { kind: "apiKey", header };
     return this;
   }
 
@@ -73,7 +103,7 @@ export class LimiterDefinition {
    * through the fluent API.
    */
   byIp(): this {
-    this._keyFn = (ctx) => `ip:${_resolveIp(ctx)}`;
+    this._key = { kind: "ip" };
     return this;
   }
 
@@ -97,7 +127,12 @@ export class LimiterDefinition {
       maxAttempts: this._max,
       windowSeconds: this._window,
     };
-    if (this._keyFn) options.keyResolver = this._keyFn;
+    if (this._trustedProxies !== undefined) options.trustedProxies = this._trustedProxies;
+
+    // `default` deliberately sets no resolver: ThrottleMiddleware's own is already
+    // proxy-aware, and every resolver set here has to be too.
+    const resolver = _resolverFor(this._key, this._trustedProxies);
+    if (resolver) options.keyResolver = resolver;
     return ThrottleMiddleware.with(options);
   }
 
@@ -114,14 +149,62 @@ export class LimiterDefinition {
   }
 }
 
-/** Resolve the best available client IP from the context. */
-function _resolveIp(ctx: HttpContext): string {
-  return (
-    ctx.ip() ??
-    ctx.header("x-forwarded-for")?.split(",")[0]?.trim() ??
-    ctx.header("x-real-ip") ??
-    "unknown"
-  );
+/** How a limiter decides which bucket a request belongs to. */
+type KeyStrategy =
+  | { kind: "default" }
+  | { kind: "ip" }
+  | { kind: "user" }
+  | { kind: "apiKey"; header: string }
+  | { kind: "custom"; fn: (ctx: HttpContext) => string };
+
+/**
+ * Build the key resolver for a strategy, or `undefined` to let `ThrottleMiddleware`
+ * use its own.
+ *
+ * Every branch that can end up keying on an address goes through `_clientIp` with the
+ * proxy count, and is marked so `zt doctor` still audits it. The previous versions
+ * used a private helper that read the socket address and fell back to the *leftmost*
+ * `X-Forwarded-For` entry with no proxy count at all — so behind a reverse proxy
+ * every visitor keyed on the proxy's own address and shared a single bucket. A named
+ * `login` limiter of five attempts a minute was five attempts a minute across the
+ * entire user base, and one attacker locked everybody out.
+ *
+ * @param strategy - What the builder recorded.
+ * @param trustedProxies - How many proxies sit in front, if the builder was told.
+ */
+function _resolverFor(
+  strategy: KeyStrategy,
+  trustedProxies: number | undefined,
+): ((ctx: HttpContext) => string) | undefined {
+  switch (strategy.kind) {
+    case "default":
+      return undefined;
+
+    case "ip":
+      return _markIpDerived((ctx) => `ip:${_clientIp(ctx, trustedProxies)}`);
+
+    case "user":
+      // Marked, because the *unauthenticated* half of this keys on an address —
+      // which is the half a rate limiter on a login form exists for.
+      return _markIpDerived((ctx) => {
+        const user = (ctx as unknown as Record<string, unknown>).user as
+          { id?: number } | undefined;
+        return user?.id !== undefined ? `user:${user.id}` : `ip:${_clientIp(ctx, trustedProxies)}`;
+      });
+
+    case "apiKey": {
+      const { header } = strategy;
+      return _markIpDerived((ctx) => {
+        const key = ctx.header(header);
+        return key ? `apikey:${key}` : `ip:${_clientIp(ctx, trustedProxies)}`;
+      });
+    }
+
+    case "custom":
+      // Unmarked on purpose: an app-supplied resolver is the app's to reason about,
+      // and most of them key on something no proxy can affect.
+      return strategy.fn;
+  }
 }
 
 /**

package/src/middleware/SecureHeadersMiddleware.ts

@@ -14,48 +14,48 @@ export interface SecureHeadersOptions {
    * `Content-Security-Policy` header value.
    * Omitted by default — set this to a policy appropriate for your application.
    */
-  contentSecurityPolicy?: string;
+  contentSecurityPolicy?: string | undefined;
 
   /**
    * `Strict-Transport-Security` max-age in seconds.
    * Defaults to 1 year (31 536 000 s). Set to `0` to disable HSTS entirely.
    * Only emitted when `secure: true` to avoid HSTS issues in plain-HTTP dev environments.
    */
-  hstsMaxAge?: number;
+  hstsMaxAge?: number | undefined;
 
   /**
    * Include `includeSubDomains` in the HSTS header. Defaults to `true`.
    */
-  hstsIncludeSubDomains?: boolean;
+  hstsIncludeSubDomains?: boolean | undefined;
 
   /**
    * Set the HSTS `preload` directive. Defaults to `false`.
    * Only set this if you have registered the domain with the HSTS preload list.
    */
-  hstsPreload?: boolean;
+  hstsPreload?: boolean | undefined;
 
   /**
    * Enable HSTS and the `Secure` flag on the XSRF-TOKEN cookie.
    * Default `false` — set to `true` in production when serving over HTTPS.
    */
-  secure?: boolean;
+  secure?: boolean | undefined;
 
   /**
    * `X-Frame-Options` value. Defaults to `'SAMEORIGIN'`.
    * Set to `'DENY'` for maximum protection, or `false` to omit the header.
    */
-  frameOptions?: "DENY" | "SAMEORIGIN" | false;
+  frameOptions?: "DENY" | "SAMEORIGIN" | false | undefined;
 
   /**
    * `Referrer-Policy` value. Defaults to `'strict-origin-when-cross-origin'`.
    */
-  referrerPolicy?: string;
+  referrerPolicy?: string | undefined;
 
   /**
    * `Permissions-Policy` header value.
    * Defaults to a conservative policy disabling sensitive APIs.
    */
-  permissionsPolicy?: string | false;
+  permissionsPolicy?: string | false | undefined;
 }
 
 const DEFAULT_PERMISSIONS_POLICY = "camera=(), microphone=(), geolocation=(), payment=()";

package/src/middleware/ThrottleMiddleware.ts

@@ -14,12 +14,12 @@ export interface ThrottleOptions {
   /** Maximum number of requests allowed within the window. */
   maxAttempts: number;
   /** Time window in seconds. Defaults to 60. */
-  windowSeconds?: number;
+  windowSeconds?: number | undefined;
   /**
    * Custom key resolver — defaults to client IP address.
    * Use this to rate-limit by user ID, API key, route, etc.
    */
-  keyResolver?: (ctx: HttpContext) => string;
+  keyResolver?: ((ctx: HttpContext) => string) | undefined;
   /**
    * Number of trusted reverse proxies in front of this server.
    *
@@ -35,7 +35,7 @@ export interface ThrottleOptions {
    * // Behind one load balancer:
    * ThrottleMiddleware.with({ maxAttempts: 60, trustedProxies: 1 })
    */
-  trustedProxies?: number;
+  trustedProxies?: number | undefined;
 }
 
 interface HitRecord {
@@ -226,7 +226,60 @@ export function _pruneStore(store: Map<string, HitRecord>, now: number): void {
   for (let i = 0; i < live.length - _MAX_KEYS; i++) store.delete(live[i]![0]);
 }
 
-function _clientIp(ctx: HttpContext, trustedProxies?: number): string {
+/**
+ * A `keyResolver` that derives its key from the client's address, tagged so the
+ * doctor can tell it apart from one that does not.
+ *
+ * `zt doctor` exempts a throttle with a custom `keyResolver` from the
+ * `trustedProxies` check, and that is right for a limiter keyed on a user id or a
+ * tenant — no proxy can affect it. It is exactly wrong for one keyed on an IP,
+ * which is what `RateLimiter`'s `.byIp()`, `.byUser()` and `.byApiKey()` build.
+ * Unmarked, those slipped past the one check that exists to catch them.
+ *
+ * @internal
+ */
+export const _IP_DERIVED_KEY = Symbol.for("zerotal.throttle.ipDerivedKey");
+
+/** Shape of a resolver carrying the marker. @internal */
+type MaybeMarked = { [_IP_DERIVED_KEY]?: boolean };
+
+/**
+ * Tag `resolver` as deriving its key from the client address.
+ *
+ * @param resolver - The key resolver to mark.
+ * @returns The same function, marked.
+ * @internal
+ */
+export function _markIpDerived<T extends (ctx: HttpContext) => string>(resolver: T): T {
+  (resolver as T & MaybeMarked)[_IP_DERIVED_KEY] = true;
+  return resolver;
+}
+
+/**
+ * Whether `resolver` keys on the client address, and so still needs `trustedProxies`.
+ *
+ * @param resolver - The key resolver to test, if there is one.
+ * @internal
+ */
+export function _isIpDerived(resolver: unknown): boolean {
+  return typeof resolver === "function" && (resolver as MaybeMarked)[_IP_DERIVED_KEY] === true;
+}
+
+/**
+ * The client's address, honouring `trustedProxies`.
+ *
+ * Exported so `RateLimiter`'s built-in key resolvers use the same rule rather than
+ * their own. Theirs read the socket address and fell back to the *leftmost*
+ * `X-Forwarded-For` entry with no proxy count at all — so behind a reverse proxy
+ * every visitor keyed on the proxy's address and shared one bucket, and a named
+ * `login` limiter of five attempts a minute was five attempts a minute for the whole
+ * user base. One attacker locked everybody out.
+ *
+ * @param ctx - The request to resolve an address for.
+ * @param trustedProxies - How many proxies sit in front; see {@link ThrottleOptions.trustedProxies}.
+ * @internal
+ */
+export function _clientIp(ctx: HttpContext, trustedProxies?: number): string {
   // Default (undefined) and an explicit 0 both mean "not behind a trusted proxy": read the raw
   // socket address, which cannot be spoofed.
   //

package/src/middleware/WebhookMiddleware.ts

@@ -13,32 +13,32 @@ export interface WebhookOptions {
   /** HMAC secret used to verify the signature. */
   secret: string;
   /** Request header that carries the signature. Default: 'x-webhook-signature'. */
-  header?: string;
+  header?: string | undefined;
   /** HMAC algorithm. Default: 'sha256'. */
-  algorithm?: "sha256" | "sha1" | "sha512";
+  algorithm?: "sha256" | "sha1" | "sha512" | undefined;
   /**
    * Expected signature prefix that will be stripped before comparison
    * (e.g. `'sha256='` for GitHub). Default: `''`.
    */
-  prefix?: string;
+  prefix?: string | undefined;
   /**
    * Max age in seconds for replay-attack protection.
    * Requires `timestampHeader` (or `format: 'stripe'`). Disabled when `undefined`.
    */
-  tolerance?: number;
+  tolerance?: number | undefined;
   /**
    * Header that carries the Unix timestamp of the request.
    * When present the signed payload becomes `{timestamp}{timestampSeparator}{body}`.
    */
-  timestampHeader?: string;
+  timestampHeader?: string | undefined;
   /** Separator between timestamp and body in the signed payload. Default: `'.'`. */
-  timestampSeparator?: string;
+  timestampSeparator?: string | undefined;
   /**
    * Header format.
    * - `'raw'` (default) — signature is the full (or prefix-stripped) header value.
    * - `'stripe'` — header is parsed as `t=<ts>,v1=<sig>` (Stripe-Signature style).
    */
-  format?: "raw" | "stripe";
+  format?: "raw" | "stripe" | undefined;
 }
 
 /**

package/src/router/RouteHandler.ts

@@ -85,7 +85,7 @@ export interface DispatchOptions {
   exceptionHandler?: ExceptionHandler | undefined;
   providerHooks?: ProviderHooks | undefined;
   /** Configure the freshly created context (params, route info) before dispatch. */
-  configure?: (ctx: HttpContext) => void;
+  configure?: ((ctx: HttpContext) => void) | undefined;
   /**
    * Path-specific work: run the pipeline and produce the response (or leave it
    * on `ctx.response`). Errors thrown here are rendered by the exception handler.
@@ -95,7 +95,7 @@ export interface DispatchOptions {
    * Render an unhandled error to a Response. Defaults to reporting + rendering
    * through `exceptionHandler` when present, else `ExceptionHandler.defaultRender`.
    */
-  renderError?: (error: unknown, ctx: HttpContext) => Promise<Response>;
+  renderError?: ((error: unknown, ctx: HttpContext) => Promise<Response>) | undefined;
 }
 
 /**

package/src/router/Router.ts

@@ -124,13 +124,13 @@ type CompiledRoutes = Record<string, Record<string, RouteHandlerFn> | Response>;
 /** Options for {@link Router.static}. */
 export interface StaticOptions {
   /** Extra response headers applied to every served file (e.g. Cache-Control). */
-  headers?: Record<string, string>;
+  headers?: Record<string, string> | undefined;
   /**
    * When true (default) every file in the directory is pre-registered at
    * compile() time as a static `Response`, so Bun serves it without invoking
    * JS. Set false to fall back to the per-request lookup in Application.fetch.
    */
-  eager?: boolean;
+  eager?: boolean | undefined;
 }
 
 type StaticDir = { prefix: string; rootDir: string; options?: StaticOptions | undefined };
@@ -143,7 +143,7 @@ type MarkdownDir = {
 /** Options for Router.group(). All fields are optional. */
 export interface GroupOptions {
   /** URL prefix applied to every route registered inside the group. */
-  prefix?: string;
+  prefix?: string | undefined;
   /**
    * Middleware to prepend to every route inside the group.
    * Accepts a named group (string), an array of names/classes, or middleware class(es) directly.
@@ -152,9 +152,9 @@ export interface GroupOptions {
    * Router.group({ middleware: 'api' }, () => { ... });
    * Router.group({ middleware: ['web', AuthMiddleware] }, () => { ... });
    */
-  middleware?: string | string[] | MiddlewareClass | MiddlewareClass[];
+  middleware?: string | string[] | MiddlewareClass | MiddlewareClass[] | undefined;
   /** Host pattern; routes inside the group only match this host (e.g. ':tenant.app.com'). */
-  domain?: string;
+  domain?: string | undefined;
 }
 
 // ── Internal helpers ──────────────────────────────────────────────────────────

package/src/security/redactGraph.ts

@@ -48,7 +48,7 @@ export interface RedactGraphOptions {
    * `JSON.stringify` drops the key it sits under, and a debugging tool that
    * silently omits a field is worse than one that says `‹fn›`.
    */
-  flatten?: (value: unknown) => string | undefined;
+  flatten?: ((value: unknown) => string | undefined) | undefined;
 }
 
 /**

package/src/shared/format.ts

@@ -25,7 +25,7 @@ export interface FormatOptions {
    * and in a browser is the reader's, and those are not the same. Pass one
    * explicitly wherever the two sides must match, and they usually must.
    */
-  locale?: string;
+  locale?: string | undefined;
 }
 
 /** How money should be written. */
@@ -37,9 +37,9 @@ export interface MoneyOptions extends FormatOptions {
    * database column that must not lose a cent stores it. Default `true`, because
    * an app that stores money in a float has a different problem.
    */
-  minorUnits?: boolean;
+  minorUnits?: boolean | undefined;
   /** Digits after the decimal point. Defaults to whatever the currency uses. */
-  fractionDigits?: number;
+  fractionDigits?: number | undefined;
 }
 
 /**
@@ -69,9 +69,9 @@ export function formatMoney(amount: number, options: MoneyOptions): string {
 /** How a plain number should be written. */
 export interface NumberOptions extends FormatOptions {
   /** Smallest number of digits after the decimal point. */
-  minimumFractionDigits?: number;
+  minimumFractionDigits?: number | undefined;
   /** Largest number of digits after the decimal point. */
-  maximumFractionDigits?: number;
+  maximumFractionDigits?: number | undefined;
 }
 
 /**
@@ -90,9 +90,9 @@ export function formatNumber(value: number, options: NumberOptions = {}): string
 /** How a date should be written. */
 export interface DateOptions extends FormatOptions {
   /** Length of the date part. Omit for none. */
-  dateStyle?: "full" | "long" | "medium" | "short";
+  dateStyle?: "full" | "long" | "medium" | "short" | undefined;
   /** Length of the time part. Omit for none. */
-  timeStyle?: "full" | "long" | "medium" | "short";
+  timeStyle?: "full" | "long" | "medium" | "short" | undefined;
   /**
    * IANA zone — `Africa/Johannesburg`, `UTC`.
    *
@@ -100,7 +100,7 @@ export interface DateOptions extends FormatOptions {
    * disagree about which day an 11pm booking happened on, and that is the shape
    * the bug takes: not a wrong time, a wrong date.
    */
-  timeZone?: string;
+  timeZone?: string | undefined;
 }
 
 /**