154 | );
155 | },
156 | () => true
157 | );
158 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # React Signify
2 |
3 | 
4 |
5 | # Introduction
6 |
7 | React Signify is a simple library that provides features for managing and updating global state efficiently. It is particularly useful in React applications for managing state and auto-syncing when their values change.
8 | Advantages of the library:
9 |
10 | - Lightweight library
11 | - Simple syntax
12 | - Supports effective re-render control
13 |
14 | # Project information
15 |
16 | - Git: https://github.com/VietCPQ94/react-signify
17 | - NPM: [https://www.npmjs.com/package/react-signify](https://www.npmjs.com/package/react-signify)
18 |
19 | # Installation
20 |
21 | React Signify is available as a package on NPM for use with React applications:
22 |
23 | ```
24 | # NPM
25 | npm install react-signify
26 |
27 | # Yarn
28 | yarn add react-signify
29 | ```
30 |
31 | # Overview
32 |
33 | ## Initialize
34 |
35 | You can initialize Signify in any file, please refer to the following example
36 |
37 | ```tsx
38 | import { signify } from 'react-signify';
39 |
40 | const sCount = signify(0);
41 | ```
42 |
43 | Here we create a variable `sCount` with an initial value of `0`.
44 |
45 | ## Used in many places
46 |
47 | The usage is simple with the export/import tool of the module.
48 | File Store.js (export Signify)
49 |
50 | ```tsx
51 | import { signify } from 'react-signify';
52 |
53 | export const sCount = signify(0);
54 | ```
55 |
56 | Component A (import Signify)
57 |
58 | ```tsx
59 | import { sCount } from './store';
60 |
61 | export default function ComponentA() {
62 | const countValue = sCount.use();
63 | const handleUp = () => {
64 | sCount.set(pre => {
65 | pre.value += 1;
66 | });
67 | };
68 |
69 | return (
70 |
71 |
{countValue}
72 |
73 |
74 | );
75 | }
76 | ```
77 |
78 | From here we can see the flexibility of Signify, simple declaration, usable everywhere.
79 |
80 | ## Basic features
81 |
82 | ### Display on the interface
83 |
84 | We will use the `html` attribute to display the value as a `string` or `number` on the interface.
85 |
86 | ```tsx
87 | import { signify } from 'react-signify';
88 |
89 | const sCount = signify(0);
90 |
91 | export default function App() {
92 | return (
93 |
195 |
196 | );
197 | }
198 |
--------------------------------------------------------------------------------
/src/package/signify-core/index.ts:
--------------------------------------------------------------------------------
1 | import { syncSystem } from '../signify-sync';
2 | import { cacheUpdateValue, getInitialValue } from '../signify-cache';
3 | import { deepClone } from '../utils/objectClone';
4 | import { deepCompare } from '../utils/objectCompare';
5 | import { HardWrapCore, WrapCore, htmlCore, subscribeCore, useCore, watchCore } from './signify.core';
6 | import { TConditionRendering, TConditionUpdate as TConditionUpdating, TListeners, TOmitHtml, TSetterCallback, TSignifyConfig, TUseValueCb } from './signify.model';
7 |
8 | /**
9 | * Signify class for managing a reactive state in a React environment.
10 | *
11 | * This class encapsulates the state management logic, providing features such
12 | * as synchronization with external systems, conditional updates and rendering,
13 | * and various utilities to interact with the state.
14 | *
15 | * @template T - Type of the state value.
16 | */
17 | class Signify {
18 | #isRender = true; // Indicates whether the component should re-render.
19 | #initialValue: T; // Stores the initial value of the state.
20 | #value: T; // Current value of the state.
21 | #config?: TSignifyConfig; // Configuration options for Signify.
22 | #listeners: TListeners = new Set(); // Listeners for state changes.
23 | #coreListeners: TListeners = new Set(); // Listeners for state changes which check every change of state1.
24 | #syncSetter?: TUseValueCb; // Function to synchronize state externally.
25 | #conditionUpdating?: TConditionUpdating; // Condition for updating the state.
26 | #conditionRendering?: TConditionRendering; // Condition for rendering.
27 |
28 | /**
29 | * Constructor to initialize the Signify instance with an initial value and optional configuration.
30 | *
31 | * @param initialValue - The initial value of the state.
32 | * @param config - Optional configuration settings for state management.
33 | */
34 | constructor(initialValue: T, config?: TSignifyConfig) {
35 | this.#initialValue = initialValue; // set initial value.
36 | this.#value = getInitialValue(deepClone(initialValue), config?.cache); // Get initial value considering caching.
37 | this.#config = config;
38 |
39 | // If synchronization is enabled, setup the sync system.
40 | if (config?.syncKey) {
41 | const { post, sync } = syncSystem({
42 | key: config.syncKey,
43 | cb: data => {
44 | this.#value = data; // Update local state with synchronized value.
45 | cacheUpdateValue(this.value, this.#config?.cache); // Update cache with new value.
46 | this.#inform(); // Notify listeners about the state change.
47 | }
48 | });
49 |
50 | this.#syncSetter = post; // Assign the sync setter function.
51 |
52 | sync(() => this.value); // Sync on value changes.
53 | }
54 | }
55 |
56 | /**
57 | * Inform all listeners about the current value if rendering is allowed.
58 | */
59 | #inform = (isEnableCore = true) => {
60 | if (this.#isRender && (!this.#conditionRendering || this.#conditionRendering(this.value))) {
61 | this.#listeners.forEach(listener => listener(this.value)); // Notify each listener with the current value.
62 | }
63 |
64 | isEnableCore && this.#coreListeners.forEach(listener => listener(this.value));
65 | };
66 |
67 | /**
68 | * Force update the current state and inform listeners of the change.
69 | *
70 | * @param value - New value to set.
71 | */
72 | #forceUpdate = (value?: T) => {
73 | if (value !== undefined) {
74 | this.#value = value; // Update current value.
75 | }
76 | cacheUpdateValue(this.value, this.#config?.cache); // Update cache if applicable.
77 | this.#syncSetter?.(this.value); // Synchronize with external system if applicable.
78 | this.#inform(); // Notify listeners about the new value.
79 | };
80 |
81 | /**
82 | * Getter for obtaining the current value of the state.
83 | */
84 | get value(): T {
85 | return this.#value;
86 | }
87 |
88 | /**
89 | * Setter function to update the state. Can take a new value or a callback function which use to update value directly.
90 | *
91 | * @param v - New value or a callback to compute the new value based on current state.
92 | */
93 | readonly set = (v: T | TSetterCallback, isForceUpdate = false) => {
94 | let tempVal: T;
95 |
96 | if (typeof v === 'function') {
97 | let params = { value: isForceUpdate ? this.#value : deepClone(this.#value) };
98 | (v as TSetterCallback)(params); // Determine new value.
99 | tempVal = params.value;
100 | } else {
101 | tempVal = v; // Determine new value.
102 | }
103 |
104 | // Check if the new value is different and meets update conditions before updating.
105 | if (isForceUpdate || (!deepCompare(this.value, tempVal) && (!this.#conditionUpdating || this.#conditionUpdating(this.value, tempVal)))) {
106 | this.#forceUpdate(tempVal); // Perform forced update if conditions are satisfied.
107 | }
108 | };
109 |
110 | /**
111 | * Stops rendering updates for this instance.
112 | */
113 | readonly stop = () => {
114 | this.#isRender = false; // Disable rendering updates.
115 | };
116 |
117 | /**
118 | * Resumes rendering updates for this instance.
119 | */
120 | readonly resume = () => {
121 | this.#isRender = true; // Enable rendering updates.
122 | this.#inform(false); // Notify listeners of any current value changes.
123 | };
124 |
125 | /**
126 | * Resets the state back to its initial value.
127 | */
128 | readonly reset = () => {
129 | this.#forceUpdate(deepClone(this.#initialValue)); // Reset to initial value.
130 | };
131 |
132 | /**
133 | * Sets a condition for updating the state. The callback receives previous and new values and returns a boolean indicating whether to update.
134 | *
135 | * @param cb - Callback function for determining update conditions.
136 | */
137 | readonly conditionUpdating = (cb: TConditionUpdating) => (this.#conditionUpdating = cb);
138 |
139 | /**
140 | * Sets a condition for rendering. The callback receives the current value and returns a boolean indicating whether to render.
141 | *
142 | * @param cb - Callback function for determining render conditions.
143 | */
144 | readonly conditionRendering = (cb: TConditionRendering) => (this.#conditionRendering = cb);
145 |
146 | /**
147 | * Function to use the current value in components. This provides reactivity to component updates based on state changes.
148 | */
149 | readonly use = useCore(this.#listeners, () => this.value);
150 |
151 | /**
152 | * Function to watch changes on state and notify listeners accordingly.
153 | */
154 | readonly watch = watchCore(this.#coreListeners);
155 |
156 | /**
157 | * Function to subscribe to state changes and notify listeners accordingly.
158 | */
159 | readonly subscribe = subscribeCore(this.#coreListeners);
160 |
161 | /**
162 | * Generates HTML output from the use function to render dynamic content based on current state.
163 | */
164 | readonly html = htmlCore(this.use);
165 |
166 | /**
167 | * A wrapper component that allows for rendering based on current state while managing reactivity efficiently.
168 | */
169 | readonly Wrap = WrapCore(this.use);
170 |
171 | /**
172 | * A hard wrapper component that provides additional control over rendering and avoids unnecessary re-renders in parent components.
173 | */
174 | readonly HardWrap = HardWrapCore(this.use);
175 |
176 | /**
177 | * Creates a sliced version of the state by applying a function to derive a part of the current value.
178 | *
179 | * @param pick - Function that extracts a portion of the current value.
180 | */
181 | readonly slice =
(pick: (v: T) => P) => {
182 | let _value: P = pick(this.value), // Extracted portion of the current state.
183 | _isRender = true, // Flag to manage rendering for sliced values.
184 | _conditionRendering: TConditionRendering