@starlove/orbit 1.4.0 → 2.0.0

package/lib/adapters/memory/board.js

@@ -0,0 +1,521 @@
+/**
+ * One board's records in memory, and the reader and writer over them. The
+ * tables are arrays in the order records were written, so "then by when it
+ * was written" is array order, and every sort here is stable.
+ */
+import { OrbitError } from "../../core/errors.js";
+import { matches } from "./search.js";
+export function emptyTables() {
+    return {
+        board: null,
+        states: [],
+        labels: [],
+        tickets: [],
+        ticketLabels: [],
+        comments: [],
+        relations: [],
+        crossBoardRelations: [],
+        entries: [],
+        verdicts: [],
+        attachments: [],
+        events: [],
+        search: new Map()
+    };
+}
+/**
+ * Every call gives other callers a turn first, as a real database's I/O does,
+ * so the conformance cases see the interleavings an adapter has to survive.
+ */
+const yieldTurn = () => Promise.resolve();
+const copy = (record) => ({ ...record });
+/** Sets the fields a patch names; a field given as undefined is not named. */
+function apply(record, patch) {
+    for (const [key, value] of Object.entries(patch)) {
+        if (value !== undefined)
+            Object.assign(record, { [key]: value });
+    }
+}
+const copies = (records) => records.map(copy);
+/** Code-point order, as SQLite compares text. */
+export function byCodePoint(a, b) {
+    let at = 0;
+    while (at < a.length && at < b.length) {
+        const left = a.codePointAt(at) ?? 0;
+        const right = b.codePointAt(at) ?? 0;
+        if (left !== right)
+            return left - right;
+        at += left > 0xffff ? 2 : 1;
+    }
+    return a.length - b.length;
+}
+const byCreated = (records) => [...records].sort((a, b) => (a.created_at < b.created_at ? -1 : a.created_at > b.created_at ? 1 : 0));
+const asciiLower = (text) => text.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+function find(records, id) {
+    return records.find((record) => record.id === id);
+}
+function filterTickets(tickets, filter) {
+    const ids = filter.ids ? new Set(filter.ids) : null;
+    return tickets
+        .filter((ticket) => (filter.archived === undefined || (ticket.archived_at !== null) === filter.archived) &&
+        (filter.parent === undefined || ticket.parent_ticket_id === filter.parent) &&
+        (filter.state === undefined || ticket.state_id === filter.state) &&
+        (ids === null || ids.has(ticket.id)))
+        .sort((a, b) => a.number - b.number);
+}
+/** A reader over `tables()`: committed tables for a read, the draft for a write. */
+export function reader(tables, ready = yieldTurn) {
+    const t = async () => {
+        await ready();
+        return tables();
+    };
+    return {
+        board: {
+            async get() {
+                const { board } = await t();
+                if (!board)
+                    throw new OrbitError("board_not_found");
+                return copy(board);
+            }
+        },
+        states: {
+            async list() {
+                return copies([...(await t()).states].sort((a, b) => a.position - b.position));
+            },
+            async get(id) {
+                const state = find((await t()).states, id);
+                return state ? copy(state) : null;
+            }
+        },
+        labels: {
+            async list() {
+                return copies([...(await t()).labels].sort((a, b) => byCodePoint(a.name, b.name)));
+            }
+        },
+        tickets: {
+            async get(id) {
+                const ticket = find((await t()).tickets, id);
+                return ticket ? copy(ticket) : null;
+            },
+            async byNumber(number) {
+                const ticket = (await t()).tickets.find((candidate) => candidate.number === number);
+                return ticket ? copy(ticket) : null;
+            },
+            async byTitle(title) {
+                const wanted = asciiLower(title);
+                const found = (await t()).tickets
+                    .filter((ticket) => asciiLower(ticket.title) === wanted)
+                    .sort((a, b) => Number(a.archived_at !== null) - Number(b.archived_at !== null) || b.number - a.number)[0];
+                return found ? copy(found) : null;
+            },
+            async list(filter = {}) {
+                return copies(filterTickets((await t()).tickets, filter));
+            },
+            async lastNumber() {
+                return (await t()).tickets.reduce((top, ticket) => Math.max(top, ticket.number), 0);
+            }
+        },
+        ticketLabels: {
+            async list(ticketIds) {
+                const { ticketLabels } = await t();
+                const wanted = ticketIds ? new Set(ticketIds) : null;
+                return copies(ticketLabels.filter((link) => wanted === null || wanted.has(link.ticket_id)));
+            }
+        },
+        comments: {
+            async get(id) {
+                const comment = find((await t()).comments, id);
+                return comment ? copy(comment) : null;
+            },
+            async list(ticketId) {
+                const all = (await t()).comments;
+                return copies(byCreated(ticketId === undefined ? all : all.filter((comment) => comment.ticket_id === ticketId)));
+            },
+            async countByTicket(options = {}) {
+                const counts = new Map();
+                for (const comment of (await t()).comments) {
+                    if (options.forAgents && comment.omitted_for_ai === 1)
+                        continue;
+                    if (options.exceptBody !== undefined && comment.body === options.exceptBody)
+                        continue;
+                    counts.set(comment.ticket_id, (counts.get(comment.ticket_id) ?? 0) + 1);
+                }
+                return [...counts].map(([ticket_id, count]) => ({ ticket_id, count }));
+            }
+        },
+        relations: {
+            async get(id) {
+                const relation = find((await t()).relations, id);
+                return relation ? copy(relation) : null;
+            },
+            async list(ticketId) {
+                const all = (await t()).relations;
+                return copies(byCreated(ticketId === undefined ? all : all.filter((r) => r.source_ticket_id === ticketId || r.target_ticket_id === ticketId)));
+            }
+        },
+        crossBoardRelations: {
+            async list(ticketId) {
+                const all = (await t()).crossBoardRelations;
+                return copies(byCreated(ticketId === undefined ? all : all.filter((r) => r.source_ticket_id === ticketId)));
+            }
+        },
+        entries: {
+            async get(id) {
+                const entry = find((await t()).entries, id);
+                return entry ? copy(entry) : null;
+            },
+            async list() {
+                return copies(byCreated((await t()).entries));
+            }
+        },
+        verdicts: {
+            async get(id) {
+                const verdict = find((await t()).verdicts, id);
+                return verdict ? copy(verdict) : null;
+            },
+            async list(ticketId) {
+                const all = (await t()).verdicts;
+                return copies(byCreated(ticketId === undefined ? all : all.filter((v) => v.ticket_id === ticketId)));
+            }
+        },
+        attachments: {
+            async get(id) {
+                const attachment = find((await t()).attachments, id);
+                return attachment ? copy(attachment) : null;
+            },
+            async list(ticketId) {
+                const all = (await t()).attachments;
+                return copies(byCreated(ticketId === undefined ? all : all.filter((a) => a.ticket_id === ticketId)));
+            }
+        },
+        events: {
+            async list(filter = {}) {
+                const types = filter.types ? new Set(filter.types) : null;
+                return copies(byCreated((await t()).events.filter((event) => (filter.ticketId === undefined || event.ticket_id === filter.ticketId) &&
+                    (types === null || types.has(event.type)) &&
+                    (filter.since === undefined || event.created_at >= filter.since))));
+            },
+            async latest(ticketIds, types) {
+                const wanted = new Set(ticketIds);
+                const kinds = new Set(types);
+                const newest = new Map();
+                for (const event of byCreated((await t()).events)) {
+                    if (event.ticket_id !== null && wanted.has(event.ticket_id) && kinds.has(event.type))
+                        newest.set(event.ticket_id, event);
+                }
+                return copies([...newest.values()]);
+            },
+            async after(id, limit) {
+                const { events } = await t();
+                const at = events.findIndex((event) => event.id === id);
+                return at < 0 ? [] : copies(events.slice(at + 1, at + 1 + limit));
+            },
+            async last() {
+                const { events } = await t();
+                const event = events[events.length - 1];
+                return event ? copy(event) : null;
+            }
+        },
+        search: {
+            async query(text, options) {
+                const { search, tickets } = await t();
+                const open = filterTickets(tickets, { archived: false });
+                return open
+                    .filter((ticket) => {
+                    const document = search.get(ticket.id);
+                    return document !== undefined && matches(document, text);
+                })
+                    .slice(0, options.limit)
+                    .map((ticket) => ({ ticket_id: ticket.id, rank: 0 }));
+            }
+        }
+    };
+}
+/**
+ * A writer over a draft. Every check the port names is made here, in the
+ * order the port lists them, so a write that breaks one throws before it
+ * changes anything.
+ */
+export function writer(boardId, draft, log, checks, guard) {
+    const read = reader(() => draft, guard);
+    const fresh = (records, record) => {
+        if (find(records, record.id))
+            throw new OrbitError("duplicate_id");
+    };
+    const onBoard = (id) => {
+        if (id !== boardId)
+            throw new OrbitError("invalid_reference");
+    };
+    const ticketHere = (id) => {
+        if (id !== null && !find(draft.tickets, id))
+            throw new OrbitError("invalid_reference");
+    };
+    const stateHere = (id) => {
+        if (!find(draft.states, id))
+            throw new OrbitError("invalid_reference");
+    };
+    const setBoard = (board) => {
+        onBoard(board.id);
+        if (checks.slugTaken(board.slug))
+            throw new OrbitError("board_slug_taken");
+        draft.board = copy(board);
+    };
+    function mustFind(records, id, code) {
+        const record = find(records, id);
+        if (!record)
+            throw new OrbitError(code);
+        return record;
+    }
+    function removeTicket(id) {
+        mustFind(draft.tickets, id, "ticket_not_found");
+        const doomedVerdicts = new Set(draft.verdicts.filter((verdict) => verdict.ticket_id === id).map((verdict) => verdict.id));
+        draft.tickets = draft.tickets.filter((ticket) => ticket.id !== id);
+        draft.comments = draft.comments.filter((comment) => comment.ticket_id !== id);
+        draft.ticketLabels = draft.ticketLabels.filter((link) => link.ticket_id !== id);
+        draft.relations = draft.relations.filter((relation) => relation.source_ticket_id !== id && relation.target_ticket_id !== id);
+        draft.crossBoardRelations = draft.crossBoardRelations.filter((relation) => relation.source_ticket_id !== id);
+        draft.verdicts = draft.verdicts
+            .filter((verdict) => !doomedVerdicts.has(verdict.id))
+            .map((verdict) => (verdict.supersedes_prior_review_id !== null && doomedVerdicts.has(verdict.supersedes_prior_review_id) ? { ...verdict, supersedes_prior_review_id: null } : verdict));
+        draft.attachments = draft.attachments.filter((attachment) => attachment.ticket_id !== id);
+        draft.events = draft.events.map((event) => (event.ticket_id === id ? { ...event, ticket_id: null } : event));
+        draft.entries = draft.entries.map((entry) => (entry.ticket_id === id ? { ...entry, ticket_id: null } : entry));
+        draft.search.delete(id);
+    }
+    return {
+        async clear() {
+            await guard();
+            Object.assign(draft, emptyTables());
+        },
+        board: {
+            ...read.board,
+            async set(board) {
+                await guard();
+                setBoard(board);
+            },
+            async update(patch) {
+                await guard();
+                if (!draft.board)
+                    throw new OrbitError("board_not_found");
+                const next = copy(draft.board);
+                apply(next, patch);
+                setBoard(next);
+                return copy(draft.board);
+            }
+        },
+        states: {
+            ...read.states,
+            async insert(state) {
+                await guard();
+                fresh(draft.states, state);
+                onBoard(state.board_id);
+                if (draft.states.some((other) => other.name === state.name))
+                    throw new OrbitError("state_name_taken");
+                draft.states.push(copy(state));
+            },
+            async update(id, patch) {
+                await guard();
+                const state = mustFind(draft.states, id, "state_not_found");
+                if (patch.name !== undefined && draft.states.some((other) => other.id !== id && other.name === patch.name))
+                    throw new OrbitError("state_name_taken");
+                apply(state, patch);
+                return copy(state);
+            },
+            async remove(id) {
+                await guard();
+                mustFind(draft.states, id, "state_not_found");
+                if (draft.tickets.some((ticket) => ticket.state_id === id))
+                    throw new OrbitError("state_has_tickets");
+                draft.states = draft.states.filter((state) => state.id !== id);
+            }
+        },
+        labels: {
+            ...read.labels,
+            async insert(label) {
+                await guard();
+                fresh(draft.labels, label);
+                onBoard(label.board_id);
+                if (draft.labels.some((other) => other.name === label.name))
+                    throw new OrbitError("label_name_taken");
+                draft.labels.push(copy(label));
+            }
+        },
+        tickets: {
+            ...read.tickets,
+            async create(ticket) {
+                await guard();
+                const number = draft.tickets.reduce((top, other) => Math.max(top, other.number), 0) + 1;
+                const made = { ...ticket, number };
+                fresh(draft.tickets, made);
+                onBoard(made.board_id);
+                stateHere(made.state_id);
+                draft.tickets.push(made);
+                return copy(made);
+            },
+            async insert(ticket) {
+                await guard();
+                fresh(draft.tickets, ticket);
+                onBoard(ticket.board_id);
+                stateHere(ticket.state_id);
+                if (draft.tickets.some((other) => other.number === ticket.number))
+                    throw new OrbitError("ticket_number_taken");
+                draft.tickets.push(copy(ticket));
+            },
+            async update(id, patch) {
+                await guard();
+                const ticket = mustFind(draft.tickets, id, "ticket_not_found");
+                if (patch.state_id !== undefined)
+                    stateHere(patch.state_id);
+                apply(ticket, patch);
+                return copy(ticket);
+            },
+            async remove(id) {
+                await guard();
+                removeTicket(id);
+            }
+        },
+        ticketLabels: {
+            ...read.ticketLabels,
+            async set(ticketId, labelIds) {
+                await guard();
+                ticketHere(ticketId);
+                for (const labelId of labelIds)
+                    if (!find(draft.labels, labelId))
+                        throw new OrbitError("invalid_reference");
+                draft.ticketLabels = draft.ticketLabels.filter((link) => link.ticket_id !== ticketId);
+                for (const labelId of new Set(labelIds))
+                    draft.ticketLabels.push({ ticket_id: ticketId, label_id: labelId });
+            },
+            async add(ticketId, labelId) {
+                await guard();
+                ticketHere(ticketId);
+                if (!find(draft.labels, labelId))
+                    throw new OrbitError("invalid_reference");
+                if (!draft.ticketLabels.some((link) => link.ticket_id === ticketId && link.label_id === labelId)) {
+                    draft.ticketLabels.push({ ticket_id: ticketId, label_id: labelId });
+                }
+            }
+        },
+        comments: {
+            ...read.comments,
+            async insert(comment) {
+                await guard();
+                fresh(draft.comments, comment);
+                ticketHere(comment.ticket_id);
+                draft.comments.push(copy(comment));
+            },
+            async update(id, patch) {
+                await guard();
+                const comment = mustFind(draft.comments, id, "comment_not_found");
+                comment.omitted_for_ai = patch.omitted_for_ai;
+                return copy(comment);
+            }
+        },
+        relations: {
+            ...read.relations,
+            async insert(relation) {
+                await guard();
+                fresh(draft.relations, relation);
+                ticketHere(relation.source_ticket_id);
+                ticketHere(relation.target_ticket_id);
+                const repeat = draft.relations.some((other) => other.source_ticket_id === relation.source_ticket_id && other.target_ticket_id === relation.target_ticket_id && other.type === relation.type);
+                if (repeat)
+                    throw new OrbitError("relation_exists");
+                draft.relations.push(copy(relation));
+            },
+            async remove(id) {
+                await guard();
+                mustFind(draft.relations, id, "relation_not_found");
+                draft.relations = draft.relations.filter((relation) => relation.id !== id);
+            }
+        },
+        crossBoardRelations: {
+            ...read.crossBoardRelations,
+            async insert(relation) {
+                await guard();
+                fresh(draft.crossBoardRelations, relation);
+                ticketHere(relation.source_ticket_id);
+                const repeat = draft.crossBoardRelations.some((other) => other.source_ticket_id === relation.source_ticket_id &&
+                    other.target_board_id === relation.target_board_id &&
+                    other.target_ticket_id === relation.target_ticket_id &&
+                    other.type === relation.type);
+                if (repeat)
+                    throw new OrbitError("relation_exists");
+                draft.crossBoardRelations.push(copy(relation));
+            },
+            async remove(id) {
+                await guard();
+                mustFind(draft.crossBoardRelations, id, "relation_not_found");
+                draft.crossBoardRelations = draft.crossBoardRelations.filter((relation) => relation.id !== id);
+            }
+        },
+        entries: {
+            ...read.entries,
+            async insert(entry) {
+                await guard();
+                fresh(draft.entries, entry);
+                onBoard(entry.board_id);
+                ticketHere(entry.ticket_id);
+                draft.entries.push(copy(entry));
+            },
+            async update(id, patch) {
+                await guard();
+                const entry = mustFind(draft.entries, id, "board_entry_not_found");
+                apply(entry, patch);
+                return copy(entry);
+            },
+            async remove(id) {
+                await guard();
+                mustFind(draft.entries, id, "board_entry_not_found");
+                draft.entries = draft.entries.filter((entry) => entry.id !== id);
+            }
+        },
+        verdicts: {
+            ...read.verdicts,
+            async insert(verdict) {
+                await guard();
+                fresh(draft.verdicts, verdict);
+                ticketHere(verdict.ticket_id);
+                if (verdict.supersedes_prior_review_id !== null && !find(draft.verdicts, verdict.supersedes_prior_review_id))
+                    throw new OrbitError("invalid_reference");
+                draft.verdicts.push(copy(verdict));
+            }
+        },
+        attachments: {
+            ...read.attachments,
+            async insert(attachment) {
+                await guard();
+                fresh(draft.attachments, attachment);
+                onBoard(attachment.board_id);
+                ticketHere(attachment.ticket_id);
+                draft.attachments.push(copy(attachment));
+            },
+            async remove(id) {
+                await guard();
+                mustFind(draft.attachments, id, "attachment_not_found");
+                draft.attachments = draft.attachments.filter((attachment) => attachment.id !== id);
+            }
+        },
+        events: {
+            ...read.events,
+            async append(event) {
+                await guard();
+                fresh(draft.events, event);
+                ticketHere(event.ticket_id);
+                draft.events.push(copy(event));
+                log.events.push(copy(event));
+            }
+        },
+        search: {
+            ...read.search,
+            async index(ticketId, document) {
+                await guard();
+                ticketHere(ticketId);
+                draft.search.set(ticketId, { ...document });
+            },
+            async remove(ticketId) {
+                await guard();
+                draft.search.delete(ticketId);
+            }
+        }
+    };
+}

