@nativescript/vite 8.0.0-alpha.6 → 8.0.0-alpha.60

package/hmr/server/deps-bundle.d.ts

@@ -0,0 +1,218 @@
+/**
+ * THE single node_modules payload for dev-session device serving.
+ *
+ * DEFAULT MODE
+ * ------------
+ * All node_modules code a session needs evaluates from ONE ESM payload served
+ * at `GET /ns/deps-bundle.mjs`. Its entry set is the union of:
+ *  - the vendor collection (direct NativeScript-plugin/framework deps from
+ *    package.json — available on the very first boot, no recording needed),
+ *  - the persisted boot recording (every deep `/ns/m/node_modules/...` file a
+ *    previous cold boot actually fetched — rxjs internals, Angular fesm
+ *    files, community plugin subpaths).
+ *
+ * The canonical `/ns/m/node_modules/...` URL space is preserved — those
+ * routes serve THIN SHIMS that statically import the bundle and re-export the
+ * requested module's namespace from the `globalThis.__NS_DEPS_MODULES__`
+ * registry the bundle populates. Because every shim's only dependency is the
+ * one bundle URL, V8 evaluates the dependency closure exactly once — module
+ * identity stays keyed by canonical URL, with ONE big prefetchable payload
+ * instead of a deep serial fetch chain.
+ *
+ * The legacy vendor realm is a VIEW over this bundle: the session bootstrap's
+ * `/@nativescript/vendor.mjs` import serves a thin module (see
+ * `buildDepsVendorRuntimeModule`) that imports this bundle and exposes
+ * package-root namespaces from the deps registry, so `ns-vendor://<pkg>`
+ * wrappers and `__nsVendorRequire` resolve into the SAME realm as every shim.
+ * No second node_modules payload ever evaluates.
+ *
+ * REALM RULES
+ * -----------
+ *  - `@nativescript/core[/*]` stays EXTERNAL as a bare specifier: the device
+ *    import map routes it to the `/ns/core` bridge, so bundled dep code joins
+ *    the live core realm.
+ *  - Dynamic `import()` targets inside dep code are externalized back to
+ *    their canonical `/ns/m/node_modules/...` URL, preserving lazy evaluation
+ *    and per-URL identity for modules the boot never touched.
+ *  - `@nativescript/vite` client modules stay per-module (dev tooling loads
+ *    independently of the app dependency closure).
+ *  - Everything else resolvable is internalized — platform-suffix resolution
+ *    (`index.ios.js`) backs up esbuild's resolver — and EVERY bundled input
+ *    file is registered, so any `/ns/m` URL minted for a bundled file
+ *    resolves to the single bundle instance. Bare externals are emitted only
+ *    for specs with no on-disk resolution at all: anything resolvable would
+ *    otherwise round-trip through a shim of this bundle mid-evaluation (ESM
+ *    cycle: the shim body runs before the registry is populated and throws).
+ *
+ * FALLBACK
+ * --------
+ * A failed esbuild build logs once and falls back to per-module serving plus
+ * the standalone vendor bundle for the session. Opt out entirely with
+ * `NS_DEPS_PER_MODULE=1` (patch-package workflows editing node_modules).
+ */
+import type { ViteDevServer } from 'vite';
+import type { Platform } from '../../helpers/platform-types.js';
+export declare const DEPS_BUNDLE_PATH = "/ns/deps-bundle.mjs";
+/**
+ * Per-module node_modules serving mode (vs the default single-eval deps
+ * bundle). `NS_DEPS_PER_MODULE=1|true` forces per-module serving — the right
+ * mode when hand-editing files inside node_modules (patch-package workflows).
+ */
+export declare function isDepsPerModuleServingEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** One bundle entry: the served spec, its registry key, and the source file. */
+export interface DepsBundleEntry {
+    /** Served spec form, e.g. `/node_modules/rxjs/dist/esm/internal/Observable`. */
+    spec: string;
+    /** Registry key: node_modules-relative file path, e.g. `node_modules/rxjs/dist/esm/internal/Observable.js`. */
+    key: string;
+    absPath: string;
+}
+/** Registry key for a physical file: substring from the LAST node_modules segment. */
+export declare function depsRegistryKeyForFile(absPath: string): string | null;
+/**
+ * Same extension/index fan-out the /ns/m route uses for a served spec,
+ * platform-suffixed variants first (`canvas` → `canvas.ios.js` before
+ * `canvas.js`, `Paywall` → `Paywall/index.ios.js`) so shim lookup lands on
+ * the same file the per-module pipeline would serve.
+ */
+export declare function buildDepsCandidateSpecs(spec: string, platform: string): string[];
+/**
+ * Map recorded boot paths to bundle entries. Skips: non-node_modules paths,
+ * blocked packages, the never-bundled `@nativescript/core` + `@nativescript/vite`
+ * realms, non-script assets, symlinked workspace-source packages, and files
+ * that cannot be resolved on disk (they stay per-module).
+ */
+export declare function resolveDepsEntriesFromRecording(recordedPaths: readonly string[], projectRoot: string, workspaceRoot: string | null, platform: string): DepsBundleEntry[];
+export interface DepsVendorSeed {
+    entries: DepsBundleEntry[];
+    /** Vendor-manifest specifier (e.g. `@ngrx/store`) → registry key of its entry file. */
+    vendorSpecToKey: Map<string, string>;
+}
+/**
+ * Seed bundle entries from the vendor collection (direct NativeScript-plugin
+ * and framework deps from package.json). This makes the bundle exist on the
+ * very first boot — no recording needed — and produces the specifier→key map
+ * that backs `__nsVendorRegistry` (see buildDepsVendorRuntimeModule), so
+ * `ns-vendor://<pkg>` wrappers resolve into THIS bundle's realm.
+ */
+export declare function resolveDepsEntriesFromVendorCollection(projectRoot: string, workspaceRoot: string | null, platform: string, flavor: string | undefined): DepsVendorSeed;
+/**
+ * Synthetic esbuild entry: evaluate the dep closure once and expose every
+ * bundled file's live namespace through `globalThis.__NS_DEPS_MODULES__`,
+ * keyed by node_modules-relative file path.
+ */
+export declare function buildDepsBundleEntryCode(files: readonly {
+    key: string;
+    absPath: string;
+}[]): string;
+export interface DepsBundleState {
+    /** Full ESM payload served at /ns/deps-bundle.mjs. */
+    code: string;
+    /** Registry keys (node_modules-relative file paths) present in the bundle. */
+    keys: Set<string>;
+    /** Served-spec → registry key for every recorded entry. */
+    specToKey: Map<string, string>;
+    /** Registry key → source file (export-name discovery for shims). */
+    keyToFile: Map<string, string>;
+    /** Vendor-manifest specifier → registry key (backs __nsVendorRegistry). */
+    vendorSpecToKey: Map<string, string>;
+    hash: string;
+    builtAt: number;
+    buildMs: number;
+}
+export interface GenerateDepsBundleOptions {
+    projectRoot: string;
+    platform: Platform | string;
+    mode: 'development' | 'production' | string;
+    flavor?: string;
+    verbose?: boolean;
+    recordedPaths: readonly string[];
+}
+export declare function computeDepsBundleCacheKey(input: {
+    platform: string;
+    mode: string;
+    flavor: string;
+    defines: Record<string, string>;
+    entryKeys: readonly string[];
+    lockfile: string;
+    vitePackageVersion: string;
+}): string;
+export declare function tryLoadDepsBundleFromDisk(projectRoot: string, platform: string, key: string): DepsBundleState | null;
+export declare function saveDepsBundleToDisk(projectRoot: string, platform: string, key: string, state: DepsBundleState, verbose?: boolean): void;
+export declare function generateDepsBundle(options: GenerateDepsBundleOptions): Promise<DepsBundleState | null>;
+export interface DepsModuleExportInfo {
+    /** Null when the file is not statically analyzable ESM (stays per-module). */
+    names: string[] | null;
+    hasDefault: boolean;
+}
+/**
+ * Static export-name discovery for a node_modules file. ESM: direct exports
+ * plus recursion through RELATIVE `export * from` chains (the shape deep
+ * package barrels like rxjs's index take). CJS: `exports.NAME` assignment
+ * scanning (esbuild's interop exposes those names on the bundled namespace at
+ * runtime). Returns `names: null` for files whose export surface is not
+ * statically enumerable — UMD factories, a bare `export * from 'pkg'` (the
+ * name set lives in another package), or an unresolvable relative `export *`
+ * target. Those files keep per-module serving, where the transform pipeline
+ * already handles them.
+ */
+export declare function collectDepsModuleExportInfo(absPath: string, platform: string, seen?: Set<string>): DepsModuleExportInfo;
+/**
+ * Shim served at `/ns/m/node_modules/...` for a bundled module. The static
+ * bundle import guarantees the registry is populated before the body reads it
+ * (ESM deps evaluate first). Modules without their own `export default` keep
+ * the self-namespace default so "default import + destructure" consumers work
+ * (same contract as the /ns/core bundle shims).
+ */
+export declare function buildDepsShimCode(key: string, exportNames: readonly string[], hasOwnDefaultExport: boolean): string;
+/**
+ * The dev-session `/@nativescript/vendor.mjs` module, backed by the deps
+ * bundle. The session bootstrap imports it and hands `__nsVendorModuleMap` +
+ * `vendorManifest` to `installVendorBootstrap`, which populates
+ * `__nsVendorRegistry` — so `ns-vendor://<pkg>` wrappers and
+ * `__nsVendorRequire` resolve package roots into the SAME realm as every
+ * `/ns/m` shim. Map entries are emitted for both the collected specifier and
+ * its manifest-canonical alias so wrapper lookups hit either form.
+ * `@nativescript/core` is the one non-deps entry: a bare import the device
+ * import map routes to the `/ns/core` bridge realm.
+ */
+export declare function buildDepsVendorRuntimeModule(vendorSpecToKey: ReadonlyMap<string, string>, manifest: {
+    modules?: Record<string, unknown>;
+    aliases?: Record<string, string>;
+} | null): string;
+export interface DepsBundleService {
+    /** Resolves the built bundle, or null (nothing to bundle / build failed / disabled). */
+    ensureBuilt(): Promise<DepsBundleState | null>;
+    getState(): DepsBundleState | null;
+    hasFailed(): boolean;
+    /**
+     * Shim body for a served `/node_modules/...` spec, or null when the spec
+     * is not bundled (or the bundle is not ready) — caller falls through to
+     * per-module serving.
+     */
+    getShimForSpec(spec: string): string | null;
+    /**
+     * Stop handing out NEW shims for the rest of the session (dependency set
+     * changed mid-session). The bundle payload stays servable so shims already
+     * delivered to devices keep resolving.
+     */
+    disableServingForSession(reason: string): void;
+    isServingDisabled(): boolean;
+}
+export interface CreateDepsBundleServiceOptions extends Omit<GenerateDepsBundleOptions, 'recordedPaths'> {
+    getRecordedPaths(): readonly string[] | null;
+}
+export declare function createDepsBundleService(options: CreateDepsBundleServiceOptions): DepsBundleService;
+/**
+ * Process-wide deps bundle service derived from the dev server's config + CLI
+ * flags (one dev server per process, like the core bundle service). Returns
+ * null when per-module serving is forced via `NS_DEPS_PER_MODULE=1`. The
+ * recording source is the persisted boot recording — the in-session recorder
+ * starts from the same file, and mid-session recordings apply on the next
+ * dev-server start.
+ */
+export declare function getSharedDepsBundleService(server: ViteDevServer): DepsBundleService | null;
+/** Test seam: drop the shared service so specs can mount fresh. */
+export declare function resetSharedDepsBundleServiceForTests(): void;
+/** GET /ns/deps-bundle.mjs — the single-eval dep closure payload. */
+export declare function registerDepsBundleRoute(server: ViteDevServer, service: DepsBundleService): void;