DEV Community: priolo

Multilevel RAG

priolo — Wed, 26 Mar 2025 06:13:53 +0000

PREMISE

Simply breaking an entire document into regular CHUNKs has some disadvantages:

It does not allow you to incorporate all the semantics of the context because the cut can potentially occur at any point
If the information is integrated into a longer context, you lose information

In fact, for very structured topics it is preferable to use GraphRAG, which remains the best solution even if it is more complex to implement.
So I implemented this technique that I used in my project and it worked pretty well.
It has probably already been implemented (and certainly even better than what I did).

sandbox project

I KNOW it's typescript and not python! I'm used to using typescript!
The code is very simple and can be translated by eye.
However, the bulk of the work was the descriptions of the llm.

If you download it, you can run it by putting your google gemini API_KEY in .env
The demo processes a text (a tourist manual for Rome) and inserts it into the VECTOR DB:
npm run storeDB

Then you can chat to get information:
npm run chat

Or put a breakpoint and debug the selected file with the launch.json.

If you are crazy, you can also FORK by putting your API_KEY in the .env and run directly in the online sandbox.

SOLUTION

STORE the DOCUMENT on multiple levels

The idea is to ask an LLM to break the DOCUMENT into semantically coherent CHAPTERS.
These CHAPTERS are in turn divided into text BLOCKS (chunks) with the classic splitting techniques.
The BLOCKS maintain a reference to the CHAPTER from which they come.
And, finally, the BLOCKS are embedding and stored in the VECTOR DB (lancedb).

RECOVERY via QUERY

When I receive a QUERY I generate its embedding vector.
I use the VECTOR DB and obtain an array of text BLOCKS (those previously stored) semantically similar to the QUERY.
Each text BLOCK has a reference to the CHAPTER from which it was generated so I recover the relevant CHAPTERS.

This allows you to recover an entire portion of text semantically consistent with the QUERY therefore useful for the RAG.

KB CREATION

Ok I have a DOCUMENT and I want to put it into a VECTOR DB, how do I do it?
Look at this code

I basically pass the DOCUMENT to the LLM and he decides how to divide it into CHAPTERS here.
This operation is performed on many tokens (the whole document) so it can be "heavy": It must be done with a single interaction and a few tricks.

FUN FACT:
If you give an LLM (gemini-2.0-flash) a very long document and ask it to return the CHAPTERS
it could take a very long time to complete the operation
or give you an error (it gave me one) because it has to re-generate all the tokens of the document itself!

The idea is to have the LLM return only the references of where each single CHAPTER begins
This allows to reduce the length of the response to a minimum and therefore speed it up a lot.

FUN FACT:
If you ask an LLM to give you a numerical position
for example: the number of characters from the beginning of the document after which a CHAPTER begins... it will surely get it wrong!
As you know an LLM cannot count the characters correctly since it uses TOKENS.

The trick is to get the first X words of the beginning of the CHAPTER.
This does it "pretty" well.

FUN FACT:
If you ask, even with threats, an LLM to return a list ordered in a certain way, sometimes he puts it in order, sometimes "almost".

I had to implement a system to make sure I get the right chapter here

So now LLM has created the CHAPTER indexes and we have extracted them from the DOCUMENT
Then it's all very simple:

I break the CHAPTER into text BLOCKS keeping the reference to the CHAPTER
I get the embedding of the text BLOCKS
I store in the VECTOR DB code

FUN FACT:
if you want to improve much the performance of the EMBEDDING always opt for batch API calls.
GEMINI generates 100 EMBEDDING at most per API call
here

CHAT

To start the CHAT you can run
npm run chat
or launch the file runChat.ts
It is a ReAct AGENT with a TOOL to query the VECTOR DB here
The implementation of the base class "Agent" deserves a separate discussion.

The retrieval from the DB takes place here. That is:

I query the VECTOR DB for semantic similarity through the EMBEDDING of the QUERY
I retrieve a list of text BLOCKS (or even directly CHAPTERS if necessary)
Of these text BLOCKS I retrieve the CHAPTERS and assign them the distance of the "best" BLOCK
Then I obtain a list of CHAPTERS ordered by "semantic distance" from the QUERY
I enrich the prompt with the CHAPTERS found (I put the first two but it could also be three!)

