@rljson/io 0.0.69 → 0.0.71

package/README.architecture.md

@@ -18,7 +18,7 @@ found in the LICENSE file in the root of this package.
 
 The central abstraction that defines all database operations:
 
-```
+```text
 ┌─────────────────────────────────────────────┐
 │              Io Interface                   │
 ├─────────────────────────────────────────────┤
@@ -42,7 +42,7 @@ The central abstraction that defines all database operations:
 
 In-memory implementation using JavaScript objects.
 
-```
+```text
 ┌─────────────────────┐
 │      IoMem          │
 ├─────────────────────┤
@@ -61,6 +61,21 @@ In-memory implementation using JavaScript objects.
 - Uses `@rljson/hash` for data hashing and identity
 - `IsReady` pattern for initialization tracking
 
+**Performance internals** (no observable API change):
+
+- Rows are indexed per table by content hash — write dedup is O(1) and
+  `readRows` with a string `_hash` in the where clause resolves through
+  the index instead of scanning the table
+- Table data is kept hash-sorted incrementally (binary-searched insert)
+  instead of re-sorting the whole table per write
+- Table and global hashes are updated lazily: writes mark tables dirty,
+  hashes are recomputed before they become observable (`dump`,
+  `dumpTable`, `createOrExtendTable`, re-`init`) — deterministic hashes
+  make the refreshed state identical to eager updates
+- The latest table configuration and column keys are cached per table
+  (updated on create/extend), so validation does not re-scan all
+  configurations per read/write
+
 **Data Structure:**
 
 ```typescript
@@ -76,7 +91,7 @@ _mem = {
 
 Remote database connection over sockets (Socket.IO compatible).
 
-```
+```text
 ┌──────────────┐         Socket          ┌──────────────┐
 │   IoPeer     │◄───────────────────────►│ IoPeerBridge │
 │  (Client)    │     Events/Acks         │   (Server)   │
@@ -107,7 +122,7 @@ Remote database connection over sockets (Socket.IO compatible).
 
 Server-side handler that bridges socket events to Io operations.
 
-```
+```text
 ┌─────────────────────────────────────┐
 │        IoPeerBridge                 │
 ├─────────────────────────────────────┤
@@ -132,7 +147,7 @@ Server-side handler that bridges socket events to Io operations.
 
 Aggregates multiple Io instances with priority-based cascading.
 
-```
+```text
 ┌────────────────────────────────────────────┐
 │             IoMulti                        │
 ├────────────────────────────────────────────┤
@@ -182,7 +197,7 @@ IoMultiIo {
 
 Provides name mapping between different table name formats.
 
-```
+```text
 ┌──────────────────────────────────────┐
 │     IoDbNameMapping                  │
 ├──────────────────────────────────────┤
@@ -202,7 +217,7 @@ Provides name mapping between different table name formats.
 
 Server implementation that combines Socket.IO with Io backends.
 
-```
+```text
 ┌─────────────────────────────────────┐
 │         IoServer                    │
 ├─────────────────────────────────────┤
@@ -230,7 +245,7 @@ Server implementation that combines Socket.IO with Io backends.
 
 ### Write Operation
 
-```
+```text
 Client Code
     │
     ▼
@@ -248,7 +263,7 @@ io.write(data)
 
 ### Read Operation (IoMulti Cascade)
 
-```
+```text
 io.readRows({table: 'users', where: {id: 1}})
     │
     ▼
@@ -293,7 +308,7 @@ return rljson; // Only after loop completes
 
 ### Event-Based Protocol
 
-```
+```text
 Client (IoPeer)                    Server (IoPeerBridge)
       │                                    │
       ├─── emit('readRows', request) ────►│

package/README.public.md

@@ -78,6 +78,11 @@ The `Io` interface is the core abstraction that defines a standard set of operat
 - **Data Operations**: `write()`, `readRows()`, `dump()`
 - **Schema Management**: `createOrExtendTable()`, `tableExists()`, `rawTableCfgs()`
 - **Metadata**: `contentType()`, `rowCount()`, `lastUpdate()`
+- **Optional Batch Reads**: `readRowsByHashes()` — answers many content
+  hash lookups in one request. Implementations may omit it; callers must
+  fall back to `readRows()` then. `IoMem`, `IoMulti` (per-hash cascade
+  across its members) and `IoPeer`/`IoServer` (one socket round trip,
+  with automatic per-hash fallback against older remotes) support it.
 
 All implementations (in-memory, remote, multi-source) conform to this interface.
 

package/dist/README.architecture.md

@@ -18,7 +18,7 @@ found in the LICENSE file in the root of this package.
 
 The central abstraction that defines all database operations:
 
-```
+```text
 ┌─────────────────────────────────────────────┐
 │              Io Interface                   │
 ├─────────────────────────────────────────────┤
@@ -42,7 +42,7 @@ The central abstraction that defines all database operations:
 
 In-memory implementation using JavaScript objects.
 
-```
+```text
 ┌─────────────────────┐
 │      IoMem          │
 ├─────────────────────┤
@@ -61,6 +61,21 @@ In-memory implementation using JavaScript objects.
 - Uses `@rljson/hash` for data hashing and identity
 - `IsReady` pattern for initialization tracking
 
+**Performance internals** (no observable API change):
+
+- Rows are indexed per table by content hash — write dedup is O(1) and
+  `readRows` with a string `_hash` in the where clause resolves through
+  the index instead of scanning the table
+- Table data is kept hash-sorted incrementally (binary-searched insert)
+  instead of re-sorting the whole table per write
+- Table and global hashes are updated lazily: writes mark tables dirty,
+  hashes are recomputed before they become observable (`dump`,
+  `dumpTable`, `createOrExtendTable`, re-`init`) — deterministic hashes
+  make the refreshed state identical to eager updates
+- The latest table configuration and column keys are cached per table
+  (updated on create/extend), so validation does not re-scan all
+  configurations per read/write
+
 **Data Structure:**
 
 ```typescript
