Type Declarations

Writing Nub type declarations

@nubjs/types describes user-visible runtime behavior that the consumer's selected TypeScript libraries and @types/node do not already describe. Runtime truth comes first: declarations follow shipped behavior; they never advertise an unimplemented convenience or preserve a stale shape for compatibility.

The package lives under npm/nub-types/:

• common.d.ts — declarations shared by every supported compiler.
• index.d.ts — the current-compiler entry point and focused standard-library references.
• ts5.9/index.d.ts — the legacy entry selected through typesVersions.
• test/fixtures/ — compile-time compatibility and negative controls.

Start with an ownership audit

1. Trace the runtime surface from its implementation and its row in crates/nub-core/src/node/feature_matrix.rs. Check runtime/polyfills.cjs, runtime/preload-common.cjs, loader modules, or other owning code rather than inferring a signature from a feature name.
2. Check the exact TypeScript libraries supported by the fixture matrix and current @types/node. ECMAScript built-ins normally belong to TypeScript's lib.*.d.ts; Node and web globals may belong to @types/node.
3. Consult primary declarations: TypeScript's src/lib or installed lib.*.d.ts, DefinitelyTyped's types/node, and Bun's types when looking for a proven step-aside pattern. A proposal README or specification establishes semantics, but the official TypeScript declaration is the compatibility target once one exists.
4. Add a declaration only for the remaining gap. If a focused TypeScript library already owns the surface, reference that library instead of copying it.

Choose the conflict-safe pattern

Merge members into existing built-ins

Augment the interface that owns an existing global:

interface PromiseConstructor {
  allKeyed<T extends object>(promises: T): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }>;
}

Use the same pattern for IteratorObject, Math, Atomics, SymbolConstructor, typed-array instances, and typed-array constructors. Never redeclare var Promise, var Symbol, or another built-in value just to add a method. Method members merge as overloads when a future standard library adds them.

Property members are stricter: their modifiers and type must match the official settled declaration exactly. Symbol.metadata, for example, must remain readonly and unique symbol.

Step aside from an optional global owner

Some globals are absent from Node's normal type environment but collide when a consumer also selects lib.dom. Follow the conditional globalThis pattern used by Node and Bun types: detect the other library, adopt its constructor type, and reduce Nub's interface extension to {}. The current helpers are __NubLibDomIsLoaded and __NubUseLibDomIfAvailable in common.d.ts.

Do not solve a global collision with skipLibCheck, a broad any, or a second incompatible declare var. The fixtures compile with skipLibCheck: false specifically to expose these conflicts.

Route declarations that cannot merge

Classes, type aliases, and some namespace members cannot safely coexist with a later official library. Route those declarations by compiler version through typesVersions:

• TypeScript 5.9 and earlier receive Nub's inlined Temporal declarations.
• TypeScript 6 and later reference the official esnext.temporal library.
• Both routes reference common.d.ts for declarations that merge safely.

Keep version routing as narrow as possible. Add a new route only after reproducing a real collision, and set its boundary to the first compiler that ships the official declaration. Do not fork the whole package for one incompatible surface.

Preserve the global-script invariant

common.d.ts must remain a global script. Never add a top-level import, export, or export {}: doing so makes wildcard declarations such as declare module "*.yaml" module-local and silently removes Nub globals from consumers.

Use triple-slash lib and path references in versioned entry points. If a declaration needs an external type, prefer a qualified ambient reference that does not convert common.d.ts into a module.

Match runtime and inference precisely

• Copy an official TypeScript signature byte-for-byte when Nub backfills an API already declared by a newer compiler.
• For a proposal without official TypeScript declarations, derive the narrowest useful signature from the proposal and runtime implementation. Preserve keys, readonly removal, Awaited, generic buffer types, and overload behavior where they are observable to callers.
• Document runtime facts the type system cannot express, such as null prototypes or enumerable-key filtering, without pretending the signature enforces them.
• Keep vendored declarations tied to the bundled implementation version. When the Temporal polyfill changes, reconcile the TypeScript 5.9 fallback against that exact package version.
• Do not duplicate surfaces already supplied by the selected TypeScript library or @types/node.