diff --git a/docs/router/guide/automatic-code-splitting.md b/docs/router/guide/automatic-code-splitting.md index 945748c391..2c7ecc07a4 100644 --- a/docs/router/guide/automatic-code-splitting.md +++ b/docs/router/guide/automatic-code-splitting.md @@ -146,7 +146,7 @@ Any of these lets the declaration load with the split chunk, from the least to t - **Create it on first use**, for example `let instance; const getConfetti = () => (instance ??= new JSConfetti())`: a function has no side effects when it is declared. - **Tell the compiler that the call has no side effects**, with one of these annotations: - `/* @__PURE__ */` before the call (`validateSearch: /* @__PURE__ */ type({ … })`), whatever the function is; - - `/* #__NO_SIDE_EFFECTS__ */` on a function declared in the route file itself: `/* #__NO_SIDE_EFFECTS__ */ function makeSchema(…) { … }` or `const makeSchema = /* #__NO_SIDE_EFFECTS__ */ (…) => …`, exported or not. + - `/* #__NO_SIDE_EFFECTS__ */` on a function declared in the route file itself: `/* #__NO_SIDE_EFFECTS__ */ function makeSchema(…) { … }` or `const makeSchema = /* #__NO_SIDE_EFFECTS__ */ (…) => …`, exported or not, declared before or after the call. The call then runs when the route file loads, which may be before the declaration: annotate only calls whose order does not matter. diff --git a/packages/router-plugin/src/planners/decisions.ts b/packages/router-plugin/src/planners/decisions.ts index 596047c53d..2d0e9b898c 100644 --- a/packages/router-plugin/src/planners/decisions.ts +++ b/packages/router-plugin/src/planners/decisions.ts @@ -6,13 +6,13 @@ */ import { unwrapExpression, walk } from '@tanstack/router-utils/compiler' import { splitGroupingsSchema } from '../core/config' -import { defaultCodeSplitGroupings } from '../core/constants' import { declaratorOf, identifierSymbol, isAlreadyLazy, isExportedSymbol, isFallbackLiteral, + liveInEnv, propertyKeyName, propertyRangeWithComma, recognizeRoute, @@ -152,9 +152,9 @@ function effectiveGroupings( return fromPlugin } } - return cfg.defaultGroupings.length > 0 - ? cfg.defaultGroupings - : defaultCodeSplitGroupings + // `[]` splits nothing unless `splitBehavior` or the route says so (as + // before this compiler: `defaultBehavior || default`) + return cfg.defaultGroupings } function methodPrefixOf(fn: Node): string { @@ -496,7 +496,7 @@ function computeSplitPlan( if ( valueSym !== null && ctx.symbols.isModuleLevel(valueSym) && - ctx.t1.mutation.isReassigned(valueSym) + ctx.t1.mutation.isReassigned(valueSym, liveInEnv(ctx)) ) { // the options object holds the binding's value at route creation; a // chunk re-exporting the live binding would render its latest value diff --git a/packages/router-plugin/src/planners/route.ts b/packages/router-plugin/src/planners/route.ts index e5e3da7ad4..c8568c0217 100644 --- a/packages/router-plugin/src/planners/route.ts +++ b/packages/router-plugin/src/planners/route.ts @@ -9,6 +9,7 @@ */ import { digestOf, unwrapExpression } from '@tanstack/router-utils/compiler' import type { + ClassifiedRef, Diagnostic, ModuleAnalysis, PlanContext, @@ -34,7 +35,7 @@ const FACTORIES: ReadonlySet = new Set([ 'createLazyFileRoute', ]) -/** Packages whose `createFileRoute` & co. are the router's (Start re-exports them). */ +/** Packages whose `createFileRoute` & co. are the router's. */ export const ROUTER_PACKAGE_RE = /^@tanstack\/(react|solid|vue)-(router|start)(\/|$)/ @@ -260,12 +261,17 @@ export function declaratorOf( ) { return null } - if (t1.mutation.isReassigned(sym)) { + if (t1.mutation.isReassigned(sym, liveInEnv(ctx))) { return null } return { unit, init: unit.node.init } } +/** R1: the mutation model as the env output sees it (a write inside code the environment erases imposes nothing). */ +export function liveInEnv(ctx: PlanContext): (ref: ClassifiedRef) => boolean { + return ctx.liveness('env').live +} + function readGroupings( ctx: PlanContext, value: Node, diff --git a/packages/router-plugin/tests/integration/code-splitter-router.test.ts b/packages/router-plugin/tests/integration/code-splitter-router.test.ts index 1acfc9b8aa..5ce05b5eae 100644 --- a/packages/router-plugin/tests/integration/code-splitter-router.test.ts +++ b/packages/router-plugin/tests/integration/code-splitter-router.test.ts @@ -225,3 +225,47 @@ export async function renderPreloaded() { expect(await renderPreloaded(true)).toEqual(preloaded) }, 120_000) }) + +// `defaultBehavior: []` means what it did before this compiler: no route +// option is split unless `splitBehavior` (or the route's own groupings) +// says so. +test('an empty `defaultBehavior` splits nothing but what `splitBehavior` asks for', async () => { + const app = await build({ + bundler: 'vite', + env: 'client', + files: { + 'routes/__root.tsx': rootRoute, + 'routes/heavy.tsx': `${head}export const Route = createFileRoute('/heavy')({ + component: () =>

{'MARK_HEAVY'}

