@rljson/server 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rljson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.architecture.md

@@ -0,0 +1,9 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Architecture

package/README.blog.md

@@ -0,0 +1,11 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Blog
+
+Add latest posts at the end.

package/README.contributors.md

@@ -0,0 +1,32 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Contributors Guide
+
+- [Prepare](#prepare)
+- [Develop](#develop)
+- [Administrate](#administrate)
+- [Fast Coding](#fast-coding)
+
+## Prepare
+
+Read [prepare.md](doc/prepare.md)
+
+<!-- ........................................................................-->
+
+## Develop
+
+Read [develop.md](doc/develop.md)
+
+## Administrate
+
+Read [create-new-repo.md](doc/create-new-repo.md)
+
+## Fast Coding
+
+Read [fast-coding-guide.md](doc/fast-coding-guide.md)

package/README.md

@@ -0,0 +1,24 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# @rljson/server
+
+## Users
+
+| File                                 | Purpose                     |
+| ------------------------------------ | --------------------------- |
+| [README.public.md](README.public.md) | Install and use the package |
+
+## Contributors
+
+| File                                             | Purpose                       |
+| ------------------------------------------------ | ----------------------------- |
+| [README.contributors.md](README.contributors.md) | Run, debug, build and publish |
+| [README.architecture.md](README.architecture.md) | Software architecture guide   |
+| [README.trouble.md](README.trouble.md)           | Errors & solutions            |
+| [README.blog.md](README.blog.md)                 | Blog                          |

package/README.public.md

@@ -0,0 +1,129 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# @rljson/server
+
+@rljson/server provides a lightweight client/server layer for Rljson storage. It wires Io (row/table data) and Bs (blob storage) over sockets so clients can read from server storage while still keeping their own local storage.
+
+## What it does (quick overview)
+
+- **Server** hosts Io + Bs and exposes them over sockets.
+- **Client** combines local Io/Bs with server Io/Bs into unified interfaces.
+- **Sockets** are provided by your runtime (e.g., Socket.IO) and wrapped by `SocketIoBridge`.
+
+## Install
+
+```sh
+pnpm add @rljson/server
+```
+
+## Basic usage
+
+### Server
+
+```ts
+import { BsMem } from '@rljson/bs';
+import { IoMem } from '@rljson/io';
+import { Route } from '@rljson/rljson';
+
+import { Server } from '@rljson/server';
+
+const route = Route.fromFlat('my.app.route');
+const serverIo = new IoMem();
+await serverIo.init();
+await serverIo.isReady();
+
+const serverBs = new BsMem();
+const server = new Server(route, serverIo, serverBs);
+await server.init();
+
+// When a socket connects:
+// await server.addSocket(new SocketIoBridge(serverSocket));
+```
+
+### Client
+
+```ts
+import { BsMem } from '@rljson/bs';
+import { IoMem } from '@rljson/io';
+
+import { Client } from '@rljson/server';
+
+const localIo = new IoMem();
+await localIo.init();
+await localIo.isReady();
+
+const localBs = new BsMem();
+
+const client = new Client(new SocketIoBridge(clientSocket), localIo, localBs);
+await client.init();
+
+// Unified interfaces
+const io = client.io;
+const bs = client.bs;
+```
+
+## How the layering works
+
+Both client and server use a **multi-layer** approach:
+
+- **Local layer** (priority 1): always read/write to local Io/Bs
+- **Peer layer** (priority 2): read-only from server Io/Bs
+
+This is implemented with `IoMulti` and `BsMulti` internally, but the public API exposes them as `Io` and `Bs`.
+
+## API highlights
+
+### Client
+
+- `init()` – builds Io/Bs multis and starts peer bridges
+- `ready()` – resolves once Io is ready
+- `tearDown()` – closes and clears local state
+- `io` – Io interface (multi-layer)
+- `bs` – Bs interface (multi-layer)
+
+### Server
+
+- `init()` – initializes server multis
+- `ready()` – resolves when Io is ready
+- `addSocket(socket)` – registers a client socket and refreshes multis
+- `io` – Io interface used by server
+- `bs` – Bs interface used by server
+
+## Example
+
+[src/example.ts](src/example.ts)
+
+## Deeper dive
+
+### Networking flow
+
+1. **Client connects** using your socket runtime.
+2. **Server registers** the socket with `addSocket()`.
+3. **IoPeerBridge** allows the server to pull from client local Io (upstream).
+4. **IoPeer** allows the client to pull from server Io (downstream).
+5. `IoMulti` merges these layers into a single Io interface.
+
+The same pattern is used for Bs (blob storage).
+
+### Consistency model
+
+- Local writes are immediate.
+- Server data is read-only from the client perspective.
+- Multi-layer priority ensures local data always wins.
+
+### When to use this package
+
+- You want **local-first** data access with server-backed reads.
+- You want **Io and Bs** to share a consistent socket layer.
+- You want a single abstraction for both **in-memory** and **networked** access.
+
+## Notes
+
+- `Client.io` and `Client.bs` are already merged interfaces. No need to access multis directly.
+- `Server.addSocket()` batches refreshes to reduce rebuild overhead when multiple sockets connect.

package/README.trouble.md

@@ -0,0 +1,23 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Trouble shooting
+
+## Table of contents <!-- omit in toc -->
+
+- [Vscode Windows: Debugging is not working](#vscode-windows-debugging-is-not-working)
+
+## Vscode Windows: Debugging is not working
+
+Date: 2025-03-08
+
+⚠️ IMPORTANT: On Windows, please check out the repo on drive C. There is a bug
+in the VS Code Vitest extension (v1.14.4), which prevents test debugging from
+working: <https://github.com/vitest-dev/vscode/issues/548> Please check from
+time to time if the issue has been fixed and remove this note once it is
+resolved.

package/dist/README.architecture.md

@@ -0,0 +1,9 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Architecture

package/dist/README.blog.md

@@ -0,0 +1,11 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Blog
+
+Add latest posts at the end.

package/dist/README.contributors.md

@@ -0,0 +1,32 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Contributors Guide
+
+- [Prepare](#prepare)
+- [Develop](#develop)
+- [Administrate](#administrate)
+- [Fast Coding](#fast-coding)
+
+## Prepare
+
+Read [prepare.md](doc/prepare.md)
+
+<!-- ........................................................................-->
+
+## Develop
+
+Read [develop.md](doc/develop.md)
+
+## Administrate
+
+Read [create-new-repo.md](doc/create-new-repo.md)
+
+## Fast Coding
+
+Read [fast-coding-guide.md](doc/fast-coding-guide.md)

package/dist/README.md

@@ -0,0 +1,24 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# @rljson/server
+
+## Users
+
+| File                                 | Purpose                     |
+| ------------------------------------ | --------------------------- |
+| [README.public.md](README.public.md) | Install and use the package |
+
+## Contributors
+
+| File                                             | Purpose                       |
+| ------------------------------------------------ | ----------------------------- |
+| [README.contributors.md](README.contributors.md) | Run, debug, build and publish |
+| [README.architecture.md](README.architecture.md) | Software architecture guide   |
+| [README.trouble.md](README.trouble.md)           | Errors & solutions            |
+| [README.blog.md](README.blog.md)                 | Blog                          |

package/dist/README.public.md

@@ -0,0 +1,129 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# @rljson/server
+
+@rljson/server provides a lightweight client/server layer for Rljson storage. It wires Io (row/table data) and Bs (blob storage) over sockets so clients can read from server storage while still keeping their own local storage.
+
+## What it does (quick overview)
+
+- **Server** hosts Io + Bs and exposes them over sockets.
+- **Client** combines local Io/Bs with server Io/Bs into unified interfaces.
+- **Sockets** are provided by your runtime (e.g., Socket.IO) and wrapped by `SocketIoBridge`.
+
+## Install
+
+```sh
+pnpm add @rljson/server
+```
+
+## Basic usage
+
+### Server
+
+```ts
+import { BsMem } from '@rljson/bs';
+import { IoMem } from '@rljson/io';
+import { Route } from '@rljson/rljson';
+
+import { Server } from '@rljson/server';
+
+const route = Route.fromFlat('my.app.route');
+const serverIo = new IoMem();
+await serverIo.init();
+await serverIo.isReady();
+
+const serverBs = new BsMem();
+const server = new Server(route, serverIo, serverBs);
+await server.init();
+
+// When a socket connects:
+// await server.addSocket(new SocketIoBridge(serverSocket));
+```
+
+### Client
+
+```ts
+import { BsMem } from '@rljson/bs';
+import { IoMem } from '@rljson/io';
+
+import { Client } from '@rljson/server';
+
+const localIo = new IoMem();
+await localIo.init();
+await localIo.isReady();
+
+const localBs = new BsMem();
+
+const client = new Client(new SocketIoBridge(clientSocket), localIo, localBs);
+await client.init();
+
+// Unified interfaces
+const io = client.io;
+const bs = client.bs;
+```
+
+## How the layering works
+
+Both client and server use a **multi-layer** approach:
+
+- **Local layer** (priority 1): always read/write to local Io/Bs
+- **Peer layer** (priority 2): read-only from server Io/Bs
+
+This is implemented with `IoMulti` and `BsMulti` internally, but the public API exposes them as `Io` and `Bs`.
+
+## API highlights
+
+### Client
+
+- `init()` – builds Io/Bs multis and starts peer bridges
+- `ready()` – resolves once Io is ready
+- `tearDown()` – closes and clears local state
+- `io` – Io interface (multi-layer)
+- `bs` – Bs interface (multi-layer)
+
+### Server
+
+- `init()` – initializes server multis
+- `ready()` – resolves when Io is ready
+- `addSocket(socket)` – registers a client socket and refreshes multis
+- `io` – Io interface used by server
+- `bs` – Bs interface used by server
+
+## Example
+
+[src/example.ts](src/example.ts)
+
+## Deeper dive
+
+### Networking flow
+
+1. **Client connects** using your socket runtime.
+2. **Server registers** the socket with `addSocket()`.
+3. **IoPeerBridge** allows the server to pull from client local Io (upstream).
+4. **IoPeer** allows the client to pull from server Io (downstream).
+5. `IoMulti` merges these layers into a single Io interface.
+
+The same pattern is used for Bs (blob storage).
+
+### Consistency model
+
+- Local writes are immediate.
+- Server data is read-only from the client perspective.
+- Multi-layer priority ensures local data always wins.
+
+### When to use this package
+
+- You want **local-first** data access with server-backed reads.
+- You want **Io and Bs** to share a consistent socket layer.
+- You want a single abstraction for both **in-memory** and **networked** access.
+
+## Notes
+
+- `Client.io` and `Client.bs` are already merged interfaces. No need to access multis directly.
+- `Server.addSocket()` batches refreshes to reduce rebuild overhead when multiple sockets connect.

package/dist/README.trouble.md

@@ -0,0 +1,23 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Trouble shooting
+
+## Table of contents <!-- omit in toc -->
+
+- [Vscode Windows: Debugging is not working](#vscode-windows-debugging-is-not-working)
+
+## Vscode Windows: Debugging is not working
+
+Date: 2025-03-08
+
+⚠️ IMPORTANT: On Windows, please check out the repo on drive C. There is a bug
+in the VS Code Vitest extension (v1.14.4), which prevents test debugging from
+working: <https://github.com/vitest-dev/vscode/issues/548> Please check from
+time to time if the issue has been fixed and remove this note once it is
+resolved.

package/dist/base-node.d.ts

@@ -0,0 +1,22 @@
+import { Io } from '@rljson/io';
+import { Rljson, TableCfg } from '@rljson/rljson';
+export declare abstract class BaseNode {
+    protected _localIo: Io;
+    private _localDb;
+    constructor(_localIo: Io);
+    /**
+     *  Creates tables in the local Db.
+     * @param cfgs - Table configurations
+     * @param cfgs.withInsertHistory - TableCfgs for tables with InsertHistory
+     * @param cfgs.withoutInsertHistory - TableCfgs for tables without InsertHistory
+     */
+    createTables(cfgs: {
+        withInsertHistory?: TableCfg[];
+        withoutInsertHistory?: TableCfg[];
+    }): Promise<void>;
+    /**
+     * Imports Rljson data into the local Db.
+     * @param data - Rljson data to import
+     */
+    import(data: Rljson): Promise<void>;
+}

package/dist/client.d.ts

@@ -0,0 +1,56 @@
+import { Bs } from '@rljson/bs';
+import { Io, IoMulti, Socket } from '@rljson/io';
+import { BaseNode } from './base-node.ts';
+export declare class Client extends BaseNode {
+    private _socketToServer;
+    protected _localIo: Io;
+    protected _localBs: Bs;
+    private _ioMultiIos;
+    private _ioMulti?;
+    private _bsMultiBss;
+    private _bsMulti?;
+    /**
+     * Creates a Client instance
+     * @param _socketToServer - Socket to connect to server
+     * @param _localIo - Local Io for local storage
+     * @param _localBs - Local Bs for local blob storage
+     */
+    constructor(_socketToServer: Socket, _localIo: Io, _localBs: Bs);
+    /**
+     * Initializes Io and Bs multis and their peer bridges.
+     * @returns The initialized Io implementation.
+     */
+    init(): Promise<IoMulti | undefined>;
+    /**
+     * Resolves once the Io implementation is ready.
+     */
+    ready(): Promise<void>;
+    /**
+     * Closes client resources and clears internal state.
+     */
+    tearDown(): Promise<void>;
+    /**
+     * Returns the Io implementation.
+     */
+    get io(): Io | undefined;
+    /**
+     * Returns the Bs implementation.
+     */
+    get bs(): Bs | undefined;
+    /**
+     * Builds the Io multi with local and peer layers.
+     */
+    private _setupIo;
+    /**
+     * Builds the Bs multi with local and peer layers.
+     */
+    private _setupBs;
+    /**
+     * Creates and initializes a downstream Io peer.
+     */
+    private _createIoPeer;
+    /**
+     * Creates and initializes a downstream Bs peer.
+     */
+    private _createBsPeer;
+}

package/dist/example.d.ts

@@ -0,0 +1 @@
+export declare const example: () => Promise<void>;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Client } from './client.ts';
+export { Server } from './server.ts';
+export { SocketIoBridge } from './socket-io-bridge.ts';

package/dist/server.d.ts

@@ -0,0 +1,104 @@
+import { Bs, BsPeer } from '@rljson/bs';
+import { Io, IoPeer, Socket } from '@rljson/io';
+import { Route } from '@rljson/rljson';
+import { BaseNode } from './base-node.ts';
+export type SocketWithClientId = Socket & {
+    __clientId?: string;
+};
+export declare class Server extends BaseNode {
+    private _route;
+    protected _localIo: Io;
+    protected _localBs: Bs;
+    private _clients;
+    private _ios;
+    private _ioMulti;
+    private _ioServer;
+    private _bss;
+    private _bsMulti;
+    private _bsServer;
+    private _multicastedRefs;
+    private _refreshPromise?;
+    private _pendingSockets;
+    constructor(_route: Route, _localIo: Io, _localBs: Bs);
+    /**
+     * Initializes Io and Bs multis on the server.
+     */
+    init(): Promise<void>;
+    /**
+     * Resolves once the Io implementation is ready.
+     */
+    ready(): Promise<void>;
+    /**
+     * Adds a client socket, rebuilds multis, and refreshes servers.
+     * @param socket - Client socket to register.
+     * @returns The server instance.
+     */
+    addSocket(socket: Socket): Promise<this>;
+    /**
+     * Removes all listeners from all connected clients.
+     */
+    private _removeAllListeners;
+    /**
+     * Broadcasts incoming payloads from any client to all other connected clients.
+     */
+    private _multicastRefs;
+    get route(): Route;
+    /**
+     * Returns the Io implementation.
+     */
+    get io(): Io;
+    /**
+     * Returns the Bs implementation.
+     */
+    get bs(): Bs;
+    /**
+     * Returns the connected clients map.
+     */
+    get clients(): Map<string, {
+        socket: SocketWithClientId;
+        io: IoPeer;
+        bs: BsPeer;
+    }>;
+    /**
+     * Creates and initializes a downstream Io peer for a socket.
+     * @param socket - Client socket to bind the peer to.
+     */
+    private _createIoPeer;
+    /**
+     * Creates and initializes a downstream Bs peer for a socket.
+     * @param socket - Client socket to bind the peer to.
+     */
+    private _createBsPeer;
+    /**
+     * Registers the client socket and peers.
+     * @param clientId - Stable client identifier.
+     * @param socket - Client socket to register.
+     * @param io - Io peer associated with the client.
+     * @param bs - Bs peer associated with the client.
+     */
+    private _registerClient;
+    /**
+     * Queues an Io peer for inclusion in the Io multi.
+     * @param ioPeer - Io peer to add.
+     */
+    private _queueIoPeer;
+    /**
+     * Queues a Bs peer for inclusion in the Bs multi.
+     * @param bsPeer - Bs peer to add.
+     */
+    private _queueBsPeer;
+    /**
+     * Rebuilds Io and Bs multis from queued peers.
+     */
+    private _rebuildMultis;
+    /**
+     * Recreates servers and reattaches sockets.
+     */
+    private _refreshServers;
+    /**
+     * Batches multi/server refreshes into a single queued task.
+     */
+    private _queueRefresh;
+    /** Example instance for test purposes */
+    static example(): Promise<Server>;
+}