@@ -76,7 +91,7 @@ _mem = {
 
 Remote database connection over sockets (Socket.IO compatible).
 
-```
+```text
 ┌──────────────┐         Socket          ┌──────────────┐
 │   IoPeer     │◄───────────────────────►│ IoPeerBridge │
 │  (Client)    │     Events/Acks         │   (Server)   │
@@ -107,7 +122,7 @@ Remote database connection over sockets (Socket.IO compatible).
 
 Server-side handler that bridges socket events to Io operations.
 
-```
+```text
 ┌─────────────────────────────────────┐
 │        IoPeerBridge                 │
 ├─────────────────────────────────────┤
@@ -132,7 +147,7 @@ Server-side handler that bridges socket events to Io operations.
 
 Aggregates multiple Io instances with priority-based cascading.
 
-```
+```text
 ┌────────────────────────────────────────────┐
 │             IoMulti                        │
 ├────────────────────────────────────────────┤
@@ -182,7 +197,7 @@ IoMultiIo {
 
 Provides name mapping between different table name formats.
 
-```
+```text
 ┌──────────────────────────────────────┐
 │     IoDbNameMapping                  │
 ├──────────────────────────────────────┤
@@ -202,7 +217,7 @@ Provides name mapping between different table name formats.
 
 Server implementation that combines Socket.IO with Io backends.
 
-```
+```text
 ┌─────────────────────────────────────┐
 │         IoServer                    │
 ├─────────────────────────────────────┤
@@ -230,7 +245,7 @@ Server implementation that combines Socket.IO with Io backends.
 
 ### Write Operation
 
-```
+```text
 Client Code
     │
     ▼
@@ -248,7 +263,7 @@ io.write(data)
 
 ### Read Operation (IoMulti Cascade)
 
-```
+```text
 io.readRows({table: 'users', where: {id: 1}})
     │
     ▼
@@ -293,7 +308,7 @@ return rljson; // Only after loop completes
 
 ### Event-Based Protocol
 
-```
+```text
 Client (IoPeer)                    Server (IoPeerBridge)
       │                                    │
       ├─── emit('readRows', request) ────►│

package/dist/README.public.md

@@ -78,6 +78,11 @@ The `Io` interface is the core abstraction that defines a standard set of operat
 - **Data Operations**: `write()`, `readRows()`, `dump()`
 - **Schema Management**: `createOrExtendTable()`, `tableExists()`, `rawTableCfgs()`
 - **Metadata**: `contentType()`, `rowCount()`, `lastUpdate()`
+- **Optional Batch Reads**: `readRowsByHashes()` — answers many content
+  hash lookups in one request. Implementations may omit it; callers must
+  fall back to `readRows()` then. `IoMem`, `IoMulti` (per-hash cascade
+  across its members) and `IoPeer`/`IoServer` (one socket round trip,
+  with automatic per-hash fallback against older remotes) support it.
 
 All implementations (in-memory, remote, multi-source) conform to this interface.
 

package/dist/io-mem.d.ts

@@ -23,6 +23,10 @@ export declare class IoMem implements Io {
             [column: string]: JsonValue;
         };
     }): Promise<Rljson>;
