@crombolo/data 0.0.0-stage → 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kineco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,69 @@
+crombolo
+Copyright (c) 2026 Kineco
+
+This product includes third-party software. crombolo is an independent project.
+It is not affiliated with, endorsed by, or sponsored by Umbraco A/S, which owns
+the Umbraco trademark.
+
+There are three places third-party material is redistributed, rather than merely
+depended on:
+
+  @crombolo/backoffice-dist   the built Umbraco backoffice and the browser
+                              packages bundled into it, produced by
+                              `bun run vendor:backoffice`
+  @crombolo/backoffice-dist   three CSS files copied unmodified from the Umbraco
+                              client source tree
+  @crombolo/contracts         the Umbraco Management API OpenAPI document,
+                              copied unmodified
+
+No Umbraco trademark is redistributed. The Umbraco wordmark, the "U" roundel
+favicon and the installer illustration are deliberately not carried in this
+repository: MIT grants copyright permission and says nothing about trademarks, so
+crombolo's own marks are served at those paths instead. See `BRANDED_ASSETS` in
+`@crombolo/backoffice-host`.
+
+The Umbraco backoffice
+----------------------
+@umbraco-cms/backoffice 18.2.0 — MIT — https://github.com/umbraco/Umbraco-CMS
+@umbraco-ui/uui 2.0.2 — MIT — https://github.com/umbraco/Umbraco.UI
+
+Static files from the Umbraco client source tree
+------------------------------------------------
+css/umb-css.css, css/rte-content.css, css/umbraco-blockgridlayout.css
+  — copied unmodified from Umbraco-CMS release-18.2.0 — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/backoffice-dist under `upstream-static/`.
+
+`rte-content.css` itself carries Tiptap's default editor styles, copied from
+tiptap v2.11.7 (MIT); the file records this in its own header.
+
+The Umbraco Management API contract
+-----------------------------------
+OpenApi.json — copied unmodified from Umbraco-CMS release-18.2.0
+  (src/Umbraco.Cms.Api.Management/OpenApi.json) — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/contracts, which also ships the TypeScript types generated
+from it.
+
+Browser runtime dependencies bundled into the backoffice build
+--------------------------------------------------------------
+@heximal/expressions 0.1.5 — BSD-3-Clause
+@microsoft/signalr 10.0.11 — MIT
+@tiptap/* 3.31.3 — MIT
+diff 9.0.0 — BSD-3-Clause
+dompurify 3.4.16 — Apache-2.0, elected from "MPL-2.0 OR Apache-2.0"
+element-internals-polyfill 3.0.2 — MIT
+lit 3.3.3 — BSD-3-Clause
+luxon 3.7.2 — MIT
+marked 18.0.14 — MIT
+monaco-editor 0.57.0 — MIT
+rxjs 7.8.2 — Apache-2.0
+uuid 14.0.2 — MIT
+
+dompurify is offered under either licence; Apache-2.0 is elected here, so no
+MPL-2.0 obligation attaches to the copy bundled into the backoffice build. Of the
+Apache-2.0 packages above, none ships a NOTICE file of its own, so Apache-2.0
+section 4(d) adds nothing to this file.
+
+Each package's own licence text ships inside its npm distribution and applies
+unchanged to the copies bundled here.

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@crombolo/data",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.1",
+  "description": "SQLite and Postgres storage for crombolo: schema, migrations and repositories.",
+  "license": "MIT",
+  "author": "Crombolo",
+  "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineco-au/crombolo-cms.git",
+    "directory": "packages/data"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@crombolo/core": "0.9.1"
+  }
+}

package/src/change-report.ts

@@ -0,0 +1,166 @@
+/**
+ * Findings, persisted. A run upserts by `(code, subject, property, culture)`
+ * within its own `(source, scope)` and resolves whatever it no longer reports,
+ * so the dashboard shows items disappearing as they are fixed.
+ *
+ * `source` is required rather than defaulted: the sweep resolves what a run
+ * omits, so a caller that forgot to say which findings it owns would silently
+ * resolve somebody else's. `scope` narrows it again — one bundle's findings do
+ * not resolve another's.
+ */
+import type { Db } from './database.ts'
+import { DbDate } from './dialect.ts'
+
+export type FindingKind = 'auto' | 'person' | 'blocking'
+
+/** Who a run of findings belongs to. Scopes the resolve sweep. */
+export type FindingSource = 'upgrade' | 'transfer'
+
+export interface Finding {
+  kind: FindingKind
+  /** Stable machine name: 'mandatory-missing', 'value-conversion', … */
+  code: string
+  subjectType:
+    | 'document'
+    | 'document-type'
+    | 'property'
+    | 'migration'
+    | 'file'
+    | 'data-type'
+    | 'media'
+    | 'element'
+    | 'bundle'
+    | 'dictionary-item'
+  subjectKey: string
+  subjectName: string
+  propertyAlias: string | null
+  culture: string | null
+  message: string
+  /** A backoffice URL, when the subject has one. */
+  link: string | null
+}
+
+export interface ReportedFinding extends Finding {
+  id: number
+  runId: string
+  source: FindingSource
+  /** What within the source these findings are about: a bundle id, or null for an upgrade. */
+  scope: string | null
+  status: 'open' | 'resolved'
+  firstSeen: Date
+  lastSeen: Date
+  resolvedAt: Date | null
+}
+
+export interface WriteReportOptions {
+  source: FindingSource
+  scope?: string | null
+  runId?: string
+}
+
+export interface ReadReportOptions {
+  includeResolved?: boolean
+  source?: FindingSource
+  scope?: string | null
+}
+
+const identity = (f: Finding) =>
+  `${f.code}|${f.subjectKey}|${f.propertyAlias ?? ''}|${f.culture ?? ''}`
+
+/** Records a run: new findings inserted, seen ones refreshed, absent ones resolved. Returns the run id. */
+export async function writeReport(
+  db: Db,
+  findings: readonly Finding[],
+  options: WriteReportOptions,
+): Promise<string> {
+  const { source } = options
+  const scope = options.scope ?? null
+  const runId = options.runId ?? crypto.randomUUID()
+  const now = DbDate.toDb(new Date())
+  const open = await readReport(db, { source, scope })
+  const openByIdentity = new Map(open.map((f) => [identity(f), f]))
+  const seen = new Set<string>()
+  for (const finding of findings) {
+    const key = identity(finding)
+    seen.add(key)
+    const existing = openByIdentity.get(key)
+    if (existing) {
+      await db.exec(
+        'UPDATE change_report SET run_id = ?, kind = ?, subject_name = ?, message = ?, link = ?, last_seen = ? WHERE id = ?',
+        [runId, finding.kind, finding.subjectName, finding.message, finding.link, now, existing.id],
+      )
+    } else {
+      await db.exec(
+        `INSERT INTO change_report (run_id, source, scope, kind, code, subject_type, subject_key, subject_name, property_alias, culture, message, link, status, first_seen, last_seen)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'open', ?, ?)`,
+        [
+          runId,
+          source,
+          scope,
+          finding.kind,
+          finding.code,
+          finding.subjectType,
+          finding.subjectKey,
+          finding.subjectName,
+          finding.propertyAlias,
+          finding.culture,
+          finding.message,
+          finding.link,
+          now,
+          now,
+        ],
+      )
+    }
+  }
+  for (const [key, existing] of openByIdentity) {
+    if (seen.has(key)) continue
+    await db.exec("UPDATE change_report SET status = 'resolved', resolved_at = ? WHERE id = ?", [
+      now,
+      existing.id,
+    ])
+  }
+  return runId
+}
+
+export async function readReport(
+  db: Db,
+  options: ReadReportOptions = {},
+): Promise<ReportedFinding[]> {
+  const where: string[] = []
+  const params: unknown[] = []
+  if (!options.includeResolved) where.push("status = 'open'")
+  if (options.source !== undefined) {
+    where.push('source = ?')
+    params.push(options.source)
+  }
+  // `scope` is meaningful when null, so only an explicit key filters.
+  if ('scope' in options) {
+    const scope = options.scope ?? null
+    where.push(scope === null ? 'scope IS NULL' : 'scope = ?')
+    if (scope !== null) params.push(scope)
+  }
+  const rows = await db.query(
+    `SELECT id, run_id, source, scope, kind, code, subject_type, subject_key, subject_name, property_alias, culture, message, link, status, first_seen, last_seen, resolved_at
+     FROM change_report ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY id`,
+    params,
+  )
+  return rows.map((row) => ({
+    id: Number(row.id),
+    runId: String(row.run_id),
+    source: String(row.source) as FindingSource,
+    scope: (row.scope as string | null) ?? null,
+    kind: String(row.kind) as FindingKind,
+    code: String(row.code),
+    subjectType: String(row.subject_type) as Finding['subjectType'],
+    subjectKey: String(row.subject_key),
+    subjectName: String(row.subject_name ?? ''),
+    propertyAlias: (row.property_alias as string | null) ?? null,
+    culture: (row.culture as string | null) ?? null,
+    message: String(row.message),
+    link: (row.link as string | null) ?? null,
+    status: String(row.status) as 'open' | 'resolved',
+    firstSeen: DbDate.fromDb(row.first_seen) ?? new Date(0),
+    lastSeen: DbDate.fromDb(row.last_seen) ?? new Date(0),
+    resolvedAt: DbDate.fromDb(row.resolved_at) ?? null,
+  }))
+}

