@nubjs/types 0.7.2 → 0.7.3

package/README.md

@@ -1,6 +1,6 @@
 # @nubjs/types
 
-TypeScript ambient declarations for code authored against the Nub runtime — global `Worker`, `Temporal`, `reportError`, data-format wildcard imports (`*.yaml`, `*.toml`, etc.), and `import.meta.hot`.
+TypeScript ambient declarations for code authored against the Nub runtime, including its global Worker, Temporal, proposal polyfills, data-format imports, and hot-reload metadata.
 
 ## Usage
 
@@ -14,4 +14,4 @@ Then in `tsconfig.json`:
 { "compilerOptions": { "types": ["node", "@nubjs/types"] } }
 ```
 
-**Recommended: `@types/node@26` (or at minimum `@types/node@25.9.3`).** This package requires `@types/node>=25` — earlier versions lack the global `MessageEvent`, `ErrorEvent`, and `MessagePort` that the `Worker` declaration depends on. Upgrade once `@types/node@26` ships.
+Use `@types/node@26`, or `@types/node@25.9.3` at minimum. TypeScript 6 and newer use the compiler's official Temporal declarations; TypeScript 5.9 uses the matching declarations bundled with this package.

package/common.d.ts

@@ -0,0 +1,243 @@
+// @nubjs/types — ambient declarations for code authored against the Nub runtime.
+//
+// Nub augments Node with surfaces TypeScript doesn't know about. This package
+// makes that nub-authored code typecheck so the parity bar holds: "if `tsc
+// --noEmit` accepts your code, nub runs it."
+//
+// Declares Nub-only surfaces plus proposal APIs that are missing from a consumer's
+// selected TypeScript lib. Proposal members augment the standard interfaces rather
+// than redeclaring their global values: an older lib gains the methods, while a
+// newer lib's declarations merge without TS2403/TS2717 conflicts. Runtime surfaces
+// already covered by @types/node or the selected standard libraries remain absent.
+// Add this package to a tsconfig with `types: ["node", "@nubjs/types"]`.
+//
+// MUST remain a global *script* file: NO top-level `import`/`export`. The wildcard
+// `declare module "*.yaml"` declarations are only visible project-wide from a
+// script file. (Adding `export {}` turns this into a module and silently breaks
+// 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) ──
+// 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,
+// unknown>` so the default can be destructured with sound `unknown` keys —
+// `import cfg from "./c.yaml"; const { host, port } = cfg;` gives `host`/`port:
+// unknown`. This is the sound, typeable equivalent of named imports.
+//
+// CAVEAT: a top-level array or scalar (e.g. a YAML document whose root is a list
+// or a bare string) is mistyped as a record by `Record<string, unknown>`; cast
+// the default in that case (`import data from "./list.yaml"; const items = data
+// as unknown as string[];`). `.txt` is always a `string`; `.json` is
+// intentionally NOT declared — it's Node-native (resolveJsonModule).
+declare module "*.yaml" {
+  const data: Record<string, unknown>;
+  export default data;
+}
+declare module "*.yml" {
+  const data: Record<string, unknown>;
+  export default data;
+}
+declare module "*.toml" {
+  const data: Record<string, unknown>;
+  export default data;
+}
+declare module "*.jsonc" {
+  const data: Record<string, unknown>;
+  export default data;
+}
+declare module "*.json5" {
+  const data: Record<string, unknown>;
+  export default data;
+}
+declare module "*.txt" {
+  const data: string;
+  export default data;
+}
+
+// ── reportError (WinterTC min-common-API; runtime/polyfills.cjs) ──
+// In no Node version, in no @types/node. Nub installs it on every supported version.
+declare function reportError(error: unknown): void;
+
+// ── lib.dom step-aside helpers (idiom from bun-types: packages/bun-types/bun.d.ts) ──
+// These two ambient *type* aliases let us declare DOM-overlapping globals (today
+// just `Worker`) WITHOUT colliding (TS2403/TS2430) when the consumer ALSO has them
+// globally — e.g. `lib: ["dom"]`, or any other lib that declares `Worker`. They
+// are pure type-level helpers: a global *script* may declare ambient `type`s
+// freely (only a top-level `import`/`export` would turn this into a module), so
+// this does NOT break the wildcard `declare module "*.yaml"` decls above.
+//
+// `__NubLibDomIsLoaded` — lib.dom defines the global `onabort`; its presence is the
+// signal that DOM is loaded, so the DOM owns these globals and we must step aside.
+// `__NubUseLibDomIfAvailable<K, T>` — when DOM is loaded, adopt whatever type
+// `globalThis` already has for key K; otherwise fall back to our own shape T. This
+// is exactly Bun's `Bun.__internal.{LibDomIsLoaded,UseLibDomIfAvailable}`, recast
+// as bare ambient globals (with a `__Nub` prefix) so the file stays a script.
+type __NubLibDomIsLoaded = typeof globalThis extends { onabort: any } ? true : false;
+type __NubUseLibDomIfAvailable<GlobalThisKeyName extends PropertyKey, Otherwise> =
+  __NubLibDomIsLoaded extends true
+    ? typeof globalThis extends { [K in GlobalThisKeyName]: infer T }
+      ? T
+      : Otherwise
+    : Otherwise;
+
+// ── Browser-shape Worker global (runtime/worker-polyfill.mjs; wiki/runtime/web-worker.md) ──
+// 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
+// global in @types/node>=25 (web-globals/fetch.d.ts + messaging.d.ts) — verified
+// empirically — so they are referenced from there and intentionally NOT redeclared
+// here (redeclaring them collides: TS2403).
+//
+// Step-aside: when `lib: ["dom"]` is in play, the DOM's own `Worker` wins — the
+// interface body resolves to `{}` (via `__NubLibWorkerOrNubWorker`) and our `var`
+// adopts the DOM type (via `__NubUseLibDomIfAvailable`), so the two coexist with
+// NO TS2403/TS2430 collision. When DOM is absent (the normal Node case), our full
+// browser-shape declaration applies unchanged.
+interface WorkerOptions {
+  type?: "module" | "classic";
+  name?: string;
+  credentials?: "omit" | "same-origin" | "include";
+  // `eval: true` runs the constructor's first argument as the worker's source
+  // (Node's worker_threads inline form) instead of resolving it as a URL.
+  eval?: true;
+}
+interface __NubWorker extends EventTarget {
+  readonly name: string;
+  postMessage(message: any, transfer?: readonly (ArrayBuffer | MessagePort)[]): void;
+  // Returns the underlying worker_threads `Promise<exitCode>` (additive
+  // void→value widening; spec code that ignores the return is unaffected).
+  terminate(): Promise<number>;
+  onmessage: ((this: Worker, ev: MessageEvent) => any) | null;
+  onmessageerror: ((this: Worker, ev: MessageEvent) => any) | null;
+  onerror: ((this: Worker, ev: ErrorEvent) => any) | null;
+  // node:worker_threads EventEmitter surface, delegated to the underlying real
+  // Worker. The node channel carries Node's shapes — `message` the RAW posted
+  // value, `error` a bare `Error`, `exit` the numeric exit code, `online` no arg —
+  // distinct from the web channel above (`MessageEvent`/`ErrorEvent`). The adders
+  // return the handle for chaining.
+  on(event: "message", listener: (value: any) => void): this;
+  on(event: "messageerror", listener: (error: Error) => void): this;
+  on(event: "error", listener: (err: Error) => void): this;
+  on(event: "exit", listener: (exitCode: number) => void): this;
+  on(event: "online", listener: () => void): this;
+  on(event: string | symbol, listener: (...args: any[]) => void): this;
+  once(event: "message", listener: (value: any) => void): this;
+  once(event: "messageerror", listener: (error: Error) => void): this;
+  once(event: "error", listener: (err: Error) => void): this;
+  once(event: "exit", listener: (exitCode: number) => void): this;
+  once(event: "online", listener: () => void): this;
+  once(event: string | symbol, listener: (...args: any[]) => void): this;
+  addListener(event: "message", listener: (value: any) => void): this;
+  addListener(event: "messageerror", listener: (error: Error) => void): this;
+  addListener(event: "error", listener: (err: Error) => void): this;
+  addListener(event: "exit", listener: (exitCode: number) => void): this;
+  addListener(event: "online", listener: () => void): this;
+  addListener(event: string | symbol, listener: (...args: any[]) => void): this;
+  off(event: string | symbol, listener: (...args: any[]) => void): this;
+  removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
+  emit(event: string | symbol, ...args: any[]): boolean;
+}
+type __NubLibWorkerOrNubWorker = __NubLibDomIsLoaded extends true ? {} : __NubWorker;
+interface Worker extends __NubLibWorkerOrNubWorker {}
+declare var Worker: __NubUseLibDomIfAvailable<
+  "Worker",
+  {
+    prototype: Worker;
+    new (scriptURL: string | URL, options?: WorkerOptions): Worker;
+  }
+>;
+
+// ── import.meta.hot (Vite-compatible; wiki/runtime/hot-mode.md — 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 {
+  readonly hot?: {
+    readonly data: Record<string, any>;
+    accept(): void;
+    accept(cb: (mod: any) => void): void;
+    accept(dep: string, cb: (mod: any) => void): void;
+    accept(deps: readonly string[], cb: (mods: any[]) => void): void;
+    dispose(cb: (data: Record<string, any>) => void): void;
+    invalidate(): void;
+    on(event: string, cb: (data: any) => void): void;
+    send(event: string, data?: any): void;
+  };
+}
+
+// ── Recently polyfilled proposal APIs (runtime/polyfills.cjs) ──
+// Use declaration merging for existing ECMAScript globals. This is the same shape
+// TypeScript's `lib.esnext.*` files and Bun's runtime types use: never redeclare
+// `var Promise`, `var Symbol`, etc. Method members safely become overloads when a
+// future standard lib adds them. The one property member (`Symbol.metadata`) is
+// byte-for-byte TypeScript's already-settled `lib.esnext.decorators` declaration.
+
+// Iterator chunking/includes/join. `IteratorObject` is in lib.es2015.iterable even
+// when the ES2025 Iterator constructor is not selected, so built-in iterators gain
+// these methods at the ES2024 target too. The versioned package entry point loads
+// TypeScript's own Iterator constructor and base-helper declarations.
+interface IteratorObject<T, TReturn, TNext> {
+  chunks(chunkSize: number): IteratorObject<T[], undefined, unknown>;
+  windows(windowSize: number): IteratorObject<T[], undefined, unknown>;
+  includes(searchElement: T): boolean;
+  join(separator?: string): string;
+}
+
+interface Math {
+  sumPrecise(items: Iterable<number>): number;
+}
+
+interface SymbolConstructor {
+  readonly metadata: unique symbol;
+}
+
+interface Atomics {
+  pause(iterationNumber?: number): void;
+}
+
+// Promise.allKeyed / Promise.allSettledKeyed (TC39 await dictionary). The mapped
+// types mirror the proposal README: the key set is preserved and each value is
+// `Awaited`. Two runtime facts TypeScript cannot express — the result object has a
+// null prototype, and only own enumerable keys appear at runtime.
+interface PromiseConstructor {
+  allKeyed<T extends object>(promises: T): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }>;
+  allSettledKeyed<T extends object>(
+    promises: T,
+  ): Promise<{ -readonly [K in keyof T]: PromiseSettledResult<Awaited<T[K]>> }>;
+}
+
+// Uint8Array base64/hex. These signatures match TypeScript 6's
+// lib.esnext.typedarrays exactly, so consumers on older TypeScript versions gain
+// them and newer standard libraries merge the identical interface members.
+interface Uint8Array<TArrayBuffer extends ArrayBufferLike> {
+  toBase64(options?: {
+    alphabet?: "base64" | "base64url" | undefined;
+    omitPadding?: boolean | undefined;
+  }): string;
+  setFromBase64(
+    string: string,
+    options?: {
+      alphabet?: "base64" | "base64url" | undefined;
+      lastChunkHandling?: "loose" | "strict" | "stop-before-partial" | undefined;
+    },
+  ): { read: number; written: number };
+  toHex(): string;
+  setFromHex(string: string): { read: number; written: number };
+}
+interface Uint8ArrayConstructor {
+  fromBase64(
+    string: string,
+    options?: {
+      alphabet?: "base64" | "base64url" | undefined;
+      lastChunkHandling?: "loose" | "strict" | "stop-before-partial" | undefined;
+    },
+  ): Uint8Array<ArrayBuffer>;
+  fromHex(string: string): Uint8Array<ArrayBuffer>;
+}
+
+// ── Date.prototype.toTemporalInstant (runtime/preload-common.cjs installs it) ──
+// Nub assigns the polyfill's `toTemporalInstant` onto Date.prototype on the floor
+// (matching native Node, which ships it once Temporal is native).
+interface Date {
+  toTemporalInstant(): Temporal.Instant;
+}