@wtfalch/threads 0.1.0

package/dist/threads.js

@@ -0,0 +1,626 @@
+import { and, asc, desc, eq, inArray, isNull, ne, sql } from 'drizzle-orm';
+import { CATEGORY, ThreadsError, categorySubject, } from './gates.js';
+import { schema, threadCategories, threadComments, threadOutbox, threadPeople, threadSubscriptions, threadVotes, threads, } from './schema.js';
+export const DEFAULT_LIMITS = { threadsPerHour: 5, commentsPerTenMinutes: 30 };
+export function slugify(title) {
+    return (title
+        .toLowerCase()
+        .normalize('NFKD')
+        .replace(/\p{M}/gu, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80) || 'thread');
+}
+function subjectOf(thread) {
+    return { kind: thread.subjectKind, id: thread.subjectId };
+}
+export function createThreads(opts) {
+    const { db, gates } = opts;
+    const limits = { ...DEFAULT_LIMITS, ...opts.limits };
+    const now = opts.now ?? (() => new Date());
+    async function mayRead(subject, who) {
+        if (!(await gates.read(subject, who))) {
+            throw new ThreadsError('forbidden', 'not allowed to read here');
+        }
+    }
+    async function mayWrite(subject, who) {
+        if (!who || !(await gates.write(subject, who))) {
+            throw new ThreadsError('forbidden', 'not allowed to write here');
+        }
+        return who;
+    }
+    async function mayModerate(subject, who) {
+        if (!who || !(await gates.moderate(subject, who))) {
+            throw new ThreadsError('forbidden', 'not allowed to moderate here');
+        }
+        return who;
+    }
+    async function moderates(subject, who) {
+        return who !== null && (await gates.moderate(subject, who));
+    }
+    /**
+     * Records the person and returns the row. Called on every write, so the
+     * name follows the issuer; the email moves only once the issuer verified it,
+     * because it is where notifications go.
+     */
+    async function seen(who) {
+        const set = who.emailVerified
+            ? { name: who.name, email: who.email, lastSeenAt: sql `now()` }
+            : { name: who.name, lastSeenAt: sql `now()` };
+        const [row] = await db
+            .insert(threadPeople)
+            .values({
+            id: who.id,
+            name: who.name,
+            email: who.emailVerified ? who.email : null,
+            lastSeenAt: sql `now()`,
+        })
+            .onConflictDoUpdate({ target: threadPeople.id, set })
+            .returning();
+        if (!row)
+            throw new Error('seen: no row');
+        return row;
+    }
+    async function inGoodStanding(who) {
+        const person = await seen(who);
+        if (person.standing !== 'ok') {
+            throw new ThreadsError('standing', `this account is ${person.standing}`);
+        }
+        return person;
+    }
+    async function underLimit(table, authorId, windowMs, max, what) {
+        const since = new Date(now().getTime() - windowMs);
+        const [row] = await db
+            .select({ n: sql `count(*)::int` })
+            .from(table)
+            .where(and(eq(table.authorId, authorId), sql `${table.createdAt} > ${since}`));
+        if ((row?.n ?? 0) >= max)
+            throw new ThreadsError('rate_limited', `too many ${what}, try later`);
+    }
+    // ---- categories --------------------------------------------------------
+    async function categories() {
+        return db
+            .select()
+            .from(threadCategories)
+            .orderBy(asc(threadCategories.position), asc(threadCategories.name));
+    }
+    async function category(slug) {
+        const [row] = await db.select().from(threadCategories).where(eq(threadCategories.slug, slug));
+        return row ?? null;
+    }
+    async function categoryById(id) {
+        if (!Number.isFinite(id))
+            return null;
+        const [row] = await db.select().from(threadCategories).where(eq(threadCategories.id, id));
+        return row ?? null;
+    }
+    /** Categories are the owner's: the moderate gate on the subject `category:*`. */
+    async function createCategory(who, input) {
+        await mayModerate(categorySubject('*'), who);
+        const [row] = await db
+            .insert(threadCategories)
+            .values({
+            slug: input.slug,
+            name: input.name,
+            description: input.description ?? null,
+            kind: input.kind ?? 'discussion',
+            position: input.position ?? 0,
+        })
+            .returning();
+        if (!row)
+            throw new Error('createCategory: no row');
+        return row;
+    }
+    // ---- reading -----------------------------------------------------------
+    const authorName = sql `(select ${threadPeople.name} from ${threadPeople} where ${threadPeople.id} = ${threads.authorId})`;
+    async function listThreads(subject, who, options = {}) {
+        await mayRead(subject, who);
+        const mod = await moderates(subject, who);
+        const page = Math.max(1, options.page ?? 1);
+        const perPage = Math.min(100, Math.max(1, options.perPage ?? 25));
+        const where = and(eq(threads.subjectKind, subject.kind), eq(threads.subjectId, subject.id), mod ? undefined : eq(threads.hidden, false), options.status ? eq(threads.status, options.status) : undefined);
+        const order = options.sort === 'newest'
+            ? [desc(threads.pinned), desc(threads.createdAt)]
+            : options.sort === 'votes'
+                ? [desc(threads.pinned), desc(threads.voteCount), desc(threads.lastActivityAt)]
+                : [desc(threads.pinned), desc(threads.lastActivityAt)];
+        const items = await db
+            .select({ ...threadColumns(), authorName })
+            .from(threads)
+            .where(where)
+            .orderBy(...order)
+            .limit(perPage)
+            .offset((page - 1) * perPage);
+        const [count] = await db.select({ n: sql `count(*)::int` }).from(threads).where(where);
+        return { items, page, perPage, total: count?.n ?? 0 };
+    }
+    async function thread(id, who) {
+        const [row] = await db
+            .select({ ...threadColumns(), authorName })
+            .from(threads)
+            .where(eq(threads.id, id));
+        if (!row)
+            throw new ThreadsError('not_found', 'no such thread');
+        await mayRead(subjectOf(row), who);
+        if (row.hidden && !(await moderates(subjectOf(row), who))) {
+            throw new ThreadsError('not_found', 'no such thread');
+        }
+        return row;
+    }
+    /** The thread a host subject's comment section belongs to, or null before the first comment. */
+    async function threadFor(subject, who) {
+        await mayRead(subject, who);
+        const [row] = await db
+            .select({ ...threadColumns(), authorName })
+            .from(threads)
+            .where(and(eq(threads.subjectKind, subject.kind), eq(threads.subjectId, subject.id)));
+        return row ?? null;
+    }
+    /**
+     * Every comment of a thread, ordered by path, which is depth-first in
+     * creation order; `buildTree` turns it into the tree. With `root`, only
+     * that comment and what is under it, for a "continue this thread" page.
+     */
+    async function comments(threadId, who, options = {}) {
+        const t = await thread(threadId, who);
+        const mod = await moderates(subjectOf(t), who);
+        let where = eq(threadComments.threadId, threadId);
+        if (options.root !== undefined) {
+            const [root] = await db
+                .select({ path: threadComments.path })
+                .from(threadComments)
+                .where(and(eq(threadComments.id, options.root), eq(threadComments.threadId, threadId)));
+            if (!root)
+                throw new ThreadsError('not_found', 'no such comment');
+            where = and(where, sql `${threadComments.path} <@ ${root.path}::ltree`) ?? where;
+        }
+        const rows = await db
+            .select({
+            id: threadComments.id,
+            threadId: threadComments.threadId,
+            replyTo: threadComments.replyTo,
+            path: threadComments.path,
+            authorId: threadComments.authorId,
+            body: threadComments.body,
+            hidden: threadComments.hidden,
+            createdAt: threadComments.createdAt,
+            updatedAt: threadComments.updatedAt,
+            authorName: sql `(select ${threadPeople.name} from ${threadPeople} where ${threadPeople.id} = ${threadComments.authorId})`,
+        })
+            .from(threadComments)
+            .where(where)
+            .orderBy(asc(threadComments.path));
+        return rows.map((r) => (r.hidden && !mod ? { ...r, body: null } : r));
+    }
+    /**
+     * Full-text over titles and bodies. Scoped to one subject kind, and every
+     * distinct subject in the result is asked of the read gate before a row
+     * of it is returned: a hit under a private subject is dropped, not shown.
+     */
+    async function search(q, who, options = {}) {
+        const term = q.trim();
+        if (!term)
+            return [];
+        const kind = options.subjectKind ?? CATEGORY;
+        const rows = await db
+            .select({ ...threadColumns(), authorName })
+            .from(threads)
+            .where(and(eq(threads.subjectKind, kind), eq(threads.hidden, false), sql `to_tsvector('simple', coalesce(${threads.title}, '') || ' ' || coalesce(${threads.body}, '')) @@ plainto_tsquery('simple', ${term})`))
+            .orderBy(desc(threads.lastActivityAt))
+            .limit(Math.min(100, options.limit ?? 25));
+        return gateRows(rows, who);
+    }
+    async function gateRows(rows, who) {
+        const allowed = new Map();
+        const out = [];
+        for (const row of rows) {
+            const key = `${row.subjectKind} ${row.subjectId}`;
+            let ok = allowed.get(key);
+            if (ok === undefined) {
+                ok = await gates.read(subjectOf(row), who);
+                allowed.set(key, ok);
+            }
+            if (ok)
+                out.push(row);
+        }
+        return out;
+    }
+    /** Every feedback thread the person may see, grouped by status. */
+    async function roadmap(who) {
+        const feedback = await db
+            .select({ id: threadCategories.id })
+            .from(threadCategories)
+            .where(eq(threadCategories.kind, 'feedback'));
+        const groups = {
+            open: [],
+            planned: [],
+            in_progress: [],
+            done: [],
+            declined: [],
+        };
+        if (feedback.length === 0)
+            return groups;
+        const rows = await db
+            .select({ ...threadColumns(), authorName })
+            .from(threads)
+            .where(and(eq(threads.subjectKind, CATEGORY), inArray(threads.subjectId, feedback.map((c) => String(c.id))), eq(threads.hidden, false), isNull(threads.duplicateOf)))
+            .orderBy(desc(threads.voteCount), desc(threads.lastActivityAt));
+        for (const row of await gateRows(rows, who)) {
+            groups[row.status ?? 'open'].push(row);
+        }
+        return groups;
+    }
+    // ---- writing -----------------------------------------------------------
+    async function post(who, subject, input) {
+        if (subject.kind !== CATEGORY) {
+            throw new ThreadsError('invalid', 'a thread with a title belongs in a category; comment on the subject instead');
+        }
+        const person = await inGoodStanding(await mayWrite(subject, who));
+        const cat = await categoryById(Number(subject.id));
+        if (!cat)
+            throw new ThreadsError('not_found', 'no such category');
+        const title = input.title.trim();
+        const body = input.body.trim();
+        if (title.length < 3 || title.length > 200) {
+            throw new ThreadsError('invalid', 'a title is 3 to 200 characters');
+        }
+        if (body.length < 1 || body.length > 20_000) {
+            throw new ThreadsError('invalid', 'a body is 1 to 20000 characters');
+        }
+        await underLimit(threads, person.id, 60 * 60 * 1000, limits.threadsPerHour, 'new threads');
+        return db.transaction(async (tx) => {
+            const [row] = await tx
+                .insert(threads)
+                .values({
+                subjectKind: subject.kind,
+                subjectId: subject.id,
+                authorId: person.id,
+                title,
+                slug: slugify(title),
+                body,
+                status: cat.kind === 'feedback' ? 'open' : null,
+            })
+                .returning();
+            if (!row)
+                throw new Error('post: no row');
+            await tx
+                .insert(threadSubscriptions)
+                .values({ threadId: row.id, personId: person.id, reason: 'author' })
+                .onConflictDoNothing();
+            return row;
+        });
+    }
+    async function comment(who, threadId, input) {
+        const [t] = await db.select().from(threads).where(eq(threads.id, threadId));
+        if (!t)
+            throw new ThreadsError('not_found', 'no such thread');
+        return addComment(who, t, input);
+    }
+    /** Comment under a host subject; the thread is created on the first comment. */
+    async function commentOn(who, subject, input) {
+        if (subject.kind === CATEGORY) {
+            throw new ThreadsError('invalid', 'a category takes threads, not comments');
+        }
+        await mayWrite(subject, who);
+        const bySubject = and(eq(threads.subjectKind, subject.kind), eq(threads.subjectId, subject.id));
+        const [existing] = await db.select().from(threads).where(bySubject);
+        let t = existing;
+        if (!t) {
+            const [created] = await db
+                .insert(threads)
+                .values({ subjectKind: subject.kind, subjectId: subject.id })
+                .onConflictDoNothing()
+                .returning();
+            t = created ?? (await db.select().from(threads).where(bySubject))[0];
+        }
+        if (!t)
+            throw new Error('commentOn: no thread');
+        return addComment(who, t, input);
+    }
+    async function addComment(who, t, input) {
+        const subject = subjectOf(t);
+        const person = await inGoodStanding(await mayWrite(subject, who));
+        const mod = await moderates(subject, who);
+        if (t.hidden && !mod)
+            throw new ThreadsError('not_found', 'no such thread');
+        if (t.locked && !mod)
+            throw new ThreadsError('locked', 'this thread is locked');
+        const body = input.body.trim();
+        if (body.length < 1 || body.length > 20_000) {
+            throw new ThreadsError('invalid', 'a comment is 1 to 20000 characters');
+        }
+        if (input.replyTo != null) {
+            const [parent] = await db
+                .select({ id: threadComments.id })
+                .from(threadComments)
+                .where(and(eq(threadComments.id, input.replyTo), eq(threadComments.threadId, t.id)));
+            if (!parent)
+                throw new ThreadsError('not_found', 'no such comment to reply to');
+        }
+        await underLimit(threadComments, person.id, 10 * 60 * 1000, limits.commentsPerTenMinutes, 'comments');
+        return db.transaction(async (tx) => {
+            const [row] = await tx
+                .insert(threadComments)
+                .values({
+                threadId: t.id,
+                replyTo: input.replyTo ?? null,
+                authorId: person.id,
+                body,
+                path: '',
+            })
+                .returning();
+            if (!row)
+                throw new Error('comment: no row');
+            await tx
+                .insert(threadSubscriptions)
+                .values({ threadId: t.id, personId: person.id, reason: 'commented' })
+                .onConflictDoNothing();
+            const listeners = await tx
+                .select({ personId: threadSubscriptions.personId })
+                .from(threadSubscriptions)
+                .innerJoin(threadPeople, eq(threadPeople.id, threadSubscriptions.personId))
+                .where(and(eq(threadSubscriptions.threadId, t.id), eq(threadSubscriptions.muted, false), ne(threadSubscriptions.personId, person.id), sql `${threadPeople.email} is not null`));
+            if (listeners.length > 0) {
+                await tx.insert(threadOutbox).values(listeners.map((l) => ({
+                    personId: l.personId,
+                    threadId: t.id,
+                    commentId: row.id,
+                    kind: 'comment',
+                })));
+            }
+            return row;
+        });
+    }
+    async function vote(who, threadId) {
+        const [t] = await db.select().from(threads).where(eq(threads.id, threadId));
+        if (!t)
+            throw new ThreadsError('not_found', 'no such thread');
+        const person = await inGoodStanding(await mayWrite(subjectOf(t), who));
+        if (t.subjectKind !== CATEGORY ||
+            (await categoryById(Number(t.subjectId)))?.kind !== 'feedback') {
+            throw new ThreadsError('invalid', 'votes belong to feedback');
+        }
+        await db.transaction(async (tx) => {
+            await tx.insert(threadVotes).values({ threadId, personId: person.id }).onConflictDoNothing();
+            await tx
+                .insert(threadSubscriptions)
+                .values({ threadId, personId: person.id, reason: 'voted' })
+                .onConflictDoNothing();
+        });
+    }
+    async function unvote(who, threadId) {
+        const [t] = await db.select().from(threads).where(eq(threads.id, threadId));
+        if (!t)
+            throw new ThreadsError('not_found', 'no such thread');
+        const person = await mayWrite(subjectOf(t), who);
+        await db
+            .delete(threadVotes)
+            .where(and(eq(threadVotes.threadId, threadId), eq(threadVotes.personId, person.id)));
+    }
+    async function voted(who, threadIds) {
+        if (!who || threadIds.length === 0)
+            return new Set();
+        const rows = await db
+            .select({ threadId: threadVotes.threadId })
+            .from(threadVotes)
+            .where(and(eq(threadVotes.personId, who.id), inArray(threadVotes.threadId, threadIds)));
+        return new Set(rows.map((r) => r.threadId));
+    }
+    async function subscribe(who, threadId, muted = false) {
+        const [t] = await db.select().from(threads).where(eq(threads.id, threadId));
+        if (!t)
+            throw new ThreadsError('not_found', 'no such thread');
+        const person = await seen(await mayWrite(subjectOf(t), who));
+        await db
+            .insert(threadSubscriptions)
+            .values({ threadId, personId: person.id, reason: 'manual', muted })
+            .onConflictDoUpdate({
+            target: [threadSubscriptions.threadId, threadSubscriptions.personId],
+            set: { muted },
+        });
+    }
+    // ---- moderating --------------------------------------------------------
+    async function moderated(who, threadId) {
+        const [t] = await db.select().from(threads).where(eq(threads.id, threadId));
+        if (!t)
+            throw new ThreadsError('not_found', 'no such thread');
+        return { t, who: await mayModerate(subjectOf(t), who) };
+    }
+    async function setFlag(who, threadId, flag, value) {
+        await moderated(who, threadId);
+        await db
+            .update(threads)
+            .set({ [flag]: value, updatedAt: sql `now()` })
+            .where(eq(threads.id, threadId));
+    }
+    async function hideComment(who, commentId, hidden = true) {
+        const [c] = await db.select().from(threadComments).where(eq(threadComments.id, commentId));
+        if (!c)
+            throw new ThreadsError('not_found', 'no such comment');
+        await moderated(who, c.threadId);
+        await db
+            .update(threadComments)
+            .set({ hidden, updatedAt: sql `now()` })
+            .where(eq(threadComments.id, commentId));
+    }
+    async function move(who, threadId, categoryId) {
+        const { t } = await moderated(who, threadId);
+        if (t.subjectKind !== CATEGORY)
+            throw new ThreadsError('invalid', 'only a forum thread moves');
+        const cat = await categoryById(categoryId);
+        if (!cat)
+            throw new ThreadsError('not_found', 'no such category');
+        await mayModerate(categorySubject(categoryId), who);
+        await db
+            .update(threads)
+            .set({
+            subjectId: String(categoryId),
+            status: cat.kind === 'feedback' ? (t.status ?? 'open') : null,
+            updatedAt: sql `now()`,
+        })
+            .where(eq(threads.id, threadId));
+    }
+    async function setStatus(who, threadId, status) {
+        const { t } = await moderated(who, threadId);
+        if (t.status === null)
+            throw new ThreadsError('invalid', 'only feedback has a status');
+        if (t.status === status)
+            return;
+        await db.transaction(async (tx) => {
+            await tx
+                .update(threads)
+                .set({ status, updatedAt: sql `now()` })
+                .where(eq(threads.id, threadId));
+            const listeners = await tx
+                .select({ personId: threadSubscriptions.personId })
+                .from(threadSubscriptions)
+                .innerJoin(threadPeople, eq(threadPeople.id, threadSubscriptions.personId))
+                .where(and(eq(threadSubscriptions.threadId, threadId), eq(threadSubscriptions.muted, false), sql `${threadPeople.email} is not null`));
+            if (listeners.length > 0) {
+                await tx.insert(threadOutbox).values(listeners.map((l) => ({
+                    personId: l.personId,
+                    threadId,
+                    kind: 'status',
+                })));
+            }
+        });
+    }
+    /** The duplicate points at the original and its votes move there; a page redirects. */
+    async function markDuplicate(who, threadId, ofId) {
+        const { t } = await moderated(who, threadId);
+        const [original] = await db.select().from(threads).where(eq(threads.id, ofId));
+        if (!original || original.id === t.id)
+            throw new ThreadsError('not_found', 'no such original');
+        await db.transaction(async (tx) => {
+            const votes = await tx.select().from(threadVotes).where(eq(threadVotes.threadId, threadId));
+            if (votes.length > 0) {
+                await tx
+                    .insert(threadVotes)
+                    .values(votes.map((v) => ({ threadId: ofId, personId: v.personId })))
+                    .onConflictDoNothing();
+                await tx.delete(threadVotes).where(eq(threadVotes.threadId, threadId));
+            }
+            await tx
+                .update(threads)
+                .set({
+                duplicateOf: ofId,
+                status: t.status === null ? null : 'declined',
+                locked: true,
+                updatedAt: sql `now()`,
+            })
+                .where(eq(threads.id, threadId));
+        });
+    }
+    /** Standing is per person, not per subject; the gate asked is `category:*`, the owner's. */
+    async function setStanding(who, personId, standing) {
+        await mayModerate(categorySubject('*'), who);
+        await db.update(threadPeople).set({ standing }).where(eq(threadPeople.id, personId));
+    }
+    // ---- outbox ------------------------------------------------------------
+    /**
+     * Claims up to `batch` unsent rows with FOR UPDATE SKIP LOCKED and hands
+     * each to `send`. A send that throws is recorded and retried by a later
+     * drain, up to five times. Run this from a small loop in the app's own
+     * process; it is safe to run from two.
+     */
+    async function drainOutbox(send, batch = 20) {
+        const claimed = await db.transaction(async (tx) => {
+            const rows = await tx
+                .select()
+                .from(threadOutbox)
+                .where(and(isNull(threadOutbox.sentAt), sql `${threadOutbox.attempts} < 5`))
+                .orderBy(asc(threadOutbox.createdAt))
+                .limit(batch)
+                .for('update', { skipLocked: true });
+            if (rows.length === 0)
+                return rows;
+            await tx
+                .update(threadOutbox)
+                .set({ claimedAt: sql `now()`, attempts: sql `${threadOutbox.attempts} + 1` })
+                .where(inArray(threadOutbox.id, rows.map((r) => r.id)));
+            return rows;
+        });
+        let sent = 0;
+        for (const row of claimed) {
+            try {
+                const [to] = await db.select().from(threadPeople).where(eq(threadPeople.id, row.personId));
+                const [t] = await db.select().from(threads).where(eq(threads.id, row.threadId));
+                const [c] = row.commentId === null
+                    ? [null]
+                    : await db.select().from(threadComments).where(eq(threadComments.id, row.commentId));
+                if (!to?.email || !t)
+                    throw new Error('outbox row points at nothing');
+                await send({
+                    id: row.id,
+                    kind: row.kind,
+                    to: { id: to.id, name: to.name, email: to.email },
+                    thread: t,
+                    comment: c ?? null,
+                });
+                await db
+                    .update(threadOutbox)
+                    .set({ sentAt: sql `now()`, lastError: null })
+                    .where(eq(threadOutbox.id, row.id));
+                sent += 1;
+            }
+            catch (e) {
+                await db
+                    .update(threadOutbox)
+                    .set({ lastError: e instanceof Error ? e.message : String(e) })
+                    .where(eq(threadOutbox.id, row.id));
+            }
+        }
+        return sent;
+    }
+    return {
+        seen,
+        categories,
+        category,
+        categoryById,
+        createCategory,
+        listThreads,
+        thread,
+        threadFor,
+        comments,
+        search,
+        roadmap,
+        post,
+        comment,
+        commentOn,
+        vote,
+        unvote,
+        voted,
+        subscribe,
+        pin: (who, id, on = true) => setFlag(who, id, 'pinned', on),
+        lock: (who, id, on = true) => setFlag(who, id, 'locked', on),
+        hide: (who, id, on = true) => setFlag(who, id, 'hidden', on),
+        hideComment,
+        move,
+        setStatus,
+        markDuplicate,
+        setStanding,
+        drainOutbox,
+    };
+}
+function threadColumns() {
+    return {
+        id: threads.id,
+        subjectKind: threads.subjectKind,
+        subjectId: threads.subjectId,
+        authorId: threads.authorId,
+        title: threads.title,
+        slug: threads.slug,
+        body: threads.body,
+        pinned: threads.pinned,
+        locked: threads.locked,
+        hidden: threads.hidden,
+        status: threads.status,
+        duplicateOf: threads.duplicateOf,
+        commentCount: threads.commentCount,
+        voteCount: threads.voteCount,
+        lastActivityAt: threads.lastActivityAt,
+        createdAt: threads.createdAt,
+        updatedAt: threads.updatedAt,
+    };
+}
+export { schema };

