@nubjs/types 0.7.5 → 0.8.0

package/common.d.ts

@@ -17,7 +17,7 @@
 // the data-import wildcards.) Globals are declared bare (`declare function …`,
 // `declare var …`, `declare namespace …`) for the same reason.
 
-// ── Data-format module imports (Nub load hook; wiki/runtime/data-loaders.md) ──
+// ── Data-format module imports (Nub load hook) ──
 // Default export ONLY — data modules expose no named exports (a named import
 // like `import { host } from "./c.yaml"` is a load-time error on nub, the same
 // as Node's JSON modules). The object formats default to `Record<string,
@@ -81,7 +81,7 @@ type __NubUseLibDomIfAvailable<GlobalThisKeyName extends PropertyKey, Otherwise>
       : Otherwise
     : Otherwise;
 
-// ── Browser-shape Worker global (runtime/worker-polyfill.mjs; wiki/runtime/web-worker.md) ──
+// ── Browser-shape Worker global (runtime/worker-polyfill.mjs) ──
 // Nub ships the WHATWG/browser subset of `Worker` over node:worker_threads.Worker.
 // @types/node has NO global `Worker` (only node:worker_threads' class), so this is
 // the genuine gap. `MessageEvent`, `ErrorEvent`, and `MessagePort` are ALREADY
@@ -148,7 +148,7 @@ declare var Worker: __NubUseLibDomIfAvailable<
   }
 >;
 
