@wtfalch/threads 0.1.0

package/dist/schema.js

@@ -0,0 +1,129 @@
+import { sql } from 'drizzle-orm';
+import { bigint, boolean, customType, index, integer, pgTable, primaryKey, text, timestamp, uniqueIndex, } from 'drizzle-orm/pg-core';
+/**
+ * The tables, mirrored from `migrations/0001_threads.sql`, which is the
+ * source of truth: the SQL carries the triggers, checks and partial indexes
+ * that drizzle-kit does not generate. An app spreads these into its own
+ * schema module so `db.query` and the types know them.
+ *
+ * Every user-owned row keys by the issuer's user id, a string.
+ */
+export const ltree = customType({
+    dataType() {
+        return 'ltree';
+    },
+});
+export const threadPeople = pgTable('thread_people', {
+    id: text('id').primaryKey(),
+    name: text('name'),
+    email: text('email'),
+    standing: text('standing', { enum: ['ok', 'muted', 'banned'] })
+        .notNull()
+        .default('ok'),
+    lastSeenAt: timestamp('last_seen_at', { withTimezone: true }).notNull().default(sql `now()`),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().default(sql `now()`),
+});
+export const threadCategories = pgTable('thread_categories', {
+    id: bigint('id', { mode: 'number' }).primaryKey().generatedAlwaysAsIdentity(),
+    slug: text('slug').notNull().unique(),
+    name: text('name').notNull(),
+    description: text('description'),
+    kind: text('kind', { enum: ['discussion', 'feedback'] })
+        .notNull()
+        .default('discussion'),
+    position: integer('position').notNull().default(0),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().default(sql `now()`),
+});
+export const threads = pgTable('threads', {
+    id: bigint('id', { mode: 'number' }).primaryKey().generatedAlwaysAsIdentity(),
+    subjectKind: text('subject_kind').notNull(),
+    subjectId: text('subject_id').notNull(),
+    authorId: text('author_id').references(() => threadPeople.id),
+    title: text('title'),
+    slug: text('slug'),
+    body: text('body'),
+    pinned: boolean('pinned').notNull().default(false),
+    locked: boolean('locked').notNull().default(false),
+    hidden: boolean('hidden').notNull().default(false),
+    status: text('status', { enum: ['open', 'planned', 'in_progress', 'done', 'declined'] }),
+    duplicateOf: bigint('duplicate_of', { mode: 'number' }),
+    commentCount: integer('comment_count').notNull().default(0),
+    voteCount: integer('vote_count').notNull().default(0),
+    lastActivityAt: timestamp('last_activity_at', { withTimezone: true })
+        .notNull()
+        .default(sql `now()`),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().default(sql `now()`),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().default(sql `now()`),
+}, (t) => [
+    index('threads_subject_idx').on(t.subjectKind, t.subjectId, t.pinned, t.lastActivityAt),
+    uniqueIndex('threads_host_subject_idx')
+        .on(t.subjectKind, t.subjectId)
+        .where(sql `${t.subjectKind} <> 'category'`),
+    index('threads_author_idx').on(t.authorId, t.createdAt),
+]);
+export const threadComments = pgTable('thread_comments', {
+    id: bigint('id', { mode: 'number' }).primaryKey().generatedAlwaysAsIdentity(),
+    threadId: bigint('thread_id', { mode: 'number' })
+        .notNull()
+        .references(() => threads.id, { onDelete: 'cascade' }),
+    replyTo: bigint('reply_to', { mode: 'number' }),
+    /** Written by a trigger; never set it from here. */
+    path: ltree('path').notNull(),
+    authorId: text('author_id')
+        .notNull()
+        .references(() => threadPeople.id),
+    body: text('body').notNull(),
+    hidden: boolean('hidden').notNull().default(false),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().default(sql `now()`),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().default(sql `now()`),
+}, (t) => [
+    index('thread_comments_thread_path_idx').on(t.threadId, t.path),
+    index('thread_comments_author_idx').on(t.authorId, t.createdAt),
+]);
+export const threadVotes = pgTable('thread_votes', {
+    threadId: bigint('thread_id', { mode: 'number' })
+        .notNull()
+        .references(() => threads.id, { onDelete: 'cascade' }),
+    personId: text('person_id')
+        .notNull()
+        .references(() => threadPeople.id),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().default(sql `now()`),
+}, (t) => [primaryKey({ columns: [t.threadId, t.personId] })]);
+export const threadSubscriptions = pgTable('thread_subscriptions', {
+    threadId: bigint('thread_id', { mode: 'number' })
+        .notNull()
+        .references(() => threads.id, { onDelete: 'cascade' }),
+    personId: text('person_id')
+        .notNull()
+        .references(() => threadPeople.id),
+    reason: text('reason', { enum: ['author', 'commented', 'voted', 'manual'] }).notNull(),
+    muted: boolean('muted').notNull().default(false),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().default(sql `now()`),
+}, (t) => [primaryKey({ columns: [t.threadId, t.personId] })]);
+export const threadOutbox = pgTable('thread_outbox', {
+    id: bigint('id', { mode: 'number' }).primaryKey().generatedAlwaysAsIdentity(),
+    personId: text('person_id')
+        .notNull()
+        .references(() => threadPeople.id),
+    threadId: bigint('thread_id', { mode: 'number' })
+        .notNull()
+        .references(() => threads.id, { onDelete: 'cascade' }),
+    commentId: bigint('comment_id', { mode: 'number' }).references(() => threadComments.id, {
+        onDelete: 'cascade',
+    }),
+    kind: text('kind', { enum: ['comment', 'status'] }).notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().default(sql `now()`),
+    claimedAt: timestamp('claimed_at', { withTimezone: true }),
+    sentAt: timestamp('sent_at', { withTimezone: true }),
+    attempts: integer('attempts').notNull().default(0),
+    lastError: text('last_error'),
+});
+export const schema = {
+    threadPeople,
+    threadCategories,
+    threads,
+    threadComments,
+    threadVotes,
+    threadSubscriptions,
+    threadOutbox,
+};