WHAT ELSE COULD BE DONE

There are, in my opinion, at least two important optimizations:

When LLM splits the document into chapters it should also create an index or summary.
This would allow the agent to understand what the entire document is about.
Otherwise, when asked "what can I do in Rome?" (in the demo I used the text of a tourist guide for Rome) he should theoretically download all the knowledge.
A sub-agent should be created to handle queries to the vector database instead of the leader agent
This would allow the request to be handled without cluttering the leader agent's window

Building a Real-Time Collaborative Text Editor with Slate.js

priolo — Wed, 04 Dec 2024 23:33:15 +0000

While slate-yjs provides a solid foundation for collaborative editing with Slate.js, I found it challenging to manage updates in a way that suited my project's requirements. To address this, I decided to build a simple synchronization system tailored to my needs, offering more control and flexibility over how updates are handled.

Jess (JavaScript Easy Sync System) is a lightweight library that enables real-time synchronization of shared objects between clients and a server. While it can be used for any type of collaborative editing.

Core Concepts

Jess is built around two main classes:

ClientObjects: Maintains local copies of shared objects on the client side and handles server communication
ServerObjects: Manages the authoritative state on the server and broadcasts changes to connected clients

The library uses a command-based approach where clients send commands to modify objects, which are then synchronized across all connected clients.

Basic Example with Slate Editor

Let's build a collaborative text editor using Jess and Slate.

First, we'll set up the server:

import { ServerObjects, SlateApplicator } from '@priolo/jess';
import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 })
const server = new ServerObjects()
// Use the Slate-specific applicator
server.apply = SlateApplicator.ApplyCommands
let timeoutId: any = null

wss.on('connection', (ws) => {
    console.log('New client connected')

    server.onSend = async (client:WebSocket, message) => client.send(JSON.stringify(message))

    ws.on('message', (message) => {
        console.log(`Received message => ${message}`)

        server.receive(message.toString(), ws)

        clearTimeout(timeoutId)
        timeoutId = setTimeout(() => server.update(), 1000)
    })

    ws.on('close', () => server.disconnect(ws))
})

console.log('WebSocket server is running on ws://localhost:8080')

On the client side, we need to set up the connection and Slate editor:

import { ClientObjects, SlateApplicator } from "@priolo/jess"

// create the local repository of objects
export const clientObjects = new ClientObjects()
// apply SLATE-friendly commands
clientObjects.apply = SlateApplicator.ApplyCommands

// create the socket
const socket = new WebSocket(`ws://${window.location.hostname}:${8080}/`);
// connection to the SERVER: observe the object with id = "doc"
socket.onopen = () => clientObjects.init("doc", true)
// receiving a message from SERVER: send it to the local repository
socket.onmessage = (event) => {
    console.log("received:", event.data)
    clientObjects.receive(event.data)
}

// specific function to send messages to the SERVER (in this case using the WEB SOCKET)
clientObjects.onSend = async (messages) => socket.send(JSON.stringify(messages))

// store COMMANDs and send them when everything is calm
let idTimeout: NodeJS.Timeout
export function sendCommands (command:any) {
    clientObjects.command("doc", command)
    clearTimeout(idTimeout)
    idTimeout = setTimeout(() => clientObjects.update(), 1000)
}

Finally, integrate with Slate in your React component:

function App() {

    const editor = useMemo(() => {
        const editor = withHistory(withReact(createEditor()))
        const { apply } = editor;
        editor.apply = (operation: Operation) => {
            // synchronize everything that is NOT a selection operation
            if (!Operation.isSelectionOperation(operation)) {
                console.log("operation:", operation)
                sendCommands(operation)
            }
            apply(operation);
        }
        clientObjects.observe("doc", () => {
            const children = clientObjects.getObject("doc").valueTemp
            SlateApplicator.UpdateChildren(editor, children)
        })
        return editor
    }, [])


    return (
        <Slate
            editor={editor}
            initialValue={[{ children: [{ text: '' }] }]}
        >
            <Editable
                style={{ backgroundColor: "lightgray", width: 400, height: 400, padding: 5 }}
                renderElement={({ attributes, element, children }) =>
                    <div {...attributes}>{children}</div>
                }
                renderLeaf={({ attributes, children, leaf }) =>
                    <span {...attributes}>{children}</span>
                }
            />
        </Slate>
    )
}