package/src/cluster.ts

@@ -0,0 +1,108 @@
+/**
+ * Multi-node plumbing: node identity in `server`, and the polled
+ * `cache_instruction` table that tells other nodes what changed.
+ * docs/09-schema-as-code.md, "Cache coherence".
+ */
+import type { Db } from './database.ts'
+import { DbDate } from './dialect.ts'
+
+/**
+ * `views` is a code change, not a data one: a template was written, so every
+ * node has to look at its views tree again. The other two invalidate the
+ * published cache; this one makes a node take a new snapshot.
+ */
+export type CacheInstructionKind = 'schema' | 'content' | 'components'
+
+export interface CacheInstruction {
+  id: number
+  kind: CacheInstructionKind
+  payload: Record<string, unknown>
+  createdBy: string | null
+}
+
+export async function appendCacheInstruction(
+  db: Db,
+  instruction: { kind: CacheInstructionKind; payload?: Record<string, unknown>; by?: string },
+): Promise<void> {
+  await db.exec(
+    'INSERT INTO cache_instruction (kind, payload, created_at, created_by) VALUES (?, ?, ?, ?)',
+    [
+      instruction.kind,
+      JSON.stringify(instruction.payload ?? {}),
+      DbDate.toDb(new Date()),
+      instruction.by ?? null,
+    ],
+  )
+}
+
+/** The highest instruction id, so a fresh node ignores history. */
+export async function latestCacheInstructionId(db: Db): Promise<number> {
+  const rows = await db.query<{ n: number | null }>('SELECT MAX(id) AS n FROM cache_instruction')
+  return Number(rows[0]?.n ?? 0)
+}
+
+export async function cacheInstructionsAfter(db: Db, afterId: number): Promise<CacheInstruction[]> {
+  const rows = await db.query(
+    'SELECT id, kind, payload, created_by FROM cache_instruction WHERE id > ? ORDER BY id',
+    [afterId],
+  )
+  return rows.map((row) => ({
+    id: Number(row.id),
+    kind: String(row.kind) as CacheInstructionKind,
+    payload: row.payload ? (JSON.parse(String(row.payload)) as Record<string, unknown>) : {},
+    createdBy: (row.created_by as string | null) ?? null,
+  }))
+}
+
+export interface ServerIdentity {
+  nodeId: string
+  version: string
+  revision: string
+  /** `all`, `api` or `web`: what this node serves, so the cluster can be read back by role. */
+  role?: string
+}
+
+/** Records this node in `server`; called at boot and on each poll. */
+export async function touchServer(db: Db, identity: ServerIdentity): Promise<void> {
+  const now = DbDate.toDb(new Date())
+  const role = identity.role ?? null
+  const existing = await db.query<{ node_id: string }>(
+    'SELECT node_id FROM server WHERE node_id = ?',
+    [identity.nodeId],
+  )
+  if (existing[0]) {
+    await db.exec(
+      'UPDATE server SET version = ?, revision = ?, role = ?, last_seen = ? WHERE node_id = ?',
+      [identity.version, identity.revision, role, now, identity.nodeId],
+    )
+  } else {
+    await db.exec(
+      'INSERT INTO server (node_id, version, revision, role, last_seen) VALUES (?, ?, ?, ?, ?)',
+      [identity.nodeId, identity.version, identity.revision, role, now],
+    )
+  }
+}
+
+export interface LiveNode {
+  nodeId: string
+  /** Null for a row written before roles were recorded. */
+  role: string | null
+  version: string | null
+  revision: string | null
+  lastSeen: Date
+}
+
+/** The nodes that have polled within `seenWithinMs`: the cluster as it stands. */
+export async function liveNodes(db: Db, options: { seenWithinMs: number }): Promise<LiveNode[]> {
+  const rows = await db.query(
+    'SELECT node_id, role, version, revision, last_seen FROM server WHERE last_seen >= ? ORDER BY node_id',
+    [DbDate.toDb(new Date(Date.now() - options.seenWithinMs))],
+  )
+  return rows.map((row) => ({
+    nodeId: String(row.node_id),
+    role: (row.role as string | null) ?? null,
+    version: (row.version as string | null) ?? null,
+    revision: (row.revision as string | null) ?? null,
+    lastSeen: DbDate.fromDb(row.last_seen) as Date,
+  }))
+}

