@bradensbay/globals-react 0.2.0

package/README.md

@@ -0,0 +1,22 @@
+# @bradensbay/globals-react
+
+The react binding for [Globals](https://github.com/christianGRogers/globals).
+
+Full guide: [docs/bindings.md](../../docs/bindings.md).
+
+## The point
+
+Reads are synchronous. A render can call `get()` on the line it needs the value, with no
+`await` and no replicated copy of state in the window.
+
+Writes are asynchronous, and the return type says so.
+
+## Equality
+
+The default is `Object.is`, which is right for a scalar and wrong for a container. Every
+commit builds a fresh decode cache, so a selector returning a nested object returns a new
+proxy each time and notifies on every commit.
+
+For a container, use the node comparing variant. An untouched subtree keeps its arena node
+across commits, so it notifies only when the subtree actually changed. The reasoning behind
+why comparing offsets is sound is in [docs/bindings.md](../../docs/bindings.md).

package/dist/src/index.d.ts

@@ -0,0 +1,55 @@
+import { type ReactNode } from "react";
+import { type ReadableStore, type Snapshot } from "@bradensbay/globals-core";
+export interface StoreProviderProps {
+    store: ReadableStore;
+    children: ReactNode;
+}
+export declare function StoreProvider({ store, children }: StoreProviderProps): ReactNode;
+export declare function useStore(): ReadableStore;
+/**
+ * Subscribe to a slice of state.
+ *
+ * The selector runs on every render and on every commit. It must be cheap.
+ *
+ * Selecting a scalar is the shape that always works, because React compares with Object.is
+ * and a number is a number. Selecting a container does not: every commit builds a fresh
+ * decode cache, so the view is a new proxy each time and the component rerenders on every
+ * commit whether or not the subtree changed.
+ *
+ * For a container, use useNodeSelector, which compares the arena node behind the value. That
+ * is the question a container selector is actually asking, and structural sharing makes the
+ * answer cheap.
+ */
+export declare function useSelector<T>(selector: (state: unknown) => T): T;
+/**
+ * Subscribe to a container slice, compared by the arena node behind it.
+ *
+ * An untouched subtree keeps its arena node across commits, so this rerenders only when the
+ * selected subtree actually changed. The cached value is held across renders and replaced
+ * only when the node moves, which is what gives useSyncExternalStore the stable identity it
+ * needs.
+ */
+export declare function useNodeSelector<T>(selector: (state: unknown) => T): T;
+/**
+ * Read one path.
+ *
+ * Cheaper than a selector over the whole state, because it walks the arena directly and
+ * never builds views for the nodes on the way down. Prefer it for a leaf value.
+ */
+export declare function usePath<T = unknown>(path: readonly (string | number)[]): T;
+/** The whole state. Convenient, and it rerenders on every commit, so use it deliberately. */
+export declare function useGlobalState<T = unknown>(): T;
+/**
+ * Hold a snapshot for the lifetime of a component.
+ *
+ * For a component that must see one consistent version across several reads and across
+ * child renders, such as a virtualised list measuring and then rendering rows. The pin is
+ * released on unmount, and refreshed when the store commits.
+ *
+ * Holding a snapshot blocks reclamation of that version, so a component that holds one and
+ * never updates will eventually be force advanced and see StaleSnapshotError. That is the
+ * bounded retention rule doing its job rather than a bug.
+ */
+export declare function usePinnedSnapshot(): Snapshot;
+export type { ReadableStore, Snapshot };
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0H,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC/J,OAAO,EAAY,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAgBvF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,kBAAkB,GAAG,SAAS,CAEhF;AAED,wBAAgB,QAAQ,IAAI,aAAa,CAMxC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAajE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAiBrE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,CAAC,CAkB1E;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,CAK/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,IAAI,QAAQ,CAwB5C;AAED,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC"}

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@bradensbay/globals-react",
+  "version": "0.2.0",
+  "description": "React binding: useSyncExternalStore over a shared memory store.",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "dependencies": {
+    "@bradensbay/globals-core": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/christianGRogers/globals.git",
+    "directory": "packages/react"
+  }
+}