package/dist/tree.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The comment tree, from rows to nodes and back to the pieces a page shows.
+ *
+ * `path` is the chain of zero-padded comment ids from the top of the thread
+ * to the comment, written by a trigger, so rows ordered by `path` are already
+ * depth-first in creation order. Building the tree is one pass over that
+ * order; nothing here touches the database.
+ */
+export declare const LABEL_WIDTH = 12;
+export declare function label(id: number): string;
+export declare function depthOf(path: string): number;
+export interface TreeRow {
+    id: number;
+    replyTo: number | null;
+    path: string;
+}
+export type Node<T extends TreeRow> = T & {
+    /** Distance from the top of the tree being built, not of the thread. */
+    depth: number;
+    children: Node<T>[];
+    /** Every comment under this one, at any depth. */
+    descendants: number;
+};
+/**
+ * Rows to a forest. Pass `root` to build only the subtree under one comment,
+ * with that comment at depth 0; the rows must already be that subtree, or the
+ * thread's whole set, either way ordered by `path`.
+ */
+export declare function buildTree<T extends TreeRow>(rows: T[], opts?: {
+    root?: number;
+}): Node<T>[];
+/** Every node in depth-first order, which is the order the page draws them. */
+export declare function walk<T extends TreeRow>(nodes: Node<T>[]): Node<T>[];
+export type Folded<T extends TreeRow> = T & {
+    depth: number;
+    descendants: number;
+    children: Folded<T>[];
+    /** How many comments sit under this one and are not drawn. */
+    folded: number;
+};
+/**
+ * What a page draws past the depth it is willing to indent: the node stays,
+ * its children are replaced by a count and a link. Eight is the reference
+ * rendering's choice; a place that renders flat passes 0, one that never
+ * folds passes Infinity.
+ */
+export declare function collapse<T extends TreeRow>(nodes: Node<T>[], at: number): Folded<T>[];