@meith/forums 0.16.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@meith/forums",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/forums"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./arrange": "./src/arrange.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/i18n": "0.16.0",
+    "@meith/core": "0.16.0"
+  }
+}

package/src/arrange.ts

@@ -0,0 +1,224 @@
+import { canHoldForums } from './placement'
+import { buildTree } from './tree'
+import type { ForumNode, ForumRow, ForumType, MoveTarget } from './types'
+
+export const NUDGES = ['up', 'down', 'in', 'out'] as const
+export type Nudge = (typeof NUDGES)[number]
+
+export interface ForumOutlineRow {
+  readonly id: number
+  readonly parentId: number | null
+  readonly depth: number
+  readonly type: ForumType
+  readonly title: string
+  readonly slug: string
+}
+
+export interface DropTarget {
+  readonly parentId: number | null
+  readonly afterId: number | null
+}
+
+export interface DropProjection extends DropTarget {
+  readonly index: number
+  readonly depth: number
+}
+
+export function isNudge(value: string): value is Nudge {
+  return (NUDGES as readonly string[]).includes(value)
+}
+
+export function outlineOf(rows: readonly ForumRow[]): ForumOutlineRow[] {
+  const outline: ForumOutlineRow[] = []
+
+  const visit = (
+    nodes: readonly ForumNode<ForumRow>[],
+    parentId: number | null,
+    depth: number,
+  ): void => {
+    for (const node of nodes) {
+      outline.push({
+        id: node.id,
+        parentId,
+        depth,
+        type: node.type,
+        title: node.title,
+        slug: node.slug,
+      })
+      visit(node.children, node.id, depth + 1)
+    }
+  }
+
+  visit(buildTree(rows), null, 0)
+  return outline
+}
+
+export function subtreeOfOutline(
+  outline: readonly ForumOutlineRow[],
+  forumId: number,
+): ForumOutlineRow[] {
+  const start = outline.findIndex((row) => row.id === forumId)
+  if (start === -1) return []
+
+  const root = outline[start] as ForumOutlineRow
+  let end = start + 1
+  while (end < outline.length && (outline[end] as ForumOutlineRow).depth > root.depth) end += 1
+
+  return outline.slice(start, end)
+}
+
+export function withoutSubtree(
+  outline: readonly ForumOutlineRow[],
+  forumId: number,
+): ForumOutlineRow[] {
+  const moving = new Set(subtreeOfOutline(outline, forumId).map((row) => row.id))
+  return outline.filter((row) => !moving.has(row.id))
+}
+
+export function childrenOf(
+  outline: readonly ForumOutlineRow[],
+  parentId: number | null,
+): ForumOutlineRow[] {
+  return outline.filter((row) => row.parentId === parentId)
+}
+
+export function nudgeTarget(
+  outline: readonly ForumOutlineRow[],
+  forumId: number,
+  nudge: Nudge,
+): DropTarget | null {
+  const row = outline.find((entry) => entry.id === forumId)
+  if (row === undefined) return null
+
+  const siblings = childrenOf(outline, row.parentId)
+  const at = siblings.findIndex((entry) => entry.id === forumId)
+
+  if (nudge === 'up') {
+    if (at <= 0) return null
+    return { parentId: row.parentId, afterId: siblings[at - 2]?.id ?? null }
+  }
+
+  if (nudge === 'down') {
+    const next = siblings[at + 1]
+    if (next === undefined) return null
+    return { parentId: row.parentId, afterId: next.id }
+  }
+
+  if (nudge === 'in') {
+    const previous = siblings[at - 1]
+    if (previous === undefined || !canHoldForums(previous.type)) return null
+    return {
+      parentId: previous.id,
+      afterId: childrenOf(outline, previous.id).at(-1)?.id ?? null,
+    }
+  }
+
+  const parent = outline.find((entry) => entry.id === row.parentId)
+  if (parent === undefined) return null
+  return { parentId: parent.parentId, afterId: parent.id }
+}
+
+export function availableNudges(
+  outline: readonly ForumOutlineRow[],
+  forumId: number,
+): Record<Nudge, boolean> {
+  return {
+    up: nudgeTarget(outline, forumId, 'up') !== null,
+    down: nudgeTarget(outline, forumId, 'down') !== null,
+    in: nudgeTarget(outline, forumId, 'in') !== null,
+    out: nudgeTarget(outline, forumId, 'out') !== null,
+  }
+}
+
+export function projectDrop(
+  rows: readonly ForumOutlineRow[],
+  index: number,
+  depth: number,
+): DropProjection {
+  const at = Math.min(Math.max(index, 0), rows.length)
+  const previous = rows[at - 1]
+  const next = rows[at]
+
+  if (previous === undefined) return { index: at, depth: 0, parentId: null, afterId: null }
+
+  const deepest = canHoldForums(previous.type) ? previous.depth + 1 : previous.depth
+  const shallowest = next?.depth ?? 0
+  const settled = Math.min(Math.max(depth, shallowest), deepest)
+
+  if (settled === previous.depth + 1) {
+    return { index: at, depth: settled, parentId: previous.id, afterId: null }
+  }
+
+  for (let cursor = at - 1; cursor >= 0; cursor -= 1) {
+    const candidate = rows[cursor] as ForumOutlineRow
+    if (candidate.depth === settled) {
+      return {
+        index: at,
+        depth: settled,
+        parentId: candidate.parentId,
+        afterId: candidate.id,
+      }
+    }
+  }
+
+  return { index: at, depth: 0, parentId: null, afterId: null }
+}
+
+export function projectionOf(
+  outline: readonly ForumOutlineRow[],
+  forumId: number,
+  target: DropTarget,
+): DropProjection {
+  const rows = withoutSubtree(outline, forumId)
+  const parent = rows.find((row) => row.id === target.parentId)
+  const depth = target.parentId === null ? 0 : (parent?.depth ?? 0) + 1
+
+  if (target.afterId === null) {
+    const index = parent === undefined ? 0 : rows.indexOf(parent) + 1
+    return { ...target, index, depth }
+  }
+
+  const after = rows.find((row) => row.id === target.afterId)
+  if (after === undefined) return { ...target, index: rows.length, depth }
+
+  const followers = subtreeOfOutline(rows, after.id)
+  return { ...target, index: rows.indexOf(after) + followers.length, depth }
+}
+
+export function applyDrop(
+  outline: readonly ForumOutlineRow[],
+  forumId: number,
+  projection: DropProjection,
+): ForumOutlineRow[] {
+  const block = subtreeOfOutline(outline, forumId)
+  if (block.length === 0) return [...outline]
+
+  const rest = withoutSubtree(outline, forumId)
+  const shift = projection.depth - (block[0] as ForumOutlineRow).depth
+
+  const moved = block.map((row, offset) => ({
+    ...row,
+    depth: row.depth + shift,
+    ...(offset === 0 ? { parentId: projection.parentId } : {}),
+  }))
+
+  return [...rest.slice(0, projection.index), ...moved, ...rest.slice(projection.index)]
+}
+
+export function isWhereItIs(
+  outline: readonly ForumOutlineRow[],
+  forumId: number,
+  target: DropTarget,
+): boolean {
+  const row = outline.find((entry) => entry.id === forumId)
+  if (row === undefined || row.parentId !== target.parentId) return false
+
+  const siblings = childrenOf(outline, row.parentId)
+  const at = siblings.findIndex((entry) => entry.id === forumId)
+
+  return (siblings[at - 1]?.id ?? null) === target.afterId
+}
+
+export function moveTargetOf(target: DropTarget): MoveTarget {
+  return { newParentId: target.parentId, after: target.afterId }
+}