, +}) +`, + 'routes/light.tsx': `${head}export const Route = createFileRoute('/light')({ + component: () =>

{'MARK_LIGHT'}

, +}) +`, + 'entry.ts': entries.client, + }, + pluginOptions: { + codeSplittingOptions: { + defaultBehavior: [], + splitBehavior: ({ routeId }) => + routeId === '/heavy' ? [['component']] : undefined, + }, + }, + }) + const { result } = await app.run(`const results = {} +for (const [path, marker] of [['/heavy', 'MARK_HEAVY'], ['/light', 'MARK_LIGHT']]) { + results[path] = (await entry.renderAt(path, marker)).includes(marker) +} +return results`) + expect({ + placement: { + heavy: app.where('MARK_HEAVY'), + light: app.where('MARK_LIGHT'), + }, + rendered: result, + }).toEqual({ + placement: { heavy: 'lazy', light: 'eager' }, + rendered: { '/heavy': true, '/light': true }, + }) +}, 120_000) diff --git a/packages/router-plugin/tests/integration/code-splitter-split-only-eager.test.ts b/packages/router-plugin/tests/integration/code-splitter-split-only-eager.test.ts index 0648db8e48..3a93a7a2e9 100644 --- a/packages/router-plugin/tests/integration/code-splitter-split-only-eager.test.ts +++ b/packages/router-plugin/tests/integration/code-splitter-split-only-eager.test.ts @@ -69,6 +69,16 @@ export const Route = createRootRoute({ component: () => }) '/* #__NO_SIDE_EFFECTS__ */ function makeSchema(shape: T) { return shape }\n', ' validateSearch: makeSchema({ tab: "string" }),', ), + // the annotated callee declared after the call (hoisted): the + // annotation counts in any order + 'routes/no-side-effects-after.tsx': `${head}import { Marker } from '../marker' +const marker = new Marker('MARK_no-side-effects-after_END') +export const Route = createFileRoute('/no-side-effects-after')({ + validateSearch: makeSchema({ tab: "string" }), + component: () =>

{marker.name}

, +}) +/* #__NO_SIDE_EFFECTS__ */ function makeSchema(shape: T) { return shape } +`, // declared after the route: moving it never crosses the call 'routes/declared-after.tsx': `${head}import { Marker } from '../marker' import { makeSchema } from '../schema' @@ -89,6 +99,7 @@ const lazyRoutes = [ 'declared-first', 'declared-after', 'no-side-effects', + 'no-side-effects-after', 'nothing-pinned', ] @@ -112,23 +123,6 @@ function expectPinnedWarning( }), times: 1, }) - const [warning] = findDiagnostics(diagnostics, { - severity: 'warning', - file: 'routes/pinned.tsx', - root, - }) - const call = diagnosticPosition(pinned, 'makeSchema({') - for (const part of [ - '`marker`', - '`makeSchema(…)`', - '`validateSearch`', - `line ${call.line}`, - 'declare `marker` after `Route`', - '`/* @__PURE__ */`', - '`component`', - ]) { - expect(warning!.text).toContain(part) - } } const builds: Array<[string, () => Promise]> = [ diff --git a/packages/router-utils/src/compiler/README.md b/packages/router-utils/src/compiler/README.md index a7b5f2bf29..ccdb8edddb 100644 --- a/packages/router-utils/src/compiler/README.md +++ b/packages/router-utils/src/compiler/README.md @@ -53,11 +53,13 @@ units that output contains. The same computation decides: chunks import it; one several groups need goes to a lazy shared module; copyable primitives and import specifiers are duplicated. An exported binding only split code needs leaves the route module for a side-effect-free extracted module (`?tsr-split=export~Name`) that the route module re-exports, so other modules importing it from the route - file still get one instance and the route module keeps none of its code or imports. A split chunk never imports - that module: when the binding is pure and never assigned (a function, class, component, pure constant), the chunk - carries its own copy, with the pure declarations and imports only they share; what has effects or state (an - effectful initialiser, an assigned `let`, a reader of mutable state, an augmented binding) is one instance that - the chunk imports, from the extracted module when only it needs it, else from the route module. Nothing but + file still get one instance and the route module keeps none of its code or imports. The rule for the route's own + chunks (R77): when the binding is pure and never assigned (a function, class, component, pure constant), the chunk + carries its own copy, with the pure declarations and imports only they share, and never imports the extracted + module; what has effects or state (an effectful initialiser, an assigned `let`, a reader of mutable state, an + augmented binding) is one instance that the chunk imports, from the extracted module when only it needs it, else + from the route module. Writes inside code the environment erases impose nothing (R1: the mutation model is read + through the env output's liveness). Nothing but importers of the route file reach the extracted module, so a bundler drops it when unused; the route's chunks never depend on where a bundler places it (Rolldown < 1.1.5 and a user `manualChunks` group that merges into the entry placed it with the entry). In dev nothing is bundled and the static re-export would only load the extracted @@ -138,8 +140,8 @@ directives, never license comments. (TanStack's own audited APIs, e.g. `getRouteApi`; the router planner owns the table, Start's recognizer reuses it). Tier 0 recognises imports of such an export from the package itself by binding (renamed, or a namespace member); an app module re-exporting it is not followed, and a third party's purity is never assumed. -- `RawFactsCache` owns the raw text per canonical id and serves summaries and import-protection _target facts_ - (marker, export names, effect classification, evaluation and lazy imports) from one read. +- `RawFactsCache` retains, per canonical id, the facts of one read and its revision, and serves summaries and + import-protection _target facts_ (marker, export names, effect classification, evaluation and lazy imports) from it. ## Pipeline (`pipeline.ts` `compileModule`) diff --git a/packages/router-utils/src/compiler/analysis.ts b/packages/router-utils/src/compiler/analysis.ts index 9db02c5d83..dfc52ee942 100644 --- a/packages/router-utils/src/compiler/analysis.ts +++ b/packages/router-utils/src/compiler/analysis.ts @@ -13,7 +13,7 @@ import { analyzeHeader } from './header' import { SymbolTable, valueBinding } from './symbols' import { buildItems, buildUnits, writesMember } from './units' import { MutationModel } from './mutation' -import { statementHasEffects } from './purity' +import { seedNoSideEffectDeclarations, statementHasEffects } from './purity' import type { PurityContext } from './purity' import type { Header, Range } from './header' import type { SymbolId } from './symbols' @@ -347,6 +347,7 @@ export class ModuleAnalysis { } } const body = file.program.body + seedNoSideEffectDeclarations(this.purity, noSideEffectCallees, body) for (let i = this.header.directiveCount; i < body.length; i++) { const stmt = body[i]! switch (stmt.type) { diff --git a/packages/router-utils/src/compiler/eager-exports.ts b/packages/router-utils/src/compiler/eager-exports.ts index 3a00d15a23..fc5f9e12a5 100644 --- a/packages/router-utils/src/compiler/eager-exports.ts +++ b/packages/router-utils/src/compiler/eager-exports.ts @@ -1,13 +1,14 @@ /** * Extracted-export outputs (`?tsr-split=export~Name`) an entry chunk of a - * client build holds. A route's own chunks never import such a module (they - * copy the binding, `reach.ts`): one reaches the entry only when a module - * loaded with the entry imports the binding through the route file (Rollup - * and Rolldown), or when any module imports it through the route file and - * the bundler cannot bypass the route module's re-export (webpack and - * Rspack without `"sideEffects": false`). The export is then eager and the - * route's chunk carries its copy: the build warns once per (file, export), - * in every host (J2.8: the user is told, the build goes on). + * client build holds. A route's own chunks copy a pure export instead of + * importing its module, and import a stateful or effectful one from it + * only when they alone need it (`reach.ts`, R77): the module reaches the + * entry only when a module loaded with the entry imports the binding + * through the route file (Rollup and Rolldown), or when any module imports + * it through the route file and the bundler cannot bypass the route + * module's re-export (webpack and Rspack without `"sideEffects": false`). + * The export is then eager: the build warns once per (file, export), in + * every host (J2.8: the user is told, the build goes on). */ import { identify } from './identity' @@ -134,5 +135,5 @@ export function eagerExportWarning( bundler === 'webpack' ? 'Move it to its own module and import it from there, or declare "sideEffects": false in package.json so the bundler can bypass the route file, so the importer and the route share one instance.' : 'Move it to its own module and import it from there, so the importer and the route share one instance.' - return `[tanstack-router] The export \`${e.name}\` of "${e.file}" loads with the entry chunk: another module imports it through the route file, so the bundler keeps it with the route module, while the route's own chunk carries its copy. ${share}` + return `[tanstack-router] The export \`${e.name}\` of "${e.file}" loads with the entry chunk: another module imports it through the route file, so the bundler keeps it with the route module instead of leaving it to the split code that needs it. ${share}` } diff --git a/packages/router-utils/src/compiler/facts.ts b/packages/router-utils/src/compiler/facts.ts index 52a0366881..dba8a8cd24 100644 --- a/packages/router-utils/src/compiler/facts.ts +++ b/packages/router-utils/src/compiler/facts.ts @@ -396,13 +396,16 @@ export class RawFactsCache { if (!facts.opaque) { return facts } - // an opaque module's target facts are asked for (a mock of it): parsed now, once + // an opaque module's target facts are asked for (a mock of it): parsed + // now, once. Its summary stays null: the module is opaque to the + // summaries whether or not a mock asked about it, so the digest plans + // recorded (`null`) stays current and nothing is evicted by the question const e = this.entries.get(canonicalId) - if (e?.pending) { - return e.pending - } const text = await this.read(canonicalId) - const full = this.build(canonicalId, text, true) + const full: RawFacts = { + ...this.build(canonicalId, text, true), + summary: null, + } if (e && this.entries.get(canonicalId) === e && e.facts === facts) { e.facts = full } diff --git a/packages/router-utils/src/compiler/mutation.ts b/packages/router-utils/src/compiler/mutation.ts index 4dc7234497..5dac8a9398 100644 --- a/packages/router-utils/src/compiler/mutation.ts +++ b/packages/router-utils/src/compiler/mutation.ts @@ -6,10 +6,11 @@ * what they write, ordered evaluation, the movable test, the extraction * candidates, the split planner's identifier option values, the server-fn * hoist and the Hydrate setters. A view over the classified references - * (nothing is built until a binding is asked about, and then once); erasure - * (which writes survive in an output) and the region holding a write - * (planners register sub-regions after the analysis) are the consumer's - * business, so the model is pristine. + * (nothing is built until a binding is asked about, and then once). The + * model is pristine: erasure is the consumer's business, passed as the + * `live` filter of the predicates (R1: a write inside erased code imposes + * nothing), and the region holding a write (planners register sub-regions + * after the analysis) is read from the regions. */ import type { ClassifiedRef, RefIndex } from './analysis' import type { SymbolId } from './symbols' @@ -46,13 +47,23 @@ export class MutationModel { return hit } - /** The binding is assigned somewhere: its value is not the one its declaration gave it. */ - isReassigned(sym: SymbolId): boolean { - return this.sitesOf(sym).some((r) => r.kind === 'write') + /** + * The binding is assigned somewhere (`live`: in code an output keeps): + * its value is not the one its declaration gave it. + */ + isReassigned(sym: SymbolId, live?: (ref: ClassifiedRef) => boolean): boolean { + return this.sitesOf(sym).some( + (r) => r.kind === 'write' && (live === undefined || live(r)), + ) } - /** The binding is assigned, or a member of what it names written, somewhere: a read of it depends on when it runs. */ - isMutated(sym: SymbolId): boolean { - return this.sitesOf(sym).length > 0 + /** + * The binding is assigned, or a member of what it names written, + * somewhere (`live`: in code an output keeps): a read of it depends on + * when it runs. + */ + isMutated(sym: SymbolId, live?: (ref: ClassifiedRef) => boolean): boolean { + const sites = this.sitesOf(sym) + return live === undefined ? sites.length > 0 : sites.some(live) } } diff --git a/packages/router-utils/src/compiler/pipeline.ts b/packages/router-utils/src/compiler/pipeline.ts index 3819210bda..b6d43fffc6 100644 --- a/packages/router-utils/src/compiler/pipeline.ts +++ b/packages/router-utils/src/compiler/pipeline.ts @@ -510,9 +510,13 @@ async function runAttempt( // at least one more region of the module, so they end within the // number of regions. Past that bound (a planner registering new regions // every round) the module is planned with every sub-region kept in - // place, which is always correct, and a warning says so. + // place, which is always correct, and a warning says so. The bound is + // the region count after the first round: regions accumulate across + // rounds (one Tier 1 per module), so a planner registering a new region + // every round would move a bound read each round out of reach. let fallbacks: Array = [] let plan!: AnalysisPlan + let bound = 0 for (let round = 0; ; round++) { plan = planRound( t0, @@ -532,10 +536,13 @@ async function runAttempt( g.range.start === f.range.start && g.range.end === f.range.end, ), ) + if (round === 0) { + bound = plan.t1.regions.regions.length + } if (fresh.length === 0) { break } - if (round >= plan.t1.regions.regions.length) { + if (round >= bound) { fallbacks = plan.t1.regions.regions .filter((r) => r.kind !== 'unit') .map((r) => ({ range: r.range, kind: r.kind, reason: 'exhausted' })) diff --git a/packages/router-utils/src/compiler/purity.ts b/packages/router-utils/src/compiler/purity.ts index a5c6437375..e860fcc1ad 100644 --- a/packages/router-utils/src/compiler/purity.ts +++ b/packages/router-utils/src/compiler/purity.ts @@ -67,6 +67,58 @@ export function commentBefore( return c } +/** + * Marks the module's own `#__NO_SIDE_EFFECTS__` callees (a function + * declaration, `const f = /* #__NO_SIDE_EFFECTS__ *\/ () => …`, exported or + * not) before any statement is classified: a function declaration is + * hoisted, so a call may precede it, and Tier 0 and the unit model must + * classify the same statement alike. The one seeding of local callees. + */ +export function seedNoSideEffectDeclarations( + ctx: PurityContext, + callees: Set, + body: ReadonlyArray, +): void { + if (!ctx.comments.some((c) => NSE_RE.test(c.value))) { + return + } + const mark = (id: Node) => { + const b = id.type === 'Identifier' ? ctx.file.rootScope.find(id.name) : null + if (b) { + callees.add(b.id) + } + } + for (const stmt of body) { + const decl = + stmt.type === 'ExportNamedDeclaration' || + stmt.type === 'ExportDefaultDeclaration' + ? stmt.declaration + : stmt + if (!decl) { + continue + } + if (decl.type === 'FunctionDeclaration' && decl.id) { + if ( + hasNoSideEffectsAnnotation(ctx, decl) || + (decl !== stmt && hasNoSideEffectsAnnotation(ctx, stmt)) + ) { + mark(decl.id) + } + } else if (decl.type === 'VariableDeclaration') { + for (const d of decl.declarations) { + if ( + d.init && + (d.init.type === 'ArrowFunctionExpression' || + d.init.type === 'FunctionExpression') && + hasNoSideEffectsAnnotation(ctx, d.init) + ) { + mark(d.id) + } + } + } + } +} + export function hasPureAnnotation(ctx: PurityContext, node: Node): boolean { const c = commentBefore(ctx.comments, ctx.file.source, node.start) return c !== null && PURE_RE.test(c.value) diff --git a/packages/router-utils/src/compiler/reach.ts b/packages/router-utils/src/compiler/reach.ts index 41342324d6..d77a468edc 100644 --- a/packages/router-utils/src/compiler/reach.ts +++ b/packages/router-utils/src/compiler/reach.ts @@ -289,6 +289,8 @@ export function computePlacement(input: PlacementInput): Placement { const envTree = treeOf('env') const isLive = (ref: ClassifiedRef, o: OutputId) => !treeOf(o).isErasedAt(ref.range.start) + /** R1: the mutation model as the env output sees it (writes inside erased code impose nothing). */ + const liveInEnv = (ref: ClassifiedRef) => isLive(ref, 'env') // ---- owner index: refs by owning region -------------------------------- const ownedRefs = new Map>() @@ -985,7 +987,7 @@ export function computePlacement(input: PlacementInput): Placement { cl.sideEffects || cl.gens.length > 0 || // a reassigned export stays: its writers would assign an import - t1.mutation.isReassigned(sym) || + t1.mutation.isReassigned(sym, liveInEnv) || // a binding a sub-region writes (Hydrate children, a split option // value) must meet the single-writer rule below: pinning its cluster // to an extracted output would let the writer assign an import @@ -1361,7 +1363,7 @@ export function computePlacement(input: PlacementInput): Placement { !clusters[c]!.effectful && !readsMutableState(c) && !claimHolders.has(c) && - ![...clusters[c]!.declares].some((s) => t1.mutation.isMutated(s)) + ![...clusters[c]!.declares].some((s) => t1.mutation.isMutated(s, liveInEnv)) // ---- env roots and extraction: one fixed point ------------------------- // The env module's roots and the extracted outputs are decided together, @@ -1391,8 +1393,9 @@ export function computePlacement(input: PlacementInput): Placement { derivedStale = false const stop = new Set(remaining.keys()) // a chunk's reach passes through the candidates it copies and stops - // at the others, which it imports; an extracted module's reach stops - // at every other candidate (it imports them) + // at the others, which it imports from their extracted module (one + // instance of state and effects, R77); an extracted module's reach + // stops at every other candidate (it imports them) const chunkStop = new Set([...stop].filter((c) => !copies(c))) for (const [c, e] of extractCandidates) { if (remaining.has(c)) { @@ -1520,7 +1523,7 @@ export function computePlacement(input: PlacementInput): Placement { } const reason: KeptReason = cl.sideEffects ? 'effects' - : t1.mutation.isReassigned(sym) || regionWrittenSyms.has(sym) + : t1.mutation.isReassigned(sym, liveInEnv) || regionWrittenSyms.has(sym) ? 'reassigned' : liveEnv.has(c) ? 'live' diff --git a/packages/router-utils/src/compiler/units.ts b/packages/router-utils/src/compiler/units.ts index 2d7948b61d..b74053bd05 100644 --- a/packages/router-utils/src/compiler/units.ts +++ b/packages/router-utils/src/compiler/units.ts @@ -11,7 +11,6 @@ import { hasRuntimeValue } from './symbols' import { extendOverTrailingLine, isLicenseComment } from './header' import { unwrapExpression } from './source' import { - hasNoSideEffectsAnnotation, isPrimitiveLiteral, isPureClass, isPureDeclarator, @@ -718,14 +717,6 @@ export function buildUnits( const b = file.bindingOf(d.id) u.copyable = b !== null && !b.references.some((r) => r.isWrite) } - if ( - d.init && - (d.init.type === 'ArrowFunctionExpression' || - d.init.type === 'FunctionExpression') && - hasNoSideEffectsAnnotation(purity, d.init) - ) { - markNoSideEffects(d.id) - } out.push(add(item, u)) } break @@ -742,12 +733,6 @@ export function buildUnits( } } u.declNameRanges.push({ start: decl.id.start, end: decl.id.end }) - if ( - hasNoSideEffectsAnnotation(purity, decl) || - hasNoSideEffectsAnnotation(purity, item.node) - ) { - markNoSideEffects(decl.id) - } } out.push(add(item, u)) break @@ -810,13 +795,6 @@ export function buildUnits( return out } - function markNoSideEffects(id: Node): void { - const b = file.bindingOf(id) - if (b) { - ;(purity.noSideEffectCallees as Set).add(b.id) - } - } - function moduleSymOf(node: Node | null): SymbolId | null { if (!node) { return null diff --git a/packages/router-utils/tests/cache.test.ts b/packages/router-utils/tests/cache.test.ts index 77ff00cbf5..ac89f5a486 100644 --- a/packages/router-utils/tests/cache.test.ts +++ b/packages/router-utils/tests/cache.test.ts @@ -239,6 +239,19 @@ describe('releasing an environment', () => { expect(stats(host)).toMatchObject({ plans: 1, planHits: 0 }) }) + it('drops its resolution memo: the next compile asks the host again, the other environment does not', async () => { + const host = new MemoryHost({ files }) + await host.compile('/app/a.ts', planners()) + await host.compile('/app/a.ts', planners(), { env: server }) + const asked = host.resolveCalls.length + expect(asked).toBeGreaterThan(0) + releaseEnvironment(host.caches, env.name) + await host.compile('/app/a.ts', planners(), { env: server }) + expect(host.resolveCalls).toHaveLength(asked) + await host.compile('/app/a.ts', planners()) + expect(host.resolveCalls.length).toBeGreaterThan(asked) + }) + it('leaves nothing of the released plans reachable from the caches', async () => { const gc = (globalThis as { gc?: () => void }).gc expect(gc).toBeTypeOf('function') diff --git a/packages/router-utils/tests/facts.test.ts b/packages/router-utils/tests/facts.test.ts index 593b26e108..325912e21c 100644 --- a/packages/router-utils/tests/facts.test.ts +++ b/packages/router-utils/tests/facts.test.ts @@ -89,13 +89,20 @@ describe('RawFactsCache', () => { expect(lib.summary).toBe(null) expect(await cache.marker('/app/node_modules/lib/index.js')).toBe(null) expect(cache.stats(false)).toMatchObject({ rawFacts: 1, rawFactsOpaque: 1 }) - // a mock of it asks for its target facts: parsed then, and kept + // a mock of it asks for its target facts: parsed then, and kept; the + // module stays opaque to the summaries (its summary digest never + // changes: no plan that summarised the package is evicted by the question) + const before = await cache.digestOf('/app/node_modules/lib/index.js') const target = await cache.getTarget('/app/node_modules/lib/index.js') expect(target.opaque).toBeUndefined() expect(target.targetFacts.exportNames).toEqual(['lib']) - expect( - (await cache.get('/app/node_modules/lib/index.js')).summary, - ).not.toBe(null) + expect((await cache.get('/app/node_modules/lib/index.js')).summary).toBe( + null, + ) + expect(await cache.digestOf('/app/node_modules/lib/index.js')).toBe(before) + expect(await cache.targetDigestOf('/app/node_modules/lib/index.js')).toBe( + target.targetFacts.digest, + ) expect(cache.stats(false)).toMatchObject({ rawFacts: 1, rawFactsOpaque: 0 }) // a marker literal is never opaque: the marker is a parse's finding expect(await cache.marker('/app/node_modules/marked/index.js')).toBe( @@ -197,6 +204,61 @@ describe('target facts of a marked module', () => { }) }) +describe('target facts of an opaque module', () => { + it('are the parsed ones even when a read of the module is in flight (a change raced the question)', async () => { + const files: Record = { + '/app/node_modules/lib/index.js': `export const lib = () => 1\n`, + } + const cache = new RawFactsCache({ + readFile: (p) => Promise.resolve(files[p] ?? null), + loadVirtual: () => Promise.resolve(null), + opaque: (path) => path.includes('/node_modules/'), + }) + await cache.get('/app/node_modules/lib/index.js') + cache.markStale('/app/node_modules/lib/index.js') + // the facts are re-read (opaque again) while a mock asks for the target facts + const [, target] = await Promise.all([ + cache.get('/app/node_modules/lib/index.js'), + cache.getTarget('/app/node_modules/lib/index.js'), + ]) + expect(target.targetFacts.exportNames).toEqual(['lib']) + expect( + (await cache.getTarget('/app/node_modules/lib/index.js')).targetFacts + .exportNames, + ).toEqual(['lib']) + }) +}) + +describe('target facts: own effects', () => { + // `#__NO_SIDE_EFFECTS__` on a callee the module declares counts whatever + // the order of the declaration and the call (function declarations are + // hoisted); Tier 0 and the unit model classify the same statement alike + it('count a call of a `#__NO_SIDE_EFFECTS__` callee declared before or after it as pure', async () => { + const files: Record = { + '/app/before.ts': `/* #__NO_SIDE_EFFECTS__ */ function make(s) { return s }\nexport const schema = make({})\n`, + '/app/after.ts': `export const schema = make({})\n/* #__NO_SIDE_EFFECTS__ */ function make(s) { return s }\n`, + '/app/plain.ts': `export const schema = make({})\nfunction make(s) { return s }\n`, + } + const cache = new RawFactsCache({ + readFile: (p) => Promise.resolve(files[p] ?? null), + loadVirtual: () => Promise.resolve(null), + }) + expect((await cache.get('/app/before.ts')).targetFacts).toMatchObject({ + effectful: false, + codeEffects: false, + }) + expect((await cache.get('/app/after.ts')).targetFacts).toMatchObject({ + effectful: false, + codeEffects: false, + }) + expect((await cache.get('/app/plain.ts')).targetFacts).toMatchObject({ + effectful: true, + codeEffects: true, + effectProvenance: 'own', + }) + }) +}) + describe('target facts: lazy imports', () => { it('lists the literal specifiers of import() and require() apart from the evaluation edges', async () => { const files: Record = { diff --git a/packages/router-utils/tests/pipeline.test.ts b/packages/router-utils/tests/pipeline.test.ts index 7b912a6e20..ba53ad4568 100644 --- a/packages/router-utils/tests/pipeline.test.ts +++ b/packages/router-utils/tests/pipeline.test.ts @@ -5,6 +5,8 @@ import { MemoryHost, dedent, envInfo, + findRouteOptions, + propertyOf, toyEdgePolicyPlanner, toyEnvPlanner, toyHydratePlanner, @@ -635,6 +637,56 @@ describe('slice gates: invalidation', () => { expect(hit!.code).toBe(fresh!.code) }) + it('(d) overlapping save: r2 shares the resolution r1 waits for, and r1 never publishes over r2', async () => { + const gate = deferred() + let suspended = false + const host = new MemoryHost({ + files: { + '/app/consumer.ts': CONSUMER, + '/app/factory-inner.ts': FACTORY('createServerOnlyFn'), + }, + recognizer: RECOGNIZER, + // r1's resolution of `./factory-inner` is slow; r2 asks the same pair + onResolve: async (specifier) => { + if (specifier === './factory-inner' && !suspended) { + suspended = true + await gate.promise + } + }, + }) + const r1 = CONSUMER + const r2 = `${CONSUMER}export const v2 = 2\n` + const planners = [toySummaryPlanner()] + const slow = host.compile('/app/consumer.ts', planners, { code: r1 }) + await new Promise((r) => setTimeout(r, 5)) + host.write('/app/consumer.ts', r2) + await invalidate( + host.caches, + { path: '/app/consumer.ts', kind: 'change' }, + host, + ) + const fresh = host.compile('/app/consumer.ts', planners, { code: r2 }) + await new Promise((r) => setTimeout(r, 5)) + // one question to the host for the pair: r2 waits on r1's answer + expect( + host.resolveCalls.filter((c) => c.specifier === './factory-inner'), + ).toHaveLength(1) + gate.resolve() + const [stale, published] = await Promise.all([slow, fresh]) + expect(published!.code).toContain('export const v2 = 2') + expect(stale!.code).not.toContain('v2') + const key = { + env: 'client', + canonicalId: '/app/consumer.ts', + configKey: 'cfg', + } + const cache = host.caches.plans.get('client')! + expect(cache.get(key)!.plan.sourceLength).toBe(r2.length) + expect( + host.resolveCalls.filter((c) => c.specifier === './factory-inner'), + ).toHaveLength(1) + }) + it('(f) in-flight dependency-only edit restarts the compile; onViolation is asked once', async () => { const verdict = deferred() const host = new MemoryHost({ @@ -895,3 +947,81 @@ function offsetOf(code: string, line: number, column: number): number { } return i + column } + +describe('planning rounds', () => { + // A planner that registers a new region every round and never reads the + // fallbacks it is handed (round r claims the r-th statement of the + // component into the chunk; each claim writes `a`, which the loader + // reads, so each round reports a fresh region). The rounds end at the + // bound (the region count after the first round) with every sub-region + // kept in place and one warning; a planner honours the exhausted + // fallbacks by splitting nothing. + it('end past the bound with everything kept in place and `fallback-rounds-exhausted`', async () => { + const statements = Array.from({ length: 12 }, (_, i) => `a = ${i + 1}`) + const code = dedent(` + import { createFileRoute } from 'toy-router' + let a = 0 + export const Route = createFileRoute('/')({ + loader: () => a, + component: () => { ${statements.join('; ')}; return null }, + }) + `) + const runaway: Planner = { + name: 'toy-runaway', + tier: 1, + gate: () => true, + plan(ctx) { + const found = findRouteOptions(ctx) + if (!found) { + return + } + ctx.setRouteModule() + ctx.markBenignEffect(found.unit.id) + if (ctx.fallbacks.some((f) => f.reason === 'exhausted')) { + return + } + const component = propertyOf(found.options, 'component')!.value + const body = ( + component as { body: { body: Array<{ start: number; end: number }> } } + ).body.body + const stmt = body[ctx.fallbacks.length] + if (!stmt) { + return + } + const output = ctx.declareOutput({ + kind: 'split', + key: 'component', + derived: { kind: 'split', value: 'component' }, + }) + const range = { start: stmt.start, end: stmt.end } + const owner = ctx.rewrites.addGenerated({ + body: [ + { k: 'text', parts: ['export const moved = () => { '] }, + { k: 'slice', range }, + { k: 'text', parts: [' }\n'] }, + ], + declares: [ctx.names.alloc('moved').sym], + effectful: false, + anchor: { k: 'end' }, + home: output, + by: 'toy-runaway', + }) + ctx.rewrites.claim({ + region: ctx.region(range, 'custom'), + owner, + placeholder: [], + by: 'toy-runaway', + }) + }, + } + const host = new MemoryHost({ files: { '/app/route.tsx': code } }) + const out = await host.compile('/app/route.tsx', [runaway]) + expect(out!.diagnostics).toMatchObject([ + { severity: 'warning', code: 'fallback-rounds-exhausted', by: 'core' }, + ]) + expect(out!.code).toContain( + `component: () => { ${statements.join('; ')}; return null }`, + ) + expect(out!.code).not.toContain('moved') + }) +}) diff --git a/packages/router-utils/tests/placement.test.ts b/packages/router-utils/tests/placement.test.ts index 517bd6769d..45a751b93a 100644 --- a/packages/router-utils/tests/placement.test.ts +++ b/packages/router-utils/tests/placement.test.ts @@ -574,6 +574,57 @@ describe('extracted-export outputs', () => { ) }) + // R1: the mutation model is read through the env output's liveness. A + // Start route file whose only write of an exported `let` is inside a + // server fn handler: on the client the handler is a stub, so nothing + // writes the binding there; it is extractable, the chunk copies it and + // the build does not say it is reassigned. + it('counts no write inside code the environment erases: the export leaves and nothing is reported', async () => { + const code = dedent(` + import { createFileRoute } from 'toy-router' + import { wrapServer } from 'toy-start' + export let hits = 0 + export const bump = wrapServer(() => { hits++ }) + function Page() { return hits } + export const Route = createFileRoute('/')({ component: Page }) + `) + const host = new MemoryHost({ files: { '/app/route.tsx': code } }) + const planners = [ + toyEnvPlanner(), + toySplitPlanner({ keys: ['component'], extractExports: true }), + ] + const out = await host.compile('/app/route.tsx', planners, build) + const chunk = await host.compile( + '/app/route.tsx?tsr-split=component', + planners, + build, + ) + expect(out!.code).toContain( + "export { hits } from './route.tsx?tsr-split=export~hits'", + ) + expect(out!.code).toContain('export const bump = tsrStub()') + expect(chunk!.code).toContain('let hits = 0') + expect( + out!.diagnostics.filter((d) => d.code?.startsWith('eager-')), + ).toEqual([]) + // the server keeps the write: the export stays, reported once + const server = await host.compile('/app/route.tsx', planners, { + env: envInfo({ + name: 'ssr', + type: 'server', + routerSplit: true, + mode: 'build', + }), + }) + expect(server!.code).toContain('export let hits = 0') + expect( + server!.diagnostics.map((d) => [d.code, d.range?.start]), + ).toContainEqual([ + expect.stringMatching(/^eager-export:/), + code.indexOf('hits = 0'), + ]) + }) + it('keeps an exported declaration the env module reads, and an unread one', async () => { const code = dedent(` import { createFileRoute } from 'toy-router' @@ -2822,6 +2873,23 @@ describe('declarations only split code needs that stay in the route module', () 'const confetti', '/* #__NO_SIDE_EFFECTS__ */ function type(shape) { return shape }\nconst confetti', ), + // declared after the call (hoisted): the annotation counts in any + // order, for the option value and for a declaration's initialiser + pinned + .replace("import { type } from 'arktype'\n", '') + .concat( + '/* #__NO_SIDE_EFFECTS__ */ function type(shape) { return shape }\n', + ), + pinned + .replace("import { type } from 'arktype'\n", '') + .replace( + 'export const Route', + "const search = type({ 'a?': 'string' })\nexport const Route", + ) + .replace(/validateSearch: type\(\{[^}]*\}\)/, 'validateSearch: search') + .concat( + '/* #__NO_SIDE_EFFECTS__ */ function type(shape) { return shape }\n', + ), dedent(` import { createFileRoute } from 'toy-router' export const Route = createFileRoute('/')({ diff --git a/packages/start-plugin-core/src/planners/start-env.ts b/packages/start-plugin-core/src/planners/start-env.ts index 206c865d88..3d581b9dea 100644 --- a/packages/start-plugin-core/src/planners/start-env.ts +++ b/packages/start-plugin-core/src/planners/start-env.ts @@ -61,8 +61,8 @@ export interface StartEnvConfig { providerDirective?: string /** * Every module defining server fns gets a derived provider module, not - * only `'use client'` ones (Rsbuild RSC: the provider is the `rsc` layer, - * selected by the `?tss-serverfn-split` query). + * only `'use client'` ones (RSC on Vite and Rsbuild: the provider is the + * `rsc` environment or layer, selected by the `?tss-serverfn-split` query). */ alwaysDeriveProvider?: boolean /** Whether resolved ids are opaque packages (never read for summaries). */ @@ -551,7 +551,14 @@ function planStartEnv( // ---- 2. server fns const sites: Array = [] const keyCount = new Map() - for (const chain of serverFnChains) { + // in source order (the analysis lists chains per import binding): an + // enclosing handler's site before a nested one, so the nested site is + // judged against the stub that replaced its handler (a nested server fn + // inside a stubbed handler is dead there, J4.6), and stable keys follow + // the source whatever the import order + for (const chain of [...serverFnChains].sort( + (a, b) => a.terminal.start - b.terminal.start, + )) { const handlerLink = chain.links.find((l) => l.method === 'handler') if (!handlerLink) { continue diff --git a/packages/start-plugin-core/src/vite/tsconfig.ts b/packages/start-plugin-core/src/tsconfig.ts similarity index 100% rename from packages/start-plugin-core/src/vite/tsconfig.ts rename to packages/start-plugin-core/src/tsconfig.ts diff --git a/packages/start-plugin-core/tests/integration/start-build-nested-server-fn-access.test.ts b/packages/start-plugin-core/tests/integration/start-build-nested-server-fn-access.test.ts new file mode 100644 index 0000000000..5be8d02c78 --- /dev/null +++ b/packages/start-plugin-core/tests/integration/start-build-nested-server-fn-access.test.ts @@ -0,0 +1,63 @@ +/** + * A server fn nested in another server fn's handler is server-only: no + * client code can reference it (the enclosing handler is a stub on the + * client), so a production build does not list it among the HTTP-callable + * functions (SPEC J4.2, J4.6), whichever import binding of the factory + * declares it. Vite and Rsbuild builds, Start's whole plugin, the server + * bundle run by Start's own server entry inside a real request. + */ +import { describe, expect, test } from 'vitest' +import { + buildStart, + callByIdExports, + callByIdPrelude, + startBundlers, +} from '../build-harness' + +const timeout = 60_000 + +const files = { + 'fns.ts': `import { createServerFn as inner } from '@tanstack/react-start' +import { createServerFn } from '@tanstack/react-start' +export const outer = createServerFn().handler(async () => { + const nested = inner().handler(async () => 'MARK_NESTED') + ;(globalThis as any).__nested = nested + return nested() +}) +`, + 'client-entry.ts': `export { outer } from './fns' +`, + 'ssr-entry.ts': `export { outer } from './fns' +${callByIdExports}`, +} + +describe.each(startBundlers)('a %s production build', (bundler) => { + test( + 'a server fn nested in a handler is callable by the handler and not over HTTP', + async () => { + const { client, ssr } = await buildStart({ + bundler, + files, + entry: { client: 'client-entry.ts', ssr: 'ssr-entry.ts' }, + }) + expect(client.where('MARK_NESTED')).toBe('nowhere') + const outerUrl = (await client.run(`return entry.outer.url`)).result + const { result } = + await ssr.run(`${callByIdPrelude}const settle = async (run) => { + try { + return await run() + } catch { + return 'rejected' + } +} +const outer = await settle(() => callById(serverFnId(${JSON.stringify(outerUrl)}))) +const nestedId = serverFnId(globalThis.__nested) +return { outer, nestedOverHttp: await settle(() => callById(nestedId)) }`) + expect(result).toEqual({ + outer: 'MARK_NESTED', + nestedOverHttp: 'rejected', + }) + }, + timeout, + ) +}) diff --git a/packages/start-plugin-core/tests/planner-outputs.test.ts b/packages/start-plugin-core/tests/planner-outputs.test.ts index 9a2409086a..b5fcfa711a 100644 --- a/packages/start-plugin-core/tests/planner-outputs.test.ts +++ b/packages/start-plugin-core/tests/planner-outputs.test.ts @@ -363,6 +363,40 @@ export function make() { expect(ssr.code).toContain("name: 'inner'") }) + // The nested site is judged against the stub of its enclosing handler + // whatever the order the analysis found the sites in (here the inner + // factory's import binding comes first): on the client the handler is a + // stub, so the nested fn is dead there and never registered as + // client-referenced (J4.2: only client-referenced fns are HTTP-callable). + test('a nested server fn inside a handler is not a client server fn, whichever import binding declares it', async () => { + const files3 = { + '/app/module.tsx': `import { createServerFn as inner } from '@tanstack/react-start' +import { createServerFn } from '@tanstack/react-start' +import { db } from './db.server' +export const outer = createServerFn().handler(async () => { + const nested = inner().handler(async () => db.inner()) + return nested() +}) +`, + '/app/db.server.ts': `export const db = { inner: () => 'inner' }\n`, + } + const client = (await compile(files3, 'client'))! + expect(client.diagnostics).toEqual([]) + expect(client.code).not.toContain('db.server') + expect( + (client.facts.planners[START_ENV] as StartEnvFacts).serverFns.map( + (fn) => fn.name, + ), + ).toEqual(['outer']) + const ssr = (await compile(files3, 'ssr'))! + expect(ssr.diagnostics).toEqual([]) + expect( + (ssr.facts.planners[START_ENV] as StartEnvFacts).serverFns.map( + (fn) => fn.name, + ), + ).toEqual(['outer', 'nested']) + }) + test('a nested server fn capturing a local is refused at the capture', async () => { const out = (await compile( {