export default App

How It Works

1) When a user makes changes in Slate, operations are intercepted and sent as commands to the server via Jess
2) The server applies the commands and broadcasts updates to all connected clients
3) Clients receive updates and apply them to their local Slate editors
4) Changes are batched and synchronized with a delay to improve performance

Try It Out

You can find a complete working example in the repository. Clone it and run:

# Start the server
cd examples/websocket_slate/server
npm install
npm start

# Start the client
cd examples/websocket_slate/client  
npm install
npm run dev

Open multiple browser tabs and start typing - you'll see changes sync across all instances.

Link to GitHub Repository

Synchronizing Collaborative Text Editing with Yjs and WebSockets

priolo — Sat, 16 Nov 2024 12:20:45 +0000

In this article, I almost do a copy-paste of what's found on the internet.
It's a "reminder" for my personal project
where I analyzed the use of Yjs.

SYNCHRONIZING DOCUMENTS VIA SOCKET

I foolishly use the y-websocket library.

NODEJS SERVER

Install:

npm install ws yjs y-websocket

create:
start.ts

import WebSocket from 'ws';
const utils = require("y-websocket/bin/utils")

/**
 * create a simple websocket server
 */
const wss = new WebSocket.Server({ port: 1234 })

wss.on('connection', (ws, req) => {

    // CONNECT the CLIENT to YJS documents
    // use the "room" passed in `req.url` (for example "/yjs-ws-demo")
    utils.setupWSConnection(ws, req)

    // and that's it.... these following are just logs
    console.log('CLIENT::CONNECTED')
    ws.on('message', message => console.log('CLIENT::MESSAGE', message))
    ws.on('close', () => console.log('CLIENT::DISCONNECTED'))
})

run:

npx ts-node start.ts

So the y-websocket library takes care of everything,
upon client connection, you just need to pass the websocket to the setupWSConnection method.

STORAGE

But if we shut down the server, all Yjs documents are lost.
To store them, we need to use y-leveldb.

Install:

npm install y-leveldb

add to
start.ts

import { LeveldbPersistence } from 'y-leveldb';
import * as Y from 'yjs';

const persistence = new LeveldbPersistence('./storage')

// apply DB updates to the Yjs document
persistence.getYDoc('yjs-ws-demo').then((persistedYdoc) => {
    Y.applyUpdate(ydoc, Y.encodeStateAsUpdate(persistedYdoc))
    ydoc.on('update', (update: Uint8Array) => {
        persistence.storeUpdate('yjs-ws-demo', update)
    })
})

With each update of the Yjs document, I store it in the DB.
It can be optimized by updating after a certain interval of time.
However, with the "update" event, we will always have a binary file "not in clear text"!
This interesting discussion: https://discuss.yjs.dev/t/decoding-yjs-messages/264/2
Given that Yjs is a CRDT system:
It allows distributing replicas of a document
these can be updated autonomously without a central server.
I realized that
implementing a custom storage and managing the clear text data of the "update"
could be a problem.

CLIENT SLATE

I use SLATE because these reflections are due to my current project.
Of course, SLATE has nothing to do with Yjs, it's just to give an example.
Later, I'll give an example with a textarea.

Create a ViteJs project for React and TypeScript

npm create vite@latest my-project --template react-ts

Install:

npm install yjs y-websocket @slate-yjs/core slate slate-react

Replace
App.ts

import { withYjs, withYHistory, YjsEditor } from '@slate-yjs/core';
import { useEffect, useMemo, useState } from 'react';
import { createEditor, Editor, Transforms } from 'slate';
import { Editable, Slate, withReact } from 'slate-react';
import { WebsocketProvider } from 'y-websocket';
import * as Y from 'yjs';

