chapterjs 0.3.0 → 0.4.0

package/dist/redis/url.js

@@ -0,0 +1,50 @@
+// What `REDIS_URL` (and `REDIS_PASSWORD`) say: where Redis is, how to
+// reach it, and as what. Read once from the environment by the CLI and
+// given to the client; a wrong value is explained in the words of `.env`.
+// https://redis.io/docs/latest/develop/clients/nodejs/connect/ (the
+// `redis://` and `rediss://` forms every client reads)
+export const REDIS_URL_HELP = 'Write it like redis://localhost:6379 (rediss:// for a TLS connection, /1 at the end for a database other than 0), with the user and password when there are some: redis://user:password@host:6379.';
+/** `host:port`, and the database when it is not the first: what messages show. Never the password. */
+export const describeRedis = (address) => `${address.host}:${address.port}${address.db === 0 ? '' : `/${address.db}`}`;
+/**
+ * Reads a `REDIS_URL`, with the `REDIS_PASSWORD` set beside it winning over
+ * the one of the URL. Answers what is wrong when it is not a Redis address.
+ */
+export function parseRedisUrl(text, password) {
+    let url;
+    try {
+        if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(text))
+            throw new Error('no scheme');
+        url = new URL(text);
+    }
+    catch {
+        return { problem: `is not an address. ${REDIS_URL_HELP}` };
+    }
+    if (url.protocol !== 'redis:' && url.protocol !== 'rediss:') {
+        return {
+            problem: `starts with "${url.protocol}//", and a Redis address starts with redis:// or rediss://. ${REDIS_URL_HELP}`,
+        };
+    }
+    if (url.hostname === '') {
+        return { problem: `names no host. ${REDIS_URL_HELP}` };
+    }
+    const port = url.port === '' ? 6379 : Number(url.port);
+    const path = url.pathname.replace(/^\//, '');
+    if (path !== '' && !/^\d+$/.test(path)) {
+        return {
+            problem: `ends with "/${path}", and what follows the host is the number of the database. ${REDIS_URL_HELP}`,
+        };
+    }
+    const own = password !== '' ? password : decodeURIComponent(url.password);
+    return {
+        address: {
+            // A URL keeps IPv6 brackets around the host; a socket wants none.
+            host: url.hostname.replace(/^\[(.*)\]$/, '$1'),
+            port,
+            tls: url.protocol === 'rediss:',
+            username: url.username === '' ? null : decodeURIComponent(url.username),
+            password: own === '' ? null : own,
+            db: path === '' ? 0 : Number(path),
+        },
+    };
+}

package/dist/store/backend.d.ts

