@crombolo/data 0.0.0-stage → 0.9.1

package/src/node-ref.ts

@@ -0,0 +1,107 @@
+/**
+ * A node named on a command line: either its uuid, or a path through the tree
+ * by name.
+ *
+ * Paths exist because nobody hand-types `9a1f3c2e-…`, and the person running a
+ * transfer knows where content sits, not what its key is. One resolver serves
+ * `content export --root` and `content import --under` so the two cannot drift
+ * in what they accept.
+ *
+ * Three rules keep the convenience from becoming ambiguity:
+ *
+ * - a uuid-shaped argument is always a uuid, never a path, so a path can never
+ *   be mistaken for a key or the other way round;
+ * - a path matches case-insensitively by node name, from the content root, with
+ *   a leading slash optional;
+ * - a path matching nothing, or more than one node, is an error that names the
+ *   candidates. Guessing here would place content somewhere nobody chose.
+ */
+import { SystemNodes } from '@crombolo/core'
+import type { Db } from './database.ts'
+import { NodeRepository, type NodeRow } from './repositories/nodes.ts'
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export type NodeRefResolution =
+  | { ok: true; node: NodeRow }
+  | {
+      ok: false
+      reason: 'not-found' | 'ambiguous'
+      /** The segment that failed, or the whole reference when it was a key. */
+      at: string
+      /** What was there instead, to print alongside the failure. */
+      candidates: string[]
+    }
+
+export const looksLikeKey = (ref: string): boolean => UUID.test(ref.trim())
+
+/** `/Campaigns/Autumn 2026` → `['Campaigns', 'Autumn 2026']` */
+export function pathSegments(ref: string): string[] {
+  return ref
+    .split('/')
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0)
+}
+
+/**
+ * Resolves a reference against the tree of `objectTypes`. Pass every object type
+ * a segment could name — a media path runs through media folders, and a document
+ * path through documents only.
+ */
+export async function resolveNodeRef(
+  db: Db,
+  objectTypes: readonly string[],
+  ref: string,
+): Promise<NodeRefResolution> {
+  const nodes = new NodeRepository(db)
+  const trimmed = ref.trim()
+  if (looksLikeKey(trimmed)) {
+    const node = await nodes.byKey(trimmed)
+    return node
+      ? { ok: true, node }
+      : { ok: false, reason: 'not-found', at: trimmed, candidates: [] }
+  }
+
+  const segments = pathSegments(trimmed)
+  if (segments.length === 0) return { ok: false, reason: 'not-found', at: trimmed, candidates: [] }
+
+  let parentId: number = SystemNodes.Root
+  let resolved: NodeRow | undefined
+  for (const segment of segments) {
+    const matches = await nodes.childrenNamed(parentId, objectTypes, segment)
+    if (matches.length === 0)
+      return {
+        ok: false,
+        reason: 'not-found',
+        at: segment,
+        candidates: await nodes.childNames(parentId, objectTypes),
+      }
+    if (matches.length > 1)
+      return {
+        ok: false,
+        reason: 'ambiguous',
+        at: segment,
+        // Two siblings of one name: the keys are the only way to tell them apart.
+        candidates: matches.map((m) => m.key),
+      }
+    resolved = matches[0] as NodeRow
+    parentId = resolved.id
+  }
+  return resolved
+    ? { ok: true, node: resolved }
+    : { ok: false, reason: 'not-found', at: trimmed, candidates: [] }
+}
+
+/** The message a CLI or a finding prints for a failed resolution. */
+export function describeRefFailure(ref: string, failure: NodeRefResolution): string {
+  if (failure.ok) return ''
+  if (failure.reason === 'ambiguous')
+    return `"${ref}": more than one node is named "${failure.at}" here — name one by key: ${failure.candidates.join(', ')}`
+  const there =
+    failure.candidates.length > 0
+      ? ` — there is ${failure.candidates.map((c) => `"${c}"`).join(', ')}`
+      : ''
+  return looksLikeKey(ref)
+    ? `"${ref}": no node with that key here`
+    : `"${ref}": nothing named "${failure.at}"${there}`
+}

package/src/pending.ts

