@volynets/reflex-store 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Andrii Volynets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+# Reflex Store
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Structured state, derived views and keyed collections with a compiler for static
+store shapes. The library distribution keeps the Reflex host and reactive kernel
+as external imports. `@volynets/reflex`, `@volynets/reflex-runtime` and
+`@volynets/reflex-framework` are peer dependencies. Framework supplies the
+shared lifecycle primitives, while Store, DOM and Async share the application's
+kernel module identity.
+The distribution includes the portable SWC WebAssembly compiler and Vite plugin.
+
+```sh
+pnpm add @volynets/reflex-store @volynets/reflex @volynets/reflex-runtime @volynets/reflex-framework
+```
+
+Requires Node.js 20.19 or newer for the compiler and Vite plugin. Published
+entrypoints use ES modules. The compiler and its SWC WASM asset are included;
+consumers do not need to install SWC separately.
+
+## Application API
+
+Start with `createStore`, `derive`, `selector`, `reactiveMap`, `action` and
+`snapshot`. Use `leaf`/`opaque` for reference boundaries and `hydrate` for
+restoring compiled data.
+
+```ts
+import { createRuntime, effect } from "@volynets/reflex-store/runtime";
+import {
+  createStore,
+  leaf,
+  derive,
+  selector,
+  reactiveMap,
+  action,
+  snapshot,
+  hydrate,
+} from "@volynets/reflex-store";
+
+createRuntime({ effectStrategy: "flush" });
+
+export function createBoard() {
+  const board = createStore(
+    {
+      filter: { status: "all", query: "" },
+      selection: { taskId: "T-101" },
+      pinned: leaf<readonly string[]>([]),
+
+      get filterLabel() {
+        const query = this.filter.query.trim().toLowerCase();
+        return query ? this.filter.status + ":" + query : this.filter.status;
+      },
+
+      setFilter(status: string, query = "") {
+        this.filter.status = status;
+        this.filter.query = query;
+      },
+    },
+    { name: "Board" },
+  );
+
+  return board;
+}
+
+const board = createBoard();
+const tasks = reactiveMap<string, { title: string; done: boolean }>();
+const isSelected = selector(() => board.selection.taskId);
+const summary = derive(
+  () => ({
+    total: tasks.size,
+    completed: [...tasks.values()].filter((task) => task.done).length,
+  }),
+  { name: "Summary" },
+);
+
+const addTasks = action(() => {
+  tasks.set("T-101", { title: "Design checkout", done: false });
+  tasks.set("T-102", { title: "Add audit log", done: true });
+});
+
+addTasks();
+console.log(summary.completed); // 1; pulls current data immediately
+const saved = snapshot(board); // frozen data; excludes methods and getters
+hydrate(board, saved); // validates the entire shape, then writes in one action
+```
+
+Every factory call creates independent state. Root methods become bound,
+synchronous actions; getters become owned lazy computeds. Static data reads and
+writes lower to direct cell calls. Getters must be pure and synchronous.
+
+`derive` accepts a pure callback returning a plain object. Its property views
+are read-only. Dynamic entity IDs belong in `reactiveMap`; map values are
+reference boundaries, so replace an entry to publish an entity change.
+
+`action` preserves callback parameters, return value and receiver. Related
+writes run untracked inside one scheduler/runtime batch. Direct reads see writes
+so far. Exceptions keep completed writes and close the batch; there is no rollback.
+
+## Compiler and Vite
+
+`createStore` requires the transform. The runtime stub throws if it executes.
+
+```ts
+import { defineConfig } from "vite";
+import reflexStore from "@volynets/reflex-store/vite";
+
+export default defineConfig({
+  plugins: [reflexStore({ eraseFacade: true })],
+});
+```
+
+The plugin transforms stores while preserving application package resolution.
+It does not redirect host or kernel imports. `@volynets/reflex-store/runtime`,
+`/runtime/core` and `/runtime/internal` re-export the shared peer APIs; they do not
+contain a private host or kernel.
+
+The standalone compiler is exported from `@volynets/reflex-store/store`.
+It includes its portable WASM asset; installing a platform-specific native SWC
+package is unnecessary. `eraseFacade` removes the object only when every use
+lowers to data cells. Factories, methods, getters, disposal and data extraction
+retain the required facade.
+
+See [compiler rules](./src/store/TRANSFORM_SPEC.md).
+
+## Ownership
+
+Compiled stores use `createStoreScope()` from `/runtime`. This thin compiler
+target delegates ownership, cancellation and rollback to Framework's
+`LifecycleScope`. It adds synchronous, untracked actions inside the host batch
+and exposes disposal through `dispose()` and `Symbol.dispose`. Cells are created
+and owned during setup; a failed initializer disposes earlier cells before
+rethrowing its original error. Computed getter resources share the same lifetime.
+
+Store compilation uses neither `createModel` nor `defineModel`. Models remain an
+optional way for application code to own a store alongside other resources.
+
+Use the shared host's model ownership to dispose resources together:
+
+```ts
+import { createModel, own, signal } from "@volynets/reflex-store/runtime";
+import { derive, reactiveMap, selector } from "@volynets/reflex-store";
+
+const createPanel = createModel((ctx) => {
+  const tasks = own(ctx, reactiveMap<string, { done: boolean }>());
+  const selectedId = signal("");
+  return {
+    tasks,
+    selected: own(ctx, selector(selectedId)),
+    summary: own(
+      ctx,
+      derive(() => ({ total: tasks.size })),
+    ),
+  };
+});
+```
+
+Maps, sets, selectors, keyed projections, structured views and compiled stores
+implement `Symbol.dispose`. They also support explicit terminal disposal. Compiled reads, methods, writes and
+restoration reject use after disposal.
+`collect` is available in the advanced API for long-lived structures with many
+previously observed keys.
+
+## Reference and data boundaries
+
+An object literal is a structural branch. `leaf(value)` is one replaceable
+location. `opaque(resource)` retains an external reference.
+
+```ts
+const state = createStore({
+  items: leaf<readonly Task[]>([]),
+  engine: opaque(new Engine()),
+});
+state.items = [...state.items, task];
+```
+
+Compiled arrays use replacement semantics. Array mutation does not publish
+fine-grained changes.
+
+Snapshots copy and freeze plain structural data, preserving cycles and shared
+references. Map/Set keys preserve identity. Opaque and foreign objects remain
+external references. Applications define encoding/exclusion for JSON, SSR
+persistence and external resources.
+
+Compiled hydration requires the full exact data shape, including empty branches.
+It rejects missing/extra fields and accessor properties before the first write,
+clones structural leaf data, and restores all fields in one action. Schema
+validation is structural; validate untrusted input value types in the application.
+
+## Advanced API
+
+`@volynets/reflex-store/advanced` preserves projection controls, depth markers,
+`raw`, `transaction`, lifecycle helpers and `createStoreCell`. It also exports:
+
+```ts
+import { reactiveSet, getStoreName } from "@volynets/reflex-store/advanced";
+
+const selectedIds = reactiveSet<string>([], { name: "Selected IDs" });
+selectedIds.add("T-101");
+console.log(getStoreName(selectedIds));
+```
+
+`ReactiveSet` follows native Set membership and iteration semantics.
+Resource names are optional store metadata and do not add runtime kernel hooks.
+The existing draft and keyed projection APIs remain available here.
+
+The [task board](./examples/task-board/README.md) demonstrates the basic API.
+The normative contract is in [SPECIFICATION.md](./SPECIFICATION.md).
+
+## Checks
+
+```sh
+pnpm --filter @volynets/reflex-store test
+pnpm --filter @volynets/reflex-store test:dev
+pnpm --filter @volynets/reflex-store typecheck
+pnpm --filter @volynets/reflex-store lint
+pnpm --filter @volynets/reflex-store test:packed-runtime
+```
+
+The packed test installs the Store and its Reflex peer tarballs in an empty
+offline project. It checks all published imports, WASM loading, one shared graph across entrypoints,
+the Vite plugin, factory isolation, batching, snapshots/hydration and consumer
+declarations with `skipLibCheck=false`.
+
+## Release preparation
+
+Run from the repository root with workspace dependencies installed:
+
+```sh
+pnpm --filter @volynets/reflex-store check:release
+pnpm --dir packages/reflex-store pack --pack-destination ../../artifacts/npm
+```
+
+`check:release` builds Store and its workspace dependencies, runs lint, production
+and development tests, checks types and artifacts, and verifies an isolated
+installation of the packed packages. `prepublishOnly` runs the same checks.
+`prepack` rebuilds Store and checks its output before creating a tarball.
+
+The package contains the MIT license and the Apache-2.0 license for the bundled
+SWC compiler. Publish compatible versions of the required Reflex peers before
+releasing Store. The repository release workflow uses `pnpm release:qualify`
+and publishes the verified tarballs through `pnpm release:publish` with the
+qualification and quality-summary paths required by that command.

