@volynets/reflex-store 0.0.0-stage → 0.0.2

package/src/store/README.md

@@ -0,0 +1,59 @@
+# Compiled static stores
+
+The root createStore API requires the compiler. Import the plugin from
+@volynets/reflex-store/vite or use compileStore from /store.
+
+```ts
+import {
+  createStore,
+  leaf,
+  opaque,
+  snapshot,
+  hydrate,
+} from "@volynets/reflex-store";
+
+export function createCounter() {
+  const state = createStore(
+    {
+      count: 0,
+      history: leaf<readonly number[]>([]),
+      engine: opaque(new Engine()),
+      get doubled() {
+        return this.count * 2;
+      },
+      increment() {
+        this.count++;
+        this.history = [...this.history, this.count];
+      },
+    },
+    { name: "Counter" },
+  );
+  return state;
+}
+```
+
+Factories allocate independent cells, computed getters and action methods.
+Static data accesses lower to direct cell calls. Root methods are bound actions;
+getters are owned lazy computeds. Snapshot extraction excludes methods/getters.
+Hydration validates the complete data schema before batched restoration.
+
+The compiler accepts data properties with unique static keys. Literal objects
+form branches; leaf/opaque imports (including aliases) define single replaceable
+locations. Arrays use replacement semantics.
+
+Unsupported syntax is diagnosed: spreads, shorthand, **proto**, reserved lifecycle
+names, setter properties, nested methods/getters, async/generator methods, dynamic
+paths, branch aliases, delete, optional chaining, structural replacement and
+arbitrary root reflection. Getters must not write store state.
+
+Use eraseFacade to remove objects proven unnecessary for direct data-cell uses.
+Returned stores, computed getters, action methods and lifecycle/data boundaries
+retain their facade.
+
+The default lowering imports createStoreScope from /runtime and cells from
+/runtime/internal. The scope uses the shared Framework LifecycleScope for resource
+ownership and rollback, and adds the Store action boundary. It has no model
+shape validation or capability brands. Custom scope/signal lowering remains
+available for data-only stores through loweringTarget; the legacy model option
+is a compatibility alias for curried factory targets.
+See [TRANSFORM_SPEC.md](./TRANSFORM_SPEC.md).

package/src/store/TRANSFORM_SPEC.md

@@ -0,0 +1,85 @@
+# Compiled store transform contract
+
+## Recognition and declarations
+
+Recognize createStore imports from @volynets/reflex-store, /advanced, /store and
+/compiled-store, including aliases. Match binding identity, not text alone.
+The compiler API may recognize unresolved bare createStore calls; the Vite plugin
+requires a matching import unless compileBareCreateStore is enabled.
+
+Lexical module/function/block declarations are supported. Each execution of a
+local declaration allocates independent store resources. Inline return
+createStore(...) and loop-header declarations remain diagnosed.
+
+## Shape and boundaries
+
+Accept unique static data keys, root method declarations and root getter
+declarations. Literal data objects become branches. Imported leaf(value) and
+opaque(value) calls define one replaceable location. Preserve opaque marking.
+Optional options require a static name string.
+
+Data initializers execute once in source order for each declaration execution.
+Data leaf reads are direct address calls. Producers materialize on tracked reads.
+
+## Methods and getters
+
+Root methods become bound ctx.action callbacks. Rewrite their store this
+references to the declaration binding, preserving lexical-arrow this and leaving
+nested ordinary function/class receivers intact. Lower static leaf reads/writes
+inside the callbacks as usual. Multi-write methods close one outer host/runtime
+batch.
+
+Root getters become owned createDisposableComputed accessors. Their this
+references lower to store locations. Clean reads cache; writes invalidate and
+pull reads compute current data. Getters cannot write store state or suspend.
+Async/generator methods, setters and nested methods/getters are unsupported.
+
+## Writes and JavaScript order
+
+Support =, +=, -=, prefix/postfix ++ and -- on declared data leaves.
+Evaluate the previous value before a compound RHS, evaluate the RHS once and
+then commit the result. Update operators preserve JavaScript ToNumeric,
+including strings, undefined, NaN, signed zero and BigInt. Exceptions before
+commit preserve the previous value; action exceptions close batches.
+
+## Facade, ownership and extraction
+
+The generated facade contains data accessors, getter accessors, bound actions,
+dispose and Symbol.dispose. A Store scope owns cells and computed getter resources
+through Framework's LifecycleScope. Cells are allocated and adopted inside the
+scope setup callback, preserving initializer order. Setup failures roll back all
+resources already owned and rethrow the original cause. Actions reject terminal
+use in production and development; raw cells expose Symbol.dispose.
+Static hidden control callbacks extract only data fields and restore values to
+known cells. Returning a facade (also within a factory return object) is supported.
+
+snapshot/hydrate imports are recognized intrinsic data boundaries. own(ctx, state)
+and getStoreName(state) are recognized ownership/diagnostic boundaries. Runtime
+snapshot invokes the generated extraction untracked, preserving structural graph
+semantics. Hydration validates the exact compiled branch/leaf schema before one
+batched write. Empty branches are represented explicitly.
+
+eraseFacade is opt-in. Omit a facade only if every use can lower to declared data
+cells and no method/getter/escape/lifecycle/data boundary needs the object.
+
+## Runtime and tooling
+
+Default imports use createStoreScope from @volynets/reflex-store/runtime and
+createStoreCell from /runtime/internal. The compiler does not call createModel
+or defineModel. The target delegates lifecycle policy to the shared Framework
+package, and keeps host/runtime imports external. The Vite plugin preserves
+application package resolution.
+
+Custom data-only lowering targets configure scope/signal names and generated
+identifiers. Scope targets return the constructed value directly; curried: true
+supports factories returning a zero-argument constructor. The deprecated model
+option remains an alias with curried: true for existing custom targets.
+Getter/method lowering requires the default Store scope target.
+The compiler includes portable SWC WASM and validates its normalized function AST
+before printing. Names are store metadata and never modify kernel hot paths.
+
+## Diagnostics
+
+Diagnose unsupported shapes and mutations before erasure. Collect mode returns
+the original code when diagnostics exist. No partial transform is published for
+an unsupported source module.