@octanejs/use-sync-external-store 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dominic Gannaway
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) Meta Platforms, Inc. and affiliates.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,61 @@
1
- # Temporary Holding Version
1
+ # @octanejs/use-sync-external-store
2
2
 
3
- 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.
3
+ The `use-sync-external-store` 1.7.0 entry points for Octane. Replace
4
+ `use-sync-external-store` imports with `@octanejs/use-sync-external-store` when
5
+ porting source to Octane.
6
+
7
+ ## Installation
8
+
9
+ ```sh
10
+ npm install @octanejs/use-sync-external-store octane
11
+ pnpm add @octanejs/use-sync-external-store octane
12
+ ```
13
+
14
+ Install it with the Octane release it is published alongside. Earlier releases
15
+ drop `getServerSnapshot` when `useSyncExternalStore` is imported through a
16
+ re-export such as this package's.
17
+
18
+ ## Usage
19
+
20
+ ```ts
21
+ import { useSyncExternalStoreWithSelector } from '@octanejs/use-sync-external-store/with-selector';
22
+
23
+ const todo = useSyncExternalStoreWithSelector(
24
+ store.subscribe,
25
+ store.getSnapshot,
26
+ store.getServerSnapshot,
27
+ (state) => state.todos[id],
28
+ (left, right) => left.done === right.done && left.title === right.title,
29
+ );
30
+ ```
31
+
32
+ Every published entry point has a counterpart, including the `.js` spellings:
33
+
34
+ | Entry point | Exports |
35
+ | --- | --- |
36
+ | `@octanejs/use-sync-external-store` | `useSyncExternalStore` |
37
+ | `/shim`, `/shim/index.js`, `/shim/index.native`, `/shim/index.native.js` | `useSyncExternalStore` |
38
+ | `/with-selector`, `/with-selector.js`, `/shim/with-selector`, `/shim/with-selector.js` | `useSyncExternalStoreWithSelector` |
39
+
40
+ `useSyncExternalStore` is Octane's own hook, the same function `octane` exports,
41
+ just as the published package re-exports React's built-in hook on React 18 and
42
+ later. Octane always has the built-in hook, so the userspace fallback the shim
43
+ keeps for React 16 and 17 is not needed. New code can import
44
+ `useSyncExternalStore` from `octane` directly.
45
+
46
+ `useSyncExternalStoreWithSelector` is a port of React's selector hook. It
47
+ recomputes the selection only when the snapshot changes, and keeps the previous
48
+ selection when `isEqual` reports the new one equal, so an unchanged selection
49
+ does not re-render.
50
+
51
+ As upstream does, the main entry point logs one error in development when it
52
+ loads, recommending `/shim` or `octane` instead.
53
+
54
+ ## Differences from React
55
+
56
+ - During server rendering, Octane's `useSyncExternalStore` falls back to
57
+ `getSnapshot` when no server snapshot is given; React throws. Pass
58
+ `getServerSnapshot` for markup that must match the client's first render.
59
+ - Octane hydrates only markup its own server renderer wrote.
60
+
61
+ `UPSTREAM.md` records the pinned source, license, and test evidence.
package/UPSTREAM.md ADDED
@@ -0,0 +1,41 @@
1
+ # Upstream boundary
2
+
3
+ - Package: `use-sync-external-store@1.7.0`.
4
+ - Source: https://github.com/react/react/tree/1d34f91dfde6bba84d08b683aaba164c7194dacb/packages/use-sync-external-store
5
+ - Immutable commit: `1d34f91dfde6bba84d08b683aaba164c7194dacb`.
6
+ - License: MIT. `LICENSE.upstream` retains the exact Meta notice and permission.
7
+ - npm integrity: `sha512-6L+EeigHMQhdaIPNIFUKwfWJSwWFQ8gJbJ2DLOs5sDIegTwR9fRxvnM3uciHKjIZhFz+KAv2emhWMRvDmMcY8A==`.
8
+
9
+ `audit/upstream.lock.json` pins every pristine source and test blob under
10
+ `upstream/`. `upstream-artifact/` holds the integrity-checked npm tarball and its
11
+ extracted files, the pristine runtime oracle. Neither ships.
12
+
13
+ ## Source boundary
14
+
15
+ | Upstream | Binding | Disposition |
16
+ | --- | --- | --- |
17
+ | `src/useSyncExternalStoreWithSelector.js` | `src/useSyncExternalStoreWithSelector.ts` | Ported onto Octane's hooks with a trailing hook slot. |
18
+ | `src/useSyncExternalStore.js`, `index.js` | `src/index.ts` | Re-exports Octane's built-in hook and keeps the development warning. |
19
+ | `src/useSyncExternalStoreShim.js`, `shim/index.js`, `shim/index.native.js` | `src/shim/index.ts` | On React 18+ the shim selects the built-in hook; Octane always has it. |
20
+ | `with-selector.js`, `shim/with-selector.js` | `src/useSyncExternalStoreWithSelector.ts` | Both builds share one module, since both resolve to the built-in hook. |
21
+ | `src/useSyncExternalStoreShimClient.js`, `src/useSyncExternalStoreShimServer.js`, `src/isServerEnvironment.js`, `src/forks/*` | none | The userspace fallback for React 16 and 17, and the build forks selecting it, are inapplicable. |
22
+
23
+ The complete published surface is accounted for: `useSyncExternalStore` from the
24
+ main entry and every `/shim` spelling, and `useSyncExternalStoreWithSelector` from
25
+ every `with-selector` spelling. The `react-native` condition of `/shim` resolves to
26
+ the same module as `default`.
27
+
28
+ ## Test evidence
29
+
30
+ The pinned package ships no TypeScript declarations or type tests; the public
31
+ types follow `@types/use-sync-external-store` and are checked by
32
+ `tests/types/public.test-d.ts`.
33
+
34
+ The three pinned runtime test files register 22 cases. The pristine lane runs
35
+ their bytes unchanged against React 19.2.7 and the npm artifact; the adapted lane
36
+ runs them, regenerated with the lock's import rewrites and the patches in
37
+ `audit/upstream-patches/`, against Octane. `tests/harness.ts` stands in for the
38
+ parts of React's Jest environment they use. In both lanes the build-test
39
+ configuration gates one legacy-root case to the React 17 shim variant. Every
40
+ `OCTANE DIVERGENCE` in the patches is listed in `audit/react-parity.json`, and
41
+ `audit/crosswalk.json` maps every registration to its evidence.
package/package.json CHANGED
@@ -1,6 +1,65 @@
1
1
  {
2
2
  "name": "@octanejs/use-sync-external-store",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.1",
4
+ "description": "use-sync-external-store 1.7.0 for Octane: Octane's built-in useSyncExternalStore and a port of useSyncExternalStoreWithSelector.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "sideEffects": false,
8
+ "engines": {
9
+ "node": ">=22.22.2"
10
+ },
11
+ "author": {
12
+ "name": "Dominic Gannaway",
13
+ "email": "dg@domgan.com"
14
+ },
15
+ "publishConfig": {
16
+ "access": "public"
17
+ },
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/octanejs/octane.git",
21
+ "directory": "packages/use-sync-external-store"
22
+ },
23
+ "main": "src/index.ts",
24
+ "module": "src/index.ts",
25
+ "types": "src/index.ts",
26
+ "exports": {
27
+ ".": "./src/index.ts",
28
+ "./with-selector": "./src/useSyncExternalStoreWithSelector.ts",
29
+ "./with-selector.js": "./src/useSyncExternalStoreWithSelector.ts",
30
+ "./shim": "./src/shim/index.ts",
31
+ "./shim/index.js": "./src/shim/index.ts",
32
+ "./shim/index.native": "./src/shim/index.ts",
33
+ "./shim/index.native.js": "./src/shim/index.ts",
34
+ "./shim/with-selector": "./src/useSyncExternalStoreWithSelector.ts",
35
+ "./shim/with-selector.js": "./src/useSyncExternalStoreWithSelector.ts",
36
+ "./package.json": "./package.json"
37
+ },
38
+ "files": [
39
+ "src",
40
+ "README.md",
41
+ "UPSTREAM.md",
42
+ "LICENSE",
43
+ "LICENSE.upstream"
44
+ ],
45
+ "octane": {
46
+ "hookSlots": {
47
+ "manual": [
48
+ "src"
49
+ ]
50
+ }
51
+ },
52
+ "peerDependencies": {
53
+ "octane": "^0.16.4"
54
+ },
55
+ "devDependencies": {
56
+ "octane": "0.16.4",
57
+ "react": "19.2.7",
58
+ "react-dom": "19.2.7",
59
+ "vitest": "^4.1.10"
60
+ },
61
+ "scripts": {
62
+ "test": "vitest run --root ../.. --project use-sync-external-store",
63
+ "upstream:verify": "node ../../scripts/react-parity/verify-provenance.mjs"
64
+ }
6
65
  }
