├── .github
└── workflows
│ ├── main.yml
│ └── size.yml
├── .gitignore
├── LICENSE
├── README.md
├── babel.config.json
├── package.json
├── src
├── events.ts
├── index.tsx
├── state.ts
└── utils.ts
├── testExample
├── index.html
├── index.tsx
├── package.json
├── tsconfig.json
└── yarn.lock
├── tsconfig.json
└── yarn.lock
/.github/workflows/main.yml:
--------------------------------------------------------------------------------
1 | name: CI
2 | on: [push]
3 | jobs:
4 | build:
5 | name: Build, lint, and test on Node ${{ matrix.node }} and ${{ matrix.os }}
6 |
7 | runs-on: ${{ matrix.os }}
8 | strategy:
9 | matrix:
10 | node: ['12.x', '14.x']
11 | os: [ubuntu-latest, windows-latest, macOS-latest]
12 |
13 | steps:
14 | - name: Checkout repo
15 | uses: actions/checkout@v2
16 |
17 | - name: Use Node ${{ matrix.node }}
18 | uses: actions/setup-node@v1
19 | with:
20 | node-version: ${{ matrix.node }}
21 |
22 | - name: Install deps and build (with cache)
23 | uses: bahmutov/npm-install@v1
24 |
25 | - name: Build
26 | run: yarn build
27 |
--------------------------------------------------------------------------------
/.github/workflows/size.yml:
--------------------------------------------------------------------------------
1 | name: size
2 | on: [pull_request]
3 | jobs:
4 | size:
5 | runs-on: ubuntu-latest
6 | env:
7 | CI_JOB_NUMBER: 1
8 | steps:
9 | - uses: actions/checkout@v1
10 | - uses: andresz1/size-limit-action@v1
11 | with:
12 | github_token: ${{ secrets.GITHUB_TOKEN }}
13 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | *.log
2 | .DS_Store
3 | node_modules
4 | .cache
5 | .parcel-cache
6 | dist
7 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2021 Benjamin Smith
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.
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Niue
2 |
3 | ### A tiny shared state and event library for React
4 |
5 | Niue is a small library (less than **800 bytes** before compression) that provides a simple way to manage your React app's shared state and send events between components. I've used it for a while in my own projects and I find it simplifies the architecture of React apps significantly.
6 |
7 | ## Why Niue?
8 |
9 | ### State
10 | - Easily create state that's shared across components without any hierarchy
11 | - Storing application state in a single place makes it very easy to save and restore it
12 | - Simple API supports state patching and imperative state updates
13 | - Components only subscribe to the state they need
14 | - You can stop making [a bunch of React contexts](https://github.com/kobra-dev/better-react-spreadsheet/blob/main/src/state.tsx#L33) which [store return values from useState](https://github.com/kobra-dev/better-react-spreadsheet/blob/main/src/Spreadsheet.tsx#L128)
15 | - You don't need to use any provider components
16 |
17 | ### Events
18 | - You don't need to keep setting up event listeners in `useEffect`s
19 | - You don't need to remember the names of events - just import the event's hook and use it
20 | - In many cases, using events instead of a mess of callback props can greatly simplify cross-component communication
21 |
22 | ## Installation
23 |
24 | ```bash
25 | yarn add niue
26 | ```
27 |
28 | ## Managing shared state
29 |
30 | To create a store (a thing to hold an object of state), use the `createState` function outside of a component:
31 |
32 | ```ts
33 | import { createState } from 'niue';
34 |
35 | const [useStore, patchStore, getStore] = createState(
36 | // Initial value
37 | { count: 0, name: "foo" }
38 | );
39 | ```
40 |
41 | The resulting `useStore` hook can be called in your component to get the latest state value:
42 |
43 | ```tsx
44 | function Counter() {
45 | const state = useStore();
46 |
47 | return (
48 |
49 |
Hello, {state.name}!
50 | {state.count}
51 |
{state.count}
76 | );
77 | }
78 | ```
79 |
80 | The `patchStore` function can be called to update the state:
81 |
82 | ```tsx
83 | function Counter() {
84 | const state = useStore();
85 |
86 | return (
87 |
88 |
Hello, {state.name}!
89 | {state.count}
90 |
patchStore({ count: state.count + 1 })}>Increment
91 |
{
116 | download(JSON.stringify(getStore()));
117 | }}>Download
118 | ```
119 |
120 | ## Events
121 |
122 | Events work similarly to state stores. You can create an event with the createEvent function:
123 |
124 | ```ts
125 | import { createEvent } from 'niue';
126 |
127 | const [useOnEvent, emit] = createEvent();
128 | ```
129 |
130 | The `createEvent` function doesn't accept any parameters, however it does have a type parameter for the message type.
131 |
132 | The `useOnEvent` hook can be used in a component to subscribe to the event, and the `emit` function can be used to send the event:
133 |
134 | ```tsx
135 | function EventDemo() {
136 | useOnEvent((message) => {
137 | alert(`Hello, ${message}!`);
138 | }, []);
139 |
140 | return (
141 |
142 | Event demo
143 |
145 | )
146 | }
147 |
148 | function EventEmitter() {
149 | return (
150 | emit(prompt("Enter your name"))}>Send event
151 | );
152 | }
153 | ```
--------------------------------------------------------------------------------
/babel.config.json:
--------------------------------------------------------------------------------
1 | {
2 | "presets": [
3 | [
4 | "@babel/preset-env",
5 | {
6 | "targets": "> 0.5%, not dead, Firefox ESR and supports es6 and supports arrow-functions"
7 | // es6 and arrow functions form a good baseline for modern browsers
8 | }
9 | ]
10 | ]
11 | }
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "version": "0.2.0",
3 | "license": "MIT",
4 | "main": "dist/index.js",
5 | "typings": "dist/index.d.ts",
6 | "files": [
7 | "dist",
8 | "src"
9 | ],
10 | "engines": {
11 | "node": ">=10"
12 | },
13 | "scripts": {
14 | "start": "dts watch",
15 | "build": "dts build",
16 | "test": "dts test --passWithNoTests",
17 | "lint": "dts lint",
18 | "prepare": "dts build",
19 | "size": "size-limit",
20 | "analyze": "size-limit --why"
21 | },
22 | "peerDependencies": {
23 | "react": ">=16"
24 | },
25 | "husky": {
26 | "hooks": {
27 | "pre-commit": "dts lint"
28 | }
29 | },
30 | "prettier": {
31 | "printWidth": 80,
32 | "semi": true,
33 | "singleQuote": false,
34 | "trailingComma": "es5"
35 | },
36 | "name": "niue",
37 | "author": "https://github.com/Merlin04",
38 | "module": "dist/niue.esm.js",
39 | "size-limit": [
40 | {
41 | "path": "dist/niue.cjs.production.min.js",
42 | "limit": "10 KB"
43 | },
44 | {
45 | "path": "dist/niue.esm.js",
46 | "limit": "10 KB"
47 | }
48 | ],
49 | "devDependencies": {
50 | "@size-limit/preset-small-lib": "^5.0.4",
51 | "@types/react": "^17.0.22",
52 | "@types/react-dom": "^17.0.9",
53 | "dts-cli": "^0.17.1",
54 | "husky": "^7.0.2",
55 | "react": "^17.0.2",
56 | "react-dom": "^17.0.2",
57 | "size-limit": "^5.0.4",
58 | "tslib": "^2.3.1",
59 | "typescript": "^4.4.3"
60 | }
61 | }
62 |
--------------------------------------------------------------------------------
/src/events.ts:
--------------------------------------------------------------------------------
1 | import { DependencyList, useEffect } from "react";
2 |
3 | let counter: number = 0;
4 |
5 | const PREFIX = "_n";
6 |
7 | export const createEvent = (): [
8 | // Receiver
9 | (callback: (data: T) => void, deps: DependencyList) => void,
10 | // Emitter
11 | (data: T) => void
12 | ] => {
13 | const eventName = PREFIX + counter;
14 | counter++;
15 |
16 | return [
17 | (callback, deps) => {
18 | useEffect(() => {
19 | const l = (e: Event) => {
20 | callback((e as CustomEvent).detail);
21 | };
22 | document.addEventListener(eventName, l);
23 |
24 | return () => {
25 | document.removeEventListener(eventName, l);
26 | }
27 | }, deps);
28 | },
29 | (data) => {
30 | const e = new CustomEvent(eventName, {
31 | detail: data
32 | });
33 | document.dispatchEvent(e);
34 | }
35 | ]
36 | };
--------------------------------------------------------------------------------
/src/index.tsx:
--------------------------------------------------------------------------------
1 | export { createEvent } from "./events";
2 | export { createState } from "./state";
3 | export { useRerender } from "./utils";
--------------------------------------------------------------------------------
/src/state.ts:
--------------------------------------------------------------------------------
1 | import { createEvent } from "./events";
2 | import { useRerender } from "./utils";
3 |
4 | export const createState = (initialValue: T): [
5 | // Consumer hook
6 | (keys?: (keyof T)[] | null) => T,
7 | // Patcher
8 | (patch?: Partial | (keyof T)[], changed?: (keyof T)[]) => void,
9 | // Get state (not hook)
10 | () => T
11 | ] => {
12 | let db = initialValue;
13 | let trackStore = {...initialValue};
14 |
15 | const [useReceiver, emitter] = createEvent<(keyof T)[]>();
16 |
17 | return [
18 | (keys) => {
19 | if(keys !== null) {
20 | const rerender = useRerender();
21 | useReceiver((changed) => {
22 | if(!keys || changed.some(k => keys.includes(k))) {
23 | rerender();
24 | }
25 | }, []);
26 | }
27 | return db;
28 | },
29 | (patch, changed) => {
30 | if(Array.isArray(patch)) {
31 | changed = patch;
32 | patch = undefined;
33 | }
34 |
35 | if(patch) {
36 | // apply patch to db
37 | for(const prop in patch) {
38 | db[prop] = patch[prop]!;
39 | }
40 | }
41 |
42 | changed ??= (
43 | Object.entries(db)
44 | .filter(([key, val]) => val !== trackStore[key as keyof T])
45 | .map(([key]) => key)
46 | ) as (keyof T)[];
47 |
48 | // update the trackStore so we can track future changes
49 | // (notably, this won't add any imperative changes that weren't in user-provided
50 | // `changed` to the trackStore, so they can still be dispatched later)
51 | for(const prop of changed) {
52 | trackStore[prop] = db[prop];
53 | }
54 |
55 | emitter(changed);
56 | },
57 | () => db
58 | ];
59 | };
60 |
--------------------------------------------------------------------------------
/src/utils.ts:
--------------------------------------------------------------------------------
1 | import { useReducer } from "react";
2 |
3 | // https://stackoverflow.com/a/58606536
4 | export const useRerender = () => useReducer(_ => ({}), 0)[1];
--------------------------------------------------------------------------------
/testExample/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Playground
8 |
9 |
10 |
11 |
12 |
13 |
14 |
15 |
--------------------------------------------------------------------------------
/testExample/index.tsx:
--------------------------------------------------------------------------------
1 | import * as React from 'react';
2 | import * as ReactDOM from 'react-dom';
3 | import { createEvent, createState, useRerender } from '../dist';
4 |
5 | const [useStore, patchStore, getStore] = createState({ n: 0, g: 0, things: ["test"] });
6 | const [useOnEvent, emit] = createEvent();
7 |
8 | function Component1() {
9 | const state = useStore();
10 |
11 | useOnEvent(() => {
12 | alert("Hello from component 1!");
13 | }, []);
14 |
15 | return (
16 | <>
17 | patchStore({ n: state.n + 1 })}>
18 | {state.n}
19 |
20 | patchStore({ g: state.g + 1 })}>
21 | {state.g}
22 |
23 | {
24 | state.things.push("test" + state.n + state.g);
25 | state.n++;
26 | state.g++;
27 | patchStore(["things"]);
28 | patchStore();
29 | }}>
30 | Add a thing
31 |
32 | {state.things.map(thing => (
33 | {thing}
34 | ))}
35 |
36 | {
37 | alert(JSON.stringify(getStore()));
38 | }}>
39 | get store
40 |
41 | {
42 | patchStore({ n: state.n + 1, g: state.g + 1}, ["g"]);
43 | setTimeout(() => {
44 | patchStore();
45 | }, 1000);
46 | }}>
47 | Another test
48 |
49 |
50 | )
51 | }
52 |
53 | function RerenderTest() {
54 | const rerender = useRerender();
55 |
56 | alert("Rerender");
57 |
58 | return (
59 | {
60 | rerender();
61 | }}>
62 | Rerender
63 |
64 | );
65 | }
66 |
67 | const App = () => {
68 | // Only rerenders when n changes
69 | const state = useStore(["n"]);
70 | return (
71 |
72 | emit(undefined)}>Dispatch event
75 |
77 | );
78 | };
79 |
80 | ReactDOM.render(