package/dist/threads.css

@@ -0,0 +1,182 @@
+/*
+ * @wtfalch/threads — layout for the reference components. Says where things
+ * stand, never how they look: every value is a token from @wtfalch/design,
+ * so a forum in lokessmie draws lokessmie's without this file knowing.
+ * Classes carry the `threads-` prefix; the package's own are unprefixed.
+ */
+
+.threads-stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+}
+
+.threads-stack-tight {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.threads-meta {
+  color: var(--muted);
+  font-size: var(--text-sm);
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  align-items: baseline;
+}
+
+.threads-meta a {
+  color: inherit;
+}
+
+.threads-title {
+  margin: 0;
+  font-size: var(--text-xl);
+  line-height: 1.25;
+}
+
+.threads-title a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.threads-title a:hover {
+  text-decoration: underline;
+}
+
+.threads-head {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.threads-body {
+  padding-block: var(--space-2);
+}
+
+.threads-bar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  align-items: center;
+}
+
+.threads-bar-grow {
+  flex: 1;
+}
+
+/* The tree. Each level is a rail down the left, drawn from the border token,
+ * so depth reads at a glance without a background per level. */
+.threads-comments {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+.threads-comment {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.threads-comment-head {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  align-items: baseline;
+  font-size: var(--text-sm);
+}
+
+.threads-comment-author {
+  font-weight: 600;
+}
+
+.threads-comment-body {
+  font-size: var(--text-md);
+}
+
+.threads-comment-hidden {
+  color: var(--muted);
+  font-style: italic;
+}
+
+.threads-comment-actions {
+  display: flex;
+  gap: var(--space-1);
+  align-items: center;
+}
+
+.threads-children {
+  margin-top: var(--space-2);
+  padding-left: var(--space-4);
+  border-left: 2px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+.threads-fold {
+  font-size: var(--text-sm);
+}
+
+.threads-form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+.threads-form-actions {
+  display: flex;
+  gap: var(--space-2);
+  justify-content: flex-end;
+}
+
+.threads-note {
+  color: var(--muted);
+  font-size: var(--text-sm);
+}
+
+.threads-section-title {
+  margin: 0;
+  font-size: var(--text-md);
+  color: var(--muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.threads-vote {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+}
+
+/* Links the package draws itself. A name is text that happens to be a link;
+ * everything smaller (a fold, a note, a time) takes the accent. */
+.threads-link {
+  color: var(--text);
+  text-decoration: underline;
+  text-decoration-color: var(--border-strong, var(--border));
+  text-underline-offset: 0.15em;
+}
+
+.threads-link:hover {
+  text-decoration-color: currentColor;
+}
+
+.threads-fold a,
+.threads-note a,
+.threads-meta a {
+  color: var(--accent);
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
+.threads-link:focus-visible,
+.threads-fold a:focus-visible,
+.threads-note a:focus-visible,
+.threads-meta a:focus-visible {
+  outline: none;
+  border-radius: var(--radius-sm);
+  box-shadow: var(--focus-ring);
+}

package/dist/threads.d.ts

@@ -0,0 +1,109 @@
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import { type Gates, type Subject, type Who } from './gates.js';
+import { type Category, type Comment, type Person, type Thread, type ThreadStatus, schema } from './schema.js';
+/**
+ * The core: every query and every action, bound to one app's database and
+ * the gates the app passed. A page or a Server Action in the app calls these
+ * with the person from its session; nothing here reads a cookie or a request.
+ *
+ * The gate is applied here and nowhere else. A list, a count, a search or a
+ * thread page that forgets it leaks a private subject into a public result,
+ * so the only way to read is through a function in this file that asks first.
+ */
+export type Db = PgDatabase<PgQueryResultHKT, any>;
+export interface Limits {
+    /** Threads one person may open per hour. */
+    threadsPerHour: number;
+    /** Comments one person may post per ten minutes. */
+    commentsPerTenMinutes: number;
+}
+export interface ThreadsOptions {
+    db: Db;
+    gates: Gates;
+    limits?: Partial<Limits>;
+    now?: () => Date;
+}
+export type Sort = 'activity' | 'newest' | 'votes';
+export interface ListOptions {
+    page?: number;
+    perPage?: number;
+    sort?: Sort;
+    status?: ThreadStatus;
+}
+export interface ThreadRow extends Thread {
+    authorName: string | null;
+}
+export interface CommentRow extends Omit<Comment, 'body'> {
+    /** Null when hidden: the tree keeps its shape, the words are gone. */
+    body: string | null;
+    authorName: string | null;
+}
+export interface OutboxItem {
+    id: number;
+    kind: 'comment' | 'status';
+    to: {
+        id: string;
+        name: string | null;
+        email: string;
+    };
+    thread: Thread;
+    comment: Comment | null;
+}
+export declare const DEFAULT_LIMITS: Limits;
+export declare function slugify(title: string): string;
+export declare function createThreads(opts: ThreadsOptions): {
+    seen: (who: Who) => Promise<Person>;
+    categories: () => Promise<Category[]>;
+    category: (slug: string) => Promise<Category | null>;
+    categoryById: (id: number) => Promise<Category | null>;
+    createCategory: (who: Who | null, input: {
+        slug: string;
+        name: string;
+        description?: string;
+        kind?: Category["kind"];
+        position?: number;
+    }) => Promise<Category>;
+    listThreads: (subject: Subject, who: Who | null, options?: ListOptions) => Promise<{
+        items: ThreadRow[];
+        page: number;
+        perPage: number;
+        total: number;
+    }>;
+    thread: (id: number, who: Who | null) => Promise<ThreadRow>;
+    threadFor: (subject: Subject, who: Who | null) => Promise<ThreadRow | null>;
+    comments: (threadId: number, who: Who | null, options?: {
+        root?: number;
+    }) => Promise<CommentRow[]>;
+    search: (q: string, who: Who | null, options?: {
+        subjectKind?: string;
+        limit?: number;
+    }) => Promise<ThreadRow[]>;
+    roadmap: (who: Who | null) => Promise<Record<ThreadStatus, ThreadRow[]>>;
+    post: (who: Who | null, subject: Subject, input: {
+        title: string;
+        body: string;
+    }) => Promise<Thread>;
+    comment: (who: Who | null, threadId: number, input: {
+        body: string;
+        replyTo?: number | null;
+    }) => Promise<Comment>;
+    commentOn: (who: Who | null, subject: Subject, input: {
+        body: string;
+        replyTo?: number | null;
+    }) => Promise<Comment>;
+    vote: (who: Who | null, threadId: number) => Promise<void>;
+    unvote: (who: Who | null, threadId: number) => Promise<void>;
+    voted: (who: Who | null, threadIds: number[]) => Promise<Set<number>>;
+    subscribe: (who: Who | null, threadId: number, muted?: boolean) => Promise<void>;
+    pin: (who: Who | null, id: number, on?: boolean) => Promise<void>;
+    lock: (who: Who | null, id: number, on?: boolean) => Promise<void>;
+    hide: (who: Who | null, id: number, on?: boolean) => Promise<void>;
+    hideComment: (who: Who | null, commentId: number, hidden?: boolean) => Promise<void>;
+    move: (who: Who | null, threadId: number, categoryId: number) => Promise<void>;
+    setStatus: (who: Who | null, threadId: number, status: ThreadStatus) => Promise<void>;
+    markDuplicate: (who: Who | null, threadId: number, ofId: number) => Promise<void>;
+    setStanding: (who: Who | null, personId: string, standing: Person["standing"]) => Promise<void>;
+    drainOutbox: (send: (item: OutboxItem) => Promise<void>, batch?: number) => Promise<number>;
+};
+export type Threads = ReturnType<typeof createThreads>;
+export { schema };