@volynets/reflex-store 0.0.0-stage → 0.0.1

package/package.json

@@ -1,6 +1,127 @@
 {
   "name": "@volynets/reflex-store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "type": "module",
+  "description": "State management primitives for Reflex",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./advanced": {
+      "types": "./dist/advanced.d.ts",
+      "import": "./dist/advanced.js"
+    },
+    "./selectors": {
+      "types": "./dist/selectors/index.d.ts",
+      "import": "./dist/selectors/index.js"
+    },
+    "./selectors/shared": {
+      "types": "./dist/selectors/shared.d.ts",
+      "import": "./dist/selectors/shared.js"
+    },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "import": "./dist/store.js"
+    },
+    "./compiled-store": {
+      "types": "./dist/compiled-store.d.ts",
+      "import": "./dist/compiled-store.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./runtime/internal": {
+      "types": "./dist/runtime/internal.d.ts",
+      "import": "./dist/runtime/internal.js"
+    },
+    "./runtime/core": {
+      "types": "./dist/runtime/core.d.ts",
+      "import": "./dist/runtime/core.js"
+    },
+    "./runtime/types": {
+      "types": "./dist/runtime/types.d.ts",
+      "import": "./dist/runtime/types.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples/task-board",
+    "src/store/README.md",
+    "src/store/TRANSFORM_SPEC.md",
+    "SPECIFICATION.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node ../../tooling/build/clean.mjs .",
+    "build": "node scripts/build.mjs",
+    "bench": "vitest bench --config vite.config.ts bench/semantic-workloads.bench.ts",
+    "bench:full": "vitest bench --mode full --config vite.config.ts bench/semantic-workloads.bench.ts",
+    "bench:hot-paths": "node --expose-gc bench/hot-paths.node.mjs",
+    "bench:metrics": "vitest run --config vite.metrics.config.ts tests/semantic-workloads.metrics.test.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run --config vite.config.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc -p tsconfig.example.json",
+    "prepublishOnly": "pnpm check:release",
+    "check:release": "pnpm build:all && pnpm lint && pnpm test && pnpm test:dev && pnpm typecheck && pnpm check:artifacts && node scripts/packed-runtime-identity.mjs",
+    "test:dev": "vitest run --config vite.dev.config.ts",
+    "test:differential": "vitest run --config vite.config.ts tests/compiler.differential.test.ts tests/runtime.differential.test.ts",
+    "test:integration": "vitest run --config vite.config.ts tests/store.integration.test.ts tests/vite-user-dx.test.ts tests/task-board",
+    "test:packed-runtime": "pnpm --filter @volynets/reflex build:all && pnpm --filter @volynets/reflex-framework build && pnpm build && node scripts/packed-runtime-identity.mjs",
+    "build:all": "node ../../tooling/build/run.mjs @volynets/reflex-store",
+    "check:artifacts": "node ../../tooling/build/verify-artifacts.mjs --directory .",
+    "prepack": "pnpm build && pnpm check:artifacts"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^29.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-replace": "^6.0.3",
+    "@rollup/plugin-swc": "^0.4.0",
+    "@swc/core": "^1.15.18",
+    "@swc/wasm": "^1.16.13",
+    "@types/node": "^26.1.2",
+    "@volynets/reflex": "workspace:^",
+    "@volynets/reflex-runtime": "workspace:*",
+    "@volynets/reflex-scheduler": "workspace:^",
+    "rollup": "^4.54.0",
+    "rollup-plugin-dts": "^6.4.1",
+    "@volynets/reflex-framework": "workspace:*"
+  },
+  "keywords": [
+    "reflex",
+    "state",
+    "store",
+    "selector",
+    "reactivity"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volynetstyle/Reflex.git",
+    "directory": "packages/reflex-store"
+  },
+  "homepage": "https://github.com/volynetstyle/Reflex/tree/main/packages/reflex-store",
+  "bugs": {
+    "url": "https://github.com/volynetstyle/Reflex/issues"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "peerDependencies": {
+    "@volynets/reflex": "^1.0.0",
+    "@volynets/reflex-runtime": "^1.0.0",
+    "@volynets/reflex-framework": "^0.1.3"
+  },
+  "private": false
+}

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.