function App() {

    const [isOnline, setIsOnline] = useState(false)
    // get the Yjs document
    const ydoc = useMemo(() => new Y.Doc(), [])
    // get the shared data type
    const sharedType = useMemo(() => ydoc.get('content', Y.XmlText), [ydoc])
    // create the Slate editor connected to Yjs
    const editor = useMemo(() => {
        const e = withReact(withYHistory(withYjs(createEditor(), sharedType)))
        // Extend normalizeNode to avoid the document being empty
        // (at least one node must be there otherwise SLATE gets very angry)
        const { normalizeNode } = e
        e.normalizeNode = (entry) => {
            const [node] = entry
            if (!Editor.isEditor(node) || node.children.length > 0) {
                return normalizeNode(entry)
            }
            Transforms.insertNodes(editor, [{ children: [{ text: '' }] }], { at: [0] })
        }
        return e
    }, [sharedType])

    // when I have all the nice things I connect to the server with the Y-websocket provider
    useEffect(() => {
        const provider = new WebsocketProvider('ws://localhost:1234', 'yjs-ws-demo', ydoc);
        provider.on('status', ({ status }: { status: string }) => 
            setIsOnline(status == 'connected')
        )

        YjsEditor.connect(editor);

        return () => {
            YjsEditor.disconnect(editor);
            provider.destroy();
        };
    }, [editor, ydoc]);

    // and here is a bit of UI
    return <div>

        <div style={{ color: isOnline ? 'green' : 'red' }}>
            {isOnline ? 'Connected' : 'Disconnected'}
        </div>

        <Slate
            editor={editor}
            initialValue={[{ children: [{ text: '' }] }]}>
            <Editable
                renderElement={({ attributes, children, element }) => <p {...attributes}>{children}</p>}
                renderLeaf={({ attributes, children, leaf }) => <span {...attributes}>{children}</span>}
                placeholder="Enter some text..."
            />
        </Slate>
    </div>
}

export default App

WebsocketProvider connects the local Yjs doc to the websocket server with the room "yjs-ws-demo":

new WebsocketProvider('ws://localhost:1234', 'yjs-ws-demo', ydoc)

So from that moment on, the Yjs document is synchronized with the WS server.
Finally, with withYjs and withYHistory, I connect the editor to Yjs.

CLIENT TEXTAREA

And if I wanted a simple textarea?
I found the solution thanks to raine. Great professional.

Install

npm install fast-diff

Replace

App.ts

import diff from 'fast-diff';
import { useEffect, useMemo, useState } from 'react';
import { WebsocketProvider } from 'y-websocket';
import * as Y from 'yjs';

function App() {

    // get the Yjs document
    const ydoc = useMemo(() => new Y.Doc(), [])
    // get the shared data type
    const sharedType = useMemo(() => ydoc.get('content', Y.Text), [ydoc])
    // connect the shared data to a "reactive" string
    const [text, setText] = useText(sharedType)

    // on component creation, connect via websocket
    useEffect(() => {
        const provider = new WebsocketProvider('ws://localhost:1234', 'yjs-ws-demo', ydoc);
        return () => {
            provider.destroy();
        };
    }, [sharedType]);

    // and here is a bit of UI
    return <div>
        <textarea style={{ width: '100%' }} rows={5}
            value={text}
            onChange={(e) => setText(e.target.value)}
        />
    </div>
}

export default App

Next, create the custom hook useText:

/** A hook to read and set a YText value. */
function useText(ytext: Y.Text) : [string, (text: string) => void] {
    // the "reactive" string
    const [text, setText] = useState(ytext.toString())
    // every time the shared data changes, update the "reactive" string
    ytext.observe(() => setText(ytext.toString()))
    // when I change the "reactive" string, update the Yjs shared data (only the differences)
    const setYText = (textNew: string) => {
        const delta = diffToDelta(diff(text, textNew));
        ytext.applyDelta(delta);
    }
    return [text, setYText]
}
/** Convert a fast-diff result to a YJS delta. */
function diffToDelta(diffResult: [number, string][]) {
    return diffResult.map(([op, value]) => ({
        [diff.INSERT]: { insert: value },
        [diff.EQUAL]: { retain: value.length },
        [diff.DELETE]: { delete: value.length },
    }[op])).filter(Boolean);
}

