Engine¶

interface Engine {
    /**
     * @description Retrieves a value by its key.
     * @param key Document path.
     * @returns JSON text or null if not found.
     */
    get(key: string): Promise<string | null>;

    /**
     * @description Saves or deletes a value.
     * If value is null, deletes the key and all sub-keys recursively (cascade delete).
     * @param key Document path.
     * @param value Text to save or null to delete recursively.
     */
    set(key: string, value: string | null): Promise<void>;

    /**
     * @description Lists keys under a prefix, ordered by most recent.
     * @param prefix Search prefix.
     * @param offset Pagination start (default: 0).
     * @param limit Maximum count (default: 50).
     * @returns Array of keys.
     */
    list(prefix: string, offset?: number, limit?: number): Promise<string[]>;
}

const messages = await wa.Message.list(cid, offset, limit);

const count = await wa.Message.count(cid);

const msg = await wa.Message.get(cid, mid);
if (msg) await msg.remove();

// Only deletes the contact index
await wa.engine.set("contact/{jid}/index", null);

// Static
await wa.Chat.remove(cid);

// Or via instance
const chat = await wa.Chat.get(cid);
if (chat) await chat.remove();

const msg = await wa.Message.get(cid, mid);
if (msg) await msg.remove();

class PostgresEngine implements Engine {
    constructor(private readonly _pool: Pool, private readonly _session: string) {}

    async get(key: string): Promise<string | null> {
        const { rows } = await this._pool.query(
            'SELECT value FROM kv_store WHERE session = $1 AND key = $2',
            [this._session, key]
        );
        return rows[0]?.value ?? null;
    }

    async set(key: string, value: string | null): Promise<void> {
        if (value) {
            await this._pool.query(
                `INSERT INTO kv_store (session, key, value, updated_at)
                 VALUES ($1, $2, $3, NOW())
                 ON CONFLICT (session, key) DO UPDATE SET value = $3, updated_at = NOW()`,
                [this._session, key, value]
            );
        } else {
            // Cascade delete: delete exact key AND all sub-keys
            await this._pool.query(
                'DELETE FROM kv_store WHERE session = $1 AND (key = $2 OR key LIKE $3)',
                [this._session, key, key + '/%']
            );
        }
    }

    async list(prefix: string, offset = 0, limit = 50): Promise<string[]> {
        const { rows } = await this._pool.query(
            `SELECT key FROM kv_store
             WHERE session = $1 AND key LIKE $2
             ORDER BY updated_at DESC
             LIMIT $3 OFFSET $4`,
            [this._session, prefix + '%', limit, offset]
        );
        return rows.map(r => r.key);
    }
}

interface EngineBatch extends Engine {
    set_batch(entries: Array<[key: string, value: string | null]>): Promise<void>;
}

interface EngineTTL extends Engine {
    set_ttl(key: string, value: string, ttl_seconds: number): Promise<void>;
}

interface EnginePrefix extends Engine {
    delete_prefix(prefix: string): Promise<number>;
}

async delete_prefix(prefix: string): Promise<number> {
    let count = 0;
    let cursor = '0';
    do {
        const [next, keys] = await this._client.scan(cursor, 'MATCH', `${this._prefix}:${prefix}*`);
        cursor = next;
        if (keys.length) {
            await this._client.del(...keys);
            count += keys.length;
        }
    } while (cursor !== '0');
    return count;
}