@crombolo/data 0.0.0-stage → 0.9.1

package/src/repositories/domains.ts

@@ -0,0 +1,108 @@
+/**
+ * Culture and hostnames (Umbraco's `umbracoDomain`): hostnames that make a
+ * document a site root, each with a culture, plus an optional wildcard that only
+ * sets the culture of a branch. The wildcard is stored as Umbraco stores it, a
+ * row named `*<node id>`.
+ */
+import type { Db } from '../database.ts'
+
+export interface DomainAssignment {
+  defaultIsoCode: string | null
+  domains: Array<{ domainName: string; isoCode: string }>
+}
+
+export interface DomainRow {
+  nodeId: number
+  domainName: string
+  isoCode: string | null
+  isWildcard: boolean
+  sortOrder: number
+}
+
+export type SetDomainsResult =
+  | { status: 'ok' }
+  | { status: 'invalidLanguage'; isoCode: string }
+  | { status: 'invalidName'; domainName: string }
+  | { status: 'conflict'; domainName: string }
+
+/** `https://Example.com/en/` → `example.com/en`; what matching and uniqueness compare. */
+export function normaliseDomainName(name: string): string {
+  return name
+    .trim()
+    .replace(/^[a-z]+:\/\//i, '')
+    .replace(/\/+$/, '')
+    .toLowerCase()
+}
+
+const VALID_DOMAIN = /^[a-z0-9.-]+(:\d+)?(\/[a-z0-9._~%-]+)*$/i
+
+export class DomainRepository {
+  #db: Db
+
+  constructor(db: Db) {
+    this.#db = db
+  }
+
+  async all(): Promise<DomainRow[]> {
+    const rows = await this.#db.query(
+      `SELECT d.node_id, d.domain_name, d.sort_order, l.iso_code FROM domain d
+       LEFT JOIN language l ON l.id = d.language_id ORDER BY d.node_id, d.sort_order, d.id`,
+    )
+    return rows.map((row) => ({
+      nodeId: Number(row.node_id),
+      domainName: String(row.domain_name),
+      isoCode: (row.iso_code as string | null) ?? null,
+      isWildcard: String(row.domain_name).startsWith('*'),
+      sortOrder: Number(row.sort_order),
+    }))
+  }
+
+  async forNode(nodeId: number): Promise<DomainAssignment> {
+    const rows = (await this.all()).filter((row) => row.nodeId === nodeId)
+    return {
+      defaultIsoCode: rows.find((row) => row.isWildcard)?.isoCode ?? null,
+      domains: rows
+        .filter((row) => !row.isWildcard)
+        .map((row) => ({ domainName: row.domainName, isoCode: row.isoCode ?? '' })),
+    }
+  }
+
+  /** Replaces a node's domains. Names are unique across the site, and each culture must exist. */
+  async setForNode(nodeId: number, assignment: DomainAssignment): Promise<SetDomainsResult> {
+    const languages = await this.#db.query<{ id: number; iso_code: string }>(
+      'SELECT id, iso_code FROM language',
+    )
+    const languageId = (iso: string) =>
+      languages.find((l) => String(l.iso_code).toLowerCase() === iso.toLowerCase())?.id
+    if (assignment.defaultIsoCode && languageId(assignment.defaultIsoCode) === undefined)
+      return { status: 'invalidLanguage', isoCode: assignment.defaultIsoCode }
+    const names: string[] = []
+    for (const domain of assignment.domains) {
+      if (languageId(domain.isoCode) === undefined)
+        return { status: 'invalidLanguage', isoCode: domain.isoCode }
+      const name = normaliseDomainName(domain.domainName)
+      if (!VALID_DOMAIN.test(name)) return { status: 'invalidName', domainName: domain.domainName }
+      if (names.includes(name)) return { status: 'conflict', domainName: domain.domainName }
+      names.push(name)
+    }
+    const taken = (await this.all()).filter(
+      (row) => !row.isWildcard && row.nodeId !== nodeId && names.includes(row.domainName),
+    )
+    if (taken[0]) return { status: 'conflict', domainName: taken[0].domainName }
+
+    await this.#db.transaction(async (tx) => {
+      await tx.exec('DELETE FROM domain WHERE node_id = ?', [nodeId])
+      if (assignment.defaultIsoCode)
+        await tx.exec(
+          'INSERT INTO domain (node_id, language_id, domain_name, sort_order) VALUES (?, ?, ?, ?)',
+          [nodeId, languageId(assignment.defaultIsoCode), `*${nodeId}`, 0],
+        )
+      for (const [index, domain] of assignment.domains.entries())
+        await tx.exec(
+          'INSERT INTO domain (node_id, language_id, domain_name, sort_order) VALUES (?, ?, ?, ?)',
+          [nodeId, languageId(domain.isoCode), names[index], index],
+        )
+    })
+    return { status: 'ok' }
+  }
+}

