@real-router/core 0.108.0 → 0.108.2

package/dist/esm/ingest-CR-wWB0O.mjs

@@ -1,2 +0,0 @@
-function e(){return Object.create(null)}function t(e){return{...e}}const n=Object.defineProperty,r=Object.hasOwn;function i(e,t,i){t in e&&!r(e,t)?n(e,t,{value:i,writable:!0,enumerable:!0,configurable:!0}):e[t]=i}function a(e,t){for(let[n,r]of Object.entries(t))i(e,n,r)}export{i,e as n,t as r,a as t};
-//# sourceMappingURL=ingest-CR-wWB0O.mjs.map

package/dist/esm/ingest-CR-wWB0O.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"ingest-CR-wWB0O.mjs","names":[],"sources":["../../src/utils/ingest.ts"],"sourcesContent":["// packages/core/src/utils/ingest.ts\n//\n// One discipline for the records core BUILDS under a key it did not CHOOSE.\n//\n// Two halves, and they answer different questions — a reader who takes them for\n// one primitive will draw the wrong conclusion from either:\n//\n//   `emptyRecord` / `publishRecord` (#1825) — a record with no prototype for the\n//     BUILD, handed out plain. Used where the record is core's alone:\n//     `buildParamMeta`, the segment-meta walk.\n//   `putField` / `copyFields` (#1852) — a guarded WRITE for the records that\n//     cannot be prototype-less because they are published, read on every render,\n//     or belong to someone else. Twenty-one sites in core, fourteen across four\n//     plugins through `@real-router/core/utils`.\n//\n// ⚠ Neither decides whether a key is PUBLISHED. `__proto__` stays out of\n// `state.params` / `state.search` by a separate skip at the channel copy sites\n// in `helpers.ts`, and stays IN a route's custom fields and a plugin's context\n// namespace, because those are not containers a consumer merges. See `putField`'s\n// docblock for that split.\n//\n// ⚠ These are WRITE-side primitives only, and the boundary is deliberate. A\n// READ-side primitive that walks a caller's prototype chain was written here,\n// wired, measured — and removed: `CLAUDE.md` \"Supported Input Shapes\" settles\n// that axis already (\"own enumerable properties only\", owner decision\n// 2026-08-18), and core is the layer that DEGRADES on a violation while\n// `@real-router/validation-plugin` is the layer that reports it. A primitive\n// that honoured inherited keys would have made core contradict its own canon,\n// and it additionally admitted the ambient `Object.prototype` — the #1840\n// class, introduced by the fix.\n//\n// So what is left is the half the canon does not cover: what happens when core\n// writes into a record of its own under a key it did not choose.\n\n/**\n * The target discipline: a record with NO prototype.\n *\n * ⚑ This one line closes two axes at once, which is why it is a primitive and\n * not an idiom. #1856 tabulates them as a structural trade — a key-by-key copy\n * fixes `\"__proto__\"` but turns a `[[DefineOwnProperty]]` into a `[[Set]]`, so\n * an ambient accessor starts throwing — and calls the conflict unavoidable. It\n * is unavoidable only while the target inherits from `Object.prototype`:\n *\n *   - `\"__proto__\"` (#1825, #1794, #1809) is an ordinary key here, because the\n *     magic accessor lives on `Object.prototype` and this object has none.\n *   - an ambient accessor named `id` / `page` / `tab` (#1852) cannot hijack the\n *     write for the same reason. #1852 notes the key's provenance is\n *     irrelevant — `SegmentMatcher` writes a name from the ROUTE TABLE and\n *     throws just the same — so a name-based skip cannot close it and this can.\n */\nexport function emptyRecord<V>(): Record<string, V> {\n  return Object.create(null) as Record<string, V>;\n}\n\n/**\n * Hand a privately-built record out with the ORDINARY prototype, keeping every\n * own key — including a literal `\"__proto__\"`.\n *\n * Discovered by measurement, not designed: wiring `emptyRecord` into\n * `buildParamMeta` alone reds **21** existing tests, all of the shape\n * `expected { id: 'url' } to strictly equal { id: 'url' }` — identical content,\n * different prototype, because `toStrictEqual` compares prototypes and\n * `paramTypeMap` is published through `getPluginApi(router).getTree()`. A\n * prototype-less record is not a drop-in at a published surface.\n *\n * The spread is what makes this work rather than undo it: it\n * `[[DefineOwnProperty]]`s, so an own `\"__proto__\"` carried on the private\n * record lands as an ordinary own key here (measured: own keys\n * `[\"__proto__\",\"keep\"]`, value intact, prototype back to `Object.prototype`).\n * Writing that same key into a fresh `{}` with `[[Set]]` loses it entirely\n * (measured: own keys `[]`) — which is the defect the private record exists to\n * avoid.\n *\n * So the rule is: **build private, publish plain.** The window in which the\n * ambient-accessor hazard (#1852) could bite is the build, and the build never\n * touches `Object.prototype`.\n */\nexport function publishRecord<V>(source: Record<string, V>): Record<string, V> {\n  return { ...source };\n}\n\n/**\n * Captured at module load for the reason `helpers.ts` gives for `freeze` /\n * `hasOwn` / `objectKeys`: this is the operation {@link putField} writes\n * through, so a guard reading it late would be reading whatever an application\n * had re-pointed it to.\n */\nconst defineProperty = Object.defineProperty;\nconst hasOwn = Object.hasOwn;\n\n/**\n * Write one field of a record core BUILDS under a key it did not choose.\n *\n * ⚑ The rule this exists to enforce: **a caller's object contributes DATA, and\n * nothing else.** No trap, no accessor, no inherited member of a bag handed to\n * the router may change what the router ends up holding — which is what\n * \"treat it as a pure dictionary\" means on the WRITE side. `Object.keys` and\n * the one-read-per-key discipline (#1854 / #1899) already say it on the read\n * side; this is the other half.\n *\n * Plain `target[key] = value` cannot say it. `[[Set]]` walks the prototype\n * chain first, so a key that resolves to an accessor or a non-writable data\n * property up there is HIJACKED — the write dispatches into application code\n * (or is silently dropped in sloppy mode, and throws in a module). The key's\n * provenance is irrelevant: `SegmentMatcher` writes a name straight off the\n * ROUTE TABLE, so `id` / `tab` / `page` are as exposed as `__proto__` (#1852),\n * and a name-based skip therefore cannot close it.\n *\n * `Object.defineProperty` CAN say it — it ignores the chain entirely — but it\n * measures ~100 ns per field against ~0 for a store, which is why #1852 priced\n * it as unaffordable on a path that runs per navigation and per `<Link>`\n * render.\n *\n * So the write is guarded rather than replaced: **ask the chain first, and pay\n * only where it answers.** In a pristine environment `in` answers `false` for\n * every name an application routes under, so the store is taken and nothing is\n * paid. It covers both halves of the hazard, which a `__proto__` name test does\n * not: an accessor (getter-only THROWS, getter+setter silently diverts the\n * value) and a **non-writable** data property. Verified on all four shapes plus\n * the overwrite cases.\n *\n * ⚠ It asks `key in target`, NOT `key in Object.prototype`, and the difference\n * is the whole robustness of the primitive rather than a style choice. The\n * cheaper form is right only while every target is a fresh `{}`, i.e. while its\n * chain IS `Object.prototype` — measured, a target inheriting the accessor from\n * anywhere else walks straight past that predicate and throws. Asking the\n * object\n * being written to cannot be wrong for any target. Measured cost of the\n * difference, measured when the two forms were compared directly: a wash on\n * every arc, bought for a predicate with no precondition. ⚠ Those figures\n * predate both the `!hasOwn` term and the restored channel skips, and the\n * number\n * that supersedes them is below — the whole guard sits under the noise floor,\n * so\n * the choice between the two predicates cannot be visible in it.\n *\n * ⚑ **`&& !hasOwn`, and that second term is not an optimisation — it is what\n * keeps this a guarded WRITE instead of a redefinition.** When the key is\n * already an OWN property of the target, `[[Set]]` finds it and never consults\n * the chain, so a plain store is both safe AND semantically right there.\n * `defineProperty` is not: it replaces the whole DESCRIPTOR with this\n * function's\n * fixed one, and three consequences of that were measured before the term was\n * added.\n *\n *   - It **throws where a plain store works**: a `configurable: false` own key\n *     (a sealed target, an array's `length`) refuses `defineProperty` while\n *     accepting an assignment.\n *   - It **silently unlocks**: an own `writable: false` key was overwritten and\n *     came back writable, and an own `enumerable: false` key came back\n *     enumerable — a \"guarded write\" that also removes the guard.\n *   - It **changed a shipped shape**, which is how this was caught rather than\n *     reasoned about. `RouterError`'s own `stack` is a non-enumerable accessor;\n *     `wrapSyncError` passes `stack` through here, so every error built from a\n *     thrown one gained an own enumerable `stack`. `Object.keys(err)` changed,\n *     and two errors differing only in stack stopped comparing equal under\n *     `isDeepStrictEqual` / `toEqual`. The two arms of `rethrowAsRouterError`\n *     disagreed with each other, because one of them assigns.\n *\n * `in` answers `false` for a fresh bag's new key and short-circuits, so\n * `hasOwn`\n * runs only on the rare branch it disambiguates. ⚠ That short-circuit is why an\n * earlier revision called the hot path \"untouched\"; it is not — one dictionary\n * lookup per written field is the price, and it is measured below.\n *\n * ⚠ The alternative that looks equivalent and is not: a prototype-less target.\n * It also closes the axis, and it costs far MORE, because the price is not on\n * the write at all — V8 puts such an object in dictionary mode, so every later\n * READ of the bag pays. Re-measured on the SHIPPED tree rather than carried\n * over from an earlier one: `buildPath` goes **+65.4 %** (one path slot) and\n * **+36.2 %** (slot + query). `{ __proto__: null }` as a literal is no better\n * (76 ns vs 70 ns for `Object.create(null)`, against 7.5 ns plain).\n *\n * ⚑ **The guard costs, and two earlier revisions of this docblock denied it.**\n * The last one said \"NOT MEASURABLE\" on medians-of-five whose A/A floors were\n * 5-6 %; on a quiet machine this harness floors at 0.1-1.7 %, and at that\n * resolution the cost is plain. Same-session A/B, ALTERNATING PROCESSES (two\n * copies of the module in one process is not a valid A/B), medians of 20 pairs,\n * against the SHIPPED bundle rather than `src`, each arc's own A/A floor in\n * brackets:\n *\n *     buildPath, splat param     232.4 -> 260.3 ns   +12.0 %  (0.7 %)\n *     isActiveRoute, exact       117.5 -> 125.4 ns    +6.8 %  (0.1 %)\n *     matchPath, path params     664.0 -> 693.8 ns    +4.5 %  (0.8 %)\n *     buildPath, static           97.5 ->  99.2 ns    +1.7 %  (1.7 %)\n *     buildPath, one path slot   145.0 -> 140.5 ns    -3.1 %  (1.0 %)\n *     isActiveRoute, sibling      38.4 ->  38.3 ns    -0.3 %  (0.3 %)\n *\n * Isolated by building the tree with the predicate replaced by `false`: it is\n * worth -6.1 % on the splat arc and -7.5 % on the exact one, i.e. the whole of\n * the regression there; the rest of `matchPath`'s is `withoutUnsafeKey`\n * (#1904), -2.1 %.\n *\n * ⚠ The old claim was less a bad measurement than a measurement of the WRONG\n * ARCS. `warm-params` and the sibling arm genuinely do not move — those are the\n * two it sampled — while the splat and exact arms do. Sampling what does not\n * move and generalising to \"not measurable\" is the same trap the reachability\n * arguments elsewhere in this file are written against.\n *\n * The price is ACCEPTED, deliberately, and three cheaper forms were measured\n * and rejected before accepting it:\n *\n *   - asking a captured `Object.prototype` instead of the target, so the `in`\n *     receiver is monomorphic: every arc inside the A/A floor. The cost is the\n *     dictionary lookup, not who is asked.\n *   - a prototype-less accumulator in `normalizeChannel` published through\n *     `publishRecord`: **+134 % … +284 %** — the dictionary-mode price above,\n *     now measured end to end rather than argued.\n *   - an optimistic plain store repaired afterwards (`hasOwn` + `try`/`catch`):\n *     -3.5 % and -2.8 % on two arcs but **+8.3 %** on a third, and it re-opens\n *     the descriptor question `&& !hasOwn(target, key)` exists to close.\n *\n * ⚠ **CodSpeed reports this change at -13.83 %, and that is not the shipped\n * cost.** The gap is measured, not assumed. The suite runs\n * `tsx tests/benchmarks/run.ts` — against `src`, unbundled — so its flamegraph\n * carries ESM module-namespace getter frames (`get (ingest.ts)`, 2.67 % of one\n * arc) that the bundle does not have: `grep -c 'get: ()' dist/esm/index.mjs` is\n * 0. `Simulation` mode additionally over-counts instructions a superscalar CPU\n * hides. On the worst-reported arc the sign inverts — -17.25 % simulated,\n * -3.1 % (i.e. FASTER) in the bundle.\n *\n * A prototype-less channel additionally changes a PUBLISHED shape:\n * `state.params` would stop inheriting from `Object.prototype`, which reds\n * **352 tests in 17 packages**, none of them for a behavioural reason.\n *\n * ⚠ That count was published as \"263 in 15\" and is a RE-MEASUREMENT, not a\n * drift: the first figure came from running the affected packages one at a time\n * partway through the change, and both halves of it were low. A full-monorepo\n * run (10 553 tests) gives 352/17 for a prototype-less channel including the\n * `EMPTY_PARAMS` / `EMPTY_SEARCH` singletons, and 286/17 for the accumulators\n * alone — the package count is 17 either way, so it was never a question of\n * which sites to mutate.\n *\n * The qualitative half held up and is the load-bearing one: all 352 are\n * `AssertionError`, zero are thrown; 336 are `toStrictEqual` and 16 are\n * explicit\n * prototype pins; and NO `toEqual` / `toMatchObject` cell moved, which is the\n * internal control that only the prototype axis shifted.\n *\n * ⚑ `defineProperty` also makes `__proto__` an ordinary own key rather than a\n * write that swaps the target's prototype — which is why the `claim.write`\n * (#1191), `assignParam` (#855) and custom-field (#1788) special cases could be\n * replaced by this one primitive instead of kept beside it.\n *\n * ⚠ **It does NOT decide whether that key is PUBLISHED, and the two questions\n * were briefly conflated here.** The channel copy sites in `helpers.ts` still\n * drop `__proto__` before it reaches `state.params` / `state.search`, and that\n * skip is orthogonal to this primitive: a bag core hands BACK carrying the key\n * is a prototype-swap primitive for any consumer that merges it with\n * `Object.assign` — measured, `?__proto__` alone yields `null` and\n * `?__proto__=1&__proto__=2` an array, and the inherited setter accepts both.\n * `getDependenciesApi.getAll()` deletes the same key for the same reason and in\n * those words. Where the record does NOT escape to a merging consumer — a\n * route's custom fields, a plugin's context namespace — the key stays as data,\n * which is what #1788 and #1191 are about.\n */\nexport function putField<V>(\n  target: Record<string, V>,\n  key: string,\n  value: V,\n): void {\n  if (key in target && !hasOwn(target, key)) {\n    defineProperty(target, key, {\n      value,\n      writable: true,\n      enumerable: true,\n      configurable: true,\n    });\n  } else {\n    target[key] = value;\n  }\n}\n\n/**\n * {@link putField} for a whole source record — what `Object.assign` would do,\n * without the hazard.\n *\n * ⚑ It exists because `Object.assign` IS the hazard, written in a form a census\n * keyed on `dst[key] = value` cannot see. It copies with `[[Set]]`, one key at\n * a\n * time, so every argument in {@link putField}'s docblock applies to it verbatim\n * — and it is the reason this class needed a second look after the obvious\n * sweep: the matcher's junction walk builds `childParams` with a computed-key\n * literal (safe: that DEFINES) and then commits it with `Object.assign` (not).\n * Measured with an ambient setter under a route's own param name, the route\n * still MATCHED and `state.params` came back empty — the URL's parameter gone,\n * with no error anywhere.\n *\n * `Object.entries` for the walk: it hands back the value it already read, so\n * there is exactly ONE read per key and no window for a drifting accessor\n * between the test and the use (#1899). It is also the idiom the sibling copy\n * loops use.\n *\n * ⚠ **Two things it does NOT buy, both measured after an earlier revision of\n * this docblock claimed them.**\n *\n *   - It is **not** a filter against a lying Proxy source. `ownKeys` is asked\n *     first, so a key that list does not contain cannot appear — but a source\n *     whose `ownKeys` DOES name a phantom and whose descriptor trap calls it\n *     enumerable gets that phantom copied, identically to `Object.assign`. The\n *     #1854 protection is narrower than \"the trap is never consulted\".\n *   - It is **not** a drop-in for `Object.assign`. `Object.entries` is\n *     string-keyed, so own enumerable SYMBOL entries are dropped where\n *     `Object.assign` copies them. That matches core's stated policy for the\n * channels (\"symbols are dropped, always\") and is a real behaviour change at\n *     the one call site that used to be an `Object.assign`\n *     (`persistent-params`' factory). ⚠ It also disagrees with `publishRecord`\n *     two functions up, which spreads and therefore keeps symbols — the same\n *     internal split `helpers.ts` records as the #1792 defect.\n */\nexport function copyFields<V>(\n  target: Record<string, V>,\n  source: Record<string, V>,\n): void {\n  for (const [key, value] of Object.entries(source)) {\n    putField(target, key, value);\n  }\n}\n"],"mappings":"AAkDA,SAAgB,GAAoC,CAClD,OAAO,OAAO,OAAO,IAAI,CAC3B,CAyBA,SAAgB,EAAiB,EAA8C,CAC7E,MAAO,CAAE,GAAG,CAAO,CACrB,CAQA,MAAM,EAAiB,OAAO,eACxB,EAAS,OAAO,OAwKtB,SAAgB,EACd,EACA,EACA,EACM,CACF,KAAO,GAAU,CAAC,EAAO,EAAQ,CAAG,EACtC,EAAe,EAAQ,EAAK,CAC1B,QACA,SAAU,GACV,WAAY,GACZ,aAAc,EAChB,CAAC,EAED,EAAO,GAAO,CAElB,CAuCA,SAAgB,EACd,EACA,EACM,CACN,IAAK,GAAM,CAAC,EAAK,KAAU,OAAO,QAAQ,CAAM,EAC9C,EAAS,EAAQ,EAAK,CAAK,CAE/B"}