package/src/database.ts

@@ -0,0 +1,121 @@
+/** Driver-agnostic database handle. */
+import { Database as BunSqlite } from 'bun:sqlite'
+import { type Dialect, type DialectName, dialectFor } from './dialect.ts'
+import { createLockManager, type LockManager } from './locks.ts'
+
+export interface Db {
+  readonly dialect: Dialect
+  readonly locks: LockManager
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>
+  exec(sql: string, params?: unknown[]): Promise<void>
+  transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T>
+  close(): Promise<void>
+}
+
+export interface ConnectOptions {
+  dialect?: DialectName
+  /** Postgres connection pool size. */
+  poolSize?: number
+  /** SQLite file path, or ':memory:'. Ignored for Postgres. */
+  file?: string
+  /** Postgres connection string. Ignored for SQLite. */
+  url?: string
+}
+
+class SqliteDb implements Db {
+  readonly dialect = dialectFor('sqlite')
+  readonly locks: LockManager
+  #db: BunSqlite
+  #inTransaction: boolean
+
+  constructor(db: BunSqlite, locks?: LockManager, inTransaction = false) {
+    this.#db = db
+    this.locks = locks ?? createLockManager(this)
+    this.#inTransaction = inTransaction
+  }
+
+  async query<T = Record<string, unknown>>(sql: string, params: unknown[] = []): Promise<T[]> {
+    return this.#db.query(this.dialect.render(sql)).all(...(params as never[])) as T[]
+  }
+
+  async exec(sql: string, params: unknown[] = []): Promise<void> {
+    this.#db.query(this.dialect.render(sql)).run(...(params as never[]))
+  }
+
+  async transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T> {
+    if (this.#inTransaction) return fn(this)
+    this.#db.exec('BEGIN')
+    try {
+      const result = await fn(new SqliteDb(this.#db, this.locks, true))
+      this.#db.exec('COMMIT')
+      return result
+    } catch (error) {
+      this.#db.exec('ROLLBACK')
+      throw error
+    }
+  }
+
+  async close(): Promise<void> {
+    this.#db.close()
+  }
+}
+
+interface SqlTag {
+  unsafe(sql: string, params?: unknown[]): Promise<unknown>
+  begin<T>(fn: (tx: SqlTag) => Promise<T>): Promise<T>
+  close(): Promise<void>
+}
+
+class PostgresDb implements Db {
+  readonly dialect = dialectFor('postgres')
+  readonly locks: LockManager
+  #sql: SqlTag
+  #inTransaction: boolean
+
+  constructor(sql: SqlTag, locks?: LockManager, inTransaction = false) {
+    this.#sql = sql
+    this.locks = locks ?? createLockManager(this)
+    this.#inTransaction = inTransaction
+  }
+
+  async query<T = Record<string, unknown>>(sql: string, params: unknown[] = []): Promise<T[]> {
+    return (await this.#sql.unsafe(this.dialect.render(sql), params)) as T[]
+  }
+
+  async exec(sql: string, params: unknown[] = []): Promise<void> {
+    await this.#sql.unsafe(this.dialect.render(sql), params)
+  }
+
+  /** Nested calls join the enclosing transaction, as they do on SQLite. */
+  async transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T> {
+    if (this.#inTransaction) return fn(this)
+    return this.#sql.begin(async (tx) => fn(new PostgresDb(tx, this.locks, true)))
+  }
+
+  async close(): Promise<void> {
+    await this.#sql.close()
+  }
+}
+
+export function resolveDialectName(options: ConnectOptions = {}): DialectName {
+  return options.dialect ?? (Bun.env.CROMBOLO_DB as DialectName | undefined) ?? 'sqlite'
+}
+
+export async function connect(options: ConnectOptions = {}): Promise<Db> {
+  if (resolveDialectName(options) === 'postgres') {
+    const url = options.url ?? Bun.env.CROMBOLO_POSTGRES_URL ?? Bun.env.DATABASE_URL
+    if (!url) throw new Error('Postgres selected but no connection string was provided.')
+    const { SQL } = await import('bun')
+    // A modest pool: many short-lived connections exhaust Postgres' client limit,
+    // and a single process does not need more.
+    const sql = new SQL({ url, max: options.poolSize ?? 5 }) as unknown as SqlTag
+    const db = new PostgresDb(sql)
+    await db.exec('CREATE EXTENSION IF NOT EXISTS citext')
+    return db
+  }
+  const sqlite = new BunSqlite(options.file ?? ':memory:', { create: true })
+  sqlite.exec('PRAGMA journal_mode = WAL')
+  sqlite.exec('PRAGMA foreign_keys = ON')
+  sqlite.exec('PRAGMA busy_timeout = 5000')
+  return new SqliteDb(sqlite)
+}

package/src/dialect.ts

@@ -0,0 +1,128 @@
+/**
+ * The single seam between the services and SQL. Queries are written once with
+ * `?` placeholders and rendered per dialect, so no service ever needs to know
+ * which database it is talking to.
+ */
+export type DialectName = 'sqlite' | 'postgres'
+
+export interface ColumnTypes {
+  identity: string
+  integer: string
+  bigint: string
+  boolean: string
+  uuid: string
+  /** Case-insensitive text. Umbraco compares aliases and logins case-insensitively. */
+  textCi: string
+  text: string
+  varchar: (n: number) => string
+  timestamp: string
+  numeric: string
+  blob: string
+}
+
+export interface Dialect {
+  readonly name: DialectName
+  readonly types: ColumnTypes
+  placeholder(index: number): string
+  quote(identifier: string): string
+  /** Rewrites `?` placeholders into the dialect's own form. */
+  render(sql: string): string
+  now(): string
+  boolValue(value: boolean): unknown
+  /** Appended to a SELECT that must block a concurrent state change; empty where the engine is single-writer. */
+  readonly forShare: string
+  readonly forUpdate: string
+  /**
+   * SQL that moves a table's identity past rows inserted with explicit ids, or
+   * undefined where the engine does that itself.
+   */
+  syncIdentity(table: string): string | undefined
+}
+
+const RESERVED_RENDER = /\?/g
+
+export const sqliteDialect: Dialect = {
+  name: 'sqlite',
+  types: {
+    identity: 'INTEGER PRIMARY KEY AUTOINCREMENT',
+    integer: 'INTEGER',
+    bigint: 'INTEGER',
+    boolean: 'INTEGER',
+    uuid: 'TEXT',
+    // COLLATE NOCASE is how Umbraco gets case-insensitive aliases on SQLite.
+    textCi: 'TEXT COLLATE NOCASE',
+    text: 'TEXT',
+    varchar: (n) => `VARCHAR(${n}) COLLATE NOCASE`,
+    timestamp: 'TEXT',
+    // REAL would be lossy for decimal property values.
+    numeric: 'TEXT',
+    blob: 'BLOB',
+  },
+  placeholder: () => '?',
+  quote: (id) => `"${id.replaceAll('"', '""')}"`,
+  render: (sql) => sql,
+  now: () => "strftime('%Y-%m-%dT%H:%M:%fZ','now')",
+  boolValue: (value) => (value ? 1 : 0),
+  forShare: '',
+  forUpdate: '',
+  syncIdentity: () => undefined,
+}
+
+export const postgresDialect: Dialect = {
+  name: 'postgres',
+  types: {
+    identity: 'INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY',
+    integer: 'INTEGER',
+    bigint: 'BIGINT',
+    boolean: 'BOOLEAN',
+    uuid: 'UUID',
+    // Postgres collates case-sensitively by default; citext restores Umbraco's semantics.
+    textCi: 'CITEXT',
+    text: 'TEXT',
+    varchar: (n) => `VARCHAR(${n})`,
+    timestamp: 'TIMESTAMPTZ',
+    numeric: 'NUMERIC',
+    blob: 'BYTEA',
+  },
+  placeholder: (index) => `$${index}`,
+  quote: (id) => `"${id.replaceAll('"', '""')}"`,
+  render(sql) {
+    let i = 0
+    return sql.replace(RESERVED_RENDER, () => `$${++i}`)
+  },
+  now: () => 'now()',
+  boolValue: (value) => value,
+  forShare: 'FOR SHARE',
+  forUpdate: 'FOR UPDATE',
+  syncIdentity: (table) =>
+    `SELECT setval(pg_get_serial_sequence('${table}', 'id'), (SELECT COALESCE(MAX(id), 1) FROM ${table}))`,
+}
+
+export function dialectFor(name: DialectName): Dialect {
+  return name === 'sqlite' ? sqliteDialect : postgresDialect
+}
+
+/**
+ * Timestamps are written as ISO strings in both dialects — SQLite stores TEXT,
+ * and Postgres parses ISO into timestamptz — but they read back differently
+ * (string vs Date), so every read goes through `fromDb`.
+ */
+export const DbDate = {
+  toDb(value: Date): string {
+    return value.toISOString()
+  },
+  fromDb(value: unknown): Date | undefined {
+    if (value === null || value === undefined) return undefined
+    if (value instanceof Date) return value
+    if (typeof value === 'string') {
+      const parsed = new Date(value)
+      return Number.isNaN(parsed.getTime()) ? undefined : parsed
+    }
+    return undefined
+  },
+}
+
+/** SQLite has no boolean type, so a 0/1 integer comes back for one dialect only. */
+export function fromDbBool(value: unknown): boolean {
+  return value === true || value === 1 || value === '1' || value === 't'
+}