@rangojs/router 0.22.1 → 0.23.0

package/dist/types/vite/plugins/hoist/literal.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Literal-level helpers shared by the build-time predicate hoists
+ * (transition-when-hoist.ts moves a `when` from a server module into a
+ * "use client" one; client-urls-revalidate-hoist.ts moves a `revalidate()`
+ * from a "use client" module into a server one): finding a urls-callback
+ * helper's calls, the lexical-capture check, and the free imports a literal
+ * re-emits in its new module.
+ */
+import { type ImportBinding, type Node, type Reference, type Scope } from "./scope.js";
+/** The offset after the directive prologue (0 when there is none). */
+export declare function directivePrologueEnd(program: Node): number;
+export declare function parseLang(file: string): "ts" | "tsx" | "jsx";
+export declare function unwrapExpression(node: Node): Node;
+export declare function isFunctionLiteral(node: Node): boolean;
+export declare function propertyKeyIs(prop: Node, name: string): boolean;
+/** Which helper calls {@link findHelperCalls} looks for. */
+interface HelperCallSpec {
+    /** Module specifiers the builder (and a direct helper import) come from. */
+    readonly sources: ReadonlySet<string>;
+    /** The builder export whose callback's first parameter hands out `helper`. */
+    readonly builder: string;
+    readonly helper: string;
+    /** A direct import of `helper` from `sources` counts too. */
+    readonly directImport: boolean;
+}
+interface HelperCall {
+    readonly call: Node;
+    readonly scope: Scope;
+}
+/**
+ * Every call of `spec.helper` the builder's callback hands out: destructured,
+ * renamed or as `helpers.<helper>`, at any depth of the callback, plus a
+ * direct import when `spec.directImport`. A builder is recognised by its
+ * import (named, renamed, or through a namespace); any other function of the
+ * same name is left alone.
+ */
+export declare function findHelperCalls(program: Node, scopeOf: Map<Node, Scope>, moduleScope: Scope, imports: Map<string, ImportBinding>, spec: HelperCallSpec): HelperCall[];
+/**
+ * What a lexical-capture error says, per hoist direction. `lexical` explains
+ * each construct (`this`, `arguments`, `super`, `new.target`); `captureHint`
+ * and `loadsHint` follow every capture and module-load message;
+ * `importMetaWhy`, `importMetaMemberWhy` and `dynamicImportWhy` explain the
+ * module-loading expressions.
+ */
+export interface LexicalCaptureMessages {
+    readonly lexical: Readonly<Record<string, string>>;
+    readonly captureHint: string;
+    readonly loadsHint: string;
+    readonly importMetaWhy: string;
+    readonly importMetaMemberWhy: string;
+    readonly dynamicImportWhy: string;
+}
+/**
+ * The first use in a literal of a lexical context it would lose when hoisted
+ * (`this`, `arguments`, `super`, `new.target` of an enclosing function or
+ * object), or of a module-loading expression the build cannot check
+ * (`import()`, `import.meta` other than `import.meta.env`). A nested
+ * non-arrow function (or class body) owns its `this`/`arguments`, so uses
+ * inside one are fine; a method literal owns them too, but its `super`
+ * loses the object it was defined on.
+ */
+export declare function findLexicalCapture(literal: Node, references: readonly Reference[], code: string, messages: LexicalCaptureMessages): {
+    node: Node;
+    detail: string;
+} | null;
+/** The free references of a literal, by what they resolve to. */
+interface FreeReferences {
+    /** Import local name -> whether any use is a value use. */
+    readonly imports: Map<string, boolean>;
+    /** Value references to a binding declared outside the literal that is not an import. */
+    readonly bindings: readonly Reference[];
+    /** References declared nowhere (window, URL, console, ...). */
+    readonly globals: readonly Reference[];
+}
+/** Every reference inside `literal` to something declared outside it. */
+export declare function collectFreeReferences(literal: Node, references: readonly Reference[], moduleScope: Scope, imports: Map<string, ImportBinding>): FreeReferences;
+/**
+ * Re-emit the imports a literal uses, grouped per source, type-only uses as
+ * `import type`. `checkValueImport` runs first for each value use and throws
+ * to reject one.
+ */
+export declare function emitImports(used: Map<string, boolean>, imports: Map<string, ImportBinding>, checkValueImport: (local: string, binding: ImportBinding) => Promise<void> | void): Promise<string[]>;
+export {};

package/dist/types/vite/plugins/hoist/scope.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Scope analysis shared by the build-time predicate hoists
+ * (transition-when-hoist.ts, client-urls-revalidate-hoist.ts): a module's
+ * scope tree, every identifier reference, and its imports. Enough of ES
+ * scoping for the free-variable analysis of one literal.
+ */
+export type Node = any;
+export interface ImportBinding {
+    readonly source: string;
+    /** "default", "*", or the imported name. */
+    readonly imported: string;
+    readonly typeOnly: boolean;
+}
+export declare class Scope {
+    readonly parent: Scope | null;
+    readonly isFunction: boolean;
+    readonly node: Node;
+    readonly declarations: Set<string>;
+    constructor(parent: Scope | null, isFunction: boolean, node: Node);
+    nearestFunction(): Scope;
+    lookup(name: string): Scope | null;
+}
+export interface Reference {
+    readonly node: Node;
+    readonly scope: Scope;
+    readonly typeOnly: boolean;
+}
+export declare const TYPE_KEYS: ReadonlySet<string>;
+/**
+ * Scope tree and every identifier reference of a module, TS type positions
+ * flagged. Enough of ES scoping for free-variable analysis of one literal:
+ * var hoists to the function scope, let/const/class to the block, function
+ * declarations to their block.
+ */
+export declare function analyzeScopes(program: Node): {
+    moduleScope: Scope;
+    references: Reference[];
+    scopeOf: Map<Node, Scope>;
+};
+export declare function collectImports(program: Node): Map<string, ImportBinding>;