package/src/cached-repo.ts

@@ -0,0 +1,55 @@
+import { type CacheDriver, CacheTags, cachedGlobal } from '@meith/core'
+
+import type { ForumRepository } from './ports'
+import type { ForumListingRow, ForumRow, MovePlan, MoveTarget, NewForum } from './types'
+
+const TREE_KEY = ['forum-tree'] as const
+
+export const TREE_TTL_SECONDS = 60
+
+export class CachedForumRepository implements ForumRepository {
+  constructor(
+    private readonly inner: ForumRepository,
+    private readonly cache: CacheDriver,
+  ) {}
+
+  async listAll(): Promise<ForumRow[]> {
+    return cachedGlobal(
+      this.cache,
+      {
+        key: TREE_KEY,
+        tags: [CacheTags.forumTree()],
+        revalidate: TREE_TTL_SECONDS,
+      },
+      () => this.inner.listAll(),
+    )
+  }
+
+  async listListing(): Promise<ForumListingRow[]> {
+    return this.inner.listListing()
+  }
+
+  async findById(id: number): Promise<ForumRow | null> {
+    return (await this.listAll()).find((row) => row.id === id) ?? null
+  }
+
+  async create(input: NewForum): Promise<ForumRow> {
+    const created = await this.inner.create(input)
+    await this.invalidate()
+    return created
+  }
+
+  async move(forumId: number, target: MoveTarget): Promise<void> {
+    await this.inner.move(forumId, target)
+    await this.invalidate()
+  }
+
+  async applyMove(plan: MovePlan): Promise<void> {
+    await this.inner.applyMove(plan)
+    await this.invalidate()
+  }
+
+  private async invalidate(): Promise<void> {
+    await this.cache.invalidateTags([CacheTags.forumTree()])
+  }
+}