package/src/index.ts ADDED
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
3
+ *
4
+ * This source code is licensed under the MIT license found in the
5
+ * LICENSE.upstream file in the root directory of this package.
6
+ */
7
+
8
+ // Adapted from use-sync-external-store@1.7.0 src/useSyncExternalStore.js: the
9
+ // main entry point re-exports the framework's built-in hook and warns once, at
10
+ // module load in development, that it is not the supported entry point.
11
+ //
12
+ // Declared locally so consumers need no Node types; bundlers replace it.
13
+ declare const process: { env: { NODE_ENV?: string } };
14
+
15
+ export { useSyncExternalStore } from 'octane';
16
+
17
+ if (process.env.NODE_ENV !== 'production') {
18
+ console['error'](
19
+ "The main '@octanejs/use-sync-external-store' entry point is not supported; " +
20
+ "all it does is re-export useSyncExternalStore from the 'octane' package." +
21
+ '\n\n' +
22
+ "Import from '@octanejs/use-sync-external-store/shim' instead, or import " +
23
+ "useSyncExternalStore from 'octane' directly.",
24
+ );
25
+ }
@@ -0,0 +1,4 @@
1
+ // use-sync-external-store@1.7.0 `shim/index.js` and `shim/index.native.js`
2
+ // select React's built-in useSyncExternalStore whenever it exists, falling back
3
+ // to a userspace implementation only before React 18. Octane always has it.
4
+ export { useSyncExternalStore } from 'octane';
@@ -0,0 +1,150 @@
1
+ /**
2
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
3
+ *
4
+ * This source code is licensed under the MIT license found in the
5
+ * LICENSE.upstream file in the root directory of this package.
6
+ */
7
+
8
+ // Adapted from use-sync-external-store@1.7.0 src/useSyncExternalStoreWithSelector.js
9
+ // onto Octane's hooks. Both `with-selector` entry points share this module:
10
+ // upstream builds one against React's built-in useSyncExternalStore and one
11
+ // against its shim, and on React 18+ the shim is the built-in, as it always is
12
+ // on Octane.
13
+ import {
14
+ createSubSlot,
15
+ useDebugValue,
16
+ useEffect,
17
+ useMemo,
18
+ useRef,
19
+ useSyncExternalStore,
20
+ } from 'octane';
21
+
22
+ // This file is not compiled, so the caller's hook slot arrives as the trailing
23
+ // argument and each composed hook derives its own sub-slot from it.
24
+ const subSlot = createSubSlot({ slotlessPrefix: '@octanejs/use-sync-external-store:' });
25
+
26
+ // Same as useSyncExternalStore, but supports selector and isEqual arguments.
27
+ export function useSyncExternalStoreWithSelector<Snapshot, Selection>(
28
+ subscribe: (onStoreChange: () => void) => () => void,
29
+ getSnapshot: () => Snapshot,
30
+ getServerSnapshot: undefined | null | (() => Snapshot),
31
+ selector: (snapshot: Snapshot) => Selection,
32
+ isEqual?: (a: Selection, b: Selection) => boolean,
33
+ ): Selection;
34
+ export function useSyncExternalStoreWithSelector<Snapshot, Selection>(
35
+ subscribe: (onStoreChange: () => void) => () => void,
36
+ getSnapshot: () => Snapshot,
37
+ getServerSnapshot: undefined | null | (() => Snapshot),
38
+ selector: (snapshot: Snapshot) => Selection,
39
+ isEqualOrSlot?: ((a: Selection, b: Selection) => boolean) | symbol,
40
+ trailingSlot?: symbol,
41
+ ): Selection {
42
+ // A call that omits isEqual carries the slot in its place.
43
+ const isEqual = typeof isEqualOrSlot === 'symbol' ? undefined : isEqualOrSlot;
44
+ const slot = typeof isEqualOrSlot === 'symbol' ? isEqualOrSlot : trailingSlot;
45
+
46
+ type Inst = { hasValue: boolean; value: Selection | null };
47
+
48
+ // Use this to track the rendered snapshot.
49
+ const instRef = useRef<Inst | null>(null, subSlot(slot, 'inst'));
50
+ let inst: Inst;
51
+ if (instRef.current === null) {
52
+ inst = {
53
+ hasValue: false,
54
+ value: null,
55
+ };
56
+ instRef.current = inst;
57
+ } else {
58
+ inst = instRef.current;
59
+ }
60
+
61
+ const [getSelection, getServerSelection] = useMemo(
62
+ () => {
63
+ // Track the memoized state using closure variables that are local to this
64
+ // memoized instance of a getSnapshot function. Intentionally not using a
65
+ // useRef hook, because that state would be shared across all concurrent
66
+ // copies of the hook/component.
67
+ let hasMemo = false;
68
+ let memoizedSnapshot: Snapshot;
69
+ let memoizedSelection: Selection;
70
+ const memoizedSelector = (nextSnapshot: Snapshot) => {
71
+ if (!hasMemo) {
72
+ // The first time the hook is called, there is no memoized result.
73
+ hasMemo = true;
74
+ memoizedSnapshot = nextSnapshot;
75
+ const nextSelection = selector(nextSnapshot);
76
+ if (isEqual !== undefined) {
77
+ // Even if the selector has changed, the currently rendered selection
78
+ // may be equal to the new selection. We should attempt to reuse the
79
+ // current value if possible, to preserve downstream memoizations.
80
+ if (inst.hasValue) {
81
+ const currentSelection = inst.value as Selection;
82
+ if (isEqual(currentSelection, nextSelection)) {
83
+ memoizedSelection = currentSelection;
84
+ return currentSelection;
85
+ }
86
+ }
87
+ }
88
+ memoizedSelection = nextSelection;
89
+ return nextSelection;
90
+ }
91
+
92
+ // We may be able to reuse the previous invocation's result.
93
+ const prevSnapshot: Snapshot = memoizedSnapshot;
94
+ const prevSelection: Selection = memoizedSelection;
95
+
96
+ if (Object.is(prevSnapshot, nextSnapshot)) {
97
+ // The snapshot is the same as last time. Reuse the previous selection.
98
+ return prevSelection;
99
+ }
100
+
101
+ // The snapshot has changed, so we need to compute a new selection.
102
+ const nextSelection = selector(nextSnapshot);
103
+
104
+ // If a custom isEqual function is provided, use that to check if the data
105
+ // has changed. If it hasn't, return the previous selection. That signals
106
+ // to Octane that the selections are conceptually equal, and we can bail
107
+ // out of rendering.
108
+ if (isEqual !== undefined && isEqual(prevSelection, nextSelection)) {
109
+ // The snapshot still has changed, so make sure to update to not keep
110
+ // old references alive
111
+ memoizedSnapshot = nextSnapshot;
112
+ return prevSelection;
113
+ }
114
+
115
+ memoizedSnapshot = nextSnapshot;
116
+ memoizedSelection = nextSelection;
117
+ return nextSelection;
118
+ };
119
+ // Assigning this to a constant so that TypeScript knows it can't change.
120
+ const maybeGetServerSnapshot = getServerSnapshot === undefined ? null : getServerSnapshot;
121
+ const getSnapshotWithSelector = () => memoizedSelector(getSnapshot());
122
+ const getServerSnapshotWithSelector =
123
+ maybeGetServerSnapshot === null
124
+ ? undefined
125
+ : () => memoizedSelector(maybeGetServerSnapshot());
126
+ return [getSnapshotWithSelector, getServerSnapshotWithSelector] as const;
127
+ },
128
+ [getSnapshot, getServerSnapshot, selector, isEqual],
129
+ subSlot(slot, 'memo'),
130
+ );
131
+
132
+ const value = useSyncExternalStore(
133
+ subscribe,
134
+ getSelection,
135
+ getServerSelection,
136
+ subSlot(slot, 'store'),
137
+ );
138
+
139
+ useEffect(
140
+ () => {
141
+ inst.hasValue = true;
142
+ inst.value = value;
143
+ },
144
+ [value],
145
+ subSlot(slot, 'effect'),
146
+ );
147
+
148
+ useDebugValue(value);
149
+ return value;
150
+ }