package/dist/types/vite/plugins/hoist/source.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Source reading shared by the build-time predicate hoists
+ * (transition-when-hoist.ts, client-urls-revalidate-hoist.ts): which ids are
+ * source files, reading one off disk, resolving an import to the file it
+ * names, and the "emitted or disk" lookup behind their `?rango-*` modules.
+ */
+/** A file path (query already stripped) a hoist transform may rewrite. */
+export declare const SOURCE_FILE_RE: RegExp;
+export declare function readSource(file: string): Promise<string | null>;
+/** The part of a plugin context {@link resolveSourceTarget} needs. */
+export interface SourceResolver {
+    resolve(source: string, importer?: string): Promise<{
+        id: string;
+        external?: boolean | string;
+    } | null>;
+}
+/**
+ * The file `source` names when imported from `importer`, query stripped, or
+ * null when it is external or virtual. `skipNodeModules` also yields null for
+ * a dependency: transition-when-hoist only looks for `import "server-only"`
+ * in project files, while client-urls-revalidate-hoist must see the
+ * "use client" directive of a package's modules too.
+ */
+export declare function resolveSourceTarget(ctx: SourceResolver, source: string, importer: string, options: {
+    readonly skipNodeModules: boolean;
+}): Promise<string | null>;
+/** What a hoist's RSC transform emitted for a file, and the disk source it saw. */
+export interface EmittedEntry<T> {
+    readonly disk: string | null;
+    readonly value: T;
+}
+export declare function recordEmitted<T>(emitted: Map<string, EmittedEntry<T>>, file: string, value: T): Promise<void>;
+/**
+ * What a `?rango-*` load serves for `hoistedFile`: the transform's emission
+ * when it saw the current disk source (or the file is gone), else
+ * `rehoist(disk)`. The transform hoists the pipeline code, which an earlier
+ * plugin may have changed, so re-hoisting the disk source is the fallback only
+ * for an environment loading before the RSC transform ran or for an edit the
+ * RSC environment has not re-transformed yet. Undefined when neither exists.
+ */
+export declare function loadEmittedOrDisk<T>(emitted: ReadonlyMap<string, EmittedEntry<T>>, hoistedFile: string, rehoist: (disk: string) => Promise<T | undefined>): Promise<T | undefined>;

package/dist/types/vite/plugins/transition-when-hoist.d.ts

@@ -2,14 +2,14 @@ import type { Plugin } from "vite";
 import MagicString from "magic-string";
 /** Specifiers that can never load in the browser. */
 export declare function isServerOnlySpecifier(source: string): boolean;
-export interface HoistTransitionWhenDeps {
+interface HoistTransitionWhenDeps {
     /**
      * Whether an import the literal re-emits is server-only beyond its
      * specifier (the plugin resolves it and looks for `import "server-only"`).
      */
     isServerOnlyImport?(source: string): Promise<boolean> | boolean;
 }
-export interface HoistTransitionWhenResult {
+interface HoistTransitionWhenResult {
     readonly code: string;
     readonly map: ReturnType<MagicString["generateMap"]>;
     /** Virtual module source per hoisted literal, by index. */
@@ -32,14 +32,11 @@ export declare function parseHoistedWhenId(id: string): {
  * evaluated) and serves the `?rango-when=N` modules in every environment
  * (RSC, SSR and client all load them).
  *
- * `load` serves the modules the transform emitted, not a re-hoist of the file
- * on disk: the transform hoists the pipeline code, which an earlier plugin
- * may have changed, so re-hoisting the disk source can number the literals
- * differently and serve the wrong one for index N. The disk source is the
- * fallback only when the transform has not seen the current file: an
- * environment loading before the RSC transform ran (the order environments
- * ask in is not fixed), or an edit the RSC environment has not re-transformed
- * yet (serving the last transform would then be stale). The map is per
- * plugin instance, so every environment of one dev server or build shares it.
+ * `load` serves the modules the transform emitted (loadEmittedOrDisk), not a
+ * re-hoist of the file on disk: re-hoisting a disk source an earlier plugin
+ * changed can number the literals differently and serve the wrong one for
+ * index N. The map is per plugin instance, so every environment of one dev
+ * server or build shares it.
  */
 export declare function transitionWhenHoistPlugin(): Plugin;
+export {};

package/dist/types/vite/router-discovery.d.ts

@@ -8,6 +8,16 @@
 import type { Plugin, ViteDevServer } from "vite";
 import { VIRTUAL_ROUTES_MANIFEST_ID, type DiscoveryState, type PluginOptions } from "./discovery/state.js";
 export { VIRTUAL_ROUTES_MANIFEST_ID };
+/** The slice of a Vite environment module graph the route-file watcher reads. */
+interface ModulesByFileGraph {
+    getModulesByFile(file: string): ReadonlySet<unknown> | undefined;
+}
+/**
+ * Whether the dev route-file watcher ignores `file`: it sits in a directory
+ * every discovery scan skips (isInSkippedScanDir) and the RSC graph has not
+ * loaded it. See docs/manifests.md, "A reload no file of the app asked for".
+ */
+export declare function isFileOutsideApp(root: string, file: string, rscGraph: ModulesByFileGraph | undefined): boolean;
 /**
  * Create a minimal Vite server for router discovery.
  *