We could send all the text with each change, but that would be inefficient.
So we use fast-diff to calculate the differences between the current text and the previous one.
And then we transform the differences into a delta object that Yjs understands.
The sending to the server is done by y-websocket without us having to worry about it.

CONCLUSIONS

My impression is that Yjs is fantastic!
But for my personal project, I will implement a server-coordinated system for document management.
In this way, I can manage permissions and data persistence more easily.

Also, I have the feeling that the implementation for SLATE is a bit neglected.
I plan to publish some other reminders of my project!

Bye!

ivano

SLATE Code editor with highlight

priolo — Thu, 07 Nov 2024 21:58:45 +0000

INTRODUCTION

SLATE is an excellent library for creating WYSIWYG editors in REACT, I find it superior to QUILL.

However, I had difficulties inserting editable BLOCKS with syntax highlighting for code.

Yes, there is an official example, but at least for me, it's not very clear.

Let's cut to the chase! Let's see the CODE!!!

Let's say you have an empty React project with typescript.

Install the dependencies:

npm install slate slate-react slate-history prismjs

in App.tsx

function App() {

  const editor = useMemo(() => withHistory(withReact(createEditor())), []);

  return (
    <Slate
      editor={editor}
      initialValue={[{ children: [{ text: '' }] }]}
    >
      <Editable style={{ backgroundColor: "lightgray" }}
        renderElement={({ attributes, element, children }) =>
          <div {...attributes}>{children}</div>
        }
        renderLeaf={({ attributes, children, leaf }) =>
          <span {...attributes}>{children}</span>
        }
      />
    </Slate>
  )
}

On initialization of the "App" component

I create the editor controller

and apply it to the Slate component.

Let's create the tokens for highlighting with PRISMJS

in App.tsx

... 

type BaseRangeCustom = BaseRange & { className: string }

function decorateCode([node, path]: NodeEntry) {
    const ranges: BaseRangeCustom[] = []

    // make sure it is an Slate Element
    if (!Element.isElement(node)) return ranges
    // transform the Element into a string 
    const text = Node.string(node)

    // create "tokens" with "prismjs" and put them in "ranges"
    const tokens = Prism.tokenize(text, Prism.languages.javascript);
    let start = 0;
    for (const token of tokens) {
        const length = token.length;
        const end = start + length;
        if (typeof token !== 'string') {
        ranges.push({
            anchor: { path, offset: start },
            focus: { path, offset: end },
            className: `token ${token.type}`,
        });
        }
        start = end;
    }

    // these will be found in "renderLeaf" in "leaf" and their "className" will be applied
    return ranges;
}

This function receives a SLATE Node.

I get the text of the "Node"

With the text, I create the "tokens" with PRISMJS.

I transform the "tokens" into Range.

The "Ranges" have the className property with the information for the highlight.

Finally, I apply the "Ranges" to the Slate component

I assign the function to the decorate property which is rendered with renderLeaf

still in App.tsx

...
<Editable style={{ backgroundColor: "lightgray" }}
    decorate={decorateCode}
    renderElement={({ attributes, element, children }) =>
        <div {...attributes}>{children}</div>
    }
    renderLeaf={({ attributes, children, leaf }) =>
        // here I apply the className that I calculated in "decorateCode"
        <span {...attributes} className={leaf.className}>{children}</span>
    }
/>
...

The code is here!

End.

Optimize the code

You will notice that the "decorateCode" function is called with every interaction.

Every time you press a key, it creates the tokens for all the lines!

To optimize, we use a cache.

Let's move the "decorateCode" function inside the "App" component

function App() {
    ...

    const cacheMem = useRef<{ text: string, ranges: BaseRange[] }[]>([])

    function decorateCode([node, path]: NodeEntry) {

        // CACHE **************
        const ranges: BaseRangeCustom[] = []

        // make sure it is an Slate Element
        if (!Element.isElement(node)) return ranges
        // transform the Element into a string 
        const text = Node.string(node)

        // CACHE **************
        const index = path[0]
        const cache = cacheMem.current[index]
        if (!!cache && cache.text == text) return cache.ranges
        // CACHE **************

        // create "tokens" with "prismjs" and put them in "ranges"
        const tokens = Prism.tokenize(text, Prism.languages.javascript);
        let start = 0;
        for (const token of tokens) {
        const length = token.length;
        const end = start + length;
        if (typeof token !== 'string') {
            ranges.push({
            anchor: { path, offset: start },
            focus: { path, offset: end },
            className: `token ${token.type}`,
            });
        }
        start = end;
        }

        // CACHE **************
        cacheMem.current[index] = { text, ranges }
        // CACHE **************

        // these will be found in "renderLeaf" in "leaf" and their "className" will be applied
        return ranges;
    }
}

