@farm.js/react 0.1.0-beta.4 → 0.1.0-beta.40
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +825 -15
- package/dist/client.d.mts +1 -0
- package/dist/client.d.ts +1 -0
- package/dist/compiled-root.cjs +17 -0
- package/dist/compiled-root.cjs.map +1 -0
- package/dist/compiled-root.d.mts +12 -0
- package/dist/compiled-root.d.ts +12 -0
- package/dist/compiled-root.mjs +14 -0
- package/dist/compiled-root.mjs.map +1 -0
- package/dist/compiler-runtime.cjs +7150 -1170
- package/dist/compiler-runtime.cjs.map +1 -1
- package/dist/compiler-runtime.d.mts +267 -5
- package/dist/compiler-runtime.d.ts +267 -5
- package/dist/compiler-runtime.mjs +7029 -1171
- package/dist/compiler-runtime.mjs.map +1 -1
- package/dist/index.cjs +45 -5
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +17 -2
- package/dist/index.d.ts +17 -2
- package/dist/index.mjs +45 -5
- package/dist/index.mjs.map +1 -1
- package/dist/list.cjs +6 -0
- package/dist/list.cjs.map +1 -1
- package/dist/list.mjs +6 -0
- package/dist/list.mjs.map +1 -1
- package/dist/server.d.mts +0 -1
- package/dist/server.d.ts +0 -1
- package/dist/vite.cjs +5181 -422
- package/dist/vite.cjs.map +1 -1
- package/dist/vite.d.mts +10 -1
- package/dist/vite.d.ts +10 -1
- package/dist/vite.mjs +5183 -425
- package/dist/vite.mjs.map +1 -1
- package/package.json +18 -10
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
React renderer integration for FARMJS, including the experimental AOT compiler.
|
|
4
4
|
|
|
5
5
|
React remains the default renderer and needs no package or configuration. Install this package only
|
|
6
|
-
when opting into the compiler
|
|
6
|
+
when opting into the compiler:
|
|
7
7
|
|
|
8
8
|
```bash
|
|
9
9
|
pnpm add @farm.js/react
|
|
@@ -15,9 +15,7 @@ import { react } from "@farm.js/react";
|
|
|
15
15
|
|
|
16
16
|
export default defineConfig({
|
|
17
17
|
renderer: react({
|
|
18
|
-
|
|
19
|
-
compiler: true,
|
|
20
|
-
},
|
|
18
|
+
compiler: true,
|
|
21
19
|
}),
|
|
22
20
|
});
|
|
23
21
|
```
|
|
@@ -25,6 +23,25 @@ export default defineConfig({
|
|
|
25
23
|
`compiler: true` uses inference: every application TSX/JSX component is considered, eligible
|
|
26
24
|
components are compiled with hybrid reactivity, and everything else keeps the normal React path.
|
|
27
25
|
|
|
26
|
+
The compiler is experimental and stays off when this option is omitted or `false`. The former
|
|
27
|
+
`react({ experimental: { compiler } })` spelling remains a deprecated alias with the same options
|
|
28
|
+
and a one-time warning. Do not configure both spellings, even when one is `false`.
|
|
29
|
+
|
|
30
|
+
### Compatibility and upgrades
|
|
31
|
+
|
|
32
|
+
`react({ compiler })`, `ReactCompilerOptions`, and `List` from `@farm.js/react/list` are the
|
|
33
|
+
application-facing API. Both inference and annotation mode, static and hybrid reactivity, fallback
|
|
34
|
+
diagnostics, and coverage reporting remain supported. Annotation and static mode are advanced
|
|
35
|
+
options, not separate experimental APIs. The package is independently versioned; a prerelease
|
|
36
|
+
version remains a beta until its stable release is published.
|
|
37
|
+
|
|
38
|
+
The compiler and `@farm.js/react/compiler-runtime` ship together. Generated definitions must use
|
|
39
|
+
the runtime from the same installed package version; they are not a cross-version interchange
|
|
40
|
+
format. Upgrade the package and rebuild the complete app, including SSR and browser output,
|
|
41
|
+
together. Do not copy generated compiler output between package versions or deploy a new server
|
|
42
|
+
with an old browser build. Existing runtime exports remain available, but prefer ordinary React
|
|
43
|
+
source over hand-authored compiler definitions.
|
|
44
|
+
|
|
28
45
|
Hybrid reactivity starts from the compiler's proven state-to-binding dependency lists, then marks
|
|
29
46
|
only multi-state short-circuit bindings for runtime read tracking. For
|
|
30
47
|
`enabled ? activeValue : inactiveValue`, an update to the inactive value does not schedule the
|
|
@@ -32,17 +49,37 @@ binding. The runtime uses direct subscription indexes rather than proxies or a c
|
|
|
32
49
|
scan. Use `compiler: { reactivity: "static" }` to retain only the complete build-time dependency
|
|
33
50
|
lists for comparison or diagnosis.
|
|
34
51
|
|
|
52
|
+
Compiler output also selects its runtime capabilities at build time. A direct counter imports only
|
|
53
|
+
the cell scheduler and direct-binding core; conditionals, keyed rows and LIS, nested host ranges,
|
|
54
|
+
and component islands are retained only when a compiled component in that module needs them. Plain
|
|
55
|
+
keyed rows omit the larger recursive-host and row-conditional extensions. This selection is
|
|
56
|
+
automatic and does not add a configuration option or asynchronous runtime loading. The legacy
|
|
57
|
+
`createCompiledComponent` export remains a complete compatibility entry for hand-authored
|
|
58
|
+
definitions, while generated code uses the tree-shakable feature entry.
|
|
59
|
+
|
|
60
|
+
Generated code also selects refresh support through `import.meta.hot`. Production bundles can
|
|
61
|
+
remove the development refresh registry and compatibility checks; development retains
|
|
62
|
+
state-preserving refresh. Both entries share the same component runtime, including SSR, hydration,
|
|
63
|
+
DOM ownership, and fallback behavior. Existing hand-authored runtime entries retain refresh support.
|
|
64
|
+
|
|
65
|
+
Plain keyed lists with filter hints and only identity-based selection also use the single-kind
|
|
66
|
+
target runtime. Filtering keeps its existing native-method checks and fallback; mixed Set/Map
|
|
67
|
+
targets, conditional rows, and nested host blocks keep their existing runtime capabilities.
|
|
68
|
+
|
|
69
|
+
The persisted production-size fixtures and regression gate live in
|
|
70
|
+
[`RUNTIME_SIZE_RESULTS.md`](./RUNTIME_SIZE_RESULTS.md). The recorded compiler-selected core runtime
|
|
71
|
+
premium is 85.4% smaller than the complete compatibility runtime premium; the feature-heavy keyed
|
|
72
|
+
benchmark application removes 6,185 gzip bytes from its previous compiler-on build.
|
|
73
|
+
|
|
35
74
|
For selective adoption, use annotation mode:
|
|
36
75
|
|
|
37
76
|
```ts
|
|
38
77
|
renderer: react({
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
reactivity: "hybrid",
|
|
45
|
-
},
|
|
78
|
+
compiler: {
|
|
79
|
+
mode: "annotation",
|
|
80
|
+
directive: "use compiler",
|
|
81
|
+
onUnsupported: "warn",
|
|
82
|
+
reactivity: "hybrid",
|
|
46
83
|
},
|
|
47
84
|
}),
|
|
48
85
|
```
|
|
@@ -82,6 +119,11 @@ The current compiler handles components that it can prove have:
|
|
|
82
119
|
- React-managed event handlers; and
|
|
83
120
|
- no refs, effects, or unsupported dynamic child structures.
|
|
84
121
|
|
|
122
|
+
State-dependent event handler selection, such as `onClick={active ? save : cancel}`, keeps the
|
|
123
|
+
component on React's normal rendering path so replacing, adding, or removing a callback updates
|
|
124
|
+
React's event props. Direct inline handlers that read state when invoked, such as
|
|
125
|
+
`onClick={() => save(active)}`, retain the existing compiled path when otherwise eligible.
|
|
126
|
+
|
|
85
127
|
The generated component preserves React ownership of initial placement, parent update commits,
|
|
86
128
|
identity-bearing props, events, SSR, and hydration. Local state cells batch updates into a
|
|
87
129
|
microtask; eligible flat destructured primitive props join the same dependency index after React
|
|
@@ -96,6 +138,10 @@ refreshes only changed React-owned row-local branches. React still creates or hy
|
|
|
96
138
|
DOM. Anything outside those narrow contracts uses a small React-owned boundary or the complete
|
|
97
139
|
original component.
|
|
98
140
|
|
|
141
|
+
Compiler-owned structural updates stay disabled inside SVG and MathML, including shared
|
|
142
|
+
HTML/SVG tag names such as `a` and `title`. React retains namespace-sensitive element creation
|
|
143
|
+
when rows are appended or conditional branches change; ordinary HTML rows remain eligible.
|
|
144
|
+
|
|
99
145
|
For a common dedicated conditional, no new component or annotation is required:
|
|
100
146
|
|
|
101
147
|
```tsx
|
|
@@ -149,6 +195,703 @@ Later list updates patch surviving rows by key, create or remove only the change
|
|
|
149
195
|
longest increasing subsequence (LIS) to minimize DOM moves during a reorder. The outer user
|
|
150
196
|
component and the list callback do not rerun for those compiler-cell updates.
|
|
151
197
|
|
|
198
|
+
When a separate state cell or primitive prop is compared with the exact row-key expression using
|
|
199
|
+
`===` or `!==`, the compiler emits a key-directed binding proof. A selection change such as
|
|
200
|
+
`item.id === selectedId` then looks up only the previously selected and newly selected row
|
|
201
|
+
instances. Class, attribute, style, and leaf-text bindings on those rows update without evaluating
|
|
202
|
+
the other keyed instances. The proof requires one reactive target used only in strict comparisons;
|
|
203
|
+
mixed structural dependencies, ambiguous expressions, non-primitive runtime targets, React-owned
|
|
204
|
+
rows, and unsupported shapes keep the complete scan or React fallback. No option is required, and
|
|
205
|
+
the compiler report exposes the emitted binding count as `keyedIdentityTargets`.
|
|
206
|
+
|
|
207
|
+
For multi-selection, an exact local-state expression such as `markedIds.has(item.id)` receives a
|
|
208
|
+
separate Set-membership proof. The runtime compares the previous and next native `Set` snapshots and
|
|
209
|
+
patches only row keys in their symmetric difference. It accepts ordinary native sets containing
|
|
210
|
+
primitive keys. Different fields, extra reactive dependencies, Set subclasses or proxies, object
|
|
211
|
+
members, customized `has` behavior, React-owned rows, nested blocks, and structural dependencies
|
|
212
|
+
stay on the existing complete or React-owned paths. The compiler report exposes this count as
|
|
213
|
+
`keyedMembershipTargets`.
|
|
214
|
+
|
|
215
|
+
For per-row data, an exact local-state expression such as `statusById.get(item.id)` receives a
|
|
216
|
+
separate Map-lookup proof. The runtime compares the previous and next native `Map` snapshots and
|
|
217
|
+
patches only row keys whose mapped primitive value changed. It accepts ordinary native maps with
|
|
218
|
+
primitive keys and primitive or nullish values. Different fields, extra dependencies, Map
|
|
219
|
+
subclasses or proxies, object values, customized `get` behavior, React-owned rows, nested blocks,
|
|
220
|
+
and structural dependencies keep the existing complete or React-owned paths. The compiler report
|
|
221
|
+
exposes this count as `keyedMapLookupTargets`.
|
|
222
|
+
|
|
223
|
+
When a targeted Set or Map is compiler-owned, Farm can also carry the exact mutated keys from a
|
|
224
|
+
proven immutable functional update:
|
|
225
|
+
|
|
226
|
+
```tsx
|
|
227
|
+
setMarkedIds((current) => {
|
|
228
|
+
const next = new Set(current);
|
|
229
|
+
if (next.has(id)) next.delete(id);
|
|
230
|
+
else next.add(id);
|
|
231
|
+
return next;
|
|
232
|
+
});
|
|
233
|
+
|
|
234
|
+
setStatusById((current) => new Map(current).set(id, "ready"));
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
The application still creates its normal immutable collection. The generated update records only
|
|
238
|
+
the native `add`, `delete`, or `set` calls that execute, and the runtime validates those keys
|
|
239
|
+
against the previous committed collection. It can then update the relevant keyed rows without
|
|
240
|
+
iterating every old and new Set member or Map entry first. Queued functional updates compose, and
|
|
241
|
+
the runtime periodically compacts its persistent snapshot so a long update chain stays bounded.
|
|
242
|
+
|
|
243
|
+
This proof is deliberately conservative. The state must start from a compiler-owned native
|
|
244
|
+
`Set`/`Map`; every setter use must be a fresh same-kind replacement or a recognized immutable
|
|
245
|
+
updater; and the collection, updater parameter, and cloned draft must not escape or be mutated
|
|
246
|
+
through unknown code. Shadowed constructors, custom collections, object keys, object Map values,
|
|
247
|
+
direct state mutation, aliased drafts, or a failed runtime check use the existing snapshot or
|
|
248
|
+
React-owned path before compiled bindings run. No option or syntax is added. The compiler report
|
|
249
|
+
counts emitted native mutation sites as `keyedCollectionUpdateHints`.
|
|
250
|
+
|
|
251
|
+
For a direct keyed `useState` collection, the compiler also recognizes conservative same-order
|
|
252
|
+
updates such as:
|
|
253
|
+
|
|
254
|
+
```tsx
|
|
255
|
+
setItems((current) =>
|
|
256
|
+
current
|
|
257
|
+
.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item))
|
|
258
|
+
.map((item) => (item.id === targetId ? { ...item, selected: !item.selected } : item)),
|
|
259
|
+
);
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Farm executes every generated native `map()` and then compares the committed and final item
|
|
263
|
+
identities once. It validates final length, keys, and positions and patches each final changed row
|
|
264
|
+
once; intermediate arrays never receive DOM work. Every user `map()` remains O(n); this removes the
|
|
265
|
+
keyed runtime's second full key-and-binding scan. Queued hints compose. The source method lookup,
|
|
266
|
+
native result, callback order, and thrown errors are preserved.
|
|
267
|
+
|
|
268
|
+
The setter may be concise or use a block containing exactly one value-returning `return`. Extra
|
|
269
|
+
updater statements, conditional returns, and missing returns keep complete keyed reconciliation.
|
|
270
|
+
Each stage requires an inline synchronous conditional mapper that returns the original item on at
|
|
271
|
+
least one path and an object-spread replacement on another. The callback may be a concise expression
|
|
272
|
+
or a structured block containing fully returning `if` or `switch` branches and proven local `const`
|
|
273
|
+
aliases. Each alias needs a simple identifier and compiler-safe initializer. A `switch` needs one
|
|
274
|
+
`default`, a complete return from every case, safe discriminant and case expressions, and no trailing
|
|
275
|
+
statements. Consecutive empty labels may share the next fully returning body; partially executed
|
|
276
|
+
fallthrough and dangling labels are rejected. An unsupported mapper anywhere in the chain disables
|
|
277
|
+
the complete setter hint. Custom methods still execute but record no metadata. Key changes, structural
|
|
278
|
+
edits, sparse or subclassed arrays, relevant mixed dependencies, and failed runtime checks use the
|
|
279
|
+
existing complete reconciliation and LIS path. Non-functional setters, derived collections,
|
|
280
|
+
referenced callbacks, mutable or destructured declarations, effectful initializers, other
|
|
281
|
+
intermediate statements, partial or dangling fallthrough, mutating mappers, and other unproven forms
|
|
282
|
+
are simply not hinted. No new option is required. A compiler report counts prepared map calls as
|
|
283
|
+
`keyedMapUpdateHints`. The separate hint runtime capability is imported only when that count is
|
|
284
|
+
nonzero, so direct-only and ordinary keyed builds do not retain it.
|
|
285
|
+
|
|
286
|
+
The same optional runtime recognizes conservative immutable appends on a direct keyed array:
|
|
287
|
+
|
|
288
|
+
```tsx
|
|
289
|
+
setItems((current) => [...current, nextItem]);
|
|
290
|
+
setItems((current) => [...current, ...nextItems]);
|
|
291
|
+
setItems((current) => {
|
|
292
|
+
return [...current, ...nextItems];
|
|
293
|
+
});
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Because every existing item keeps its key and index, Farm validates the committed source and the
|
|
297
|
+
queued append chain, reads keys and descriptors only for the appended suffix, and mounts that
|
|
298
|
+
suffix in one fragment. Existing row DOM is left untouched. The setter may be concise or use a
|
|
299
|
+
block containing exactly one direct value-returning `return`. Extra statements, conditional
|
|
300
|
+
returns, and missing returns keep complete keyed reconciliation. Native arrays are required;
|
|
301
|
+
middle insertion, removal, direct replacement, duplicate keys, rows that read the collection
|
|
302
|
+
itself, and failed runtime checks use complete keyed reconciliation. A key that reads the
|
|
303
|
+
collection prevents hint emission entirely. The compiler report exposes the emitted-site count as
|
|
304
|
+
`keyedArrayAppendHints`.
|
|
305
|
+
|
|
306
|
+
When all keyed-row plans in a component are plain, target-free rows and the only emitted update
|
|
307
|
+
hints are appends, the compiler selects a smaller append-only runtime. This omits unused map-update
|
|
308
|
+
and keyed-target fast paths, not support for other state changes: opaque updates and rejected hints
|
|
309
|
+
still use complete keyed reconciliation. Mixed hints, targeted bindings, conditional rows, and host
|
|
310
|
+
blocks keep their existing runtime. No additional option is required.
|
|
311
|
+
|
|
312
|
+
The same component-wide proof selects a smaller removal-only runtime when the only emitted
|
|
313
|
+
update hints are `filter()` and/or `slice()`. It omits unused append, map-update, and keyed-target
|
|
314
|
+
fast paths while retaining complete keyed reconciliation for opaque updates or rejected hints.
|
|
315
|
+
A sibling list requiring broader hints, targeted bindings, conditional rows, or host blocks keeps
|
|
316
|
+
the existing combined runtime. This changes bundle selection, not native array or React semantics.
|
|
317
|
+
|
|
318
|
+
Adjacent removal and append setters can share the same committed-row proof:
|
|
319
|
+
|
|
320
|
+
```tsx
|
|
321
|
+
setItems((current) => current.filter((item) => item.id !== expiredId));
|
|
322
|
+
setItems((current) => [...current, incoming]);
|
|
323
|
+
|
|
324
|
+
setItems((current) => current.slice(start, end));
|
|
325
|
+
setItems((current) => [...current, ...incoming]);
|
|
326
|
+
|
|
327
|
+
setItems((current) => current.slice(start, end));
|
|
328
|
+
setItems((current) => [...current, incoming]);
|
|
329
|
+
setItems((current) =>
|
|
330
|
+
current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
|
|
331
|
+
);
|
|
332
|
+
|
|
333
|
+
setItems((current) => current.filter((item) => item.id !== expiredId));
|
|
334
|
+
setItems((current) =>
|
|
335
|
+
current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
|
|
336
|
+
);
|
|
337
|
+
setItems((current) => [...current, incoming]);
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
The setters still execute in order and still create their normal native arrays. Before changing the
|
|
341
|
+
DOM, Farm validates the original committed token, every filter or slice survivor, the complete final
|
|
342
|
+
length, and every incoming key. It prepares all incoming keys, descriptors, bindings, and detached
|
|
343
|
+
host rows first; only then does it remove rejected rows, update survivor indexes, and append the new
|
|
344
|
+
suffix in one fragment. Existing survivors are neither rebound nor recreated, and additional
|
|
345
|
+
adjacent append setters are collapsed into the same final suffix. This keeps the unavoidable native
|
|
346
|
+
filter or slice work while removing the keyed runtime's second full scan.
|
|
347
|
+
|
|
348
|
+
One or more immediately adjacent safe same-key `map()` setters may run between the filter or slice
|
|
349
|
+
and the append, after the append, or in both positions. A safe map may also precede the structural
|
|
350
|
+
removal. Farm carries the original survivor indices or retained interval through those native maps
|
|
351
|
+
and records each replacement against its committed row. Before touching the DOM it validates the
|
|
352
|
+
complete dense result, every survivor identity, every changed key and binding, and every incoming
|
|
353
|
+
row. It then removes only rejected rows, patches only changed survivors, and creates the suffix from
|
|
354
|
+
its final values. The owner stays mounted, survivor DOM identity is preserved, and the suffix is
|
|
355
|
+
appended once.
|
|
356
|
+
|
|
357
|
+
Only concise updater results and blocks with one direct value-returning `return` that form one
|
|
358
|
+
direct chain for the same state array are linked. The row and key must be compiler-owned and
|
|
359
|
+
index-independent. A reorder in the structural-append chain, an
|
|
360
|
+
unsupported or non-adjacent map, an unhinted update to that state, another dirty row dependency,
|
|
361
|
+
collection-reading binding, custom, sparse, or subclassed array, nested or React-owned row,
|
|
362
|
+
duplicate final key, or reuse of any committed key in the appended suffix keeps complete React
|
|
363
|
+
reconciliation before a DOM write. A mapped survivor whose key changes also falls back before
|
|
364
|
+
mutation. No API or configuration is added. Compiler reports use the existing
|
|
365
|
+
`keyedArrayFilterHints`, `keyedArraySliceHints`, and `keyedArrayAppendHints` counts, and modules
|
|
366
|
+
without both accepted operations omit the composed runtime.
|
|
367
|
+
|
|
368
|
+
The mirror-image prepend form is supported when the keyed row and key do not read the row index:
|
|
369
|
+
|
|
370
|
+
```tsx
|
|
371
|
+
setItems((current) => [nextItem, ...current]);
|
|
372
|
+
setItems((current) => [...nextItems, ...current]);
|
|
373
|
+
setItems((current) => {
|
|
374
|
+
return [...nextItems, ...current];
|
|
375
|
+
});
|
|
376
|
+
|
|
377
|
+
setItems((current) => current.filter((item) => item.id !== expiredId));
|
|
378
|
+
setItems((current) => [nextItem, ...current]);
|
|
379
|
+
|
|
380
|
+
setItems((current) => current.slice(start, end));
|
|
381
|
+
setItems((current) => [...nextItems, ...current]);
|
|
382
|
+
|
|
383
|
+
setItems((current) => current.filter((item) => item.id !== expiredId));
|
|
384
|
+
setItems((current) => [nextItem, ...current]);
|
|
385
|
+
setItems((current) =>
|
|
386
|
+
current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
|
|
387
|
+
);
|
|
388
|
+
|
|
389
|
+
setItems((current) => current.slice(start, end));
|
|
390
|
+
setItems((current) =>
|
|
391
|
+
current.map((item) => (item.id === targetId ? { ...item, label: nextLabel } : item)),
|
|
392
|
+
);
|
|
393
|
+
setItems((current) => [nextItem, ...current]);
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
Farm validates the committed source and queued prepend chain, creates only the new prefix, inserts
|
|
397
|
+
it before the first existing row, and shifts the stored indexes used by delegated row events.
|
|
398
|
+
When an adjacent filter or bounded slice runs first, the compiler also carries the exact survivor
|
|
399
|
+
positions into the prepend. The runtime removes only rejected rows, preserves every surviving DOM
|
|
400
|
+
node, and creates only the final prefix instead of rescanning and rebinding the whole result.
|
|
401
|
+
Multiple adjacent prepends share the same proof.
|
|
402
|
+
|
|
403
|
+
When every keyed list in a component is plain and has no targeted bindings, and prepend is
|
|
404
|
+
the only emitted update hint, Farm selects a smaller prepend-only runtime. It omits unused
|
|
405
|
+
target and map/append fast paths, but keeps the same prepend validation and complete keyed
|
|
406
|
+
reconciliation for opaque or rejected updates. Mixed hints, conditional/host rows, and targeted
|
|
407
|
+
bindings on any sibling list keep their existing runtime. This changes bundle size, not the
|
|
408
|
+
supported update semantics or the prepend algorithm.
|
|
409
|
+
|
|
410
|
+
The setter may be concise or use a block containing exactly one direct value-returning `return`.
|
|
411
|
+
Extra statements, conditional returns, and missing returns keep complete keyed reconciliation.
|
|
412
|
+
|
|
413
|
+
One or more immediately adjacent safe same-key `map()` setters may run after the prepend or between
|
|
414
|
+
the removal and prepend. A safe map may also run immediately before the removal. Farm carries every
|
|
415
|
+
survivor back to its committed row, validates the complete dense result and every final key, then
|
|
416
|
+
patches only changed survivors and creates the prefix from its final mapped values. A surviving DOM
|
|
417
|
+
node keeps its identity even when its item object changes.
|
|
418
|
+
|
|
419
|
+
Index-aware rows, collection-reading bindings or keys, React-owned or nested row structures,
|
|
420
|
+
middle insertion, direct replacement, a reordered structural chain, an unsupported or non-adjacent
|
|
421
|
+
map, duplicate final keys, reuse of any committed key in the new prefix, custom or sparse arrays,
|
|
422
|
+
and failed validation use complete keyed reconciliation before any DOM mutation. A mapped survivor
|
|
423
|
+
whose key changes also falls back before mutation. The compiler report exposes the emitted-site
|
|
424
|
+
count as `keyedArrayPrependHints`; no option or component API is added, and modules without the
|
|
425
|
+
accepted removal, prepend, and map chain omit its mapped runtime.
|
|
426
|
+
|
|
427
|
+
Native slices with compiler-safe bounds can carry their exact retained interval into the same
|
|
428
|
+
removal runtime:
|
|
429
|
+
|
|
430
|
+
```tsx
|
|
431
|
+
setItems((current) => current.slice(1_000));
|
|
432
|
+
setItems((current) => current.slice(0, -1_000));
|
|
433
|
+
setItems((current) => current.slice(2, 8));
|
|
434
|
+
setItems((current) => current.slice(trimCount));
|
|
435
|
+
setItems((current) => current.slice(visible.start, visible.end));
|
|
436
|
+
setItems((current) => {
|
|
437
|
+
return current.slice(visible.start, visible.end);
|
|
438
|
+
});
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
For compiler-owned host rows whose render and key do not read the row index, Farm validates the
|
|
442
|
+
committed source and queued slice chain, preserves every surviving DOM row, and removes only rows
|
|
443
|
+
outside the retained interval. A slice-only chain does not reread surviving keys, descriptors, or
|
|
444
|
+
bindings. One or two safe-integer literals or compiler-safe runtime expressions are required.
|
|
445
|
+
Identifiers, property reads, side-effect-free arithmetic and conditionals, and safe `Math` calls
|
|
446
|
+
are supported. The setter may be concise or use a block containing exactly one direct
|
|
447
|
+
value-returning `return`. Farm preserves native method lookup, argument evaluation, coercion,
|
|
448
|
+
results, and errors, then records metadata only when the evaluated bounds are already safe integers.
|
|
449
|
+
Calls, assignments, updates, unsafe evaluated bounds, updater blocks with extra statements,
|
|
450
|
+
directives, conditional returns, or no value-returning `return`, chained updates, custom slice
|
|
451
|
+
methods, sparse or subclassed arrays, index-aware or collection-reading rows, React-owned structures,
|
|
452
|
+
and failed validation keep complete keyed reconciliation. No option or component is added. The
|
|
453
|
+
compiler report exposes the emitted-site count as `keyedArraySliceHints`.
|
|
454
|
+
|
|
455
|
+
A fixed-size feed can combine that retained tail with a new keyed suffix:
|
|
456
|
+
|
|
457
|
+
```tsx
|
|
458
|
+
setItems((current) => [...current.slice(1), nextItem]);
|
|
459
|
+
setItems((current) => [...current.slice(1_000), ...nextItems]);
|
|
460
|
+
|
|
461
|
+
const trimCount = pageSize * pagesToExpire;
|
|
462
|
+
setItems((current) => [...current.slice(trimCount), ...nextItems]);
|
|
463
|
+
setItems((current) => {
|
|
464
|
+
return [...current.slice(trimCount), ...nextItems];
|
|
465
|
+
});
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
Farm executes the ordinary native slice and array construction, then validates the complete hint
|
|
469
|
+
chain back to the committed source, retained item identities, and final incoming keys. Multiple
|
|
470
|
+
rolling setters queued before one compiler flush collapse into one cumulative prefix removal; rows
|
|
471
|
+
introduced by an earlier setter are created only if they remain in the final suffix. Farm removes
|
|
472
|
+
only the expired committed prefix, leaves the retained DOM rows in place, and creates only that
|
|
473
|
+
final incoming suffix. The setter may be concise or use a block containing exactly one direct
|
|
474
|
+
value-returning `return`. This form supports one safe-integer literal or compiler-safe runtime slice
|
|
475
|
+
bound and compiler-owned, index-independent host rows. Identifiers, property reads,
|
|
476
|
+
side-effect-free arithmetic and conditionals, and safe `Math` calls are supported while preserving
|
|
477
|
+
native lookup, evaluation, results, and errors.
|
|
478
|
+
|
|
479
|
+
Immediately adjacent safe same-key maps may run before, after, or between one or more rolling
|
|
480
|
+
setters in the same synchronous setter segment:
|
|
481
|
+
|
|
482
|
+
```tsx
|
|
483
|
+
setItems((current) =>
|
|
484
|
+
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
|
|
485
|
+
);
|
|
486
|
+
setItems((current) => [...current.slice(trimCount), ...nextItems]);
|
|
487
|
+
setItems((current) =>
|
|
488
|
+
current.map((item) => (item.id === selectedId ? { ...item, selected: true } : item)),
|
|
489
|
+
);
|
|
490
|
+
setItems((current) => [...current.slice(secondTrimCount), ...laterItems]);
|
|
491
|
+
setItems((current) =>
|
|
492
|
+
current.map((item) => (item.id === editedId ? { ...item, status: "ready" } : item)),
|
|
493
|
+
);
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
Each map may use a compiler-safe nested conditional to update several retained rows.
|
|
497
|
+
The compiler carries mapped survivor identity through the retained tail, creates incoming rows
|
|
498
|
+
from their final mapped values, and patches only changed committed survivors. A single rolling
|
|
499
|
+
setter uses the optional structural append/map runtime. Multiple rolling setters keep their
|
|
500
|
+
cumulative retained-window metadata and mapped provenance through an optional runtime dedicated to
|
|
501
|
+
mapped rolling chains. No new public helper, option, or always-loaded browser code is added.
|
|
502
|
+
|
|
503
|
+
Effectful expressions, reused keys, updater blocks with extra statements, directives, conditional
|
|
504
|
+
returns, or no value-returning `return`, custom slice behavior, collection-reading or index-aware
|
|
505
|
+
rows, nested or React-owned rows, mixed or unhinted queued chains, a statement or unsupported setter
|
|
506
|
+
inside the segment, changed mapped keys, unsafe or no-op evaluated bounds, and failed checks use
|
|
507
|
+
complete keyed reconciliation. Unmapped rolling modules retain the smaller optional all-hint
|
|
508
|
+
runtime. Reports expose each emitted rolling site as `keyedArrayRollingWindowHints`, each rolling
|
|
509
|
+
step retained across a multi-window mapped chain as `keyedArrayMappedRollingWindowChainHints`, and
|
|
510
|
+
each safe map as `keyedMapUpdateHints`.
|
|
511
|
+
|
|
512
|
+
Native known-position updates can avoid a complete keyed scan too:
|
|
513
|
+
|
|
514
|
+
```tsx
|
|
515
|
+
setItems((current) => current.toSpliced(selectedIndex, 0, nextItem));
|
|
516
|
+
setItems((current) => current.toSpliced(selectedIndex, 0, nextA, nextB));
|
|
517
|
+
setItems((current) => current.toSpliced(selectedIndex, 0, ...incomingItems));
|
|
518
|
+
setItems((current) => current.toSpliced(selectedIndex, 1));
|
|
519
|
+
setItems((current) => current.toSpliced(selectedIndex, 25));
|
|
520
|
+
setItems((current) => current.toSpliced(selectedIndex, 1, replacement));
|
|
521
|
+
setItems((current) => current.toSpliced(selectedIndex, 25, ...replacements));
|
|
522
|
+
setItems((current) => current.with(selectedIndex, replacement));
|
|
523
|
+
setItems((current) => {
|
|
524
|
+
return current.toSpliced(selectedIndex, 0, nextItem);
|
|
525
|
+
});
|
|
526
|
+
setItems((current) => {
|
|
527
|
+
return current.with(selectedIndex, replacement);
|
|
528
|
+
});
|
|
529
|
+
|
|
530
|
+
// Two same-key windows may be queued before one compiler flush.
|
|
531
|
+
setItems((current) => current.toSpliced(firstIndex, 25, ...firstRefresh));
|
|
532
|
+
setItems((current) => current.toSpliced(secondIndex, 25, ...secondRefresh));
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
When every keyed list in a component is plain and has no identity, `Set` membership, or `Map`
|
|
536
|
+
lookup targets, single-item position hints (including range removal) select a smaller runtime
|
|
537
|
+
without target tracking. Ordinary map and append updates and complete reconciliation remain
|
|
538
|
+
available. Any sibling with targets, conditional content, host scopes, or broader structural hints
|
|
539
|
+
retains the corresponding full-capability runtime. Batch insertion and window replacement keep
|
|
540
|
+
their existing runtimes. This changes payload size, not array-method or React behavior.
|
|
541
|
+
|
|
542
|
+
The compiler recognizes a concise functional setter or a setter block containing exactly one direct
|
|
543
|
+
`return`. Its position must be either a safe-integer literal or a compiler-safe runtime expression,
|
|
544
|
+
such as an identifier, property read, arithmetic, conditional, or safe `Math` call. The update must insert
|
|
545
|
+
one or more compiler-safe items with zero removals, remove one item or a fixed positive safe-integer
|
|
546
|
+
literal range, replace one item through either `toSpliced()` or `with()`, or replace a fixed positive
|
|
547
|
+
safe-integer literal window with compiler-safe explicit items or a safe spread. Farm preserves method lookup,
|
|
548
|
+
evaluates the position and remaining arguments once in their original order, executes the ordinary
|
|
549
|
+
native call, and records metadata only after validating the committed native source, result, and
|
|
550
|
+
actual safe-integer position and clamped removal count. A batch requires at least two evaluated
|
|
551
|
+
items at runtime. Exact-window replacement supports a safe spread that evaluates to zero, one, or
|
|
552
|
+
many items. A fresh-key window creates every incoming key, descriptor, binding snapshot, and
|
|
553
|
+
detached row before changing the live DOM, rejects key collisions, and mounts the complete batch
|
|
554
|
+
through one document fragment. It then removes only the replaced window. When the incoming window
|
|
555
|
+
has the same length and the same keys in the same order, Farm prepares every binding read and
|
|
556
|
+
changed DOM target across the complete window first, patches the existing rows in place, and
|
|
557
|
+
updates the stored row objects used by later events. That path creates no descriptors or DOM rows,
|
|
558
|
+
and preserves row identity, focus, and selection. Validated same-key row and window refreshes also
|
|
559
|
+
keep the existing row map and element lookup, and skip redundant cache cleanup instead of
|
|
560
|
+
rebuilding whole-list bookkeeping. Source and key validation still run, and each flush commits the
|
|
561
|
+
new collection token for subsequent updates. Structural changes retain index rebuilding and cache
|
|
562
|
+
cleanup. A window may instead grow or shrink while it
|
|
563
|
+
reorders keys from inside its own removed interval and mixes them with globally fresh keys. Farm
|
|
564
|
+
prepares all reused binding updates, new descriptors, binding snapshots, and detached rows before
|
|
565
|
+
the first DOM write. It removes only retired rows, preserves each reused row, batches adjacent new
|
|
566
|
+
rows in a fragment, updates shifted suffix indexes, and applies LIS only to the reused part of that
|
|
567
|
+
interval so it moves the fewest connected rows needed by the local permutation. Rows outside the
|
|
568
|
+
interval are not rerendered or rebound.
|
|
569
|
+
Multiple length-preserving same-key windows
|
|
570
|
+
queued before one compiler flush compose into one atomic refresh. Fixed-length queued windows may
|
|
571
|
+
mix same-key refreshes with globally new final keys, and both disjoint and overlapping windows are
|
|
572
|
+
supported. An overlapping position uses the last queued value; intermediate identities are never
|
|
573
|
+
mounted. Farm validates the complete chain and final key set, then prepares every touched key,
|
|
574
|
+
binding value, DOM target, new descriptor, binding snapshot, and disconnected DOM row before the
|
|
575
|
+
first write. It patches same-key positions and swaps only final fresh-key positions. Untouched rows
|
|
576
|
+
keep their identity and are not recreated. The runtime otherwise creates one inserted row,
|
|
577
|
+
removes only the known row or range, or patches/replaces one row at that position without rereading
|
|
578
|
+
every existing key, descriptor, and binding. Surviving rows keep their DOM identity. Index-aware or
|
|
579
|
+
collection-reading rows, custom methods, position expressions with user calls or mutations,
|
|
580
|
+
runtime positions that are not safe integers, dynamic, zero, negative, or fractional removal
|
|
581
|
+
counts, other `toSpliced()` forms, updater blocks with extra statements, directives, conditional
|
|
582
|
+
returns, or no value-returning `return`, unsafe incoming expressions, queued chains containing a
|
|
583
|
+
structural window or unhinted intermediate update, existing keys moved from outside the removed
|
|
584
|
+
interval, duplicate final keys, nested or React-owned rows, and failed checks use complete keyed
|
|
585
|
+
reconciliation before the fast path mutates the DOM.
|
|
586
|
+
Reports expose the site count as `keyedArrayPositionHints`. Batch insertion and exact-window
|
|
587
|
+
replacement use progressively separate optional runtime capabilities, so existing single-position
|
|
588
|
+
and batch-only bundles do not retain window validation or replacement code.
|
|
589
|
+
|
|
590
|
+
A direct native reverse can carry its complete permutation to a separate optional runtime:
|
|
591
|
+
|
|
592
|
+
```tsx
|
|
593
|
+
setItems((current) => current.toReversed());
|
|
594
|
+
setItems((current) => {
|
|
595
|
+
return current.toReversed();
|
|
596
|
+
});
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
Farm recognizes the concise form and a block containing exactly one direct `return`. It preserves
|
|
600
|
+
the method lookup, call result, and errors, then records metadata only for the native method on an
|
|
601
|
+
ordinary array whose chain starts at the committed collection. One direct reverse
|
|
602
|
+
verifies equal lengths and every reversed item identity before moving the existing keyed elements
|
|
603
|
+
with the minimum `n - 1` connected DOM moves. It does not reread row keys, descriptors, or bindings
|
|
604
|
+
and does not run the generic LIS calculation. Consecutive concise native `toReversed()` and
|
|
605
|
+
`toSorted()` setters queued before one flush compose into one final validated permutation. The
|
|
606
|
+
runtime skips intermediate DOM states. When the proven chain contains only reversals, Farm tracks
|
|
607
|
+
their parity relative to the committed rows: an even count validates exact identity and performs
|
|
608
|
+
no DOM moves, source-item map construction, or LIS; an odd count validates exact reverse and uses
|
|
609
|
+
the same minimum `n - 1` moves as one reverse. A chain containing a sort keeps the general final
|
|
610
|
+
permutation and uses LIS once. A concise updater or a block containing exactly one direct
|
|
611
|
+
value-returning `return` may also chain two or more native reorder operations:
|
|
612
|
+
|
|
613
|
+
```tsx
|
|
614
|
+
setItems((current) => current.toSorted((left, right) => left.rank - right.rank).toReversed());
|
|
615
|
+
setItems((current) => {
|
|
616
|
+
return current.toSorted((left, right) => left.rank - right.rank).toReversed();
|
|
617
|
+
});
|
|
618
|
+
```
|
|
619
|
+
|
|
620
|
+
Farm evaluates every lookup and call in JavaScript order, carries the same committed token through
|
|
621
|
+
the pipeline, and reconciles only its final result. Index-aware or collection-reading rows,
|
|
622
|
+
arguments to `toReversed()`, referenced comparators, computed methods, updater blocks with extra
|
|
623
|
+
statements, directives, conditional returns, or no returned value, custom methods, sparse or
|
|
624
|
+
subclassed behavior, structural calls after reordering, an unhinted intermediate update, nested or
|
|
625
|
+
React-owned rows, and failed checks keep complete keyed reconciliation.
|
|
626
|
+
|
|
627
|
+
A compiler-safe `filter()` or bounded `slice()` prefix may precede the native reorder suffix in a
|
|
628
|
+
concise updater or exact one-return block. A filter predicate may be concise or contain exactly one
|
|
629
|
+
direct value-returning `return`:
|
|
630
|
+
|
|
631
|
+
```tsx
|
|
632
|
+
setItems((current) =>
|
|
633
|
+
current
|
|
634
|
+
.filter((item) => {
|
|
635
|
+
return item.visible;
|
|
636
|
+
})
|
|
637
|
+
.toSorted((left, right) => left.rank - right.rank)
|
|
638
|
+
.toReversed(),
|
|
639
|
+
);
|
|
640
|
+
```
|
|
641
|
+
|
|
642
|
+
Farm validates the complete survivor set and final order before the first DOM write, removes only
|
|
643
|
+
rejected rows, and applies LIS once to the survivors. Concise or exact one-return filter/slice and
|
|
644
|
+
reorder setters also compose when queued in that order before one flush. Unsupported calls or a
|
|
645
|
+
structural call after a reorder fall back. Reports count each compiled step in the existing filter,
|
|
646
|
+
slice, sort, or reverse counter, and modules without those operations omit their optional runtimes.
|
|
647
|
+
Farm does not polyfill `Array.prototype.toReversed`.
|
|
648
|
+
|
|
649
|
+
A compiler-safe same-key map may also appear before or after native reorder steps:
|
|
650
|
+
|
|
651
|
+
```tsx
|
|
652
|
+
setItems((current) =>
|
|
653
|
+
current
|
|
654
|
+
.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
|
|
655
|
+
.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item))
|
|
656
|
+
.toSorted((left, right) => left.rank - right.rank),
|
|
657
|
+
);
|
|
658
|
+
```
|
|
659
|
+
|
|
660
|
+
One callback may select several rows through nested expressions, structured early returns, or a
|
|
661
|
+
fully returning `switch`:
|
|
662
|
+
|
|
663
|
+
```tsx
|
|
664
|
+
setItems((current) =>
|
|
665
|
+
current.map((item) => {
|
|
666
|
+
const matchesReviewed = item.id === reviewedId;
|
|
667
|
+
if (matchesReviewed) return { ...item, status: "reviewed" };
|
|
668
|
+
const matchesEscalated = item.id === escalatedId;
|
|
669
|
+
if (matchesEscalated) {
|
|
670
|
+
return { ...item, status: "escalated", priority: 1 };
|
|
671
|
+
}
|
|
672
|
+
return item;
|
|
673
|
+
}),
|
|
674
|
+
);
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
Every condition must be compiler-safe, and every leaf must return the original item or a safe
|
|
678
|
+
object spread of it, with at least one unchanged and one replacement path. Concise expressions and
|
|
679
|
+
blocks made from fully returning `if` or `switch` branches plus local `const` aliases are accepted.
|
|
680
|
+
Each alias must have a simple identifier and compiler-safe initializer. A switch requires one
|
|
681
|
+
`default` and complete returning cases. Consecutive empty labels may share the next body, while
|
|
682
|
+
partial or dangling fallthrough is rejected. Mutable or destructured declarations, effectful
|
|
683
|
+
initializers, other intermediate statements, and ambiguous leaves use complete keyed
|
|
684
|
+
reconciliation. A runtime key change also falls back before any DOM write.
|
|
685
|
+
|
|
686
|
+
The functional setter may be concise or a block containing exactly one direct value-returning
|
|
687
|
+
`return`. Farm executes every native map and reorder call normally. For consecutive accepted maps,
|
|
688
|
+
it checks each native call but compares only the input and final result of that map segment, avoiding
|
|
689
|
+
a full lineage scan for every intermediate array. It verifies the committed token, dense-array
|
|
690
|
+
shape, a one-to-one source-item match, and every final replacement key before touching the DOM, then runs one
|
|
691
|
+
LIS and patches each changed row once. Unchanged rows need no second key or binding read. Queued
|
|
692
|
+
supported map-and-reorder setters compose against the same committed rows. Every accepted map
|
|
693
|
+
requires an inline synchronous conditional mapper whose leaves return either the original item or
|
|
694
|
+
an object-spread replacement, plus index-independent compiler-owned host rows. Concise expressions
|
|
695
|
+
and structured blocks with proven local `const` aliases plus fully returning `if` or `switch`
|
|
696
|
+
branches are supported.
|
|
697
|
+
Changed keys, referenced callbacks, mutable, destructured, or effectful declarations, other
|
|
698
|
+
intermediate statements or partial/dangling fallthrough, unconditional replacements, `thisArg`,
|
|
699
|
+
structural calls in the same chain, computed or custom methods, sparse or subclassed arrays,
|
|
700
|
+
collection-reading bindings, nested or React-owned rows, and failed checks use complete keyed
|
|
701
|
+
reconciliation. Reports use the existing map, sort, and reorder hint counters, and unrelated modules
|
|
702
|
+
do not retain this optional runtime.
|
|
703
|
+
|
|
704
|
+
The maps may also finish the concise pipeline:
|
|
705
|
+
|
|
706
|
+
```tsx
|
|
707
|
+
setItems((current) =>
|
|
708
|
+
current
|
|
709
|
+
.toReversed()
|
|
710
|
+
.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
|
|
711
|
+
.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
|
|
712
|
+
);
|
|
713
|
+
```
|
|
714
|
+
|
|
715
|
+
Farm retains the preceding reorder instead of treating the mapped result as an unhinted snapshot.
|
|
716
|
+
An exact reverse uses the minimum-move reverse path without a general source-item lookup or LIS. A
|
|
717
|
+
sort remains an ambiguous permutation, so Farm performs one validated source lookup and LIS pass.
|
|
718
|
+
Safe maps on both sides of a reorder flatten their replacements back to the same committed rows.
|
|
719
|
+
|
|
720
|
+
Safe maps may also run before, between, or after index-independent `filter` or `slice` steps in one
|
|
721
|
+
concise functional setter or one block with a single direct `return`. A final native reorder is optional:
|
|
722
|
+
|
|
723
|
+
```tsx
|
|
724
|
+
setItems((current) =>
|
|
725
|
+
current
|
|
726
|
+
.filter((item) => item.visible)
|
|
727
|
+
.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
|
|
728
|
+
.slice(0, limit)
|
|
729
|
+
.toSorted((left, right) => left.rank - right.rank),
|
|
730
|
+
);
|
|
731
|
+
|
|
732
|
+
setItems((current) =>
|
|
733
|
+
current
|
|
734
|
+
.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item))
|
|
735
|
+
.filter((item) => item.visible)
|
|
736
|
+
.slice(0, limit),
|
|
737
|
+
);
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
The structural helpers retain both the committed survivor indices and mapped-item sources across
|
|
741
|
+
each accepted step. The final commit removes rejected rows, performs LIS moves only when a reorder
|
|
742
|
+
needs them, and patches bindings only for changed survivors. Every native callback and method still
|
|
743
|
+
runs in JavaScript order.
|
|
744
|
+
|
|
745
|
+
The structural and map steps may also be split across immediately adjacent setter calls in either
|
|
746
|
+
order:
|
|
747
|
+
|
|
748
|
+
```tsx
|
|
749
|
+
// Map, then structural work.
|
|
750
|
+
setItems((current) =>
|
|
751
|
+
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
|
|
752
|
+
);
|
|
753
|
+
setItems((current) => current.filter((item) => item.visible));
|
|
754
|
+
setItems((current) => current.slice(0, limit));
|
|
755
|
+
|
|
756
|
+
// Structural work, then maps.
|
|
757
|
+
setItems((current) => current.filter((item) => item.visible));
|
|
758
|
+
setItems((current) => current.slice(0, limit));
|
|
759
|
+
setItems((current) =>
|
|
760
|
+
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
|
|
761
|
+
);
|
|
762
|
+
setItems((current) =>
|
|
763
|
+
current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
|
|
764
|
+
);
|
|
765
|
+
```
|
|
766
|
+
|
|
767
|
+
Farm links only consecutive calls to the same setter. A leading map retains its first committed
|
|
768
|
+
source through later structural work; a terminal map consumes the saved survivor lineage from the
|
|
769
|
+
preceding filter or slice. Multiple safe steps in either segment may share the proof, and mixed
|
|
770
|
+
map/structural/map sequences compose. Every result and key is validated before the queued commit
|
|
771
|
+
touches the DOM. An intervening statement, another setter, an unsafe callback, a changed key, or
|
|
772
|
+
failed runtime validation keeps complete keyed reconciliation.
|
|
773
|
+
|
|
774
|
+
The survivor proof may continue through adjacent native reorder setters:
|
|
775
|
+
|
|
776
|
+
```tsx
|
|
777
|
+
setItems((current) => current.filter((item) => item.visible));
|
|
778
|
+
setItems((current) =>
|
|
779
|
+
current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
|
|
780
|
+
);
|
|
781
|
+
setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
|
|
782
|
+
setItems((current) => current.toReversed());
|
|
783
|
+
```
|
|
784
|
+
|
|
785
|
+
Farm retains the committed survivor positions and same-key replacements until the final queued
|
|
786
|
+
value. The commit removes rejected rows, patches changed survivors, and applies the final order in
|
|
787
|
+
one validated DOM transaction. Exact reverses use the minimum-move reverse path; an arbitrary sort
|
|
788
|
+
uses one source lookup and LIS. Non-adjacent calls, another setter, unsupported syntax, or a failed
|
|
789
|
+
shape/key check keep complete reconciliation.
|
|
790
|
+
|
|
791
|
+
The reorder and safe maps may also be adjacent setter calls in the same synchronous block:
|
|
792
|
+
|
|
793
|
+
```tsx
|
|
794
|
+
setItems((current) => current.toReversed());
|
|
795
|
+
setItems((current) =>
|
|
796
|
+
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)),
|
|
797
|
+
);
|
|
798
|
+
setItems((current) =>
|
|
799
|
+
current.map((item) => (item.id === editedId ? { ...item, rank: nextRank } : item)),
|
|
800
|
+
);
|
|
801
|
+
```
|
|
802
|
+
|
|
803
|
+
The compiler links only consecutive calls to the same setter. It keeps the reorder token through
|
|
804
|
+
each accepted native map, then validates row keys before applying the same exact-reverse or
|
|
805
|
+
sort-permutation path at commit. Adjacent compiler-safe filter or slice work switches to the
|
|
806
|
+
structural proof above. An intervening statement, another setter, an unsupported map, or a changed
|
|
807
|
+
key keeps the ordinary complete fallback. Standalone map-only components do not retain the
|
|
808
|
+
map-and-reorder runtime.
|
|
809
|
+
|
|
810
|
+
The mirror order is supported as well: two or more adjacent concise same-key map setters may be
|
|
811
|
+
followed by a concise native reverse or sort setter. Farm records their replacement lineage from
|
|
812
|
+
the committed collection and carries it into the final reorder. Only adjacent calls to the same
|
|
813
|
+
setter are linked; intervening work and unsupported updates retain complete reconciliation.
|
|
814
|
+
|
|
815
|
+
Mapped lineage also continues through multiple adjacent native reorder setters. For example,
|
|
816
|
+
`map -> reverse -> sort -> reverse` keeps the same committed-row proof until the final value, then
|
|
817
|
+
performs one validated keyed reconciliation. A concise `map().toReversed()` pipeline may start the
|
|
818
|
+
same chain. Adjacent compiler-safe filter or slice work changes it into a structural chain while
|
|
819
|
+
retaining the committed source. Every updater and native method still executes in order; another
|
|
820
|
+
setter, intervening work, or an unsupported method ends the chain and preserves the complete
|
|
821
|
+
fallback.
|
|
822
|
+
|
|
823
|
+
A reverse before the safe map pipeline may be queued in a separate setter:
|
|
824
|
+
|
|
825
|
+
```tsx
|
|
826
|
+
setItems((current) => current.toReversed());
|
|
827
|
+
setItems((current) =>
|
|
828
|
+
current.map((item) => (item.id === editedId ? { ...item, label: nextLabel } : item)).toReversed(),
|
|
829
|
+
);
|
|
830
|
+
```
|
|
831
|
+
|
|
832
|
+
A direct `toReversed()` suffix is more specific than an arbitrary permutation. When all preceding
|
|
833
|
+
maps retain committed row order, Farm validates the mirrored source-to-result relation and every
|
|
834
|
+
changed binding before touching the DOM, then performs the minimum-move reverse without building a
|
|
835
|
+
second item lookup map or running LIS. Additional exact reversals toggle that proof between reverse
|
|
836
|
+
and identity. Therefore two reversals after safe maps patch changed rows in committed order without
|
|
837
|
+
moving DOM nodes or creating the generic source map; three use the exact reverse path. Exact reverse
|
|
838
|
+
metadata also composes across queued setters: a queued reverse followed by safe maps and another
|
|
839
|
+
reverse retains exact identity, so only changed row bindings are patched. A preceding sort or any
|
|
840
|
+
ambiguous order keeps the general permutation path.
|
|
841
|
+
|
|
842
|
+
A direct native immutable sort can use the same optional reorder runtime:
|
|
843
|
+
|
|
844
|
+
```tsx
|
|
845
|
+
setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
|
|
846
|
+
setLabels((current) => current.toSorted());
|
|
847
|
+
setItems((current) => {
|
|
848
|
+
return current.toSorted((left, right) => left.rank - right.rank);
|
|
849
|
+
});
|
|
850
|
+
```
|
|
851
|
+
|
|
852
|
+
Farm recognizes a concise functional setter or a block containing exactly one direct `return`,
|
|
853
|
+
with no comparator or an inline synchronous comparator from the compiler-safe expression subset.
|
|
854
|
+
It preserves the original method lookup, comparator, stable native result, and errors. After the
|
|
855
|
+
native sort runs, the runtime validates an ordinary dense array whose reorder chain starts at the
|
|
856
|
+
committed collection, equal lengths, and a unique one-to-one item-identity permutation. It then
|
|
857
|
+
uses LIS to move only `n - LIS` keyed DOM nodes without rereading row keys, descriptors, or
|
|
858
|
+
bindings. Multiple concise native sorts and reverses queued in one flush, or chained in one concise
|
|
859
|
+
updater, share the original committed token and reconcile only their final permutation. The native
|
|
860
|
+
sorting work itself is unchanged.
|
|
861
|
+
|
|
862
|
+
Index-aware or collection-reading rows, referenced comparators, updater blocks with extra
|
|
863
|
+
statements, directives, conditional returns, or no returned value, computed or unsupported chained
|
|
864
|
+
calls, custom methods, sparse or subclassed arrays, duplicate item identities, unhinted intermediate
|
|
865
|
+
updates, structural calls after reordering, nested or React-owned rows, and failed checks keep
|
|
866
|
+
complete keyed reconciliation. A compiler-safe filter/slice prefix is supported. Reports count each
|
|
867
|
+
compiled sort step as a `keyedArraySortHints` entry; sort shares the optional reorder runtime, and
|
|
868
|
+
Farm does not polyfill `Array.prototype.toSorted`.
|
|
869
|
+
|
|
870
|
+
Concise or single-return block-bodied immutable filters on a direct keyed array can carry removal
|
|
871
|
+
positions into the same optional runtime:
|
|
872
|
+
|
|
873
|
+
```tsx
|
|
874
|
+
setItems((current) => current.filter((item) => item.id !== removedId));
|
|
875
|
+
setItems((current) => {
|
|
876
|
+
return current.filter((item) => item.id !== removedId);
|
|
877
|
+
});
|
|
878
|
+
setItems((current) =>
|
|
879
|
+
current.filter((item) => {
|
|
880
|
+
return item.id !== removedId;
|
|
881
|
+
}),
|
|
882
|
+
);
|
|
883
|
+
```
|
|
884
|
+
|
|
885
|
+
For compiler-owned host rows whose render and key do not observe the row index, Farm validates the
|
|
886
|
+
native filter chain, every surviving item identity, and every surviving key before removing only
|
|
887
|
+
the rejected DOM rows. It does not recreate descriptors or reread bindings for unchanged rows,
|
|
888
|
+
and queued filters compose before one compiler flush. Index-aware rows or predicates, updater blocks
|
|
889
|
+
with extra statements, directives, conditional returns, or no value-returning `return`, predicate
|
|
890
|
+
blocks with those unsupported shapes, custom filter methods, sparse or subclassed arrays,
|
|
891
|
+
collection-reading bindings or keys, React-owned row structures, mixed dirty dependencies, and
|
|
892
|
+
failed validation use complete keyed reconciliation. No option or new component is required. The
|
|
893
|
+
compiler report exposes the emitted-site count as `keyedArrayFilterHints`.
|
|
894
|
+
|
|
152
895
|
An otherwise eligible host row may also contain an inline synchronous React event:
|
|
153
896
|
|
|
154
897
|
```tsx
|
|
@@ -237,6 +980,12 @@ components, fragments, refs, SVG, spreads, dangerous HTML, and index keys keep t
|
|
|
237
980
|
row on React's fallback. Additional keyed levels that satisfy the same host-only contract are
|
|
238
981
|
analyzed recursively instead of using a fixed nesting limit.
|
|
239
982
|
|
|
983
|
+
When every inner key stays in the same order, the nested scope reuses its row table and skips
|
|
984
|
+
position-map construction and LIS planning. It still validates all keys and updates every child
|
|
985
|
+
scope and binding. Insertions, removals, and reorders keep the existing structural reconciliation;
|
|
986
|
+
duplicate keys or an invalid child scope keep the existing React fallback. This also applies to
|
|
987
|
+
keyed ranges next to host-only conditions inside a nested mixed range.
|
|
988
|
+
|
|
240
989
|
For example, `boards → columns → cards → tags` becomes a tree of keyed scopes. Each stable parent
|
|
241
990
|
key owns its child key table and LIS pass. Moving a board carries its column, card, and tag scopes;
|
|
242
991
|
reordering cards reconciles only the selected column. Block IDs stay globally unique while runtime
|
|
@@ -374,8 +1123,27 @@ Generated callback refs give directly patched host elements stable private targe
|
|
|
374
1123
|
React-owned component may therefore return `null`, a fragment, or multiple host nodes without
|
|
375
1124
|
shifting an unrelated compiler binding. These refs do not add attributes to SSR output.
|
|
376
1125
|
|
|
1126
|
+
Custom element tags and customized built-ins using `is` remain React-owned rather than receiving
|
|
1127
|
+
compiler attribute writes or host descriptors. React controls property setters, attributes, events,
|
|
1128
|
+
and element creation according to the installed React version, including during hydration.
|
|
1129
|
+
|
|
1130
|
+
State-dependent `contentEditable` bindings and non-literal `contentEditable` values in host
|
|
1131
|
+
descriptors remain React-owned. This preserves the difference between explicit `false` (not editable)
|
|
1132
|
+
and an absent value (inherit from the parent). Literal strings on ordinary direct hosts remain
|
|
1133
|
+
eligible for compilation.
|
|
1134
|
+
|
|
1135
|
+
`title` and `meta` elements inside conditional, keyed, or recursive host descriptors remain
|
|
1136
|
+
React-owned. React decides their document placement and cleanup, including React 19 head placement
|
|
1137
|
+
and the `itemProp` exception. The compiler does not implement a separate metadata manager.
|
|
1138
|
+
|
|
377
1139
|
Conditional blocks have three safe ownership levels. One or more proven host-only direct branches
|
|
378
1140
|
may become compiler-owned ranges among static host siblings, including at the exact component root.
|
|
1141
|
+
Script elements in conditional branches or keyed rows remain React-owned, including nested and
|
|
1142
|
+
non-executable scripts. React retains responsibility for inert script creation on insertion and
|
|
1143
|
+
reinsertion; the compiler does not create these elements through its host descriptors.
|
|
1144
|
+
The production browser control is
|
|
1145
|
+
`NODE_ENV=production node packages/farm-react/scripts/test-script-ownership-browser.mjs` from the
|
|
1146
|
+
workspace root. Set `CHROME_PATH` to use an installed Chrome instead of Playwright's browser.
|
|
379
1147
|
A dedicated container with exactly one conditional child uses the smaller compiler-owned branch
|
|
380
1148
|
boundary. The more general React-owned conditional path accepts supported events, nested host
|
|
381
1149
|
conditionals, keyed lists, and component islands. A compiler-owned host branch may now recursively
|
|
@@ -425,17 +1193,59 @@ compiler: {
|
|
|
425
1193
|
|
|
426
1194
|
The default path is `.farm/react-compiler.json`. The report covers the production browser graph and
|
|
427
1195
|
contains project-relative module paths, compiled component names, fallback details, and fallback
|
|
428
|
-
reasons aggregated by count.
|
|
1196
|
+
reasons aggregated by count. Its summary and per-module `optimizations` also report
|
|
1197
|
+
`keyedIdentityTargets`, the number of scalar key-directed row bindings;
|
|
1198
|
+
`keyedMapLookupTargets`, the number of native-Map keyed lookup bindings;
|
|
1199
|
+
`keyedMembershipTargets`, the number of native-Set membership bindings;
|
|
1200
|
+
`keyedCollectionUpdateHints`, the number of compiler-proven native Set/Map mutation sites; and
|
|
1201
|
+
`keyedMapUpdateHints`, the number of compiler-proven keyed `map()` update calls; and
|
|
1202
|
+
`keyedArrayAppendHints`, the number of compiler-proven direct keyed-array append sites; and
|
|
1203
|
+
`keyedArrayFilterHints`, the number of compiler-proven keyed-array filter sites, including supported
|
|
1204
|
+
structural reorder pipelines; and
|
|
1205
|
+
`keyedArrayPrependHints`, the number of compiler-proven direct keyed-array prepend sites; and
|
|
1206
|
+
`keyedArrayPositionHints`, the number of compiler-proven native exact-position insertion, single or
|
|
1207
|
+
contiguous-range removal, single-row replacement, or exact-window replacement sites, including
|
|
1208
|
+
guarded compiler-safe runtime positions;
|
|
1209
|
+
and
|
|
1210
|
+
`keyedArrayReorderHints`, the number of compiler-proven native keyed-array reverse steps; and
|
|
1211
|
+
`keyedArraySortHints`, the number of compiler-proven native keyed-array sort steps; and
|
|
1212
|
+
`keyedArrayMappedRollingWindowChainHints`, the number of compiler-proven rolling steps retained
|
|
1213
|
+
across multi-window same-key map chains; and
|
|
1214
|
+
`keyedArrayRollingWindowHints`, the number of compiler-proven retained-tail plus incoming-suffix
|
|
1215
|
+
sites; and
|
|
1216
|
+
`keyedArraySliceHints`, the number of compiler-proven keyed-array slice sites with literal or guarded
|
|
1217
|
+
compiler-safe runtime bounds, including supported structural reorder pipelines. A custom
|
|
1218
|
+
project-relative `reportFile` also enables reporting.
|
|
429
1219
|
|
|
430
1220
|
The runtime test compares the same counter interaction on both paths: ordinary React performs a
|
|
431
1221
|
second component render and commit, while the compiled component remains at one render and one
|
|
432
1222
|
commit and updates its two bindings directly. This is a deterministic structural performance
|
|
433
1223
|
assertion; it is not presented as a cross-machine timing benchmark.
|
|
434
1224
|
|
|
1225
|
+
`pnpm --filter @farm.js/react test:runtime-size` checks both gzip and Brotli compiler premiums
|
|
1226
|
+
against `RUNTIME_SIZE_RESULTS.json`, including plain keyed lists and the isolated core runtime.
|
|
1227
|
+
Missing or non-finite budget inputs and fixtures without an explicit budget policy fail the check.
|
|
1228
|
+
When intentionally adding or changing a baseline, generate it with
|
|
1229
|
+
`pnpm --filter @farm.js/react benchmark:runtime-size` and review the byte changes before committing;
|
|
1230
|
+
do not regenerate baselines just to hide a regression. These checks do not change application output.
|
|
1231
|
+
|
|
1232
|
+
Both runtime-size and keyed-target measurements compress each emitted JavaScript file independently,
|
|
1233
|
+
then sum the bytes. Multi-chunk builds also report per-file bytes and the union of entry chunks plus
|
|
1234
|
+
their static imports (`initial`), reachable dynamic imports and their dependencies (`deferred`), and
|
|
1235
|
+
any remaining emitted chunks (`unreferenced`). Shared chunks count once; deferred totals include all
|
|
1236
|
+
reachable lazy chunks, not a claim that every navigation downloads them. CSS, other assets, external
|
|
1237
|
+
dependencies and HTTP overhead are outside these JavaScript-only measurements. Existing single-chunk
|
|
1238
|
+
measurements are unchanged; concatenated code is used only for structural-marker checks.
|
|
1239
|
+
|
|
1240
|
+
Plain keyed-row features also omit conditional-boundary subscriptions, render adapters, and
|
|
1241
|
+
snapshot-update loops. Conditional features retain their per-block ownership and React fallback.
|
|
1242
|
+
The size suite checks a combined create/append/update/select/swap/remove/clear table as well as
|
|
1243
|
+
isolated operations, so an isolated fixture cannot hide retained conditional machinery.
|
|
1244
|
+
|
|
435
1245
|
Application and prototype calls, dynamic style objects, handlers outside JSX events, nested,
|
|
436
|
-
computed, and rest props patterns, async handlers, unkeyed or index-keyed lists,
|
|
437
|
-
unsupported conditional roots, effects, and more advanced hook support intentionally stay
|
|
438
|
-
in this release. Compiler-owned keyed rows support either one dedicated host-only map/`List` or
|
|
1246
|
+
computed, and rest props patterns, async handlers, unkeyed or index-keyed lists, unsupported map
|
|
1247
|
+
chains, unsupported conditional roots, effects, and more advanced hook support intentionally stay
|
|
1248
|
+
on React in this release. Compiler-owned keyed rows support either one dedicated host-only map/`List` or
|
|
439
1249
|
one or more non-interactive ranges in a nested or component-root host container. A dedicated
|
|
440
1250
|
non-interactive row may also contain multiple recursive logical or ternary host branches beside
|
|
441
1251
|
stateful static host siblings, plus recursively nested non-interactive keyed ranges scoped by every
|