+    readRowsByHashes(request: {
+        table: string;
+        hashes: string[];
+    }): Promise<Rljson>;
     rowCount(table: string): Promise<number>;
     write(request: {
         data: Rljson;
@@ -36,6 +40,79 @@ export declare class IoMem implements Io {
     private _isReady;
     private _isOpen;
     private _mem;
+    /**
+     * Latest table configuration per table (the one with the most
+     * columns). Kept in sync by _createTable/_extendTable so that reads
+     * and writes need no repeated scan over all configurations.
+     */
+    private readonly _latestCfgs;
+    /** Column key sets per table, derived from _latestCfgs */
+    private readonly _columnKeys;
+    /**
+     * Per-table index of rows by content hash. Rows are only ever added,
+     * never removed, so the index cannot go stale.
+     */
+    private readonly _rowIndex;
+    /**
+     * Tables whose table hash (and thus the global hash) is outdated
+     * after writes. Hashes are refreshed lazily before they become
+     * observable (dump, dumpTable, create/extend) instead of after every
+     * single write — row hashes themselves are always up to date.
+     */
+    private readonly _dirtyTableHashes;
+    /**
+     * Recomputes the hashes of all dirty tables and the global hash.
+     * Produces exactly the state an eager per-write update would have
+     * produced (hashes are deterministic over the same data).
+     */
+    private _refreshHashes;
+    /**
+     * Returns the row index of a table, building it lazily from the
+     * table data on first access.
+     * @param table - The table to index
+     */
+    private _rowIndexFor;
+    /**
+     * Inserts a row into hash-sorted table data at its sorted position —
+     * preserves the order sortTableDataAndUpdateHash establishes without
+     * a full re-sort.
+     * @param data - The hash-sorted table data
+     * @param row - The row to insert
+     */
+    private static _insertSortedByHash;
+    /**
+     * The row filter predicate of readRows. Extracted so that the indexed
+     * fast path and the full scan share identical semantics.
+     * @param row - The row to check
+     * @param where - The where clause
+     */
+    private static _rowMatchesWhere;
+    /**
+     * Returns the latest table configuration, filling the cache lazily
+     * from IoTools (which picks the config with the most columns).
+     * @param table - The table to get the configuration for
+     */
+    private _latestCfg;
+    /**
+     * Updates the cached latest configuration of a table
+     * @param cfg - The new latest configuration
+     */
+    private _setLatestCfg;
+    /**
+     * Throws when one of the given columns does not exist in the table.
+     * Mirrors IoTools.throwWhenColumnDoesNotExist but uses the cached
+     * configuration.
+     * @param table - The table to check
+     * @param columns - The columns to check
+     */
+    private _throwWhenColumnDoesNotExist;
+    /**
+     * Throws when the data does not match the table configurations.
+     * Mirrors IoTools.throwWhenTableDataDoesNotMatchCfg but uses the
+     * cached configurations.
+     * @param data - The data to validate
+     */
+    private _throwWhenTableDataDoesNotMatchCfg;
     private _init;
     private _initTableCfgs;
     private _updateGlobalHash;
@@ -48,5 +125,5 @@ export declare class IoMem implements Io {
     private _contentType;
     private _write;
     private _readRows;
-    _removeNullValues(rljson: Rljson): void;
+    _removeNullValues(rljson: Rljson): boolean;
 }

package/dist/io-multi.d.ts

@@ -112,6 +112,23 @@ export declare class IoMulti implements Io {
      * @returns A promise that resolves to the row count of the table.
      */
     rowCount(table: string): Promise<number>;
+    /**
+     * Batch read with PER-HASH cascade: every hash not found in a
+     * higher-priority readable is looked up in the next one. Readables
+     * without readRowsByHashes are queried per hash via readRows.
+     * @param request - The table and the row hashes to read
+     */
+    readRowsByHashes(request: {
+        table: string;
+        hashes: string[];
+    }): Promise<Rljson>;
+    /**
+     * Per-hash fallback for readables without readRowsByHashes.
+     * @param io - The readable io
+     * @param table - The table to read from
+     * @param hashes - The row hashes to read
+     */
+    private static _readHashesViaReadRows;
     /**
      * Gets the list of underlying readable Io instances, sorted by priority.
      */

package/dist/io-peer.d.ts

@@ -88,6 +88,21 @@ export declare class IoPeer implements Io {
             [column: string]: JsonValue | null;
         };
     }): Promise<Rljson>;
+    /**
+     * True once the remote side signalled that it does not support batch
+     * reads — all further batch reads then use per-hash readRows.
+     */
+    private _batchReadsUnsupported;
+    /**
+     * Batch read over the socket. Falls back to per-hash readRows when
+     * the remote side does not support it (older server) and remembers
+     * the capability for subsequent calls.
+     * @param request - The table and the row hashes to read
+     */
+    readRowsByHashes(request: {
+        table: string;
+        hashes: string[];
+    }): Promise<Rljson>;
     /**
      * Retrieves the number of rows in a specific table.
      * @param table The name of the table to count rows in.

package/dist/io.d.ts

@@ -50,6 +50,17 @@ export interface Io {
             [column: string]: JsonValue | null;
         };
     }): Promise<Rljson>;
+    /**
+     * Optional batch read: returns the rows matching the given content
+     * hashes in one request. Hashes without a matching row are simply
+     * absent from the result. Implementations answering many hash lookups
+     * in one round trip should provide this; callers MUST fall back to
+     * readRows when the method is not implemented.
+     */
+    readRowsByHashes?(request: {
+        table: string;
+        hashes: string[];
+    }): Promise<Rljson>;
     /** Returns the number of rows in the given table */
     rowCount(table: string): Promise<number>;
 }