chapterjs 0.2.3 → 0.4.0

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

@@ -0,0 +1,17 @@
+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;
+    constructor(options?: {
+        now?: () => number;
+    });
+    get(store: string, key: StoreKeyParts): Promise<StoreEntry | undefined>;
+    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. */
+    reset(): void;
+    close(): Promise<void>;
+}

package/dist/store/memory-backend.js

@@ -0,0 +1,82 @@
+// A backend that keeps the data of the stores in memory and nowhere else:
+// what `chapterjs test` gives a bot under test, so a test never touches
+// the `data/` folder of the project and starts from nothing every time.
+import { alive, decodeKey, encodeKey, startsWith, } from './backend.js';
+/** The data of every store, in memory, forgotten with the process. */
+export class MemoryStoreBackend {
+    #stores = new Map();
+    #now;
+    constructor(options = {}) {
+        this.#now = options.now ?? Date.now;
+    }
+    #store(name) {
+        let store = this.#stores.get(name);
+        if (!store) {
+            store = new Map();
+            this.#stores.set(name, store);
+        }
+        return store;
+    }
+    async get(store, key) {
+        const entry = this.#store(store).get(encodeKey(key));
+        if (!entry)
+            return undefined;
+        if (!alive(entry, this.#now())) {
+            this.#store(store).delete(encodeKey(key));
+            return undefined;
+        }
+        return entry;
+    }
+    async set(store, key, entry) {
+        this.#store(store).set(encodeKey(key), entry);
+    }
+    async delete(store, key) {
+        return this.#store(store).delete(encodeKey(key));
+    }
+    async entries(store, prefix) {
+        const now = this.#now();
+        const result = [];
+        for (const [encoded, entry] of this.#store(store)) {
+            const key = decodeKey(encoded);
+            if (!startsWith(key, prefix))
+                continue;
+            if (!alive(entry, now)) {
+                this.#store(store).delete(encoded);
+                continue;
+            }
+            result.push({ key, ...entry });
+        }
+        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. */
+    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;
+}

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

@@ -0,0 +1,38 @@
+import { RedisClient } from '../redis/client.js';
+import { RedisRankingBackend } from './redis-ranking.js';
+import { type StoreBackend, type StoreChange, type StoreEntry, type StoreKeyParts, type StoreListedEntry } from './backend.js';
+/** The prefix of every key written by `chapterjs dev`. */
+export declare const DEV_PREFIX = "dev:";
+export interface RedisStoreBackendOptions {
+    /** Put in front of every key: `dev:` under `chapterjs dev`, nothing in production. */
+    prefix?: string;
+    /** How many keys SCAN is asked for at a time. */
+    scanCount?: number;
+    /** How many connections updates may use at once, besides the main one. */
+    transactions?: number;
+    /** A new connection to the same Redis, for an update. */
+    connect?: () => RedisClient;
+    now?: () => number;
+}
+/** A part of a key, safe between two `:` and in a MATCH pattern. */
+export declare const escapePart: (part: string) => string;
+/** The parts back from a key, after the prefix and the name of the store. */
+export declare const unescapePart: (text: string) => string;
+/** The data of every store with `storage: 'redis'`, in one Redis. */
+export declare class RedisStoreBackend implements StoreBackend {
+    #private;
+    constructor(client: RedisClient, options?: RedisStoreBackendOptions);
+    /** Rankings as sorted sets: the key of a ranking is the key of its scope. */
+    rankings(): RedisRankingBackend;
+    /** The client, for the preflight check of the CLI. */
+    get client(): RedisClient;
+    /** The Redis key of a store and parts. */
+    key(store: string, parts: StoreKeyParts): string;
+    get(store: string, key: StoreKeyParts): Promise<StoreEntry | undefined>;
+    set(store: string, key: StoreKeyParts, entry: StoreEntry): Promise<void>;
+    update(store: string, key: StoreKeyParts, change: StoreChange): Promise<StoreEntry | undefined>;
+    clear(store: string, prefix: StoreKeyParts): Promise<number>;
+    delete(store: string, key: StoreKeyParts): Promise<boolean>;
+    entries(store: string, prefix: StoreKeyParts): Promise<StoreListedEntry[]>;
+    close(): Promise<void>;
+}