You can find the code here!

Basically, if the Path of the Node (which is an index)

is present in the cache and the text is the same

it immediately returns the "ranges" from the cache without creating the "tokens".

Design pattern: DECK of CARDS

priolo — Mon, 29 Apr 2024 21:48:54 +0000

We're talking about managment-type web-apps.

The standard is a structure with menu and a master/detail pattern
There are many examples: G-Mail, Slack, Linear and others
However, I have often found structural limits when faced with this pattern

A new pattern: DECK-of-CARDS

old work that used the DECK-of-CARDS pattern

Generally the forms are developed vertically
and the monitors offer more than enough width.
The idea is to line up the form details next to each other like a deck of cards and eliminate the "master".

Of course, this approach has challenges (I talk about them at the end).
I implement this pattern in a very recent work that you find here:

NUI (demo)
GitHub

The first thing you see is a card on a work surface!
This represents a list of connections
We don't care what it is: let's just focus on the UI/UX.

By clicking on a connections in the list another card appears
represents a single connection.
Click on the seed of the card (lightning bolt at the top) and you can open it
and you can drag it from the title... basically that's all!

the connection card has properties (name, host, auth) and contains other cards that it can "generate"

For example:
by pressing on streams the streams list card appears
and continuing to press on a line we obtain the stream detail card and so on.
The cards can be detached from their parent-card and rearranged as you see fit.

Use cases and possibilities:

Compare two different details with each other.

I detach a card from its parent and I can generate another one side by side, making it easier to identify differences and relationships between the data. For example to compare two JSON.

Have a value that is always visible regardless of what you are doing.

While continuing to manage messages
I can always see the values present in the stream detail card.
For example, it could facilitate the work of a financial analyst who compares market data.

Easily locate items that would otherwise be hidden by the MANU/MASTER/DETAIL structure

I moved the "interesting" cards into the "drawer" so I could use them at any time.

Since the cards are "atomic" I can pin them on the menu and recall them individually at any time

Personalized work environment

I can arrange my deck of cards in order to have an overall view.
This arrangement can be stored in session and will be my usual work-space.
Also I could have different work-spaces to manage different projects.

Sharing individual information

I could share (via link) a single card
in order to give precise and limited information to that area.

Global search

With this layout it is easy to implement a search/filter that only shows the important cards.

Realtime simultaneous work

Potentially having all the CARDS visible on my work-space
I could "invite" collaborators to see or modify the cards.
This would not be possible with a classic MASTER/DETAIL pattern.

Global stocks

For example: print, destroy, send, export...
It's easy to imagine moving a card into a bin or onto a printer and so on.
These actions would be intuitive and applicable to any entity
without having to implement them for every detail.

Modular development

You just need to render your card correctly from creation to destruction.
But you can go further! You could load cards into your app from an external repository developed by others

Automate processes

Set up an action flow, for example:
"If a message arrives in this messages-card
then write it to a file (file-system-card) and display the streams-card".
That is, connect the cards to nodes with a graph scheme to automate these functions.

Challenges and possible solutions

Onboarding

Since it is a new pattern, the average user does not know how to interact "instinctively".
In fact, I would not recommend it for an occasional service such as an institutional site or a product.
However, if the user is expert and requires a fair level of complexity there are certainly notable advantages!
A solution could be the classic "tutorial" that appears on the first visit.

BACK/FOWARD buttons

the MASTER/DETAIL, using routing, has no problems with this.
For DECK-OF-CARDS it is necessary to implement a history of the positions of the cards
which is absolutely possible but more complex to achieve.