package/lib/adapters/memory/index.d.ts

@@ -0,0 +1,2 @@
+export { createMemoryStore, MemoryData } from "./store.ts";
+export { createMemoryBlobStore } from "./blobs.ts";

package/lib/adapters/memory/index.js

@@ -0,0 +1,2 @@
+export { createMemoryStore, MemoryData } from "./store.js";
+export { createMemoryBlobStore } from "./blobs.js";

package/lib/adapters/memory/search.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Search in memory: the reference for what `SearchReader.query` must match.
+ * A real adapter ranks; this one only filters, and lists hits by card number.
+ */
+import type { SearchDocument } from "../../store/types.ts";
+export declare function matches(document: SearchDocument, query: string): boolean;

package/lib/adapters/memory/search.js

@@ -0,0 +1,30 @@
+/**
+ * Search in memory: the reference for what `SearchReader.query` must match.
+ * A real adapter ranks; this one only filters, and lists hits by card number.
+ */
+import { literalQuery, queryWords } from "../../store/search-words.js";
+/**
+ * A document's words: runs of letters, digits and `_`, lowercased, accents
+ * folded (as SQLite's unicode61 tokenizer with `_` as a token character).
+ */
+function words(text) {
+    return text
+        .normalize("NFD")
+        .replace(/\p{M}/gu, "")
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}_]+/u)
+        .filter(Boolean);
+}
+const asciiLower = (text) => text.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+export function matches(document, query) {
+    const wanted = queryWords(query);
+    if (wanted.length === 0) {
+        const text = literalQuery(query);
+        if (text === null)
+            return false;
+        const literal = asciiLower(text);
+        return [document.title, document.description, document.details, document.comments].some((field) => asciiLower(field).includes(literal));
+    }
+    const have = words([document.title, document.description, document.type, document.details, document.comments].join("\n"));
+    return wanted.every((word) => have.some((token) => token.startsWith(word)));
+}