package/SPECIFICATION.md

@@ -0,0 +1,137 @@
+# Reflex Store Specification
+
+**Revision:** 2026-10-07  
+**Scope:** compiled static state and runtime structured views/collections.
+
+## Package boundary
+
+The published package MUST declare no dependencies, peer dependencies or optional
+dependencies. Runtime, host, scheduler, compiler and WASM assets MUST be included.
+All runtime entrypoints MUST share the same kernel and host bindings.
+
+The basic root exports createStore, derive, selector, reactiveMap, action,
+snapshot, leaf, opaque and hydrate. Advanced projections, Set, lifecycle controls,
+names and compiler primitives belong to /advanced. Headless host APIs belong to
+/runtime; compiler and Vite entrypoints belong to /store and /vite.
+
+Kernel read/write/link/unlink code MUST remain independent from store ownership,
+names and compiler metadata. This package makes no kernel source changes.
+
+## Static stores
+
+createStore is compile-only and MUST throw if its source stub executes.
+Declarations may appear at module scope or inside lexical function/block bodies.
+Binding identity MUST distinguish aliases, shadowing and separate factory calls.
+Loop-header declarations and arbitrary inline factories remain unsupported.
+
+A literal object property defines a structural branch. Other accepted initial
+values define leaves. leaf(value) forces one replaceable leaf. opaque(value)
+retains an external resource/reference boundary. Marker aliases MUST resolve by
+import binding identity.
+
+Root methods become synchronous bound actions. Their this references to the
+store are lowered to the same static locations; nested ordinary functions
+retain their own this. Async/generator store methods are rejected.
+Root getters become lazy disposable computeds. They MUST be pure, synchronous,
+memoize clean reads and validate dependencies on pull. Store writes in getters
+are rejected. Setters and nested methods/getters remain unsupported.
+
+Static leaf reads/writes lower to callable cells and action writers. Data cells
+create their producer only on the first tracked read. Initializers MUST run once
+per declaration execution. Compound assignment and update lowering MUST preserve
+JavaScript evaluation order, single RHS evaluation, ToNumeric and exceptions.
+
+Dynamic root paths, branch aliases, structural replacement, delete, optional
+chaining and general root reflection are diagnosed. Returning a facade from a
+factory and snapshot/hydrate data intrinsics are supported escape boundaries.
+
+Optional static name options label the store and its cells. Optional eraseFacade
+may remove a facade only when every use lowers directly to declared data leaves.
+Escapes, methods, getters and lifecycle references MUST keep it.
+
+## Collections
+
+ReactiveMap uses native SameValueZero keys and Object.is value equality by
+default. get, has, size, key iteration and value iteration observe different
+semantic locations. Replacing an existing value MUST not invalidate key-only
+consumers. Untracked lookups MUST not allocate key observation producers.
+
+ReactiveSet follows native Set membership, insertion order, deletion, clear,
+iteration and forEach semantics. It uses keyed membership observations.
+No-op add/delete operations MUST not notify consumers.
+
+Collection values are reference boundaries. In-place mutation of an entity or
+array is not a reactive publication. Optional initializers materialize backing
+data lazily. Reads after terminal disposal MUST fail.
+
+## Derivations and selectors
+
+derive accepts a pure-return callback producing a plain object. Structured
+projections use lazy Demand and semantic path observations; compatible plain
+objects and arrays are traversed by default. Foreign/ref/opaque values retain
+reference semantics. Returned structured views are read-only.
+
+Selectors route old/new semantic keys with configurable equality and preserve
+Object.is behavior for signed zero/NaN. Keyed projections represent the active
+source key; they are not arbitrary entity lookup. ReactiveMap provides that lookup.
+
+Advanced draft projections, clone/equality/depth controls and keyed projections
+remain available. Clean reads MUST memoize and dirty reads MUST pull fresh data
+without waiting for an effect flush. Equal projected results MUST cut off
+downstream user computation.
+
+## Actions and delivery
+
+action runs the synchronous callback untracked within one scheduler and reactive
+batch. Nested actions compose. The callback receiver, arguments and return value
+MUST be preserved. Reads inside an action see writes so far. Completed writes
+survive exceptions; all batch boundaries MUST close.
+
+The active host controls flush/eager/SAB delivery. Runtime and scheduler batching
+MUST compose so one logical multi-write action never publishes an intermediate
+state to eager effects.
+
+## Extraction, hydration and SSR
+
+snapshot is untracked. Compiled stores expose statically generated data extraction
+callbacks, including nested/empty branches and excluding methods/getters.
+Plain snapshots MUST be independent and frozen, preserving cycles, shared
+references, symbols, enumerable descriptors and sparse array structure.
+Map and Set representations preserve key identity and disable public mutators.
+
+Opaque/foreign values remain external references. No arbitrary JSON or
+structured-clone guarantee is made. Applications define serialization policies
+for cycles, BigInt, symbols, functions, external resources and Map/Set keys.
+
+hydrate requires a complete compiled data schema. It MUST validate all structural
+fields before writing: exact branch keys, required fields and own data-property
+descriptors. Structural values MUST be cloned with shared references preserved.
+All writes MUST occur in one logical batch. Field value types are checked by
+TypeScript/application validation, not inferred from initial primitive values.
+
+Each SSR request creates its own store factory instance. Snapshot/restore operate
+on those instances and never require module-global application state.
+
+## Ownership and diagnostic names
+
+Maps, Sets, selectors, keyed projections, structured projection views and compiled
+stores MUST implement Symbol.dispose and work with own(ctx, resource).
+Disposal is terminal and idempotent. Compiled data reads/writes, getters, methods,
+extraction and hydration MUST reject use after disposal. Collecting unused observations MUST preserve
+nodes that still have outgoing consumer links. Owners stop consumers before
+collection and collect derived layers from downstream to upstream.
+
+Names are optional resource metadata exposed through getStoreName. Looking up a
+name MUST not compute a lazy projection or create reactive observations. Names
+MUST not add metadata or hooks to runtime kernel hot paths.
+
+## Conformance evidence
+
+Tests cover native collection differential behavior, compiler/JavaScript
+differential behavior, all scheduler strategies, getter caching, coherent methods
+and hydration, factory isolation, ownership and erasure safety.
+
+The packed-install check MUST install only the local tarball in a clean offline
+project, reject external package imports in JS/declarations, load WASM, validate
+shared graph behavior and Vite integration, and typecheck a consumer without
+skipLibCheck. Build-only tooling belongs in devDependencies.

