@farm.js/react 0.1.0-beta.5 → 0.1.0-beta.7

package/README.md

@@ -162,6 +162,216 @@ Later list updates patch surviving rows by key, create or remove only the change
 longest increasing subsequence (LIS) to minimize DOM moves during a reorder. The outer user
 component and the list callback do not rerun for those compiler-cell updates.
 
+When a separate state cell or primitive prop is compared with the exact row-key expression using
+`===` or `!==`, the compiler emits a key-directed binding proof. A selection change such as
+`item.id === selectedId` then looks up only the previously selected and newly selected row
+instances. Class, attribute, style, and leaf-text bindings on those rows update without evaluating
+the other keyed instances. The proof requires one reactive target used only in strict comparisons;
+mixed structural dependencies, ambiguous expressions, non-primitive runtime targets, React-owned
+rows, and unsupported shapes keep the complete scan or React fallback. No option is required, and
+the compiler report exposes the emitted binding count as `keyedIdentityTargets`.
+
+For multi-selection, an exact local-state expression such as `markedIds.has(item.id)` receives a
+separate Set-membership proof. The runtime compares the previous and next native `Set` snapshots and
+patches only row keys in their symmetric difference. It accepts ordinary native sets containing
+primitive keys. Different fields, extra reactive dependencies, Set subclasses or proxies, object
+members, customized `has` behavior, React-owned rows, nested blocks, and structural dependencies
+stay on the existing complete or React-owned paths. The compiler report exposes this count as
+`keyedMembershipTargets`.
+
+For per-row data, an exact local-state expression such as `statusById.get(item.id)` receives a
+separate Map-lookup proof. The runtime compares the previous and next native `Map` snapshots and
+patches only row keys whose mapped primitive value changed. It accepts ordinary native maps with
+primitive keys and primitive or nullish values. Different fields, extra dependencies, Map
+subclasses or proxies, object values, customized `get` behavior, React-owned rows, nested blocks,
+and structural dependencies keep the existing complete or React-owned paths. The compiler report
+exposes this count as `keyedMapLookupTargets`.
+
+When a targeted Set or Map is compiler-owned, Farm can also carry the exact mutated keys from a
+proven immutable functional update:
+
+```tsx
+setMarkedIds((current) => {
+  const next = new Set(current);
+  if (next.has(id)) next.delete(id);
+  else next.add(id);
+  return next;
+});
+
+setStatusById((current) => new Map(current).set(id, "ready"));
+```
+
+The application still creates its normal immutable collection. The generated update records only
+the native `add`, `delete`, or `set` calls that execute, and the runtime validates those keys
+against the previous committed collection. It can then update the relevant keyed rows without
+iterating every old and new Set member or Map entry first. Queued functional updates compose, and
+the runtime periodically compacts its persistent snapshot so a long update chain stays bounded.
+
+This proof is deliberately conservative. The state must start from a compiler-owned native
+`Set`/`Map`; every setter use must be a fresh same-kind replacement or a recognized immutable
+updater; and the collection, updater parameter, and cloned draft must not escape or be mutated
+through unknown code. Shadowed constructors, custom collections, object keys, object Map values,
+direct state mutation, aliased drafts, or a failed runtime check use the existing snapshot or
+React-owned path before compiled bindings run. No option or syntax is added. The compiler report
+counts emitted native mutation sites as `keyedCollectionUpdateHints`.
+
+For a direct keyed `useState` collection, the compiler also recognizes conservative same-order
+updates such as:
+
+```tsx
+setItems((current) =>
+  current.map((item) => (item.id === targetId ? { ...item, selected: !item.selected } : item)),
+);
+```
+
+The generated native `map()` records which indexes returned new item identities. Farm then
+validates that length, keys, and positions are unchanged and patches only those row instances. The
+user's `map()` remains O(n); this removes the keyed runtime's second full key-and-binding scan.
+Queued hints compose. Key changes, structural edits, relevant mixed dependencies, and failed runtime
+checks use the existing complete reconciliation and LIS path. Non-functional setters, derived
+collections, block-bodied or mutating mappers, and other unproven forms are simply not hinted. No
+new option is required. A compiler report exposes the emitted-site count as
+`keyedMapUpdateHints`. The separate hint runtime capability is imported only when that count is
+nonzero, so direct-only and ordinary keyed builds do not retain it.
+
+The same optional runtime recognizes conservative immutable appends on a direct keyed array:
+
+```tsx
+setItems((current) => [...current, nextItem]);
+setItems((current) => [...current, ...nextItems]);
+```
+
+Because every existing item keeps its key and index, Farm validates the committed source and the
+queued append chain, reads keys and descriptors only for the appended suffix, and mounts that
+suffix in one fragment. Existing row DOM is left untouched. The concise functional updater and
+native arrays are required; middle insertion, removal, direct replacement, duplicate
+keys, rows that read the collection itself, and failed runtime checks use complete keyed
+reconciliation. A key that reads the collection prevents hint emission entirely. The compiler
+report exposes the emitted-site count as
+`keyedArrayAppendHints`.
+
+The mirror-image prepend form is supported when the keyed row and key do not read the row index:
+
+```tsx
+setItems((current) => [nextItem, ...current]);
+setItems((current) => [...nextItems, ...current]);
+```
+
+Farm validates the committed source and queued prepend chain, creates only the new prefix, inserts
+it before the first existing row, and shifts the stored indexes used by delegated row events.
+Existing row DOM and bindings stay in place. Index-aware rows, collection-reading bindings or
+keys, React-owned row structures, middle insertion, direct replacement, duplicate keys, custom or
+sparse arrays, and failed validation use complete keyed reconciliation. The compiler report
+exposes the emitted-site count as `keyedArrayPrependHints`.
+
+Literal native slices can carry their exact retained interval into the same removal runtime:
+
+```tsx
+setItems((current) => current.slice(1_000));
+setItems((current) => current.slice(0, -1_000));
+setItems((current) => current.slice(2, 8));
+```
+
+For compiler-owned host rows whose render and key do not read the row index, Farm validates the
+committed source and queued slice chain, preserves every surviving DOM row, and removes only rows
+outside the retained interval. A slice-only chain does not reread surviving keys, descriptors, or
+bindings. One or two build-time safe-integer bounds are required. Runtime bounds, block-bodied or
+chained updates, custom slice methods, sparse or subclassed arrays, index-aware or
+collection-reading rows, React-owned structures, and failed validation keep complete keyed
+reconciliation. No option or component is added. The compiler report exposes the emitted-site
+count as `keyedArraySliceHints`.
+
+A fixed-size feed can combine that retained tail with a new keyed suffix:
+
+```tsx
+setItems((current) => [...current.slice(1), nextItem]);
+setItems((current) => [...current.slice(1_000), ...nextItems]);
+```
+
+Farm executes the ordinary native slice and array construction, then validates the committed
+source, retained item identities, and incoming keys. It removes only the expired prefix, leaves
+the retained DOM rows in place, and creates only the incoming suffix. This first form supports one
+build-time safe-integer slice bound and compiler-owned, index-independent host rows. Reused keys,
+block-bodied updaters, custom slice behavior, collection-reading or index-aware rows, nested or
+React-owned rows, queued uncommitted windows, and failed checks use complete keyed reconciliation.
+The optional all-hint runtime is selected only for modules that emit this optimization. Reports
+expose the site count as `keyedArrayRollingWindowHints`.
+
+Native known-position updates can avoid a complete keyed scan too:
+
+```tsx
+setItems((current) => current.toSpliced(selectedIndex, 0, nextItem));
+setItems((current) => current.toSpliced(selectedIndex, 1));
+setItems((current) => current.with(selectedIndex, replacement));
+```
+
+The compiler recognizes only a concise functional setter and either a safe-integer literal or a
+compiler-safe runtime position expression, such as an identifier, property read, arithmetic,
+conditional, or safe `Math` call. The update must insert one item with zero removals, remove one
+item, or directly replace one item. Farm preserves method lookup, evaluates the position and
+remaining arguments once in their original order, executes the ordinary native call, and records
+metadata only after validating the committed native source, result, and actual safe-integer
+position. The runtime creates one inserted row, removes one known row, or patches/replaces one row
+at that position without rereading every existing key, descriptor, and binding. Surviving rows keep
+their DOM identity. Index-aware or collection-reading rows, custom methods, position expressions
+with user calls or mutations, runtime positions that are not safe integers, other `toSpliced()`
+forms, block-bodied updaters, unsafe incoming expressions, queued uncommitted updates, reused keys,
+nested or React-owned rows, and failed checks use complete keyed reconciliation. Reports expose the
+site count as `keyedArrayPositionHints`; the capability is tree-shaken from modules that do not emit
+it.
+
+A direct native reverse can carry its complete permutation to a separate optional runtime:
+
+```tsx
+setItems((current) => current.toReversed());
+```
+
+Farm preserves the method lookup, call result, and errors, then records metadata only for the native
+method on a committed ordinary array. The runtime verifies equal lengths and every reversed item
+identity before moving the existing keyed elements with the minimum `n - 1` connected DOM moves.
+It does not reread row keys, descriptors, or bindings and does not run the generic LIS calculation.
+Index-aware or collection-reading rows, arguments, computed or chained calls, block-bodied
+updaters, custom methods, sparse or subclassed behavior, queued uncommitted reversals, nested or
+React-owned rows, and failed checks keep complete keyed reconciliation. Reports expose the site
+count as `keyedArrayReorderHints`, and modules without one omit the reorder runtime. Farm does not
+polyfill `Array.prototype.toReversed`.
+
+A direct native immutable sort can use the same optional reorder runtime:
+
+```tsx
+setItems((current) => current.toSorted((left, right) => left.rank - right.rank));
+setLabels((current) => current.toSorted());
+```
+
+Farm recognizes a concise functional setter with no comparator or an inline synchronous comparator
+from the compiler-safe expression subset. It preserves the original method lookup, comparator,
+stable native result, and errors. After the native sort runs, the runtime validates a committed
+ordinary dense array, equal lengths, and a unique one-to-one item-identity permutation. It then
+uses LIS to move only `n - LIS` keyed DOM nodes without rereading row keys, descriptors, or
+bindings. The native sorting work itself is unchanged.
+
+Index-aware or collection-reading rows, referenced comparators, block-bodied updaters, computed or
+chained calls, custom methods, sparse or subclassed arrays, duplicate item identities, queued
+uncommitted sorts, nested or React-owned rows, and failed checks keep complete keyed
+reconciliation. Reports expose the site count as `keyedArraySortHints`; sort shares the optional
+reorder runtime, and Farm does not polyfill `Array.prototype.toSorted`.
+
+Concise immutable filters on a direct keyed array can carry removal positions into the same
+optional runtime:
+
+```tsx
+setItems((current) => current.filter((item) => item.id !== removedId));
+```
+
+For compiler-owned host rows whose render and key do not observe the row index, Farm validates the
+native filter chain, every surviving item identity, and every surviving key before removing only
+the rejected DOM rows. It does not recreate descriptors or reread bindings for unchanged rows,
+and queued filters compose before one compiler flush. Index-aware rows or predicates,
+block-bodied updates, custom filter methods, sparse or subclassed arrays, collection-reading
+bindings or keys, React-owned row structures, mixed dirty dependencies, and failed validation use
+complete keyed reconciliation. No option or new component is required. The compiler report exposes
+the emitted-site count as `keyedArrayFilterHints`.
+
 An otherwise eligible host row may also contain an inline synchronous React event:
 
 ```tsx
@@ -438,7 +648,23 @@ compiler: {
 
 The default path is `.farm/react-compiler.json`. The report covers the production browser graph and
 contains project-relative module paths, compiled component names, fallback details, and fallback
-reasons aggregated by count. A custom project-relative `reportFile` also enables reporting.
+reasons aggregated by count. Its summary and per-module `optimizations` also report
+`keyedIdentityTargets`, the number of scalar key-directed row bindings;
+`keyedMapLookupTargets`, the number of native-Map keyed lookup bindings;
+`keyedMembershipTargets`, the number of native-Set membership bindings;
+`keyedCollectionUpdateHints`, the number of compiler-proven native Set/Map mutation sites; and
+`keyedMapUpdateHints`, the number of compiler-proven direct keyed `map()` update sites; and
+`keyedArrayAppendHints`, the number of compiler-proven direct keyed-array append sites; and
+`keyedArrayFilterHints`, the number of compiler-proven direct keyed-array filter sites; and
+`keyedArrayPrependHints`, the number of compiler-proven direct keyed-array prepend sites; and
+`keyedArrayPositionHints`, the number of compiler-proven native exact-position insertion, removal,
+or replacement sites, including guarded compiler-safe runtime positions; and
+`keyedArrayReorderHints`, the number of compiler-proven direct native keyed-array reverse sites; and
+`keyedArraySortHints`, the number of compiler-proven direct native keyed-array sort sites; and
+`keyedArrayRollingWindowHints`, the number of compiler-proven retained-tail plus incoming-suffix
+sites; and
+`keyedArraySliceHints`, the number of compiler-proven direct keyed-array slice sites. A custom
+project-relative `reportFile` also enables reporting.
 
 The runtime test compares the same counter interaction on both paths: ordinary React performs a
 second component render and commit, while the compiled component remains at one render and one