react-single-instance 0.1.0 → 0.1.2
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/README.md +11 -12
- package/dist/index.cjs +9 -9
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +10 -10
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,17 +4,18 @@
|
|
|
4
4
|
|
|
5
5
|
Render something at most once for a given `id`, app-wide - a component, a hook, and a HOC, all sharing one registry. Useful for a modal root, a toast host, or any other element that must exist exactly once even if it gets mounted from more than one place by mistake.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
| | first claimant | every claimant after it |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `<SingleInstance id="x">children</SingleInstance>` | renders `children` | renders nothing |
|
|
10
|
+
| `useSingleInstance('x')` | returns `true` | returns `false` |
|
|
11
|
+
| `withSingleInstance(Component, 'x')` | renders `<Component />` | renders nothing |
|
|
8
12
|
|
|
9
13
|
```bash
|
|
10
14
|
npm i react-single-instance
|
|
11
15
|
```
|
|
12
16
|
|
|
13
17
|
```tsx
|
|
14
|
-
import {
|
|
15
|
-
|
|
16
|
-
// once, at app startup, before anything below renders
|
|
17
|
-
initSingleInstance();
|
|
18
|
+
import { SingleInstance, useSingleInstance, withSingleInstance } from 'react-single-instance';
|
|
18
19
|
```
|
|
19
20
|
|
|
20
21
|
## `<SingleInstance>`
|
|
@@ -42,22 +43,20 @@ function ModalHost() {
|
|
|
42
43
|
const GuardedModalHost = withSingleInstance(ModalHost, 'modal-root');
|
|
43
44
|
```
|
|
44
45
|
|
|
45
|
-
##
|
|
46
|
-
|
|
47
|
-
`React.StrictMode` invokes a function component's render body twice, back to back, in development only. There's no purity-safe way, from inside render, to tell "this is my own StrictMode replay" apart from "this is a genuinely different caller" - so the registry allows exactly two claims per id before rejecting the rest, which absorbs StrictMode's double-invoke without ever risking a real mount silently rendering nothing.
|
|
46
|
+
## `initSingleInstance()`
|
|
48
47
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
**Known limitation:** two genuinely different call sites that both mount with the same `id` in the same commit, *outside* of StrictMode, will both be granted - the two-slot slack that makes StrictMode safe is indistinguishable, from inside render, from two real callers. Run under StrictMode (React's development default) and a real duplicate's own two extra invocations get caught immediately; without it, a duplicate that stays mounted is still caught the moment a third claimant shows up, or after the next `initSingleInstance()` cycle.
|
|
48
|
+
Not required — claims release automatically when their component unmounts. Kept for compatibility with earlier versions, and as a manual way to reset the registry (e.g. in tests).
|
|
52
49
|
|
|
53
50
|
## Playground
|
|
54
51
|
|
|
55
|
-
|
|
52
|
+
An interactive demo of all three APIs side by side, with the source for each shown right next to it:
|
|
56
53
|
|
|
57
54
|
```bash
|
|
58
55
|
npm run playground
|
|
59
56
|
```
|
|
60
57
|
|
|
58
|
+
Click "mount another claimant" to watch new attempts get rejected live, "re-render" to confirm a granted instance never loses its slot, and "unmount" to see that removing a claimant frees its id for the next one.
|
|
59
|
+
|
|
61
60
|
## Development
|
|
62
61
|
|
|
63
62
|
```bash
|
package/dist/index.cjs
CHANGED
|
@@ -32,25 +32,24 @@ module.exports = __toCommonJS(index_exports);
|
|
|
32
32
|
var import_react = require("react");
|
|
33
33
|
|
|
34
34
|
// src/registry.ts
|
|
35
|
-
var STRICT_MODE_SLACK = 2;
|
|
36
35
|
var counts = /* @__PURE__ */ new Map();
|
|
37
|
-
var initialized = false;
|
|
38
36
|
function initSingleInstance() {
|
|
39
|
-
initialized = true;
|
|
40
37
|
counts.clear();
|
|
41
38
|
}
|
|
42
39
|
function claimSingleInstance(id) {
|
|
43
40
|
var _a;
|
|
44
|
-
|
|
45
|
-
console.warn(
|
|
46
|
-
`[react-single-instance] "${id}" rendered before initSingleInstance() ran. Call initSingleInstance() once at app startup - otherwise ids never reset between test runs, hot reloads, or route remounts.`
|
|
47
|
-
);
|
|
48
|
-
}
|
|
41
|
+
const slack = process.env.NODE_ENV === "production" ? 1 : 2;
|
|
49
42
|
const count = (_a = counts.get(id)) != null ? _a : 0;
|
|
50
|
-
if (count >=
|
|
43
|
+
if (count >= slack) return false;
|
|
51
44
|
counts.set(id, count + 1);
|
|
52
45
|
return true;
|
|
53
46
|
}
|
|
47
|
+
function releaseSingleInstance(id) {
|
|
48
|
+
var _a;
|
|
49
|
+
const count = (_a = counts.get(id)) != null ? _a : 0;
|
|
50
|
+
if (count <= 1) counts.delete(id);
|
|
51
|
+
else counts.set(id, count - 1);
|
|
52
|
+
}
|
|
54
53
|
|
|
55
54
|
// src/useSingleInstance.ts
|
|
56
55
|
function useSingleInstance(id) {
|
|
@@ -58,6 +57,7 @@ function useSingleInstance(id) {
|
|
|
58
57
|
if (settled.current === void 0) {
|
|
59
58
|
settled.current = claimSingleInstance(id);
|
|
60
59
|
}
|
|
60
|
+
(0, import_react.useEffect)(() => () => releaseSingleInstance(id), [id]);
|
|
61
61
|
return settled.current;
|
|
62
62
|
}
|
|
63
63
|
|
package/dist/index.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts","../src/useSingleInstance.ts","../src/registry.ts","../src/SingleInstance.tsx","../src/withSingleInstance.tsx"],"sourcesContent":["export { SingleInstance, default } from './SingleInstance';\nexport type { SingleInstanceProps } from './SingleInstance';\nexport { useSingleInstance } from './useSingleInstance';\nexport { withSingleInstance } from './withSingleInstance';\nexport { initSingleInstance } from './registry';\n","import { useRef } from 'react';\nimport { claimSingleInstance } from './registry';\n\
|
|
1
|
+
{"version":3,"sources":["../src/index.ts","../src/useSingleInstance.ts","../src/registry.ts","../src/SingleInstance.tsx","../src/withSingleInstance.tsx"],"sourcesContent":["export { SingleInstance, default } from './SingleInstance';\nexport type { SingleInstanceProps } from './SingleInstance';\nexport { useSingleInstance } from './useSingleInstance';\nexport { withSingleInstance } from './withSingleInstance';\nexport { initSingleInstance } from './registry';\n","import { useEffect, useRef } from 'react';\nimport { claimSingleInstance, releaseSingleInstance } from './registry';\n\nexport function useSingleInstance(id: string): boolean {\n const settled = useRef<boolean | undefined>(undefined);\n if (settled.current === undefined) {\n settled.current = claimSingleInstance(id);\n }\n\n useEffect(() => () => releaseSingleInstance(id), [id]);\n\n return settled.current;\n}\n","const counts = new Map<string, number>();\n\n/** Optional manual reset, e.g. in tests — never required for normal use. */\nexport function initSingleInstance(): void {\n counts.clear();\n}\n\n/** @internal exposed for tests only */\nexport function __resetSingleInstanceForTests(): void {\n counts.clear();\n}\n\nexport function claimSingleInstance(id: string): boolean {\n\n const slack = process.env.NODE_ENV === 'production' ? 1 : 2;\n\n const count = counts.get(id) ?? 0;\n if (count >= slack) return false;\n\n counts.set(id, count + 1);\n return true;\n}\n\nexport function releaseSingleInstance(id: string): void {\n const count = counts.get(id) ?? 0;\n if (count <= 1) counts.delete(id);\n else counts.set(id, count - 1);\n}\n","import type { ReactNode } from 'react';\nimport { useSingleInstance } from './useSingleInstance';\n\nexport interface SingleInstanceProps {\n id: string;\n children: ReactNode;\n}\n\nexport function SingleInstance({ id, children }: SingleInstanceProps): ReactNode {\n return useSingleInstance(id) ? children : null;\n}\n\nexport default SingleInstance;\n","import type { ComponentType } from 'react';\nimport { useSingleInstance } from './useSingleInstance';\n\nexport function withSingleInstance<P extends object>(Component: ComponentType<P>, id: string): ComponentType<P> {\n function WithSingleInstance(props: P) {\n return useSingleInstance(id) ? <Component {...props} /> : null;\n }\n\n WithSingleInstance.displayName = `withSingleInstance(${Component.displayName || Component.name || 'Component'})`;\n\n return WithSingleInstance;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAAkC;;;ACAlC,IAAM,SAAS,oBAAI,IAAoB;AAGhC,SAAS,qBAA2B;AACzC,SAAO,MAAM;AACf;AAOO,SAAS,oBAAoB,IAAqB;AAZzD;AAcE,QAAM,QAAQ,QAAQ,IAAI,aAAa,eAAe,IAAI;AAE1D,QAAM,SAAQ,YAAO,IAAI,EAAE,MAAb,YAAkB;AAChC,MAAI,SAAS,MAAO,QAAO;AAE3B,SAAO,IAAI,IAAI,QAAQ,CAAC;AACxB,SAAO;AACT;AAEO,SAAS,sBAAsB,IAAkB;AAvBxD;AAwBE,QAAM,SAAQ,YAAO,IAAI,EAAE,MAAb,YAAkB;AAChC,MAAI,SAAS,EAAG,QAAO,OAAO,EAAE;AAAA,MAC3B,QAAO,IAAI,IAAI,QAAQ,CAAC;AAC/B;;;ADxBO,SAAS,kBAAkB,IAAqB;AACrD,QAAM,cAAU,qBAA4B,MAAS;AACrD,MAAI,QAAQ,YAAY,QAAW;AACjC,YAAQ,UAAU,oBAAoB,EAAE;AAAA,EAC1C;AAEA,8BAAU,MAAM,MAAM,sBAAsB,EAAE,GAAG,CAAC,EAAE,CAAC;AAErD,SAAO,QAAQ;AACjB;;;AEJO,SAAS,eAAe,EAAE,IAAI,SAAS,GAAmC;AAC/E,SAAO,kBAAkB,EAAE,IAAI,WAAW;AAC5C;AAEA,IAAO,yBAAQ;;;ACPoB;AAF5B,SAAS,mBAAqC,WAA6B,IAA8B;AAC9G,WAAS,mBAAmB,OAAU;AACpC,WAAO,kBAAkB,EAAE,IAAI,4CAAC,aAAW,GAAG,OAAO,IAAK;AAAA,EAC5D;AAEA,qBAAmB,cAAc,sBAAsB,UAAU,eAAe,UAAU,QAAQ,WAAW;AAE7G,SAAO;AACT;","names":[]}
|
package/dist/index.d.cts
CHANGED
|
@@ -10,6 +10,7 @@ declare function useSingleInstance(id: string): boolean;
|
|
|
10
10
|
|
|
11
11
|
declare function withSingleInstance<P extends object>(Component: ComponentType<P>, id: string): ComponentType<P>;
|
|
12
12
|
|
|
13
|
+
/** Optional manual reset, e.g. in tests — never required for normal use. */
|
|
13
14
|
declare function initSingleInstance(): void;
|
|
14
15
|
|
|
15
16
|
export { SingleInstance, type SingleInstanceProps, SingleInstance as default, initSingleInstance, useSingleInstance, withSingleInstance };
|
package/dist/index.d.ts
CHANGED
|
@@ -10,6 +10,7 @@ declare function useSingleInstance(id: string): boolean;
|
|
|
10
10
|
|
|
11
11
|
declare function withSingleInstance<P extends object>(Component: ComponentType<P>, id: string): ComponentType<P>;
|
|
12
12
|
|
|
13
|
+
/** Optional manual reset, e.g. in tests — never required for normal use. */
|
|
13
14
|
declare function initSingleInstance(): void;
|
|
14
15
|
|
|
15
16
|
export { SingleInstance, type SingleInstanceProps, SingleInstance as default, initSingleInstance, useSingleInstance, withSingleInstance };
|
package/dist/index.js
CHANGED
|
@@ -1,26 +1,25 @@
|
|
|
1
1
|
// src/useSingleInstance.ts
|
|
2
|
-
import { useRef } from "react";
|
|
2
|
+
import { useEffect, useRef } from "react";
|
|
3
3
|
|
|
4
4
|
// src/registry.ts
|
|
5
|
-
var STRICT_MODE_SLACK = 2;
|
|
6
5
|
var counts = /* @__PURE__ */ new Map();
|
|
7
|
-
var initialized = false;
|
|
8
6
|
function initSingleInstance() {
|
|
9
|
-
initialized = true;
|
|
10
7
|
counts.clear();
|
|
11
8
|
}
|
|
12
9
|
function claimSingleInstance(id) {
|
|
13
10
|
var _a;
|
|
14
|
-
|
|
15
|
-
console.warn(
|
|
16
|
-
`[react-single-instance] "${id}" rendered before initSingleInstance() ran. Call initSingleInstance() once at app startup - otherwise ids never reset between test runs, hot reloads, or route remounts.`
|
|
17
|
-
);
|
|
18
|
-
}
|
|
11
|
+
const slack = process.env.NODE_ENV === "production" ? 1 : 2;
|
|
19
12
|
const count = (_a = counts.get(id)) != null ? _a : 0;
|
|
20
|
-
if (count >=
|
|
13
|
+
if (count >= slack) return false;
|
|
21
14
|
counts.set(id, count + 1);
|
|
22
15
|
return true;
|
|
23
16
|
}
|
|
17
|
+
function releaseSingleInstance(id) {
|
|
18
|
+
var _a;
|
|
19
|
+
const count = (_a = counts.get(id)) != null ? _a : 0;
|
|
20
|
+
if (count <= 1) counts.delete(id);
|
|
21
|
+
else counts.set(id, count - 1);
|
|
22
|
+
}
|
|
24
23
|
|
|
25
24
|
// src/useSingleInstance.ts
|
|
26
25
|
function useSingleInstance(id) {
|
|
@@ -28,6 +27,7 @@ function useSingleInstance(id) {
|
|
|
28
27
|
if (settled.current === void 0) {
|
|
29
28
|
settled.current = claimSingleInstance(id);
|
|
30
29
|
}
|
|
30
|
+
useEffect(() => () => releaseSingleInstance(id), [id]);
|
|
31
31
|
return settled.current;
|
|
32
32
|
}
|
|
33
33
|
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/useSingleInstance.ts","../src/registry.ts","../src/SingleInstance.tsx","../src/withSingleInstance.tsx"],"sourcesContent":["import { useRef } from 'react';\nimport { claimSingleInstance } from './registry';\n\
|
|
1
|
+
{"version":3,"sources":["../src/useSingleInstance.ts","../src/registry.ts","../src/SingleInstance.tsx","../src/withSingleInstance.tsx"],"sourcesContent":["import { useEffect, useRef } from 'react';\nimport { claimSingleInstance, releaseSingleInstance } from './registry';\n\nexport function useSingleInstance(id: string): boolean {\n const settled = useRef<boolean | undefined>(undefined);\n if (settled.current === undefined) {\n settled.current = claimSingleInstance(id);\n }\n\n useEffect(() => () => releaseSingleInstance(id), [id]);\n\n return settled.current;\n}\n","const counts = new Map<string, number>();\n\n/** Optional manual reset, e.g. in tests — never required for normal use. */\nexport function initSingleInstance(): void {\n counts.clear();\n}\n\n/** @internal exposed for tests only */\nexport function __resetSingleInstanceForTests(): void {\n counts.clear();\n}\n\nexport function claimSingleInstance(id: string): boolean {\n\n const slack = process.env.NODE_ENV === 'production' ? 1 : 2;\n\n const count = counts.get(id) ?? 0;\n if (count >= slack) return false;\n\n counts.set(id, count + 1);\n return true;\n}\n\nexport function releaseSingleInstance(id: string): void {\n const count = counts.get(id) ?? 0;\n if (count <= 1) counts.delete(id);\n else counts.set(id, count - 1);\n}\n","import type { ReactNode } from 'react';\nimport { useSingleInstance } from './useSingleInstance';\n\nexport interface SingleInstanceProps {\n id: string;\n children: ReactNode;\n}\n\nexport function SingleInstance({ id, children }: SingleInstanceProps): ReactNode {\n return useSingleInstance(id) ? children : null;\n}\n\nexport default SingleInstance;\n","import type { ComponentType } from 'react';\nimport { useSingleInstance } from './useSingleInstance';\n\nexport function withSingleInstance<P extends object>(Component: ComponentType<P>, id: string): ComponentType<P> {\n function WithSingleInstance(props: P) {\n return useSingleInstance(id) ? <Component {...props} /> : null;\n }\n\n WithSingleInstance.displayName = `withSingleInstance(${Component.displayName || Component.name || 'Component'})`;\n\n return WithSingleInstance;\n}\n"],"mappings":";AAAA,SAAS,WAAW,cAAc;;;ACAlC,IAAM,SAAS,oBAAI,IAAoB;AAGhC,SAAS,qBAA2B;AACzC,SAAO,MAAM;AACf;AAOO,SAAS,oBAAoB,IAAqB;AAZzD;AAcE,QAAM,QAAQ,QAAQ,IAAI,aAAa,eAAe,IAAI;AAE1D,QAAM,SAAQ,YAAO,IAAI,EAAE,MAAb,YAAkB;AAChC,MAAI,SAAS,MAAO,QAAO;AAE3B,SAAO,IAAI,IAAI,QAAQ,CAAC;AACxB,SAAO;AACT;AAEO,SAAS,sBAAsB,IAAkB;AAvBxD;AAwBE,QAAM,SAAQ,YAAO,IAAI,EAAE,MAAb,YAAkB;AAChC,MAAI,SAAS,EAAG,QAAO,OAAO,EAAE;AAAA,MAC3B,QAAO,IAAI,IAAI,QAAQ,CAAC;AAC/B;;;ADxBO,SAAS,kBAAkB,IAAqB;AACrD,QAAM,UAAU,OAA4B,MAAS;AACrD,MAAI,QAAQ,YAAY,QAAW;AACjC,YAAQ,UAAU,oBAAoB,EAAE;AAAA,EAC1C;AAEA,YAAU,MAAM,MAAM,sBAAsB,EAAE,GAAG,CAAC,EAAE,CAAC;AAErD,SAAO,QAAQ;AACjB;;;AEJO,SAAS,eAAe,EAAE,IAAI,SAAS,GAAmC;AAC/E,SAAO,kBAAkB,EAAE,IAAI,WAAW;AAC5C;AAEA,IAAO,yBAAQ;;;ACPoB;AAF5B,SAAS,mBAAqC,WAA6B,IAA8B;AAC9G,WAAS,mBAAmB,OAAU;AACpC,WAAO,kBAAkB,EAAE,IAAI,oBAAC,aAAW,GAAG,OAAO,IAAK;AAAA,EAC5D;AAEA,qBAAmB,cAAc,sBAAsB,UAAU,eAAe,UAAU,QAAQ,WAAW;AAE7G,SAAO;AACT;","names":[]}
|
package/package.json
CHANGED