package/src/repositories/folders.ts

@@ -0,0 +1,120 @@
+/**
+ * Folders in the settings trees: nodes of a container object type whose only
+ * data is a name. Files place types in them by `folder = "A/B"`; the sync makes
+ * the path exist; the backoffice's folder actions rewrite the files.
+ */
+import type { Page } from '@crombolo/core'
+import { SystemNodes } from '@crombolo/core'
+import type { Db } from '../database.ts'
+import { NodeRepository, type NodeRow } from './nodes.ts'
+
+export interface FolderModel {
+  key: string
+  name: string
+  parentKey: string | null
+}
+
+export class FolderRepository {
+  #db: Db
+  #nodes: NodeRepository
+  #objectType: string
+  /** The object type of the things the folders hold, for emptiness checks. */
+  #itemType: string
+
+  constructor(db: Db, containerObjectType: string, itemObjectType: string) {
+    this.#db = db
+    this.#nodes = new NodeRepository(db)
+    this.#objectType = containerObjectType
+    this.#itemType = itemObjectType
+  }
+
+  async byKey(key: string): Promise<FolderModel | undefined> {
+    const node = await this.#nodes.byKey(key)
+    if (!node || node.objectType !== this.#objectType) return undefined
+    return this.#toModel(node)
+  }
+
+  async #toModel(node: NodeRow): Promise<FolderModel> {
+    const parent = node.parentId > 0 ? await this.#nodes.byId(node.parentId) : undefined
+    return {
+      key: node.key,
+      name: node.text ?? '',
+      parentKey: parent && parent.objectType === this.#objectType ? parent.key : null,
+    }
+  }
+
+  async create(init: {
+    key?: string
+    name: string
+    parentKey: string | null
+  }): Promise<FolderModel> {
+    const parentId = init.parentKey
+      ? ((await this.#nodes.byKey(init.parentKey))?.id ?? SystemNodes.Root)
+      : SystemNodes.Root
+    const node = await this.#nodes.create({
+      key: init.key,
+      parentId,
+      objectType: this.#objectType,
+      text: init.name,
+    })
+    return this.#toModel(node)
+  }
+
+  async rename(key: string, name: string): Promise<boolean> {
+    const node = await this.#nodes.byKey(key)
+    if (!node || node.objectType !== this.#objectType) return false
+    await this.#nodes.rename(node.id, name)
+    return true
+  }
+
+  /** Deletes an empty folder; 'not-empty' when anything is still inside. */
+  async delete(key: string): Promise<'deleted' | 'not-empty' | 'not-found'> {
+    const node = await this.#nodes.byKey(key)
+    if (!node || node.objectType !== this.#objectType) return 'not-found'
+    const inside = await this.#nodes.childrenOf(node.id, [this.#objectType, this.#itemType], 0, 1)
+    if (inside.total > 0) return 'not-empty'
+    await this.#nodes.delete(node.id)
+    return 'deleted'
+  }
+
+  /** Makes `A/B/C` exist, creating what is missing; returns the leaf's key, or null for an empty path. */
+  async ensurePath(names: readonly string[]): Promise<string | null> {
+    let parentId: number = SystemNodes.Root
+    let key: string | null = null
+    for (const name of names) {
+      const found = await this.#db.query<{ unique_id: string; id: number }>(
+        'SELECT unique_id, id FROM node WHERE parent_id = ? AND node_object_type = ? AND text = ?',
+        [parentId, this.#objectType, name],
+      )
+      if (found[0]) {
+        parentId = Number(found[0].id)
+        key = String(found[0].unique_id).toLowerCase()
+      } else {
+        const created = await this.#nodes.create({
+          parentId,
+          objectType: this.#objectType,
+          text: name,
+        })
+        parentId = created.id
+        key = created.key
+      }
+    }
+    return key
+  }
+
+  /** The folder names above a node, outermost first. */
+  async pathOf(nodeKey: string): Promise<string[]> {
+    const ancestors = await this.#nodes.ancestors(nodeKey)
+    return ancestors.filter((a) => a.objectType === this.#objectType).map((a) => a.text ?? '')
+  }
+
+  children(parentKey: string | null, skip: number, take: number): Promise<Page<NodeRow>> {
+    return this.#childrenWhere(parentKey, [this.#objectType], skip, take)
+  }
+
+  async #childrenWhere(parentKey: string | null, types: string[], skip: number, take: number) {
+    const parentId = parentKey ? (await this.#nodes.byKey(parentKey))?.id : SystemNodes.Root
+    if (parentId === undefined) return { total: 0, items: [] }
+    return this.#nodes.childrenOf(parentId, types, skip, take)
+  }
+}

package/src/repositories/form-entries.ts

@@ -0,0 +1,314 @@
+/**
+ * Form entries: what visitors submitted. `docs/18-forms.md`.
+ *
+ * Keyed by the form's UUID rather than a foreign key, because the definition is
+ * a file. An entry outlives its definition on purpose.
+ *
+ * Values are stored as text whatever the field collects — a number as its
+ * decimal string, a checkbox as `true`/`false`, a multiple choice as one row
+ * per selection. The field type in the definition says how to read it back,
+ * which keeps this table free of a type column that could disagree with the
+ * file.
+ */
+import { randomUUID } from 'node:crypto'
+import type { Db } from '../database.ts'
+import { DbDate, fromDbBool } from '../dialect.ts'
+
+/** Where an entry is in its life: approval is the only transition. */
+export type FormEntryState = 'submitted' | 'approved' | 'rejected'
+
+export const FORM_ENTRY_STATES: readonly FormEntryState[] = ['submitted', 'approved', 'rejected']
+
+export interface FormEntryValue {
+  fieldAlias: string
+  /** One row per selection for a multi-value field, in the order submitted. */
+  values: string[]
+}
+
+export interface FormEntry {
+  id: string
+  formKey: string
+  /** The alias the form had when this was submitted, for an orphaned entry. */
+  formAlias: string
+  state: FormEntryState
+  culture: string | null
+  /** The page the form was submitted from, when it was on one. */
+  pageKey: string | null
+  /** A salted hash, never an address: enough to rate-limit, not a liability. */
+  ipHash: string | null
+  userAgent: string | null
+  spam: boolean
+  createDate: Date
+  updateDate: Date
+  values: FormEntryValue[]
+}
+
+export type FormEntryInput = Omit<
+  FormEntry,
+  'id' | 'createDate' | 'updateDate' | 'state' | 'spam'
+> & {
+  state?: FormEntryState
+  spam?: boolean
+}
+
+export interface FormEntryQuery {
+  formKey: string
+  state?: FormEntryState
+  /** Inclusive; the entries view defaults to the last month. */
+  from?: Date
+  to?: Date
+  /** Matched against any value, which is what the list's search box does. */
+  search?: string
+  includeSpam?: boolean
+  skip?: number
+  take?: number
+}
+
+interface EntryRow {
+  id: string
+  form_key: string
+  form_alias: string
+  state: string
+  culture: string | null
+  page_key: string | null
+  ip_hash: string | null
+  user_agent: string | null
+  spam: unknown
+  create_date: unknown
+  update_date: unknown
+}
+
+interface ValueRow {
+  entry_id: string
+  field_alias: string
+  sort_order: number
+  value: string | null
+}
+
+const SELECT = `SELECT id, form_key, form_alias, state, culture, page_key, ip_hash,
+                       user_agent, spam, create_date, update_date
+                  FROM form_entry`
+
+const state = (value: string): FormEntryState =>
+  FORM_ENTRY_STATES.includes(value as FormEntryState) ? (value as FormEntryState) : 'submitted'
+
+const hydrate = (row: EntryRow, values: FormEntryValue[]): FormEntry => ({
+  id: row.id,
+  formKey: row.form_key,
+  formAlias: row.form_alias,
+  state: state(row.state),
+  culture: row.culture,
+  pageKey: row.page_key,
+  ipHash: row.ip_hash,
+  userAgent: row.user_agent,
+  spam: fromDbBool(row.spam),
+  createDate: DbDate.fromDb(row.create_date) ?? new Date(0),
+  updateDate: DbDate.fromDb(row.update_date) ?? new Date(0),
+  values,
+})
+
+/** Value rows into one entry per id, each field's selections in order. */
+function group(rows: readonly ValueRow[]): Map<string, FormEntryValue[]> {
+  const byEntry = new Map<string, Map<string, string[]>>()
+  for (const row of rows) {
+    const fields = byEntry.get(row.entry_id) ?? new Map<string, string[]>()
+    byEntry.set(row.entry_id, fields)
+    const values = fields.get(row.field_alias) ?? []
+    fields.set(row.field_alias, values)
+    values.push(row.value ?? '')
+  }
+  const out = new Map<string, FormEntryValue[]>()
+  for (const [id, fields] of byEntry)
+    out.set(
+      id,
+      [...fields].map(([fieldAlias, values]) => ({ fieldAlias, values })),
+    )
+  return out
+}
+
+export class FormEntryRepository {
+  #db: Db
+  constructor(db: Db) {
+    this.#db = db
+  }
+
+  /** The values for a page of entries, in one query rather than one each. */
+  async #valuesFor(ids: readonly string[]): Promise<Map<string, FormEntryValue[]>> {
+    if (ids.length === 0) return new Map()
+    const placeholders = ids.map(() => '?').join(', ')
+    const rows = await this.#db.query<ValueRow>(
+      `SELECT entry_id, field_alias, sort_order, value
+         FROM form_entry_value
+        WHERE entry_id IN (${placeholders})
+        ORDER BY field_alias, sort_order`,
+      [...ids],
+    )
+    return group(rows)
+  }
+
+  async byId(id: string): Promise<FormEntry | undefined> {
+    const rows = await this.#db.query<EntryRow>(`${SELECT} WHERE id = ?`, [id])
+    const row = rows[0]
+    if (!row) return undefined
+    return hydrate(row, (await this.#valuesFor([id])).get(id) ?? [])
+  }
+
+  async list(query: FormEntryQuery): Promise<{ total: number; items: FormEntry[] }> {
+    const where: string[] = ['form_key = ?']
+    const params: unknown[] = [query.formKey]
+    if (query.state) {
+      where.push('state = ?')
+      params.push(query.state)
+    }
+    if (query.from) {
+      where.push('create_date >= ?')
+      params.push(DbDate.toDb(query.from))
+    }
+    if (query.to) {
+      where.push('create_date <= ?')
+      params.push(DbDate.toDb(query.to))
+    }
+    // Spam is stored and flagged rather than dropped — a false positive that
+    // silently discarded an enquiry is worse than one to review — so it is
+    // hidden from the list by default rather than absent from the table.
+    if (!query.includeSpam) {
+      where.push('spam = ?')
+      params.push(this.#db.dialect.boolValue(false))
+    }
+    if (query.search) {
+      where.push(`id IN (SELECT entry_id FROM form_entry_value WHERE LOWER(value) LIKE ?)`)
+      params.push(`%${query.search.toLowerCase()}%`)
+    }
+    const clause = `WHERE ${where.join(' AND ')}`
+
+    const counted = await this.#db.query<{ total: number }>(
+      `SELECT COUNT(*) AS total FROM form_entry ${clause}`,
+      params,
+    )
+    const rows = await this.#db.query<EntryRow>(
+      `${SELECT} ${clause} ORDER BY create_date DESC, id LIMIT ? OFFSET ?`,
+      [...params, query.take ?? 100, query.skip ?? 0],
+    )
+    const values = await this.#valuesFor(rows.map((row) => row.id))
+    return {
+      total: Number(counted[0]?.total ?? 0),
+      items: rows.map((row) => hydrate(row, values.get(row.id) ?? [])),
+    }
+  }
+
+  /** How many entries a form has, for a form with a hard cap. */
+  async count(formKey: string, options: { includeSpam?: boolean } = {}): Promise<number> {
+    const rows = options.includeSpam
+      ? await this.#db.query<{ total: number }>(
+          'SELECT COUNT(*) AS total FROM form_entry WHERE form_key = ?',
+          [formKey],
+        )
+      : await this.#db.query<{ total: number }>(
+          'SELECT COUNT(*) AS total FROM form_entry WHERE form_key = ? AND spam = ?',
+          [formKey, this.#db.dialect.boolValue(false)],
+        )
+    return Number(rows[0]?.total ?? 0)
+  }
+
+  async create(input: FormEntryInput, id: string = randomUUID()): Promise<FormEntry> {
+    const now = new Date()
+    await this.#db.exec(
+      `INSERT INTO form_entry
+         (id, form_key, form_alias, state, culture, page_key, ip_hash, user_agent,
+          spam, create_date, update_date)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        input.formKey,
+        input.formAlias,
+        input.state ?? 'submitted',
+        input.culture,
+        input.pageKey,
+        input.ipHash,
+        input.userAgent,
+        this.#db.dialect.boolValue(input.spam ?? false),
+        DbDate.toDb(now),
+        DbDate.toDb(now),
+      ],
+    )
+    await this.#writeValues(id, input.values)
+    return (await this.byId(id)) as FormEntry
+  }
+
+  async #writeValues(id: string, values: readonly FormEntryValue[]): Promise<void> {
+    for (const value of values) {
+      // An empty list still means "this field was answered with nothing", which
+      // is different from the field being absent; one empty row records it.
+      const list = value.values.length === 0 ? [''] : value.values
+      for (const [sort, text] of list.entries())
+        await this.#db.exec(
+          `INSERT INTO form_entry_value (entry_id, field_alias, sort_order, value)
+           VALUES (?, ?, ?, ?)`,
+          [id, value.fieldAlias, sort, text],
+        )
+    }
+  }
+
+  /**
+   * Approve or reject. Returns undefined when there is no such entry, so a
+   * caller can tell "gone" from "done".
+   */
+  async setState(id: string, next: FormEntryState): Promise<FormEntry | undefined> {
+    const existing = await this.byId(id)
+    if (!existing) return undefined
+    await this.#db.exec('UPDATE form_entry SET state = ?, update_date = ? WHERE id = ?', [
+      next,
+      DbDate.toDb(new Date()),
+      id,
+    ])
+    return this.byId(id)
+  }
+
+  /** Marks an entry as spam, or clears the mark after a person looked. */
+  async setSpam(id: string, spam: boolean): Promise<FormEntry | undefined> {
+    const existing = await this.byId(id)
+    if (!existing) return undefined
+    await this.#db.exec('UPDATE form_entry SET spam = ?, update_date = ? WHERE id = ?', [
+      this.#db.dialect.boolValue(spam),
+      DbDate.toDb(new Date()),
+      id,
+    ])
+    return this.byId(id)
+  }
+
+  /** Replaces an entry's values, for the backoffice's edit of one. */
+  async setValues(id: string, values: readonly FormEntryValue[]): Promise<FormEntry | undefined> {
+    const existing = await this.byId(id)
+    if (!existing) return undefined
+    await this.#db.exec('DELETE FROM form_entry_value WHERE entry_id = ?', [id])
+    await this.#writeValues(id, values)
+    await this.#db.exec('UPDATE form_entry SET update_date = ? WHERE id = ?', [
+      DbDate.toDb(new Date()),
+      id,
+    ])
+    return this.byId(id)
+  }
+
+  async remove(id: string): Promise<boolean> {
+    const existing = await this.byId(id)
+    if (!existing) return false
+    // Explicit rather than relying on the cascade: SQLite enforces foreign keys
+    // only when the pragma is on, and this must not depend on that.
+    await this.#db.exec('DELETE FROM form_entry_value WHERE entry_id = ?', [id])
+    await this.#db.exec('DELETE FROM form_entry WHERE id = ?', [id])
+    return true
+  }
+
+  /** Every form that has entries, with how many — including orphaned ones. */
+  async forms(): Promise<{ formKey: string; formAlias: string; total: number }[]> {
+    const rows = await this.#db.query<{ form_key: string; form_alias: string; total: number }>(
+      `SELECT form_key, MAX(form_alias) AS form_alias, COUNT(*) AS total
+         FROM form_entry GROUP BY form_key ORDER BY MAX(form_alias)`,
+    )
+    return rows.map((row) => ({
+      formKey: row.form_key,
+      formAlias: row.form_alias,
+      total: Number(row.total),
+    }))
+  }
+}