package/lib/adapters/memory/store.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The memory adapter: Orbit's storage port over plain objects. It is the
+ * reference the conformance suite is written against, the fast store for the
+ * core's own tests, and the smallest example of an adapter.
+ *
+ * Several stores can share one MemoryData, as several processes share a data
+ * folder: each write is serialised across all of them, and each hears the
+ * others' changes. A write works on a copy of the board's tables and swaps it
+ * in when the body returns, so a read always holds one committed state.
+ */
+import type { BoardChange, Id, RegisteredBoard } from "../../core/model.ts";
+import type { OrbitStore } from "../../store/types.ts";
+import type { Tables, WriteLog } from "./board.ts";
+/** Everything one Orbit keeps, shared by every memory store opened over it. */
+export declare class MemoryData {
+    /** In the order boards were registered. */
+    directory: RegisteredBoard[];
+    readonly settings: Map<string, string>;
+    /** Each board's committed tables. A write replaces them whole and never changes them in place. */
+    readonly tables: Map<string, Tables>;
+    private readonly tails;
+    private readonly listeners;
+    /** Runs `body` once every earlier body with the same key has finished. */
+    exclusive<T>(key: string, body: () => Promise<T>): Promise<T>;
+    listen(boardId: Id, listener: (change: BoardChange) => void): () => void;
+    /** Tells every listener on the board, after the write that made them has committed. */
+    announce(boardId: Id, log: WriteLog): void;
+    entry(id: Id): RegisteredBoard | undefined;
+    slugTaken(slug: string, exceptId: Id): boolean;
+    /** Swaps in a write's tables and, when the write changed the board's record, brings its listing in line (as SQLite does). */
+    commit(boardId: Id, draft: Tables): void;
+}
+/** A store over `data`; pass the same MemoryData to two stores to have two views of one Orbit. */
+export declare function createMemoryStore(data?: MemoryData): OrbitStore;