react-synced-object v1.2.1

react-synced-object

A lightweight, efficient, and versatile package for seamless state synchronization across a React application.

Overview

• This package provides a way to create, access, and synchronize universal state across React components and classes.
• It offers a simple, user-friendly alternative to state-management libraries like redux.
• Additionally, it comes with built-in features optimized for performance.

Features

• Universal State Management: Create a SyncedObject with a unique key and access it from anywhere.
• Automated Synchronization: Manages synchronization tasks, including automatic rerendering of dependent components, integration with third-party APIs (e.g., databases), and seamless callback handling (e.g., error handling).
• Custom Debouncing: Defers multiple consecutive data changes into a single synchronization request.
• Local Storage Functionality: Provides utility functions for finding, removing, and deleting from the browser's local storage.

Interface

• SyncedObject: A data wrapper class with a custom type, options, and methods.
• initializeSyncedObject: The factory function for a SyncedObject.
• useSyncedObject: A custom React hook to interact with a SyncedObject from any component.
• getSyncedObject: A universal point of access for any SyncedObject.
• deleteSyncedObject: Safe-deletion of a SyncedObject.
• updateSyncedObject: A synchronization-aware function for modifying a SyncedObject.
• findInLocalStorage: Utility function to retrieve from local storage.
• removeInLocalStorage: Utility function to delete from local storage.

Usage

• Note: Some parameters, options, and use cases are omitted for brevity - see below for the full breakdown.

Setup

npm install react-synced-object

• react-synced-object works with any version of react with the hooks [useState, useEffect, useMemo].

Create a Synced Object

import { initializeSyncedObject } from 'react-synced-object';

const options = { defaultValue: { myProperty: "hello world" }, debounceTime: 5000 };

const myObject = initializeSyncedObject("myObject", "local", options);
// Create a synced object with key "myObject", type "local", and the specified options.

• You can initialize a synced object from anywhere - at the root of your application, in a static class, or in a component. Just make sure to initialize it before trying to access it.
• Re-initializing a synced object simply returns the existing one - thus, you can initialize multiple times without worry.

Access a Synced Object

Access a Synced Object via getter:

import { getSyncedObject } from 'react-synced-object';

const myObject = getSyncedObject("myObject");
console.log(myObject?.data.myProperty); // "hello world"

Access a Synced Object via hook:

import { useSyncedObject } from 'react-synced-object';

function MyComponent() {
  const { syncedObject } = useSyncedObject("myObject");

  return (
    <div>{syncedObject && syncedObject.data.myProperty}</div>
  );
}

Modify a Synced Object

Modify a Synced Object via setter:

import { initializeSyncedObject } from 'react-synced-object';

const myObject = initializeSyncedObject("myObject", "local", options);

myObject.data = { myProperty: "hello world", myProperty2: "hello world again!" };
myObject.modify(0);
// Set data, then handle modifications to `myObject` with a sync debounce time of 0.

Modify a Synced Object via hook:

import { useSyncedObject } from 'react-synced-object';

function MyComponent() {
  const { syncedObject } = useSyncedObject("myObject");

  return (
    <input onChange={(event) => {syncedObject.modify().myProperty = event.target.value}}>
    </input>
  );
    // Set myProperty to the input's value, then handle modifications with myObject's     debounce time of 5000 ms.
}

• The modify function immediately syncs state accross the entire application and, in this case, prepares to update local storage.
• Other parameters and specific use cases are discussed below.

Details

• Note: All interactables have JSDoc annotations with helpful information, as well.

Structure

• react-synced-object uses a static class SyncedObjectManager to manage all synced objects.
• This means that synced objects will be shared across the same JavaScript environment (such as between separate tabs or windows), and will persist until page reload.
• This package was stress-tested with an upcoming full-stack application.

SyncedObject Initialization

A SyncedObject is a wrapper class for data. Every instance must be initialized through initializeSyncedObject with a key, type, and (optional) options.

key: Any unique identifier, usually a string.

type: Either "temp", "local", or "custom".

options: An optional object parameter with several properties.

SyncedObject Runtime Properties

A SyncedObject has several runtime properties and methods which provide useful behavior.

SyncedObject.data (property)

• This is where the information payload is stored. Access it as a normal property, change it as needed, and then call the below:

SyncedObject.modify (method)

• This is a function to signify that a change was made to SyncedObject data.
• It immediately updates state accross the entire application, while preparing to sync to external sources (in the case of local and custom objects).
• Additionally, it returns SyncedObject.data, allowing us to chain property modifications with the function call itself.

SyncedObject.changelog (property)

• This array keeps track of property names modified using modify(propertyName). It is automaticaly populated and cleared upon a successful push. Accessible directly from the SyncedObject, this property can prove useful in custom sync functions and callbacks.

SyncedObject.state (property)

• An object with two properties: success and error, tracking the status of the last sync.

useSyncedObject

• useSyncedObject is an easy-to-use hook for interacting with an initialized SyncedObject from any component.
• Traditional approaches to updating component state, such as prop chaining or Context, can lead to rerendering issues, especially when dealing with complex, nested data objects. This is due to React's shallow comparison method, which often results in either unsuccessful or unnecessary rerenders.
• In contrast, useSyncedObject establishes direct dependencies to specific SyncedObject properties using event listeners, resulting in highly accurate and performant component updates.

  const options = {dependencies: ["modify"], properties: ["myProperty"]};

  const { syncedObject, syncedData, 
  syncedSuccess, syncedError, modify } = useSyncedObject("myObject", options);
  // This component will rerender when property `myProperty` of "myObject" is modified.

Options

• You can specify exactly when a component should rerender, through a combination of dependent events and property names.

options.dependencies

• The conditions in which component should rerender itself. Leave undefined for the default (all events), set equal to exactly one event, or set equal to an array of events.

options.properties

• Upon modify or modify_external, the affected properties for which a component should rerender itself. Leave undefined or set as [""] for the default (all properties), set equal to exactly one property, or set equal to an array of properties.

• Note that in order for a rerender to occur, both the dependencies and properties must be satisfied.

options.safeMode

• Similar to the safeMode option from initializeSyncedObject - default is true in development, false in production.

Return Bundle

• Most of useSyncedObject returns are aliases to SyncedObject properties. However, modify has a special use case.

Other Utility Functions

findInLocalStorage(keyPattern, returnType = "key")

const myKeys = findInLocalStorage(\myObject\);
console.log(myKeys); // ['myObject1', 'myObject2']

• findInLocalStorage will search in local storage for an exact string match or regex pattern, and return an array of keys (returnType = "key") or data objects (returnType = "data").

removeFromLocalStorage(keyPattern, affectedObjects = "ignore")

const deletedKeys = removeFromLocalStorage(\myObject\);
console.log(deletedKeys); // ['myObject1', 'myObject2']

• removeFromLocalStorage will also search in local storage, deleting any matches, and handling any affected objects.
  • affectedObjects = ignore: Does not delete the objects - they may re-push their data to local storage again.
  • affectedObjects = decouple: The affected objects will be decoupled from local storage, turning into temp objects.
  • affectedObjects = delete: The affected objects will be deleted from the manager.

deleteSyncedObject(key)

deleteSyncedObject("myObject");

• deleteSyncedObject deletes an initialized SyncedObject with the given key from the manager. It also updates dependent components and prevents further modify calls.
• Be wary when deleting an SyncedObject initialized inside a component - it could be reinitialized.

updateSyncedObject(key, updater)

const myObject = initializeSyncedObject("myObject", "custom", {
  customSyncFunctions: { pull: fetchFromDatabase } });

const myUpdatedObject = await updateSyncedObject("myObject", { 
  prop1: "new value", prop2: "new value2" }); // Executes once `myObject` completes initial pull.

console.log(myObject.data.prop1); // "new value"
console.log(myObject.state.success); // true

• updateSyncedObject updates the data of an initialized SyncedObject with the given key, returning the newly modified object after attempted synchronization.
• Used when the order of modification matters - updateSyncedObject waits until after existing sync requests finish, eliminating race conditions and ensuring access to the most recent data.
• Provides the resulting state for use in error-sensitive standalone function calls.
• updater: If an object, overwrites the specified properties of SyncedObject.data with the provided values. If a non-object, overwrites the SyncedObject.data field itself.

Outro

• Feel free to comment or bug report here.
• Happy Coding!