@@ -0,0 +1,25 @@
+/**
+ * An element is pending on a node when the deployment that created it is newer
+ * than the node, or its file says `since` a version the node has not reached.
+ * The one place the rule lives. docs/09-schema-as-code.md, "since".
+ */
+import { compareStates, compareVersions, type NodeSchemaState } from './schema-state.ts'
+
+export interface SinceMarkers {
+  /** The `(version, revision)` of the state that created the row, when known. */
+  since: NodeSchemaState | null
+  /** The file's explicit `since`, when written. */
+  sinceVersion: string | null
+}
+
+/** The state the element goes live in, or null when it is live on this node. */
+export function pendingUntil(markers: SinceMarkers, node: NodeSchemaState): NodeSchemaState | null {
+  if (markers.sinceVersion && compareVersions(markers.sinceVersion, node.version) > 0)
+    return { version: markers.sinceVersion, revision: '0' }
+  if (markers.since && compareStates(markers.since, node) > 0) return markers.since
+  return null
+}
+
+export function isPending(markers: SinceMarkers, node: NodeSchemaState): boolean {
+  return pendingUntil(markers, node) !== null
+}

package/src/repositories/bundles.ts

@@ -0,0 +1,191 @@
+/**
+ * The bundle definitions: what a bundle would contain, not a built bundle.
+ * `docs/17-bundles.md`.
+ *
+ * The selection lists travel as JSON text in single columns. A malformed list
+ * reads back as empty rather than throwing: a definition whose row was edited
+ * by hand should still list and still be deletable.
+ */
+import { randomUUID } from 'node:crypto'
+import type { Db } from '../database.ts'
+import { DbDate, fromDbBool } from '../dialect.ts'
+
+export interface Bundle {
+  id: string
+  name: string
+  contentNodeId: string | null
+  contentLoadChildNodes: boolean
+  mediaIds: string[]
+  mediaLoadChildNodes: boolean
+  elementIds: string[] | null
+  contentTypes: string[]
+  mediaTypes: string[]
+  dataTypes: string[]
+  components: string[]
+  stylesheets: string[]
+  scripts: string[]
+  languages: string[]
+  dictionaryItems: string[]
+  createDate: Date
+  updateDate: Date
+}
+
+/** A definition to store; `id` is assigned when it is new, the dates always. */
+export type BundleInput = Omit<Bundle, 'id' | 'createDate' | 'updateDate'>
+
+interface Row {
+  id: string
+  name: string
+  content_node_id: string | null
+  content_load_child_nodes: unknown
+  media_load_child_nodes: unknown
+  media_ids: string
+  element_ids: string | null
+  content_types: string
+  media_types: string
+  data_types: string
+  components: string
+  stylesheets: string
+  scripts: string
+  languages: string
+  dictionary_items: string
+  create_date: unknown
+  update_date: unknown
+}
+
+const SELECT = `SELECT id, name, content_node_id, content_load_child_nodes,
+                       media_load_child_nodes, media_ids, element_ids, content_types,
+                       media_types, data_types, components, stylesheets,
+                       scripts, languages, dictionary_items, create_date, update_date
+                  FROM bundle`
+
+const list = (value: string | null): string[] => {
+  if (!value) return []
+  try {
+    const parsed = JSON.parse(value) as unknown
+    return Array.isArray(parsed)
+      ? parsed.filter((item): item is string => typeof item === 'string')
+      : []
+  } catch {
+    return []
+  }
+}
+
+const hydrate = (row: Row): Bundle => ({
+  id: row.id,
+  name: row.name,
+  contentNodeId: row.content_node_id,
+  contentLoadChildNodes: fromDbBool(row.content_load_child_nodes),
+  mediaIds: list(row.media_ids),
+  mediaLoadChildNodes: fromDbBool(row.media_load_child_nodes),
+  elementIds: row.element_ids === null ? null : list(row.element_ids),
+  contentTypes: list(row.content_types),
+  mediaTypes: list(row.media_types),
+  dataTypes: list(row.data_types),
+  components: list(row.components),
+  stylesheets: list(row.stylesheets),
+  scripts: list(row.scripts),
+  languages: list(row.languages),
+  dictionaryItems: list(row.dictionary_items),
+  createDate: DbDate.fromDb(row.create_date) ?? new Date(0),
+  updateDate: DbDate.fromDb(row.update_date) ?? new Date(0),
+})
+
+export class BundleRepository {
+  #db: Db
+  constructor(db: Db) {
+    this.#db = db
+  }
+
+  /** By name, which is the order the section lists them in. */
+  async list(
+    options: { skip?: number; take?: number } = {},
+  ): Promise<{ total: number; items: Bundle[] }> {
+    const counted = await this.#db.query<{ total: number }>('SELECT COUNT(*) AS total FROM bundle')
+    const rows = await this.#db.query<Row>(`${SELECT} ORDER BY name LIMIT ? OFFSET ?`, [
+      options.take ?? 100,
+      options.skip ?? 0,
+    ])
+    return { total: Number(counted[0]?.total ?? 0), items: rows.map(hydrate) }
+  }
+
+  async byId(id: string): Promise<Bundle | undefined> {
+    const rows = await this.#db.query<Row>(`${SELECT} WHERE id = ?`, [id])
+    const row = rows[0]
+    return row ? hydrate(row) : undefined
+  }
+
+  async byName(name: string): Promise<Bundle | undefined> {
+    const rows = await this.#db.query<Row>(`${SELECT} WHERE LOWER(name) = ?`, [
+      name.trim().toLowerCase(),
+    ])
+    const row = rows[0]
+    return row ? hydrate(row) : undefined
+  }
+
+  async create(input: BundleInput, id: string = randomUUID()): Promise<Bundle> {
+    const now = new Date()
+    await this.#db.exec(
+      `INSERT INTO bundle
+         (id, name, content_node_id, content_load_child_nodes, media_load_child_nodes,
+          media_ids, element_ids, content_types, media_types, data_types, components,
+          stylesheets, scripts, languages, dictionary_items,
+          create_date, update_date)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        input.name,
+        input.contentNodeId,
+        this.#db.dialect.boolValue(input.contentLoadChildNodes),
+        this.#db.dialect.boolValue(input.mediaLoadChildNodes),
+        JSON.stringify(input.mediaIds),
+        input.elementIds === null ? null : JSON.stringify(input.elementIds),
+        JSON.stringify(input.contentTypes),
+        JSON.stringify(input.mediaTypes),
+        JSON.stringify(input.dataTypes),
+        JSON.stringify(input.components),
+        JSON.stringify(input.stylesheets),
+        JSON.stringify(input.scripts),
+        JSON.stringify(input.languages),
+        JSON.stringify(input.dictionaryItems),
+        DbDate.toDb(now),
+        DbDate.toDb(now),
+      ],
+    )
+    return { ...input, id, createDate: now, updateDate: now }
+  }
+
+  async update(id: string, input: BundleInput): Promise<void> {
+    await this.#db.exec(
+      `UPDATE bundle
+          SET name = ?, content_node_id = ?, content_load_child_nodes = ?,
+              media_load_child_nodes = ?, media_ids = ?, element_ids = ?,
+              content_types = ?, media_types = ?, data_types = ?, components = ?,
+              stylesheets = ?, scripts = ?, languages = ?,
+              dictionary_items = ?, update_date = ?
+        WHERE id = ?`,
+      [
+        input.name,
+        input.contentNodeId,
+        this.#db.dialect.boolValue(input.contentLoadChildNodes),
+        this.#db.dialect.boolValue(input.mediaLoadChildNodes),
+        JSON.stringify(input.mediaIds),
+        input.elementIds === null ? null : JSON.stringify(input.elementIds),
+        JSON.stringify(input.contentTypes),
+        JSON.stringify(input.mediaTypes),
+        JSON.stringify(input.dataTypes),
+        JSON.stringify(input.components),
+        JSON.stringify(input.stylesheets),
+        JSON.stringify(input.scripts),
+        JSON.stringify(input.languages),
+        JSON.stringify(input.dictionaryItems),
+        DbDate.toDb(new Date()),
+        id,
+      ],
+    )
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.#db.exec('DELETE FROM bundle WHERE id = ?', [id])
+  }
+}