@@ -1,3 +1,6 @@
+/** Where a store keeps its data: what `storage` of its config names. */
+export type StoreStorage = 'file' | 'redis';
+export declare const STORAGES: readonly StoreStorage[];
 /** One value of a store, with when it expires. */
 export interface StoreEntry {
     value: unknown;
@@ -10,6 +13,7 @@ export type StoreKeyParts = readonly string[];
 export interface StoreListedEntry extends StoreEntry {
     key: StoreKeyParts;
 }
+import type { RankingBackend } from './ranking-backend.js';
 /** What keeps the data of every store. Expired entries are never given. */
 export interface StoreBackend {
     get(store: string, key: StoreKeyParts): Promise<StoreEntry | undefined>;
@@ -17,9 +21,35 @@ export interface StoreBackend {
     delete(store: string, key: StoreKeyParts): Promise<boolean>;
     /** The entries whose key starts with `prefix`, in no particular order. */
     entries(store: string, prefix: StoreKeyParts): Promise<StoreListedEntry[]>;
+    /**
+     * Reads the entry at `key` and keeps what `change` returns, with nothing
+     * written there by anyone in between: two updates never lose one
+     * another, in one process or in several. `change` may run more than
+     * once, when the entry changed meanwhile; `undefined` writes nothing.
+     * Resolves with the entry kept.
+     */
+    update(store: string, key: StoreKeyParts, change: StoreChange): Promise<StoreEntry | undefined>;
+    /** Forgets every entry whose key starts with `prefix`; how many there were. */
+    clear(store: string, prefix: StoreKeyParts): Promise<number>;
+    /**
+     * A native way to keep rankings, when the backend has one. Without it,
+     * rankings are kept as entries of the backend (`StoreRankingBackend`).
+     */
+    rankings?(): RankingBackend;
     /** Writes what is pending, if anything. */
     close(): Promise<void>;
 }
+/** What `update()` makes of the current entry: the next one, or `undefined` for none. */
+export type StoreChange = (current: StoreEntry | undefined) => StoreEntry | undefined;
+/**
+ * Runs what is given for one key one after the other, in this process:
+ * updates of one key here never compete with each other, only with the
+ * other processes. Keys that are not busy cost nothing.
+ */
+export declare class KeyQueue {
+    #private;
+    run<T>(id: string, fn: () => Promise<T>): Promise<T>;
+}
 /** The map key of a key: unambiguous whatever the parts hold. */
 export declare const encodeKey: (key: StoreKeyParts) => string;
 export declare const decodeKey: (encoded: string) => string[];
@@ -27,7 +57,22 @@ export declare const decodeKey: (encoded: string) => string[];
 export declare function startsWith(key: StoreKeyParts, prefix: StoreKeyParts): boolean;
 /** Whether an entry is still good at `now`. */
 export declare const alive: (entry: StoreEntry, now?: number) => boolean;
-/** Gives every store its backend: called by the CLI, once per process. */
-export declare function setStoreBackend(backend: StoreBackend | null): void;
-/** The backend of the process, or an error that says when stores work. */
-export declare function storeBackend(): StoreBackend;
+/**
+ * Gives every store of one storage its backend: called by the CLI, once
+ * per process and per storage the project has a backend for; `null`
+ * takes it away.
+ */
+export declare function setStoreBackend(storage: StoreStorage, backend: StoreBackend | null): void;
+/** The backends of the process, by storage. */
+export declare const storeBackends: () => ReadonlyMap<StoreStorage, StoreBackend>;
+/** A store of a storage the process has no backend for: nothing to fix in the file. */
+export declare class NowhereToKeepError extends TypeError {
+    name: string;
+}
+/** Why a store of `storage` can't be used: the process has no backend for it. */
+export declare function nowhereToKeep(storage: StoreStorage, name: string, what?: string): string;
+/**
+ * The backend of a storage, or an error that says when stores work: for
+ * Redis, that the project gave no address.
+ */
+export declare function storeBackend(storage: StoreStorage, name?: string): StoreBackend;

package/dist/store/backend.js

@@ -1,7 +1,36 @@
 // Where the data of the stores is kept, behind an interface: a file per
-// store by default (`file-backend.ts`), the first process of a cluster for
-// the others (`ipc-backend.ts`), and later anything else. A backend knows
-// nothing of servers: the scope of a store is part of the key it gets.
+// store by default (`file-backend.ts`), Redis when a store asks for it
+// (`redis-backend.ts`), the first process of a cluster for the others
+// (`ipc-backend.ts`), and later anything else. A backend knows nothing of
+// servers: the scope of a store is part of the key it gets. Each kind of
+// storage a store may name has one backend per process.
+export const STORAGES = ['file', 'redis'];
+/**
+ * Runs what is given for one key one after the other, in this process:
+ * updates of one key here never compete with each other, only with the
+ * other processes. Keys that are not busy cost nothing.
+ */
+export class KeyQueue {
+    #tails = new Map();
+    // Chained with await, not .then: an error keeps the line of the file
+    // that asked (see Interaction).
+    async run(id, fn) {
+        const before = this.#tails.get(id);
+        let done;
+        const tail = new Promise(resolve => (done = resolve));
+        this.#tails.set(id, tail);
+        try {
+            if (before)
+                await before;
+            return await fn();
+        }
+        finally {
+            done();
+            if (this.#tails.get(id) === tail)
+                this.#tails.delete(id);
+        }
+    }
+}
 /** The map key of a key: unambiguous whatever the parts hold. */
 export const encodeKey = (key) => JSON.stringify(key);
 export const decodeKey = (encoded) => JSON.parse(encoded);
@@ -13,15 +42,41 @@ export function startsWith(key, prefix) {
 }
 /** Whether an entry is still good at `now`. */
 export const alive = (entry, now = Date.now()) => entry.expiresAt === null || entry.expiresAt > now;
-let current = null;
-/** Gives every store its backend: called by the CLI, once per process. */
-export function setStoreBackend(backend) {
-    current = backend;
+const current = new Map();
+/**
+ * Gives every store of one storage its backend: called by the CLI, once
+ * per process and per storage the project has a backend for; `null`
+ * takes it away.
+ */
+export function setStoreBackend(storage, backend) {
+    if (backend)
+        current.set(storage, backend);
+    else
+        current.delete(storage);
+}
+/** The backends of the process, by storage. */
+export const storeBackends = () => current;
+/** A store of a storage the process has no backend for: nothing to fix in the file. */
+export class NowhereToKeepError extends TypeError {
+    name = 'NowhereToKeepError';
+}
+/** Why a store of `storage` can't be used: the process has no backend for it. */
+export function nowhereToKeep(storage, name, what = 'store') {
+    if (storage === 'redis') {
+        return `${name} is kept in Redis (storage: 'redis'), but REDIS_URL is not set: add it to .env (like redis://localhost:6379) and start again, or remove storage: 'redis' to keep its ${what === 'store' ? 'data' : 'scores'} in data/.`;
+    }
+    return `Nothing keeps the data of ${name} (storage: '${storage}').`;
 }
-/** The backend of the process, or an error that says when stores work. */
-export function storeBackend() {
-    if (!current) {
+/**
+ * The backend of a storage, or an error that says when stores work: for
+ * Redis, that the project gave no address.
+ */
+export function storeBackend(storage, name = 'This store') {
+    const backend = current.get(storage);
+    if (backend)
+        return backend;
+    if (current.size === 0) {
         throw new Error('Stores only work while the bot runs: use a store in the functions of your files (run), not when a file loads.');
     }
-    return current;
+    throw new NowhereToKeepError(nowhereToKeep(storage, name));
 }

package/dist/store/declaration.d.ts

@@ -1,10 +1,13 @@
 import type { Declaration } from '../loader/loader.js';
+import { type StoreStorage } from './backend.js';
 import { type StoreScope } from './store.js';
 /** A store, checked: what the project keeps of it. */
 export interface LoadedStore {
     /** The name of the store: the name of the export that declares it. */
     readonly name: string;
     readonly scope: StoreScope;
+    /** Where its data is: a file of `data/`, or Redis. */
+    readonly storage: StoreStorage;
     /** The default expiration, in ms, or `null` for never. */
     readonly expires: number | null;
 }

package/dist/store/declaration.js

@@ -2,12 +2,13 @@
 // scope or expiration is explained before anything is kept; the store is
 // then bound to the name of its export, which names its data.
 import { DURATION_EXAMPLE, parseDuration } from '../util/duration.js';
+import { STORAGES } from './backend.js';
 import { bindStore, isStoreDeclaration, storeStateOf, } from './store.js';
 const fail = (message) => {
     throw new TypeError(message);
 };
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-const KEYS = ['scope', 'expires'];
+const KEYS = ['scope', 'storage', 'expires'];
 const SCOPES = ['guild', 'global'];
 /** What a name can be: a file in `data/` is called after it. */
 const NAME = /^[\w.-]+$/;
@@ -37,6 +38,10 @@ export const storeDeclaration = {
         if (!SCOPES.includes(scope)) {
             fail(`"scope" is 'guild' (the data is kept per server, the default) or 'global' (one set of data for the whole bot), got ${JSON.stringify(config.scope)}.`);
         }
+        const storage = (config.storage ?? 'file');
+        if (!STORAGES.includes(storage)) {
+            fail(`"storage" is 'file' (a file in data/, the default) or 'redis' (the Redis of REDIS_URL in .env), got ${JSON.stringify(config.storage)}.`);
+        }
         let expires = null;
         if (config.expires !== undefined) {
             const ms = typeof config.expires === 'string'
@@ -47,7 +52,7 @@ export const storeDeclaration = {
             }
             expires = ms;
         }
-        bindStore(value, { name, scope, expires });
-        return Object.freeze({ name, scope, expires });
+        bindStore(value, { name, scope, storage, expires });
+        return Object.freeze({ name, scope, storage, expires });
     },
 };

package/dist/store/file-backend.d.ts

@@ -1,4 +1,4 @@
-import { type StoreBackend, type StoreEntry, type StoreKeyParts, type StoreListedEntry } from './backend.js';
+import { type StoreBackend, type StoreChange, type StoreEntry, type StoreKeyParts, type StoreListedEntry } from './backend.js';
 /** The folder of a project where the stores keep their files. */
 export declare const DATA_FOLDER = "data";
 export interface FileStoreBackendOptions {
@@ -18,5 +18,7 @@ export declare class FileStoreBackend implements StoreBackend {
     set(store: string, key: StoreKeyParts, entry: StoreEntry): Promise<void>;
     delete(store: string, key: StoreKeyParts): Promise<boolean>;
     entries(store: string, prefix: StoreKeyParts): Promise<StoreListedEntry[]>;
+    update(store: string, key: StoreKeyParts, change: StoreChange): Promise<StoreEntry | undefined>;
+    clear(store: string, prefix: StoreKeyParts): Promise<number>;
     close(): Promise<void>;
 }

package/dist/store/file-backend.js

@@ -164,6 +164,35 @@ export class FileStoreBackend {
         }
         return listed;
     }
+    // Read and written without an await in between: nothing else runs there.
+    async update(store, key, change) {
+        const entries = this.#load(store);
+        const encoded = encodeKey(key);
+        let current = entries.get(encoded);
+        if (current && !alive(current, this.#now()))
+            current = undefined;
+        const next = change(current);
+        if (next === undefined)
+            return current;
+        entries.set(encoded, next);
+        this.#changed(store);
+        return next;
+    }
+    async clear(store, prefix) {
+        const entries = this.#load(store);
+        const now = this.#now();
+        let count = 0;
+        for (const [encoded, entry] of entries) {
+            if (!startsWith(decodeKey(encoded), prefix))
+                continue;
+            entries.delete(encoded);
+            if (alive(entry, now))
+                count++;
+        }
+        if (count > 0)
+            this.#changed(store);
+        return count;
+    }
     async close() {
         clearInterval(this.#sweeper);
         process.off('exit', this.#onExit);

package/dist/store/ipc-backend.d.ts

@@ -1,4 +1,6 @@
-import type { StoreBackend, StoreEntry, StoreKeyParts, StoreListedEntry } from './backend.js';
+import { type StoreBackend, type StoreChange, type StoreEntry, type StoreKeyParts, type StoreListedEntry } from './backend.js';
+/** How many times an update is tried before giving up: the value changes faster than it can be read. */
+export declare const UPDATE_ATTEMPTS = 50;
 /** What a process asks the first one. */
 export type StoreRequest = {
     type: 'store';
@@ -20,6 +22,18 @@ export type StoreRequest = {
     op: 'entries';
     store: string;
     prefix: StoreKeyParts;
+} | {
+    op: 'clear';
+    store: string;
+    prefix: StoreKeyParts;
+}
+/** Keeps `entry` only if the entry is still `expected` (`null`: none). */
+ | {
+    op: 'swap';
+    store: string;
+    key: StoreKeyParts;
+    expected: StoreEntry | null;
+    entry: StoreEntry;
 });
 /** What the first process answers. */
 export interface StoreReply {
@@ -35,6 +49,8 @@ export interface Channel<Out, In> {
 }
 export declare const isStoreRequest: (message: unknown) => message is StoreRequest;
 export declare const isStoreReply: (message: unknown) => message is StoreReply;
+/** What an update says when it never got through. */
+export declare const tooBusy: (store: string) => string;
 /** The backend of a process that is not the first: every call is a message. */
 export declare class IpcStoreBackend implements StoreBackend {
     #private;
@@ -43,6 +59,13 @@ export declare class IpcStoreBackend implements StoreBackend {
     set(store: string, key: StoreKeyParts, entry: StoreEntry): Promise<void>;
     delete(store: string, key: StoreKeyParts): Promise<boolean>;
     entries(store: string, prefix: StoreKeyParts): Promise<StoreListedEntry[]>;
+    /**
+     * A change can't cross the channel: it runs here, on what the first
+     * process gave, and the first process keeps the result only if nobody
+     * wrote in between; otherwise it runs again on the new value.
+     */
+    update(store: string, key: StoreKeyParts, change: StoreChange): Promise<StoreEntry | undefined>;
+    clear(store: string, prefix: StoreKeyParts): Promise<number>;
     close(): Promise<void>;
 }
 /**

package/dist/store/ipc-backend.js

@@ -2,6 +2,11 @@
 // process keeps it (with the file backend) and the others ask it over
 // IPC, the channel they already share with it. Each process then sees the
 // same thing, whichever shard a command was used on.
+import { encodeKey, KeyQueue, } from './backend.js';
+/** How many times an update is tried before giving up: the value changes faster than it can be read. */
+export const UPDATE_ATTEMPTS = 50;
+/** Two entries are the same when their JSON is: what crossed the channel kept its order. */
+const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b);
 export const isStoreRequest = (message) => typeof message === 'object' &&
     message !== null &&
     message.type === 'store' &&
@@ -10,11 +15,14 @@ export const isStoreReply = (message) => typeof message === 'object' &&
     message !== null &&
     message.type === 'store' &&
     !('op' in message);
+/** What an update says when it never got through. */
+export const tooBusy = (store) => `The value of ${store} changed ${UPDATE_ATTEMPTS} times while update() was trying to change it: it is written too often by too many at once. Keep what changes this often under several keys.`;
 /** The backend of a process that is not the first: every call is a message. */
 export class IpcStoreBackend {
     #channel;
     #waiting = new Map();
     #lastId = 0;
+    #updates = new KeyQueue();
     constructor(channel) {
         this.#channel = channel;
         channel.on(message => {
@@ -52,6 +60,35 @@ export class IpcStoreBackend {
     entries(store, prefix) {
         return this.#ask({ op: 'entries', store, prefix });
     }
+    /**
+     * A change can't cross the channel: it runs here, on what the first
+     * process gave, and the first process keeps the result only if nobody
+     * wrote in between; otherwise it runs again on the new value.
+     */
+    update(store, key, change) {
+        return this.#updates.run(`${store}\u0000${encodeKey(key)}`, () => this.#update(store, key, change));
+    }
+    async #update(store, key, change) {
+        for (let attempt = 0; attempt < UPDATE_ATTEMPTS; attempt++) {
+            const current = await this.get(store, key);
+            const next = change(current);
+            if (next === undefined)
+                return current;
+            const kept = await this.#ask({
+                op: 'swap',
+                store,
+                key,
+                expected: current ?? null,
+                entry: next,
+            });
+            if (kept)
+                return next;
+        }
+        throw new Error(tooBusy(store));
+    }
+    clear(store, prefix) {
+        return this.#ask({ op: 'clear', store, prefix });
+    }
     async close() {
         // Nothing is kept here: the first process writes.
     }
@@ -76,6 +113,18 @@ export function serveStores(backend, reply) {
                     return backend.delete(message.store, message.key);
                 case 'entries':
                     return backend.entries(message.store, message.prefix);
+                case 'clear':
+                    return backend.clear(message.store, message.prefix);
+                case 'swap': {
+                    let kept = false;
+                    const { expected, entry } = message;
+                    return backend
+                        .update(message.store, message.key, current => {
+                        kept = same(current, expected);
+                        return kept ? entry : undefined;
+                    })
+                        .then(() => kept);
+                }
             }
         };
         run().then(result => reply({ type: 'store', id, result }), (error) => reply({

package/dist/store/memory-backend.d.ts

@@ -1,4 +1,4 @@
-import { type StoreBackend, type StoreEntry, type StoreKeyParts, type StoreListedEntry } from './backend.js';
+import { type StoreBackend, type StoreChange, type StoreEntry, type StoreKeyParts, type StoreListedEntry } from './backend.js';
 /** The data of every store, in memory, forgotten with the process. */
 export declare class MemoryStoreBackend implements StoreBackend {
     #private;
@@ -9,7 +9,9 @@ export declare class MemoryStoreBackend implements StoreBackend {
     set(store: string, key: StoreKeyParts, entry: StoreEntry): Promise<void>;
     delete(store: string, key: StoreKeyParts): Promise<boolean>;
     entries(store: string, prefix: StoreKeyParts): Promise<StoreListedEntry[]>;
+    update(store: string, key: StoreKeyParts, change: StoreChange): Promise<StoreEntry | undefined>;
+    clear(store: string, prefix: StoreKeyParts): Promise<number>;
     /** Forgets everything: what a test does with its stores stays in it. */
-    clear(): void;
+    reset(): void;
     close(): Promise<void>;
 }

package/dist/store/memory-backend.js

@@ -48,8 +48,34 @@ export class MemoryStoreBackend {
         }
         return result;
     }
+    // Read and written without an await in between: nothing else runs there.
+    async update(store, key, change) {
+        const entries = this.#store(store);
+        const encoded = encodeKey(key);
+        let current = entries.get(encoded);
+        if (current && !alive(current, this.#now()))
+            current = undefined;
+        const next = change(current);
+        if (next === undefined)
+            return current;
+        entries.set(encoded, next);
+        return next;
+    }
+    async clear(store, prefix) {
+        const entries = this.#store(store);
+        const now = this.#now();
+        let count = 0;
+        for (const [encoded, entry] of entries) {
+            if (!startsWith(decodeKey(encoded), prefix))
+                continue;
+            entries.delete(encoded);
+            if (alive(entry, now))
+                count++;
+        }
+        return count;
+    }
     /** Forgets everything: what a test does with its stores stays in it. */
-    clear() {
+    reset() {
         this.#stores.clear();
     }
     async close() { }

package/dist/store/ranking-backend.d.ts

@@ -0,0 +1,45 @@
+import type { StoreBackend, StoreKeyParts } from './backend.js';
+/** Which end of a ranking comes first. */
+export type RankingOrder = 'highest' | 'lowest';
+/** A member of a ranking, and its score. */
+export interface RankedScore {
+    id: string;
+    score: number;
+}
+/** What keeps the scores of every ranking. `scope` is the server, or nothing. */
+export interface RankingBackend {
+    /** Adds `by` to the score of `id` (from 0), in one go; the new score. */
+    add(name: string, scope: StoreKeyParts, id: string, by: number): Promise<number>;
+    set(name: string, scope: StoreKeyParts, id: string, score: number): Promise<void>;
+    score(name: string, scope: StoreKeyParts, id: string): Promise<number | undefined>;
+    /** Where `id` is, from 0, in `order`; `undefined` when it has no score. */
+    rank(name: string, scope: StoreKeyParts, id: string, order: RankingOrder): Promise<number | undefined>;
+    /** `count` members from position `start` (from 0), in `order`. */
+    range(name: string, scope: StoreKeyParts, order: RankingOrder, start: number, count: number): Promise<RankedScore[]>;
+    remove(name: string, scope: StoreKeyParts, id: string): Promise<boolean>;
+    size(name: string, scope: StoreKeyParts): Promise<number>;
+    /** Forgets every score; how many there were. */
+    clear(name: string, scope: StoreKeyParts): Promise<number>;
+}
+/**
+ * The order of a ranking, ties included, as Redis sorts a sorted set: by
+ * score, then by the bytes of the id (ZRANGE), both reversed for the
+ * highest first (ZREVRANGE). Every backend ranks the same way.
+ * https://redis.io/docs/latest/commands/zrange/
+ */
+export declare function compareRanked(order: RankingOrder): (a: RankedScore, b: RankedScore) => number;
+/** The rankings of a backend of stores: one entry per member. */
+export declare class StoreRankingBackend implements RankingBackend {
+    #private;
+    constructor(store: StoreBackend);
+    add(name: string, scope: StoreKeyParts, id: string, by: number): Promise<number>;
+    set(name: string, scope: StoreKeyParts, id: string, score: number): Promise<void>;
+    score(name: string, scope: StoreKeyParts, id: string): Promise<number | undefined>;
+    rank(name: string, scope: StoreKeyParts, id: string, order: RankingOrder): Promise<number | undefined>;
+    range(name: string, scope: StoreKeyParts, order: RankingOrder, start: number, count: number): Promise<RankedScore[]>;
+    remove(name: string, scope: StoreKeyParts, id: string): Promise<boolean>;
+    size(name: string, scope: StoreKeyParts): Promise<number>;
+    clear(name: string, scope: StoreKeyParts): Promise<number>;
+}
+/** The rankings of a backend of stores: its own when it has one. */
+export declare function rankingsOf(store: StoreBackend): RankingBackend;

package/dist/store/ranking-backend.js

@@ -0,0 +1,82 @@
+// Where the scores of a ranking are kept, behind an interface like the data
+// of a store. Any backend of stores keeps rankings with
+// `StoreRankingBackend`, one entry per member (`[...scope, id]` → score):
+// a file, the first process of a cluster, memory, with nothing to write.
+// A backend with a native way to rank gives its own with `rankings()`
+// (Redis: sorted sets), and is then used instead.
+/**
+ * The order of a ranking, ties included, as Redis sorts a sorted set: by
+ * score, then by the bytes of the id (ZRANGE), both reversed for the
+ * highest first (ZREVRANGE). Every backend ranks the same way.
+ * https://redis.io/docs/latest/commands/zrange/
+ */
+export function compareRanked(order) {
+    const sign = order === 'highest' ? -1 : 1;
+    return (a, b) => a.score !== b.score
+        ? sign * (a.score - b.score)
+        : sign * Buffer.compare(Buffer.from(a.id), Buffer.from(b.id));
+}
+/** The rankings of a backend of stores: one entry per member. */
+export class StoreRankingBackend {
+    #store;
+    constructor(store) {
+        this.#store = store;
+    }
+    async #all(name, scope, order) {
+        const entries = await this.#store.entries(name, scope);
+        return entries
+            .filter(entry => entry.key.length === scope.length + 1 &&
+            typeof entry.value === 'number')
+            .map(entry => ({
+            id: entry.key[scope.length],
+            score: entry.value,
+        }))
+            .sort(compareRanked(order));
+    }
+    async add(name, scope, id, by) {
+        const kept = await this.#store.update(name, [...scope, id], current => ({
+            value: (typeof current?.value === 'number' ? current.value : 0) + by,
+            expiresAt: null,
+        }));
+        return kept.value;
+    }
+    async set(name, scope, id, score) {
+        await this.#store.set(name, [...scope, id], {
+            value: score,
+            expiresAt: null,
+        });
+    }
+    async score(name, scope, id) {
+        const entry = await this.#store.get(name, [...scope, id]);
+        return typeof entry?.value === 'number' ? entry.value : undefined;
+    }
+    async rank(name, scope, id, order) {
+        const index = (await this.#all(name, scope, order)).findIndex(ranked => ranked.id === id);
+        return index === -1 ? undefined : index;
+    }
+    async range(name, scope, order, start, count) {
+        return (await this.#all(name, scope, order)).slice(start, start + count);
+    }
+    remove(name, scope, id) {
+        return this.#store.delete(name, [...scope, id]);
+    }
+    async size(name, scope) {
+        return (await this.#all(name, scope, 'highest')).length;
+    }
+    clear(name, scope) {
+        return this.#store.clear(name, scope);
+    }
+}
+const generic = new WeakMap();
+/** The rankings of a backend of stores: its own when it has one. */
+export function rankingsOf(store) {
+    const own = store.rankings?.();
+    if (own)
+        return own;
+    let found = generic.get(store);
+    if (!found) {
+        found = new StoreRankingBackend(store);
+        generic.set(store, found);
+    }
+    return found;
+}