-// ── import.meta.hot (Vite-compatible; wiki/runtime/hot-mode.md — v0.x, shape committed v0.1) ──
+// ── import.meta.hot (Vite-compatible — v0.x, shape committed v0.1) ──
 // Forward-compat commitment: ships now so framework authors can code against the
 // shape. `import.meta.hot` is `undefined` unless `nub watch --hot` is active.
 interface ImportMeta {
@@ -187,6 +187,60 @@ interface Math {
   sumPrecise(items: Iterable<number>): number;
 }
 
+// Iterator.concat (Stage 4; native only on Node 26+, polyfilled below). TypeScript's
+// iterator libraries declare `from` and the helpers on IteratorConstructor but not
+// this, so no `reference lib` reaches it on any version. The sibling statics Nub also
+// installs — `zip` and `zipKeyed` — are deliberately still absent: their element type
+// depends on the `mode` option ("longest" pads with undefined), so declaring them
+// honestly needs mode-discriminated overloads, which is its own change.
+interface IteratorConstructor {
+  // The element type DISTRIBUTES over the sources — `concat<T>(...items:
+  // Iterable<T>[])` would bind T to the first argument and reject a differently
+  // typed second one, which the runtime accepts (it just delegates with `yield*`).
+  concat<T extends readonly Iterable<unknown>[]>(
+    ...items: T
+  ): IteratorObject<T[number] extends Iterable<infer U> ? U : never, undefined, unknown>;
+}
+
+// Polyfilled members declared HERE rather than reached through a `reference lib`,
+// because no library spans every TypeScript this package serves. `escape` and
+// `getOrInsert` have no library below TypeScript 6 at all. `isError` is the sharper
+// case: `lib.esnext.error` does not exist before TypeScript 5.9, and an unknown lib
+// name is a hard TS2726 that fails the consumer's WHOLE build — so referencing it
+// from the `<=5.9` entry point broke every TypeScript 5.7/5.8 consumer outright.
+// Declaring all three in this shared file covers both entry points at once, which
+// is why neither references lib.es2025.regexp, lib.esnext.collection or
+// lib.esnext.error. Signatures match TypeScript 6's exactly, so a 6+ consumer
+// merges identical members rather than gaining a second, divergent overload.
+interface RegExpConstructor {
+  escape(string: string): string;
+}
+
+interface ErrorConstructor {
+  isError(error: unknown): error is Error;
+}
+
+// `Promise.try` is the fourth: TypeScript 5.7 resolves `esnext.promise` to a library
+// that predates it, so the reference is silently empty there rather than an error.
+interface PromiseConstructor {
+  try<T, U extends unknown[]>(
+    callbackFn: (...args: U) => T | PromiseLike<T>,
+    ...args: U
+  ): Promise<Awaited<T>>;
+}
+
+// Nub installs both methods on BOTH constructors (runtime/polyfills.cjs
+// `installMapGetOrInsert`), so both are declared; the proposal's original `upsert`
+// name is deliberately absent, matching every runtime that shipped this.
+interface Map<K, V> {
+  getOrInsert(key: K, defaultValue: V): V;
+  getOrInsertComputed(key: K, callback: (key: K) => V): V;
+}
+interface WeakMap<K extends WeakKey, V> {
+  getOrInsert(key: K, defaultValue: V): V;
+  getOrInsertComputed(key: K, callback: (key: K) => V): V;
+}
+
 interface SymbolConstructor {
   readonly metadata: unique symbol;
 }

package/index.d.ts

@@ -1,9 +1,27 @@
 // @nubjs/types — TypeScript 6+ entry point.
 //
-// TypeScript 6 ships the official Temporal declarations. Reference that focused
-// library even when a consumer targets ES2024, then layer Nub's additive runtime
-// augmentations from common.d.ts on top. Keeping this file a global script is
-// intentional; see common.d.ts for the data-import wildcard invariant.
+// Every `reference lib` below names a library TypeScript already ships for a
+// feature Nub GUARANTEES across its whole Node floor — native where the running
+// Node has it, polyfilled below (feature_matrix.rs gives the band per feature).
+// Pulling the focused libraries in HERE is what lets a consumer keep
+// `lib: ["es2024"]` — the target `nub init` scaffolds — and still type that
+// surface, rather than raising `lib` to `esnext` and picking up features Nub does
+// not provide at all. Nub then layers its additive runtime augmentations from
+// common.d.ts on top. Keeping this file a global script is intentional; see
+// common.d.ts for the data-import wildcard invariant.
+//
+// A library reference is only safe where the name resolves in EVERY TypeScript the
+// entry point serves: an unknown one is a hard TS2726 that fails the consumer's
+// whole build. TypeScript keeps a promoted library's old name working as an alias
+// (7.0 ships no lib.esnext.array.d.ts yet still resolves `esnext.array`), so the
+// risk is a name that does not exist YET, not one that has moved. Anything a
+// supported TypeScript lacks is hand-declared in common.d.ts instead — which is
+// also why nothing here references lib.es2025.regexp, lib.esnext.collection,
+// lib.esnext.error or lib.es2025.promise: common.d.ts already carries their whole
+// contents. `es2025.collection` is a different library from `esnext.collection` —
+// it holds the Set methods, which common.d.ts does not declare.
 /// <reference lib="esnext.temporal" />
 /// <reference lib="es2025.iterator" />
+/// <reference lib="es2025.collection" />
+/// <reference lib="esnext.array" />
 /// <reference path="./common.d.ts" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubjs/types",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "description": "TypeScript ambient declarations for code authored against the Nub runtime",
   "license": "MIT",
   "repository": "https://github.com/nubjs/nub",

package/ts5.9/index.d.ts

@@ -1,8 +1,19 @@
 // TypeScript 5.9 fallback entry point for @nubjs/types.
-// Common Nub augmentations stay shared; only Temporal is version-routed because
+// Common Nub augmentations stay shared; Temporal is version-routed because
 // TypeScript 6 added an official lib.esnext.temporal whose type aliases cannot merge.
+// The library references cover the same features as index.d.ts. Two are spelled
+// differently because TypeScript 5.9 has not yet moved the ratified ES2025 features
+// out of `esnext.*`: `esnext.collection` here is TypeScript 6's `es2025.collection`,
+// and `esnext.iterator` its `es2025.iterator`. Everything else is hand-declared in
+// common.d.ts, which is what keeps both entry points describing ONE surface. That
+// matters most for `Error.isError`: `lib.esnext.error` does not exist before
+// TypeScript 5.9, and `typesVersions` routes every TypeScript at or below 5.9 here —
+// so referencing it broke 5.7 and 5.8 consumers with a TS2726 that failed their
+// whole build, which is why the package now declares that member by hand.
 /// <reference path="../common.d.ts" />
 /// <reference lib="esnext.iterator" />
+/// <reference lib="esnext.array" />
+/// <reference lib="esnext.collection" />
 
 // ── Temporal (vendored @js-temporal/polyfill@0.5.1; runtime/preload-common.cjs) ──
 // TypeScript <=5.9 has no official Temporal library. The namespace below is