@arcaelas/whatsapp 4.5.0 → 6.0.0

package/build/cjs/lib/store/engine/lib/file_system/index.js

@@ -6,40 +6,100 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileSystemEngine = void 0;
+const node_crypto_1 = require("node:crypto");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
+const lib_1 = require("../../../../../lib/store/engine/lib");
 const INDEX_FILE = 'index.json';
-/**
- * Normaliza un path colapsando slashes redundantes.
- * Normalizes a path by collapsing redundant slashes.
- */
-function normalize_path(path) {
-    return path.replace(/\/+/g, '/').replace(/^\/|\/$/g, '');
-}
+/** Índice de orden persistido junto a los hijos del directorio. / Ordering index persisted next to the directory children. */
+const ORDER_FILE = '.order';
+/** Binario del documento, guardado crudo junto a su JSON. / Document binary, stored raw next to its JSON. */
+const BINARY_FILE = 'content.bin';
 /**
  * Driver de persistencia en sistema de archivos.
  * Cada documento se almacena como `<base>/<path>/index.json` de modo que un recurso pueda
- * coexistir con sub-recursos anidados.
+ * coexistir con sub-recursos anidados. Las escrituras son atómicas (tmp + rename) y el score
+ * de orden viaja en el mtime del archivo.
+ *
+ * Para que `list`/`count` cuesten O(limit) mantiene un índice ordenado por directorio
+ * (`SortedIndex`), acotado por LRU y respaldado en `<dir>/.order`: al abrir un directorio
+ * carga ese archivo y sólo reconstruye con `readdir` + `stat` cuando el conteo no coincide.
+ * Asume un único proceso escritor sobre el directorio base.
  *
  * Filesystem persistence driver. Each document lives at `<base>/<path>/index.json` so a
- * resource can coexist with nested sub-resources.
+ * resource can coexist with nested sub-resources. Writes are atomic (tmp + rename) and the
+ * ordering score travels in the file mtime.
+ *
+ * To keep `list`/`count` at O(limit) it maintains a per-directory sorted index
+ * (`SortedIndex`), LRU-bounded and backed by `<dir>/.order`: opening a directory loads that
+ * file and only rebuilds via `readdir` + `stat` when the count does not match. Assumes a
+ * single writer process over the base directory.
  *
  * @example
  * const engine = new FileSystemEngine('/tmp/wa');
  * await engine.set('/chat/123', JSON.stringify({ name: 'John' }));
  */
 class FileSystemEngine {
-    constructor(_base) {
+    /**
+     * @param _base - Directorio raíz del almacén / Store root directory
+     * @param cached - Directorios indexados simultáneamente en memoria / Simultaneously in-memory indexed directories
+     */
+    constructor(_base, cached = 12) {
         this._base = _base;
+        this._indexes = new lib_1.IndexCache(cached);
     }
     /** @internal */
     _dir(path) {
-        return (0, node_path_1.join)(this._base, normalize_path(path));
+        return (0, node_path_1.join)(this._base, (0, lib_1.normalize_path)(path));
     }
     /** @internal */
     _file(path) {
         return (0, node_path_1.join)(this._dir(path), INDEX_FILE);
     }
+    /**
+     * @internal
+     * Índice del directorio: lo toma de la caché, del `.order` persistido (validando el conteo
+     * contra `readdir`) o lo reconstruye leyendo el mtime de cada hijo.
+     * Directory index: taken from the cache, from the persisted `.order` (validating the count
+     * against `readdir`) or rebuilt reading each child's mtime.
+     */
+    async _index(path) {
+        const key = (0, lib_1.normalize_path)(path);
+        const cached = this._indexes.get(key);
+        if (cached) {
+            return cached;
+        }
+        const dir = (0, node_path_1.join)(this._base, key);
+        const index = new lib_1.SortedIndex(async (entries) => {
+            await this._write((0, node_path_1.join)(dir, ORDER_FILE), entries.map(([name, score]) => `${score}\t${name}`).join('\n')).catch(() => { });
+        });
+        const children = (await (0, promises_1.readdir)(dir, { withFileTypes: true }).catch(() => [])).filter((entry) => entry.isDirectory());
+        const persisted = (await (0, promises_1.readFile)((0, node_path_1.join)(dir, ORDER_FILE), 'utf-8').catch(() => null))
+            ?.split('\n')
+            .filter(Boolean)
+            .map((line) => {
+            const cut = line.indexOf('\t');
+            return [line.slice(cut + 1), Number(line.slice(0, cut))];
+        });
+        if (persisted?.length === children.length) {
+            index.load(persisted);
+        }
+        else {
+            const scanned = await Promise.all(children.map(async (entry) => {
+                const found = await (0, promises_1.stat)((0, node_path_1.join)(dir, entry.name, INDEX_FILE)).catch(() => null);
+                return found ? [entry.name, found.mtimeMs] : null;
+            }));
+            index.load(scanned.filter((entry) => entry !== null));
+        }
+        this._indexes.set(key, index);
+        return index;
+    }
+    /** @internal Escritura atómica: archivo temporal y rename sobre el destino. / Atomic write: temp file plus rename onto the target. */
+    async _write(file, value) {
+        const tmp = `${file}.${(0, node_crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+        await (0, promises_1.writeFile)(tmp, value, 'utf-8');
+        await (0, promises_1.rename)(tmp, file);
+    }
     /**
      * Lee el valor de un documento.
      * Reads a document's value.
@@ -53,13 +113,22 @@ class FileSystemEngine {
         }
     }
     /**
-     * Escribe el valor de un documento, creando los directorios necesarios.
-     * Writes a document's value, creating directories as needed.
+     * Escribe el valor de un documento de forma atómica creando los directorios necesarios;
+     * con `score` fija el mtime del archivo (y por tanto el orden de `list`).
+     * Atomically writes a document's value creating directories as needed; `score` fixes the
+     * file mtime (and therefore `list` ordering).
      */
-    async set(path, value) {
+    async set(path, value, score) {
         const dir = this._dir(path);
         await (0, promises_1.mkdir)(dir, { recursive: true });
-        await (0, promises_1.writeFile)((0, node_path_1.join)(dir, INDEX_FILE), value, 'utf-8');
+        const file = (0, node_path_1.join)(dir, INDEX_FILE);
+        await this._write(file, value);
+        const when = score ?? Date.now();
+        if (score !== undefined) {
+            await (0, promises_1.utimes)(file, new Date(score), new Date(score)).catch(() => { });
+        }
+        const { parent, name } = (0, lib_1.split_path)(path);
+        this._indexes.get(parent)?.set(name, when);
     }
     /**
      * Elimina el documento y todos sus descendientes. Idempotente.
@@ -72,70 +141,52 @@ class FileSystemEngine {
         catch {
             /* idempotent */
         }
+        const { parent, name } = (0, lib_1.split_path)(path);
+        this._indexes.get(parent)?.delete(name);
+        this._indexes.drop((0, lib_1.normalize_path)(path));
         return true;
     }
     /**
-     * Lista los valores de los hijos directos, ordenados por mtime DESC.
-     * Lists direct children values ordered by mtime DESC.
+     * Lista los valores de los hijos directos, ordenados por score DESC.
+     * Lists direct children values ordered by score DESC.
      */
     async list(path, offset = 0, limit = 50) {
         const dir = this._dir(path);
-        try {
-            const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
-            const stats = await Promise.all(entries
-                .filter((e) => e.isDirectory())
-                .map(async (entry) => {
-                const file = (0, node_path_1.join)(dir, entry.name, INDEX_FILE);
-                try {
-                    const st = await (0, promises_1.stat)(file);
-                    return { file, mtime: st.mtimeMs };
-                }
-                catch {
-                    return null;
-                }
-            }));
-            const valid = stats.filter((x) => x !== null);
-            valid.sort((a, b) => b.mtime - a.mtime);
-            const page = valid.slice(offset, offset + limit);
-            const values = await Promise.all(page.map(async ({ file }) => {
-                try {
-                    return await (0, promises_1.readFile)(file, 'utf-8');
-                }
-                catch {
-                    return null;
-                }
-            }));
-            return values.filter((value) => value !== null);
-        }
-        catch {
-            return [];
-        }
+        const page = (await this._index(path)).page(offset, limit);
+        const values = await Promise.all(page.map((name) => (0, promises_1.readFile)((0, node_path_1.join)(dir, name, INDEX_FILE), 'utf-8').catch(() => null)));
+        return values.filter((value) => value !== null);
     }
     /**
      * Cuenta los hijos directos que tienen un documento válido.
      * Counts direct children with a valid document.
      */
     async count(path) {
+        return (await this._index(path)).size;
+    }
+    /**
+     * Lee el binario del documento, o null si no existe.
+     * Reads the document binary, or null when missing.
+     */
+    async get_buffer(path) {
+        return (0, promises_1.readFile)((0, node_path_1.join)(this._dir(path), BINARY_FILE)).catch(() => null);
+    }
+    /**
+     * Escribe el binario del documento como archivo crudo, sin JSON ni base64.
+     * Writes the document binary as a raw file, with no JSON nor base64.
+     */
+    async set_buffer(path, data, score) {
         const dir = this._dir(path);
-        try {
-            const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
-            let total = 0;
-            await Promise.all(entries
-                .filter((e) => e.isDirectory())
-                .map(async (entry) => {
-                try {
-                    await (0, promises_1.stat)((0, node_path_1.join)(dir, entry.name, INDEX_FILE));
-                    total++;
-                }
-                catch {
-                    /* not a valid child doc */
-                }
-            }));
-            return total;
-        }
-        catch {
-            return 0;
+        await (0, promises_1.mkdir)(dir, { recursive: true });
+        const file = (0, node_path_1.join)(dir, BINARY_FILE);
+        const tmp = `${file}.${(0, node_crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+        await (0, promises_1.writeFile)(tmp, data);
+        await (0, promises_1.rename)(tmp, file);
+        const when = score ?? Date.now();
+        if (score !== undefined) {
+            await (0, promises_1.utimes)(file, new Date(score), new Date(score)).catch(() => { });
         }
+        const { parent, name } = (0, lib_1.split_path)(path);
+        this._indexes.get(parent)?.set(name, when);
     }
     /**
      * Vacía completamente el almacén.
@@ -148,7 +199,7 @@ class FileSystemEngine {
         catch {
             /* idempotent */
         }
+        this._indexes.clear();
     }
 }
 exports.FileSystemEngine = FileSystemEngine;
-//# sourceMappingURL=index.js.map

package/build/cjs/lib/store/engine/lib/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @file store/engine/lib/index.ts
+ * @description Utilidades compartidas por los drivers: índice ordenado por directorio,
+ * caché LRU de índices y normalización de rutas.
+ * Shared driver utilities: per-directory sorted index, LRU index cache and path normalization.
+ */
+/**
+ * @internal
+ * Índice ordenado por score DESC de los hijos de un directorio, mantenido incrementalmente:
+ * `page()` recorta sin re-ordenar y `set`/`delete` reubican una sola entrada por búsqueda
+ * binaria. Persiste su contenido con el callback `_flush`, agrupando ráfagas de escritura.
+ *
+ * Score-DESC sorted index of a directory's children, kept incrementally: `page()` slices
+ * without re-sorting and `set`/`delete` relocate a single entry via binary search. Persists
+ * through the `_flush` callback, coalescing write bursts.
+ */
+export declare class SortedIndex {
+    private readonly _flush;
+    private readonly _delay;
+    /** @internal Nombres ordenados por score DESC. / Names ordered by score DESC. */
+    private _order;
+    /** @internal Score vigente de cada nombre. / Current score per name. */
+    private _scores;
+    private _dirty;
+    private _timer;
+    /**
+     * @param _flush - Persiste el índice; recibe los pares ordenados / Persists the index; receives the ordered pairs
+     * @param _delay - Espera antes de persistir, agrupando ráfagas / Wait before persisting, coalescing bursts
+     */
+    constructor(_flush: (entries: [string, number][]) => Promise<void>, _delay?: number);
+    /** Cantidad de hijos indexados. / Indexed children count. */
+    get size(): number;
+    /** Pares `[nombre, score]` en orden DESC. / `[name, score]` pairs in DESC order. */
+    get entries(): [string, number][];
+    /**
+     * Reemplaza el índice completo con las entradas dadas, ordenándolas una sola vez.
+     * Replaces the whole index with the given entries, sorting them once.
+     */
+    load(entries: Iterable<[string, number]>): void;
+    /** Página de nombres en orden DESC, sin re-ordenar. / Page of names in DESC order, no re-sorting. */
+    page(offset: number, limit: number): string[];
+    /**
+     * Inserta o reubica un hijo con su score, manteniendo el orden.
+     * Inserts or relocates a child with its score, keeping the order.
+     */
+    set(name: string, score: number): void;
+    /**
+     * Quita un hijo del índice.
+     * Removes a child from the index.
+     */
+    delete(name: string): void;
+    /**
+     * Cancela la persistencia pendiente; se usa al descartar el índice de la caché.
+     * Cancels the pending persistence; used when dropping the index from the cache.
+     */
+    dispose(): void;
+    /** @internal Saca el nombre de la lista ordenada si estaba presente. / Detaches the name from the ordered list when present. */
+    private _detach;
+    /** @internal Primera posición cuyo score es menor o igual al dado (orden DESC). / First position whose score is lower or equal to the given one (DESC order). */
+    private _locate;
+    /** @internal Programa la persistencia diferida. / Schedules the deferred persistence. */
+    private _schedule;
+}
+/**
+ * @internal
+ * Caché LRU de índices por directorio: mantiene acotada la memoria del driver descartando
+ * el directorio menos usado cuando se supera el límite.
+ * Per-directory LRU cache of indexes: keeps driver memory bounded by dropping the
+ * least-recently-used directory once the limit is exceeded.
+ */
+export declare class IndexCache {
+    private readonly _limit;
+    private readonly _cache;
+    /** @param _limit - Directorios indexados simultáneamente / Simultaneously indexed directories */
+    constructor(_limit?: number);
+    /**
+     * Índice ya cargado del directorio, marcándolo como recién usado.
+     * Already loaded index for the directory, marking it as recently used.
+     */
+    get(key: string): SortedIndex | undefined;
+    /**
+     * Registra el índice del directorio, descartando el menos usado si se supera el límite.
+     * Registers the directory index, dropping the least used one when over the limit.
+     */
+    set(key: string, index: SortedIndex): void;
+    /**
+     * Descarta el índice del directorio y de todo su sub-árbol.
+     * Drops the directory index and its whole subtree.
+     */
+    drop(key: string): void;
+    /** Vacía la caché completa. / Clears the whole cache. */
+    clear(): void;
+}
+/**
+ * Normaliza un path colapsando slashes redundantes y recortando los extremos.
+ * Normalizes a path collapsing redundant slashes and trimming both ends.
+ *
+ * @param path - Ruta cruda / Raw path
+ * @returns Ruta normalizada / Normalized path
+ */
+export declare function normalize_path(path: string): string;
+/**
+ * Separa una ruta normalizada en directorio padre y nombre del hijo.
+ * Splits a normalized path into parent directory and child name.
+ *
+ * @param path - Ruta a separar / Path to split
+ * @returns `{ parent, name }` / `{ parent, name }`
+ */
+export declare function split_path(path: string): {
+    parent: string;
+    name: string;
+};

package/build/cjs/lib/store/engine/lib/index.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * @file store/engine/lib/index.ts
+ * @description Utilidades compartidas por los drivers: índice ordenado por directorio,
+ * caché LRU de índices y normalización de rutas.
+ * Shared driver utilities: per-directory sorted index, LRU index cache and path normalization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexCache = exports.SortedIndex = void 0;
+exports.normalize_path = normalize_path;
+exports.split_path = split_path;
+/**
+ * @internal
+ * Índice ordenado por score DESC de los hijos de un directorio, mantenido incrementalmente:
+ * `page()` recorta sin re-ordenar y `set`/`delete` reubican una sola entrada por búsqueda
+ * binaria. Persiste su contenido con el callback `_flush`, agrupando ráfagas de escritura.
+ *
+ * Score-DESC sorted index of a directory's children, kept incrementally: `page()` slices
+ * without re-sorting and `set`/`delete` relocate a single entry via binary search. Persists
+ * through the `_flush` callback, coalescing write bursts.
+ */
+class SortedIndex {
+    /**
+     * @param _flush - Persiste el índice; recibe los pares ordenados / Persists the index; receives the ordered pairs
+     * @param _delay - Espera antes de persistir, agrupando ráfagas / Wait before persisting, coalescing bursts
+     */
+    constructor(_flush, _delay = 1_000) {
+        this._flush = _flush;
+        this._delay = _delay;
+        /** @internal Nombres ordenados por score DESC. / Names ordered by score DESC. */
+        this._order = [];
+        /** @internal Score vigente de cada nombre. / Current score per name. */
+        this._scores = new Map();
+        this._dirty = false;
+        this._timer = null;
+    }
+    /** Cantidad de hijos indexados. / Indexed children count. */
+    get size() {
+        return this._order.length;
+    }
+    /** Pares `[nombre, score]` en orden DESC. / `[name, score]` pairs in DESC order. */
+    get entries() {
+        return this._order.map((name) => [name, this._scores.get(name) ?? 0]);
+    }
+    /**
+     * Reemplaza el índice completo con las entradas dadas, ordenándolas una sola vez.
+     * Replaces the whole index with the given entries, sorting them once.
+     */
+    load(entries) {
+        const pairs = [...entries].sort((a, b) => b[1] - a[1]);
+        this._order = pairs.map(([name]) => name);
+        this._scores = new Map(pairs);
+    }
+    /** Página de nombres en orden DESC, sin re-ordenar. / Page of names in DESC order, no re-sorting. */
+    page(offset, limit) {
+        return this._order.slice(offset, offset + limit);
+    }
+    /**
+     * Inserta o reubica un hijo con su score, manteniendo el orden.
+     * Inserts or relocates a child with its score, keeping the order.
+     */
+    set(name, score) {
+        this._detach(name);
+        this._order.splice(this._locate(score), 0, name);
+        this._scores.set(name, score);
+        this._schedule();
+    }
+    /**
+     * Quita un hijo del índice.
+     * Removes a child from the index.
+     */
+    delete(name) {
+        if (this._scores.has(name)) {
+            this._detach(name);
+            this._schedule();
+        }
+    }
+    /**
+     * Cancela la persistencia pendiente; se usa al descartar el índice de la caché.
+     * Cancels the pending persistence; used when dropping the index from the cache.
+     */
+    dispose() {
+        if (this._timer) {
+            clearTimeout(this._timer);
+            this._timer = null;
+        }
+    }
+    /** @internal Saca el nombre de la lista ordenada si estaba presente. / Detaches the name from the ordered list when present. */
+    _detach(name) {
+        const previous = this._scores.get(name);
+        if (previous !== undefined) {
+            let position = this._locate(previous);
+            while (position < this._order.length && this._order[position] !== name) {
+                position++;
+            }
+            if (position < this._order.length) {
+                this._order.splice(position, 1);
+            }
+            this._scores.delete(name);
+        }
+    }
+    /** @internal Primera posición cuyo score es menor o igual al dado (orden DESC). / First position whose score is lower or equal to the given one (DESC order). */
+    _locate(score) {
+        let low = 0;
+        let high = this._order.length;
+        while (low < high) {
+            const middle = (low + high) >> 1;
+            if ((this._scores.get(this._order[middle]) ?? 0) > score) {
+                low = middle + 1;
+            }
+            else {
+                high = middle;
+            }
+        }
+        return low;
+    }
+    /** @internal Programa la persistencia diferida. / Schedules the deferred persistence. */
+    _schedule() {
+        this._dirty = true;
+        if (!this._timer) {
+            this._timer = setTimeout(() => {
+                this._timer = null;
+                if (this._dirty) {
+                    this._dirty = false;
+                    void this._flush(this.entries).catch(() => { });
+                }
+            }, this._delay);
+            this._timer.unref?.();
+        }
+    }
+}
+exports.SortedIndex = SortedIndex;
+/**
+ * @internal
+ * Caché LRU de índices por directorio: mantiene acotada la memoria del driver descartando
+ * el directorio menos usado cuando se supera el límite.
+ * Per-directory LRU cache of indexes: keeps driver memory bounded by dropping the
+ * least-recently-used directory once the limit is exceeded.
+ */
+class IndexCache {
+    /** @param _limit - Directorios indexados simultáneamente / Simultaneously indexed directories */
+    constructor(_limit = 12) {
+        this._limit = _limit;
+        this._cache = new Map();
+    }
+    /**
+     * Índice ya cargado del directorio, marcándolo como recién usado.
+     * Already loaded index for the directory, marking it as recently used.
+     */
+    get(key) {
+        const index = this._cache.get(key);
+        if (index) {
+            this._cache.delete(key);
+            this._cache.set(key, index);
+        }
+        return index;
+    }
+    /**
+     * Registra el índice del directorio, descartando el menos usado si se supera el límite.
+     * Registers the directory index, dropping the least used one when over the limit.
+     */
+    set(key, index) {
+        this._cache.set(key, index);
+        while (this._cache.size > this._limit) {
+            const oldest = this._cache.keys().next().value;
+            this._cache.get(oldest)?.dispose();
+            this._cache.delete(oldest);
+        }
+    }
+    /**
+     * Descarta el índice del directorio y de todo su sub-árbol.
+     * Drops the directory index and its whole subtree.
+     */
+    drop(key) {
+        for (const cached of [...this._cache.keys()]) {
+            if (cached === key || cached.startsWith(`${key}/`)) {
+                this._cache.get(cached)?.dispose();
+                this._cache.delete(cached);
+            }
+        }
+    }
+    /** Vacía la caché completa. / Clears the whole cache. */
+    clear() {
+        for (const index of this._cache.values()) {
+            index.dispose();
+        }
+        this._cache.clear();
+    }
+}
+exports.IndexCache = IndexCache;
+/**
+ * Normaliza un path colapsando slashes redundantes y recortando los extremos.
+ * Normalizes a path collapsing redundant slashes and trimming both ends.
+ *
+ * @param path - Ruta cruda / Raw path
+ * @returns Ruta normalizada / Normalized path
+ */
+function normalize_path(path) {
+    return path.replace(/\/+/g, '/').replace(/^\/|\/$/g, '');
+}
+/**
+ * Separa una ruta normalizada en directorio padre y nombre del hijo.
+ * Splits a normalized path into parent directory and child name.
+ *
+ * @param path - Ruta a separar / Path to split
+ * @returns `{ parent, name }` / `{ parent, name }`
+ */
+function split_path(path) {
+    const full = normalize_path(path);
+    const cut = full.lastIndexOf('/');
+    return cut === -1 ? { parent: '', name: full } : { parent: full.slice(0, cut), name: full.slice(cut + 1) };
+}

package/build/cjs/lib/store/engine/lib/redis/index.d.ts

@@ -5,28 +5,45 @@
  */
 import type { Engine } from '../../../../../lib/store/engine';
 /**
- * Interface mínima del cliente Redis (compatible con ioredis).
- * Minimal Redis client interface (ioredis-compatible).
+ * Interface mínima del cliente Redis (compatible con ioredis). `pipeline` es opcional:
+ * cuando existe, las escrituras que tocan documento e índice viajan en un solo round-trip.
+ * Minimal Redis client interface (ioredis-compatible). `pipeline` is optional: when present,
+ * writes touching document and index travel in a single round-trip.
  */
 export interface RedisClient {
     get(key: string): Promise<string | null>;
     set(key: string, value: string): Promise<unknown>;
-    del(keys: string | string[]): Promise<unknown>;
+    del(...keys: unknown[]): Promise<unknown>;
     mget(keys: string[]): Promise<(string | null)[]>;
     scan(cursor: number | string, ...args: unknown[]): Promise<[string, string[]]>;
     zadd(key: string, score: number, member: string): Promise<unknown>;
-    zrem(key: string, members: string | string[]): Promise<unknown>;
+    zrem(...args: unknown[]): Promise<unknown>;
     zrevrange(key: string, start: number, stop: number): Promise<string[]>;
     zcard(key: string): Promise<number>;
+    getBuffer?(...args: unknown[]): Promise<Buffer | null>;
+    setBuffer?(...args: unknown[]): Promise<unknown>;
+    pipeline?(): {
+        set(key: string, value: string): unknown;
+        del(...keys: unknown[]): unknown;
+        zadd(key: string, score: number, member: string): unknown;
+        zrem(...args: unknown[]): unknown;
+        exec(): Promise<unknown>;
+    };
 }
 /**
  * Driver de persistencia con Redis.
  *
  * Keyspaces:
  * - `<prefix>:doc:<path>` → string del documento.
- * - `<prefix>:idx:<parent>` → sorted set (score=mtime, member=path completo).
+ * - `<prefix>:idx:<parent>` → sorted set (score explícito o de escritura, member=path completo).
  *
- * `list` combina ZREVRANGE + MGET → O(log N + M) en una sola round-trip.
+ * El índice ordenado vive en Redis: `list` combina ZREVRANGE + MGET (dos round-trips, O(log N + M))
+ * y `count` es un ZCARD O(1); las escrituras agrupan documento e índice en un pipeline para que
+ * no queden documentos huérfanos del índice si el proceso muere entre ambas operaciones.
+ *
+ * Redis persistence driver. The sorted index lives in Redis: `list` combines ZREVRANGE + MGET
+ * and `count` is an O(1) ZCARD; writes group document and index in a pipeline so no document
+ * is left orphaned from the index when the process dies between both operations.
  *
  * @example
  * import IORedis from 'ioredis';
@@ -40,26 +57,26 @@ export declare class RedisEngine implements Engine {
     private _doc_key;
     /** @internal */
     private _idx_key;
-    /** @internal */
-    private _split;
     /**
      * Lee el valor de un documento.
      * Reads a document's value.
      */
     get(path: string): Promise<string | null>;
     /**
-     * Escribe el valor y actualiza el índice del padre con el timestamp actual.
-     * Writes the value and updates the parent's index with current timestamp.
+     * Escribe el valor y su entrada de índice en una sola operación; `score` fija el orden
+     * de `list` (por defecto, la hora de escritura).
+     * Writes the value and its index entry in a single operation; `score` drives `list`
+     * ordering (write time by default).
      */
-    set(path: string, value: string): Promise<void>;
+    set(path: string, value: string, score?: number): Promise<void>;
     /**
-     * Elimina el doc, su índice y todo el sub-árbol.
-     * Deletes the doc, its index, and the entire subtree.
+     * Elimina el doc, su entrada de índice y todo el sub-árbol.
+     * Deletes the doc, its index entry, and the entire subtree.
      */
     unset(path: string): Promise<boolean>;
     /**
-     * Lista valores de los hijos directos, ordenados por mtime DESC en una round-trip.
-     * Lists direct children values ordered by mtime DESC in a single round-trip.
+     * Lista valores de los hijos directos, ordenados por score DESC en dos round-trips.
+     * Lists direct children values ordered by score DESC in two round-trips.
      */
     list(path: string, offset?: number, limit?: number): Promise<string[]>;
     /**
@@ -67,6 +84,18 @@ export declare class RedisEngine implements Engine {
      * Counts direct children in O(1) via ZCARD.
      */
     count(path: string): Promise<number>;
+    /**
+     * Lee el binario del documento. Requiere un cliente con soporte de buffers (ioredis lo
+     * trae con `getBuffer`); sin él la librería cae al documento serializado.
+     * Reads the document binary. Requires a buffer-capable client (ioredis ships `getBuffer`);
+     * without it the library falls back to the serialized document.
+     */
+    get_buffer(path: string): Promise<Buffer | null>;
+    /**
+     * Escribe el binario del documento en su propia key, sin JSON ni base64.
+     * Writes the document binary in its own key, with no JSON nor base64.
+     */
+    set_buffer(path: string, data: Buffer, score?: number): Promise<void>;
     /**
      * Vacía todo el prefix del cliente.
      * Clears the entire client prefix.