package/dist/advanced.d.ts

@@ -0,0 +1,13 @@
+/// <reference lib="esnext.disposable" />
+import type { Destructor, Accessor } from "./runtime/types.js";
+export { C as CompiledStore, S as StoreData, a as StoreOptions, b as StoreShape, c as createStore, l as leaf } from './types/createStore-BJ66-pfq.js';
+export { action, derive, hydrate } from './index.js';
+export { A as Accessor, D as Destructor, a as DisposableAccessor, S as StoreDisposable, c as createKeyedProjection, b as createSelector, b as selector } from './types/keyed-CdSYzIOc.js';
+export { D as Depth, K as KeyedOptions, P as ProjectionOptions, R as ReactiveMap, a as ReactiveMapOptions, b as ReactiveSet, S as Snapshot, c as StoreProjectionOptions, d as collectStore, e as createReactiveMap, f as deep, g as disposeStore, o as opaque, r as raw, e as reactiveMap, h as reactiveSet, i as ref, s as shallow, j as snapshot, t as transaction } from './types/shared-CdTKzvLe.js';
+export { createProjection, createStoreProjection } from './selectors/index.js';
+export { S as StoreCell, c as createStoreCell } from './types/internal-BIzJSPwN.js';
+import '@volynets/reflex-runtime/internal';
+
+declare function getStoreName(resource: object): string | undefined;
+
+export { getStoreName };

package/dist/advanced.js

@@ -0,0 +1,9 @@
+export { createProjection } from './selectors/index.js';
+export { R as ReactiveMap, b as ReactiveSet, d as createKeyedProjection, c as createReactiveMap, a as createSelector, e as createStoreProjection, c as reactiveMap, r as reactiveSet, a as selector, t as transaction } from './chunks/keyed-C-QvvUv4.js';
+export { g as getStoreName } from './chunks/names-BF36AyM3.js';
+export { c as collectStore, d as deep, a as disposeStore, o as opaque, r as raw, b as ref, e as shallow, s as snapshot } from './chunks/shared-BHHficW8.js';
+export { createStoreCell } from './runtime/internal.js';
+export { a as action, d as derive, h as hydrate, l as leaf } from './chunks/hydrate-Bdtl9XyA.js';
+export { c as createStore } from './chunks/createStore-DHj16Ehk.js';
+import '@volynets/reflex-runtime/internal';
+import '@volynets/reflex';