package/src/create.ts

@@ -0,0 +1,54 @@
+import { ConflictError, ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+import type { ForumRow, NewForum } from './types'
+
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export interface CreatePlan {
+  readonly parentId: number | null
+  readonly parentPath: string | null
+  readonly depth: number
+  readonly displayOrder: number
+}
+
+export function planCreate(rows: readonly ForumRow[], input: NewForum): CreatePlan {
+  const title = input.title.trim()
+  if (title === '') throw new ValidationError(msg('error.forums.forum-needs-title'))
+
+  if (!SLUG.test(input.slug)) {
+    throw new ValidationError(
+      `"${input.slug}" is not a valid slug: use lowercase letters, digits and single hyphens.`,
+    )
+  }
+
+  if (input.type === 'link' && !input.linkUrl) {
+    throw new ValidationError(msg('error.forums.link-forum-needs-linkurl'))
+  }
+
+  const parent = input.parentId === null ? null : rows.find((r) => r.id === input.parentId)
+  if (input.parentId !== null && !parent) {
+    throw new ValidationError(`No such parent forum: ${input.parentId}`)
+  }
+
+  if (parent?.type === 'link') {
+    throw new ValidationError(`"${parent.title}" is a link and cannot contain forums.`)
+  }
+
+  const siblings = rows.filter((r) => r.parentId === input.parentId)
+  if (siblings.some((s) => s.slug === input.slug)) {
+    throw new ConflictError(
+      `A forum with the slug "${input.slug}" already exists in that location.`,
+    )
+  }
+
+  const parentPath = parent?.path ?? null
+
+  return {
+    parentId: input.parentId,
+    parentPath,
+    depth: parent === null || parent === undefined ? 0 : parent.depth + 1,
+    displayOrder:
+      input.displayOrder ?? siblings.reduce((max, s) => Math.max(max, s.displayOrder + 1), 0),
+  }
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export {
+  applyDrop,
+  availableNudges,
+  childrenOf,
+  type DropProjection,
+  type DropTarget,
+  type ForumOutlineRow,
+  isNudge,
+  isWhereItIs,
+  moveTargetOf,
+  NUDGES,
+  type Nudge,
+  nudgeTarget,
+  outlineOf,
+  projectDrop,
+  projectionOf,
+  subtreeOfOutline,
+  withoutSubtree,
+} from './arrange'
+export { CachedForumRepository } from './cached-repo'
+export { type CreatePlan, planCreate } from './create'
+export { planMove } from './move'
+export {
+  ancestorIds,
+  childPath,
+  depthOf,
+  formatPath,
+  isInSubtree,
+  PATH_SEPARATOR,
+  parsePath,
+  rehang,
+  subtreeOf,
+} from './path'
+export { acceptsThreads, canHoldForums, canHoldThreads } from './placement'
+export type { ForumRepository } from './ports'
+export { buildTree, flattenTree, keepVisibleSubtrees } from './tree'
+export {
+  FORUM_TYPES,
+  type ForumListingRow,
+  type ForumNode,
+  type ForumRow,
+  type ForumType,
+  type LastPostSummary,
+  type MovePlan,
+  type MoveTarget,
+  type NewForum,
+  type PathUpdate,
+  type TreeShaped,
+} from './types'

package/src/move.ts

@@ -0,0 +1,95 @@
+import { ConflictError, ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+import { childPath, depthOf, isInSubtree, rehang } from './path'
+import type { ForumRow, MovePlan, MoveTarget, PathUpdate } from './types'
+
+export function planMove(rows: readonly ForumRow[], forumId: number, target: MoveTarget): MovePlan {
+  const byId = new Map(rows.map((r) => [r.id, r]))
+
+  const forum = byId.get(forumId)
+  if (!forum) throw new ValidationError(`No such forum: ${forumId}`)
+
+  const { newParentId } = target
+  const newParent = newParentId === null ? null : byId.get(newParentId)
+  if (newParentId !== null && !newParent) {
+    throw new ValidationError(`No such parent forum: ${newParentId}`)
+  }
+
+  if (newParent) {
+    if (newParent.id === forum.id) {
+      throw new ValidationError(msg('error.forums.forum-its-own-parent'))
+    }
+
+    if (isInSubtree(newParent.path, forum.path)) {
+      throw new ValidationError(
+        `Cannot move "${forum.title}" into its own descendant "${newParent.title}".`,
+      )
+    }
+
+    if (newParent.type === 'link') {
+      throw new ValidationError(`"${newParent.title}" is a link and cannot contain forums.`)
+    }
+  }
+
+  const siblings = rows
+    .filter((r) => r.parentId === newParentId && r.id !== forum.id)
+    .sort((a, b) => a.displayOrder - b.displayOrder || a.id - b.id)
+
+  const collision = siblings.find((s) => s.slug === forum.slug)
+  if (collision) {
+    throw new ConflictError(
+      `A forum with the slug "${forum.slug}" already exists in that location.`,
+    )
+  }
+
+  return {
+    forumId,
+    newParentId,
+    pathUpdates: planPathUpdates(rows, forum, newParent?.path ?? null),
+    orderUpdates: planOrderUpdates(siblings, forum.id, target),
+  }
+}
+
+function planPathUpdates(
+  rows: readonly ForumRow[],
+  forum: ForumRow,
+  newParentPath: string | null,
+): PathUpdate[] {
+  const newRoot = childPath(newParentPath, forum.id)
+
+  if (newRoot === forum.path) return []
+
+  return rows
+    .filter((row) => isInSubtree(row.path, forum.path))
+    .map((row) => {
+      const path = rehang(row.path, forum.path, newRoot)
+      return { id: row.id, path, depth: depthOf(path) }
+    })
+}
+
+function planOrderUpdates(
+  siblings: readonly ForumRow[],
+  forumId: number,
+  target: MoveTarget,
+): { id: number; displayOrder: number }[] {
+  const ids = siblings.map((s) => s.id)
+
+  ids.splice(insertionIndex(ids, target), 0, forumId)
+  return ids.map((id, displayOrder) => ({ id, displayOrder }))
+}
+
+function insertionIndex(ids: readonly number[], target: MoveTarget): number {
+  if (target.after !== undefined) {
+    if (target.after === null) return 0
+
+    const at = ids.indexOf(target.after)
+    if (at === -1) {
+      throw new ConflictError(msg('error.forums.forum-follow-longer-there-reload'))
+    }
+    return at + 1
+  }
+
+  const { position } = target
+  return position === undefined ? ids.length : Math.min(Math.max(position, 0), ids.length)
+}

package/src/path.ts

@@ -0,0 +1,49 @@
+import { ValidationError } from '@meith/core'
+
+export const PATH_SEPARATOR = '.'
+
+export function formatPath(ids: readonly number[]): string {
+  return ids.join(PATH_SEPARATOR)
+}
+
+export function parsePath(path: string): number[] {
+  if (path === '') return []
+  return path.split(PATH_SEPARATOR).map((segment) => {
+    const id = Number(segment)
+    if (!Number.isInteger(id) || id <= 0) {
+      throw new ValidationError(`Malformed forum path segment: ${segment}`)
+    }
+    return id
+  })
+}
+
+export function ancestorIds(path: string): number[] {
+  const ids = parsePath(path)
+  return ids.slice(0, -1)
+}
+
+export function depthOf(path: string): number {
+  return Math.max(parsePath(path).length - 1, 0)
+}
+
+export function childPath(parentPath: string | null, childId: number): string {
+  return parentPath === null || parentPath === ''
+    ? String(childId)
+    : `${parentPath}${PATH_SEPARATOR}${childId}`
+}
+
+export function isInSubtree(candidate: string, ancestor: string): boolean {
+  if (candidate === ancestor) return true
+  return candidate.startsWith(`${ancestor}${PATH_SEPARATOR}`)
+}
+
+export function subtreeOf(path: string): { exact: string; prefix: string } {
+  return { exact: path, prefix: `${path}${PATH_SEPARATOR}%` }
+}
+
+export function rehang(descendantPath: string, oldRoot: string, newRoot: string): string {
+  if (!isInSubtree(descendantPath, oldRoot)) {
+    throw new ValidationError(`${descendantPath} is not inside ${oldRoot}; refusing to rehang it`)
+  }
+  return `${newRoot}${descendantPath.slice(oldRoot.length)}`
+}

package/src/placement.ts

@@ -0,0 +1,16 @@
+import type { ForumType } from './types'
+
+export function canHoldThreads(type: ForumType): boolean {
+  return type !== 'link'
+}
+
+export function canHoldForums(type: ForumType): boolean {
+  return type !== 'link'
+}
+
+export function acceptsThreads(row: {
+  readonly type: ForumType
+  readonly allowThreads: boolean
+}): boolean {
+  return row.type === 'forum' || (row.type === 'category' && row.allowThreads)
+}

package/src/ports.ts

@@ -0,0 +1,15 @@
+import type { ForumListingRow, ForumRow, MovePlan, MoveTarget, NewForum } from './types'
+
+export interface ForumRepository {
+  listAll(): Promise<ForumRow[]>
+
+  listListing(): Promise<ForumListingRow[]>
+
+  findById(id: number): Promise<ForumRow | null>
+
+  create(input: NewForum): Promise<ForumRow>
+
+  applyMove(plan: MovePlan): Promise<void>
+
+  move(forumId: number, target: MoveTarget): Promise<void>
+}

package/src/tree.ts

@@ -0,0 +1,70 @@
+import type { ForumNode, TreeShaped } from './types'
+
+function bySiblingOrder(a: TreeShaped, b: TreeShaped): number {
+  return a.displayOrder - b.displayOrder || a.id - b.id
+}
+
+export function keepVisibleSubtrees<T extends TreeShaped>(
+  rows: readonly T[],
+  isVisible: (row: T) => boolean,
+): T[] {
+  const visible = rows.filter(isVisible)
+  const survived = new Set(visible.map((row) => row.id))
+
+  for (;;) {
+    const orphaned = visible.filter(
+      (row) => survived.has(row.id) && row.parentId !== null && !survived.has(row.parentId),
+    )
+    if (orphaned.length === 0) break
+    for (const row of orphaned) survived.delete(row.id)
+  }
+
+  return visible.filter((row) => survived.has(row.id))
+}
+
+export function buildTree<T extends TreeShaped>(rows: readonly T[]): ForumNode<T>[] {
+  const byId = new Map<number, T>(rows.map((row) => [row.id, row]))
+  const childrenOf = new Map<number | null, T[]>()
+
+  for (const row of rows) {
+    const parentKey =
+      row.parentId !== null && byId.has(row.parentId) && !isSelfOrCyclic(row, byId)
+        ? row.parentId
+        : null
+
+    const bucket = childrenOf.get(parentKey)
+    if (bucket) bucket.push(row)
+    else childrenOf.set(parentKey, [row])
+  }
+
+  const attach = (row: T): ForumNode<T> => ({
+    ...row,
+    children: (childrenOf.get(row.id) ?? []).sort(bySiblingOrder).map(attach),
+  })
+
+  return (childrenOf.get(null) ?? []).sort(bySiblingOrder).map(attach)
+}
+
+function isSelfOrCyclic<T extends TreeShaped>(row: T, byId: Map<number, T>): boolean {
+  const seen = new Set<number>([row.id])
+  let current = row.parentId
+
+  while (current !== null) {
+    if (seen.has(current)) return true
+    seen.add(current)
+    const parent = byId.get(current)
+    if (!parent) return false
+    current = parent.parentId
+  }
+  return false
+}
+
+export function flattenTree<T extends TreeShaped>(nodes: readonly ForumNode<T>[]): ForumNode<T>[] {
+  const out: ForumNode<T>[] = []
+  const visit = (node: ForumNode<T>): void => {
+    out.push(node)
+    for (const child of node.children) visit(child)
+  }
+  for (const node of nodes) visit(node)
+  return out
+}

package/src/types.ts

@@ -0,0 +1,67 @@
+export const FORUM_TYPES = ['category', 'forum', 'link'] as const
+export type ForumType = (typeof FORUM_TYPES)[number]
+
+export interface TreeShaped {
+  readonly id: number
+  readonly parentId: number | null
+  readonly displayOrder: number
+}
+
+export interface ForumRow extends TreeShaped {
+  readonly type: ForumType
+  readonly title: string
+  readonly slug: string
+  readonly description: string | null
+  readonly path: string
+  readonly depth: number
+  readonly linkUrl: string | null
+}
+
+export type ForumNode<T extends TreeShaped = ForumRow> = T & {
+  readonly children: readonly ForumNode<T>[]
+}
+
+export interface LastPostSummary {
+  readonly postId: number
+  readonly threadId: number
+  readonly threadTitle: string
+  readonly userId: number | null
+  readonly username: string
+  readonly at: Date
+}
+
+export interface ForumListingRow extends ForumRow {
+  readonly allowThreads: boolean
+  readonly threadCount: number
+  readonly postCount: number
+  readonly lastPost: LastPostSummary | null
+}
+
+export interface NewForum {
+  readonly type: ForumType
+  readonly title: string
+  readonly slug: string
+  readonly description?: string | undefined
+  readonly parentId: number | null
+  readonly linkUrl?: string | undefined
+  readonly displayOrder?: number | undefined
+}
+
+export interface MoveTarget {
+  readonly newParentId: number | null
+  readonly position?: number
+  readonly after?: number | null
+}
+
+export interface PathUpdate {
+  readonly id: number
+  readonly path: string
+  readonly depth: number
+}
+
+export interface MovePlan {
+  readonly forumId: number
+  readonly newParentId: number | null
+  readonly pathUpdates: readonly PathUpdate[]
+  readonly orderUpdates: readonly { readonly id: number; readonly displayOrder: number }[]
+}