That's all.
I look forward to reading comments and any criticisms
I recommend delicacy! :)
CIAO!

A good reason to use React18: useSyncExternalStore

priolo — Fri, 07 Oct 2022 19:50:32 +0000

Let's consider a simple ToDo
This is what your colleague left you as a gift 💩 before going on holiday:

codesandbox

In index.js there is a mess of functions within components passed between components that call other functions.
And if it were a real project it would be MUCH MUCH worse

because the COMPONENT TREE is deeper
and the nesting of COMPONENTs multiplies the complexity!

Let's create a STORE

Let us try to extrapolate the LOGIC and STATUS from the COMPONENTs to put it into a STORE.

const myStore = {

    callbacks: new Set(),
    subscribe: (callback) => {
        myStore.callbacks.add(callback)
        return () => myStore.callbacks.delete(callback)
    },
    getSnapshot: () => myStore.state,
    changeState: (newState) => {
        myStore.state = newState
        myStore.callbacks.forEach( cb => cb() )
    },

}

codesandbox

It is a generic implementation of a STORE using useSyncExternalStore
the new React18 hook (but it can also be done with React17!).
therefore:

subscribe Stores a callback to be called when the STATE of the STORE is changed
getSnapshot Returns the current STATE
changeState It is convenient to exchange one STATE for another STATE. Remember that a STATE is immutable! And notify all registered callbacks of the change

Enter the STATE

const myStore = {
    ...
    state: {
        todos: [
            { desc : "init value" },
        ],
        todoInEdit: {
            desc: ""
        },
    },
    ...
}

codesandbox

It is a picture of what our VIEW, in this case the ToDo app, should look like.
A STATE represents one and only one view of the VIEW.

Enter the MUTATORS

const myStore = {
    ...
    setTodos: todos => myStore.changeState({
        ...myStore.state,
        todos
    }),
    setTodoInEditProp: prop => myStore.changeState({
        ...myStore.state,
        todoInEdit: { ...myStore.state.todoInEdit, ...prop }
    }),
    ...
}

codesandbox

They simply execute the changeState by passing it the modified STATE.
Consequently, they will notify the changes to the COMPONENTS.
(as said before)

Let's add the ACTIONS

const myStore = {
    ...
    deleteTodo: (index) => {
        const newTodos = myStore.state.todos.filter ((_,i)=>i!==index)
        myStore.setTodos(newTodos)
    },
    addTodoInEdit: () => {
        const newTodos = [...myStore.state.todos, myStore.state.todoInEdit]
        myStore.setTodos(newTodos)
        myStore.setTodoInEditProp({desc: ""}) 
    },
    ...
}

codesandbox

Let's update the VIEW

function App() {
    return (<div>
        <List />
        <Form />
    </div>);
}

function List() {
    const state = useSyncExternalStore(store.subscribe, store.getSnapshot)

    return (
        <ul>
            {state.todos.map((td, index) => (<li>
                {td.desc}
                <button onClick={_=>store.deleteTodo(index)}>
                    Delete
                </button>
            </li>))}
        </ul>
    )
}

function Form() {
    const state = useSyncExternalStore(store.subscribe, store.getSnapshot)
    const handleChange = e => store.setTodoInEditProp({desc:e.target.value})
    const handleClickAdd = _ => store.addTodoInEdit()

    return (<div>
        <input
            value={state.todoInEdit.desc}
            onChange={handleChange}
        />
        <button onClick={handleClickAdd}>Add</button>
    </div>)
}

codesandbox

The STORE is responsible for managing the LOGIC and the STATE
the VIEW simply synchronises with the STORE

The COMPONENTS are more readable

and can be moved without problems.
For example, List can be put inside another component without changing anything
because it is no longer "dependent" on its PARENT
In fact List has no properties

this also makes unit-testing easier.

In short, if I have to change the behavior I have to look at the STOREs.
If I have to change the display I will have to act on the COMPONENTS

Jon

There are many libraries in React (as usual) that allow STATE management.
Of course I made one 😃
In my opinion, compared to the others, it allows

1) to see perfectly how it works under the hood. NO MAGIC
2) is super light
3) does only this, and nothing else

If you want, check it out here