@async/db 0.2.0

package/examples/schema-ui/src/cms-ssr.mjs

@@ -0,0 +1,276 @@
+/**
+ * Minimal SSR HTML from schema manifest metadata plus collection records.
+ * @param {unknown} manifest
+ * @param {Record<string, unknown[]>} recordsByCollection
+ */
+export function renderHomePage(manifest, recordsByCollection, options = {}) {
+  const basePath = normalizeBasePath(options.basePath);
+  const collections = Object.values(manifest.collections ?? {}).filter((c) => c.kind === 'collection');
+  const links = collections.map((resource) => {
+    const count = recordsByCollection[resource.name]?.length ?? 0;
+    return `<li><a href="${escapeHtml(joinPaths(basePath, `/cms/${resource.name}`))}">${escapeHtml(resource.editor?.title ?? resource.name)}</a> — ${count} record${count === 1 ? '' : 's'}</li>`;
+  });
+
+  return pageShell({
+    title: 'Schema UI · CMS home',
+    body: `
+    <h1>CMS home</h1>
+    <p>Resources from <code>src/generated/db.schema.json</code>, records loaded from the db mirror.</p>
+    <ul>${links.join('\n')}</ul>
+    <p><a href="${escapeHtml(joinPaths(basePath, '/templates'))}">Static component templates</a> (no live data).</p>`,
+  });
+}
+
+/**
+ * @param {unknown} manifest
+ * @param {string} collectionName
+ * @param {unknown[]} records
+ */
+export function renderCollectionListPage(manifest, collectionName, records, options = {}) {
+  const basePath = normalizeBasePath(options.basePath);
+  const resource = manifest.collections?.[collectionName];
+  if (!resource || resource.kind !== 'collection') {
+    return null;
+  }
+
+  const title = resource.editor?.title ?? collectionName;
+  const rows = records.map((record) => {
+    const id = record?.[resource.idField ?? 'id'];
+    const label = pickListLabel(record, resource);
+    return `<li><a href="${escapeHtml(joinPaths(basePath, `/cms/${collectionName}/${encodeURIComponent(String(id))}`))}">${escapeHtml(label)}</a> <small>(<code>${escapeHtml(String(id))}</code>)</small></li>`;
+  });
+
+  return pageShell({
+    title: `Schema UI · ${title}`,
+    body: `
+    <p><a href="${escapeHtml(joinPaths(basePath, '/'))}">← Home</a></p>
+    <h1>${escapeHtml(title)}</h1>
+    ${resource.editor?.description ? `<p>${escapeHtml(resource.editor.description)}</p>` : ''}
+    <ul>${rows.join('\n')}</ul>`,
+  });
+}
+
+/**
+ * @param {unknown} manifest
+ * @param {string} collectionName
+ * @param {Record<string, unknown> | null} record
+ * @param {Record<string, unknown[]>} recordsByCollection
+ */
+export function renderRecordDetailPage(manifest, collectionName, record, recordsByCollection, options = {}) {
+  const basePath = normalizeBasePath(options.basePath);
+  const resource = manifest.collections?.[collectionName];
+  if (!resource || resource.kind !== 'collection' || !record) {
+    return null;
+  }
+
+  const title = resource.editor?.title ?? collectionName;
+  const fields = Object.entries(resource.fields ?? {});
+  const viewBlocks = fields.map(([fieldName, field]) => renderFieldBlock('view', fieldName, field, record[fieldName], recordsByCollection, { basePath }));
+  const editorBlocks = fields.map(([fieldName, field]) => renderFieldBlock('editor', fieldName, field, record[fieldName], recordsByCollection));
+
+  const id = record[resource.idField ?? 'id'];
+
+  return pageShell({
+    title: `Schema UI · ${title} · ${id}`,
+    body: `
+    <p><a href="${escapeHtml(joinPaths(basePath, '/'))}">← Home</a> · <a href="${escapeHtml(joinPaths(basePath, `/cms/${collectionName}`))}">← ${escapeHtml(title)}</a></p>
+    <h1>${escapeHtml(String(record.title ?? record.name ?? id))}</h1>
+    ${resource.editor?.description ? `<p>${escapeHtml(resource.editor.description)}</p>` : ''}
+    <section class="cms-live-view">
+      <h2>Rendered view</h2>
+${viewBlocks.join('\n')}
+    </section>
+    <section class="cms-live-editor">
+      <h2>Rendered editor</h2>
+      <form method="post" action="#" class="cms-editor-demo">
+        <p><small>This example only renders markup; it does not persist edits.</small></p>
+${editorBlocks.join('\n')}
+      </form>
+    </section>`,
+  });
+}
+
+function pageShell({ title, body }) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(title)}</title>
+  <style>
+    body { font-family: system-ui, sans-serif; line-height: 1.45; max-width: 52rem; margin: 2rem auto; padding: 0 1rem; color: #111; }
+    code { font-size: 0.9em; }
+    section { margin-top: 2rem; padding-top: 1rem; border-top: 1px solid #ddd; }
+    .field-block { margin: 1rem 0; }
+    .field-block label { display: block; font-weight: 600; margin-bottom: 0.25rem; }
+    .field-block small { display: block; color: #555; margin-top: 0.25rem; }
+    article[data-markdown] { white-space: pre-wrap; border-left: 3px solid #ccc; padding-left: 1rem; }
+  </style>
+</head>
+<body>
+  <main>
+${body}
+  </main>
+</body>
+</html>`;
+}
+
+function pickListLabel(record, resource) {
+  if (!record || typeof record !== 'object') {
+    return '';
+  }
+  if (typeof record.title === 'string') {
+    return record.title;
+  }
+  if (typeof record.name === 'string') {
+    return record.name;
+  }
+  const idField = resource.idField ?? 'id';
+  return String(record[idField] ?? '');
+}
+
+/**
+ * @param {'view' | 'editor'} mode
+ */
+function renderFieldBlock(mode, fieldName, field, value, recordsByCollection, options = {}) {
+  const component = field.ui?.component ?? 'text';
+  const label = field.ui?.label ?? labelFromFieldName(fieldName);
+  const inner = mode === 'view'
+    ? renderViewField(component, fieldName, field, value, recordsByCollection, options)
+    : renderEditorField(component, fieldName, field, value, recordsByCollection);
+
+  return `      <div class="field-block" data-component="${escapeHtml(component)}" data-field="${escapeHtml(fieldName)}">
+        <label>${escapeHtml(label)}</label>
+        ${inner}
+      </div>`;
+}
+
+function renderViewField(component, fieldName, field, value, recordsByCollection, options = {}) {
+  switch (component) {
+    case 'email': {
+      const text = scalarText(value);
+      return `<a href="mailto:${escapeHtml(text)}">${escapeHtml(text)}</a>${hint(field)}`;
+    }
+    case 'textarea':
+      return `<p>${escapeHtml(scalarText(value))}</p>${hint(field)}`;
+    case 'markdown':
+      return `<article data-markdown data-field="${escapeHtml(fieldName)}">${escapeHtml(scalarText(value))}</article>${hint(field)}`;
+    case 'segmented-control':
+      return `<span>${escapeHtml(scalarText(value))}</span>${hint(field)}`;
+    case 'relationSelect':
+      return `${relationAnchor(field, value, recordsByCollection, options)}${hint(field)}`;
+    case 'text':
+    default:
+      if (field.ui?.readonly) {
+        return `<span><code>${escapeHtml(scalarText(value))}</code></span>${hint(field)}`;
+      }
+      return `<span>${escapeHtml(scalarText(value))}</span>${hint(field)}`;
+  }
+}
+
+function renderEditorField(component, fieldName, field, value, recordsByCollection) {
+  if (field.ui?.readonly) {
+    return `<span><code>${escapeHtml(scalarText(value))}</code></span>${hint(field)}`;
+  }
+
+  const req = field.required ? 'required' : '';
+
+  switch (component) {
+    case 'email':
+      return `<input type="email" name="${escapeHtml(fieldName)}" value="${escapeHtml(scalarText(value))}" ${req}>${hint(field)}`;
+    case 'textarea':
+      return `<textarea name="${escapeHtml(fieldName)}" rows="4" cols="48" ${req}>${escapeHtml(scalarText(value))}</textarea>${hint(field)}`;
+    case 'markdown':
+      return `<textarea name="${escapeHtml(fieldName)}" rows="10" cols="48" data-editor="markdown" ${req}>${escapeHtml(scalarText(value))}</textarea>${hint(field)}`;
+    case 'segmented-control': {
+      const vals = Array.isArray(field.values) ? field.values : [];
+      const current = scalarText(value);
+      const radios = vals.map((option) => (
+        `<label><input type="radio" name="${escapeHtml(fieldName)}" value="${escapeHtml(String(option))}" ${current === String(option) ? 'checked' : ''}> ${escapeHtml(String(option))}</label>`
+      ));
+      return `<fieldset>${radios.join('<br>\n')}</fieldset>${hint(field)}`;
+    }
+    case 'relationSelect':
+      return `${relationSelect(field, fieldName, value, recordsByCollection)}${hint(field)}`;
+    case 'text':
+    default:
+      return `<input type="text" name="${escapeHtml(fieldName)}" value="${escapeHtml(scalarText(value))}" ${req}>${hint(field)}`;
+  }
+}
+
+function relationAnchor(field, foreignKey, recordsByCollection, options = {}) {
+  const keyText = scalarText(foreignKey);
+  if (!field.relation?.to || keyText === '') {
+    return `<span>${escapeHtml(keyText)}</span>`;
+  }
+  const label = relationDisplayLabel(field, foreignKey, recordsByCollection);
+  const targetCollection = field.relation.to;
+  return `<a href="${escapeHtml(joinPaths(options.basePath, `/cms/${targetCollection}/${encodeURIComponent(keyText)}`))}">${escapeHtml(label)}</a>`;
+}
+
+function relationSelect(field, fieldName, selectedKey, recordsByCollection) {
+  const targetCollection = field.relation?.to ?? field.ui?.optionsFrom;
+  const idField = field.relation?.toField ?? 'id';
+  const rows = targetCollection ? recordsByCollection[targetCollection] ?? [] : [];
+  const current = scalarText(selectedKey);
+  const options = [`<option value="">Choose…</option>`].concat(rows.map((row) => {
+    const id = row?.[idField];
+    const label = row?.name ?? row?.email ?? row?.title ?? String(id ?? '');
+    return `<option value="${escapeHtml(String(id ?? ''))}" ${String(id ?? '') === current ? 'selected' : ''}>${escapeHtml(String(label))}</option>`;
+  }));
+  return `<select name="${escapeHtml(fieldName)}">${options.join('\n')}</select>`;
+}
+
+function relationDisplayLabel(field, foreignKey, recordsByCollection) {
+  const targetCollection = field.relation?.to;
+  const idField = field.relation?.toField ?? 'id';
+  if (!targetCollection) {
+    return scalarText(foreignKey);
+  }
+  const rows = recordsByCollection[targetCollection] ?? [];
+  const match = rows.find((row) => String(row?.[idField] ?? '') === String(foreignKey ?? ''));
+  if (!match) {
+    return scalarText(foreignKey);
+  }
+  return String(match.name ?? match.email ?? match.title ?? foreignKey ?? '');
+}
+
+function scalarText(value) {
+  if (value === undefined || value === null) {
+    return '';
+  }
+  return String(value);
+}
+
+function hint(field) {
+  return field.description ? `<small>${escapeHtml(field.description)}</small>` : '';
+}
+
+function labelFromFieldName(fieldName) {
+  return fieldName
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+
+function normalizeBasePath(basePath) {
+  if (!basePath || basePath === '/') {
+    return '';
+  }
+  return `/${String(basePath).replace(/^\/+|\/+$/gu, '')}`;
+}
+
+function joinPaths(basePath, childPath) {
+  const normalizedBase = normalizeBasePath(basePath);
+  const normalizedChild = `/${String(childPath).replace(/^\/+/u, '')}`;
+  return `${normalizedBase}${normalizedChild}`;
+}
+
+export function escapeHtml(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#039;');
+}

package/examples/schema-ui/src/generated/db.schema.json

@@ -0,0 +1,133 @@
+{
+  "version": 1,
+  "collections": {
+    "pages": {
+      "kind": "collection",
+      "name": "pages",
+      "fields": {
+        "id": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Stable page id.",
+          "ui": {
+            "label": "Id",
+            "component": "text",
+            "readonly": true
+          }
+        },
+        "title": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Page title shown in the CMS list.",
+          "ui": {
+            "label": "Title",
+            "component": "text"
+          }
+        },
+        "status": {
+          "type": "enum",
+          "required": false,
+          "nullable": false,
+          "description": "Publication state.",
+          "default": "draft",
+          "values": [
+            "draft",
+            "review",
+            "published"
+          ],
+          "ui": {
+            "label": "Status",
+            "component": "segmented-control"
+          }
+        },
+        "authorId": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Page author.",
+          "relation": {
+            "name": "author",
+            "to": "users",
+            "toField": "id",
+            "cardinality": "one"
+          },
+          "ui": {
+            "label": "Author Id",
+            "component": "relationSelect",
+            "optionsFrom": "users"
+          }
+        },
+        "summary": {
+          "type": "string",
+          "required": false,
+          "nullable": false,
+          "description": "Short page summary.",
+          "maxLength": 160,
+          "ui": {
+            "label": "Summary",
+            "component": "textarea"
+          }
+        },
+        "bodyMarkdown": {
+          "type": "string",
+          "required": false,
+          "nullable": false,
+          "description": "Markdown body content.",
+          "ui": {
+            "label": "Body",
+            "component": "markdown"
+          }
+        }
+      },
+      "description": "CMS pages rendered by a tiny schema-driven UI example.",
+      "idField": "id",
+      "editor": {
+        "title": "Pages",
+        "description": "CMS pages edited from generated schema metadata."
+      }
+    },
+    "users": {
+      "kind": "collection",
+      "name": "users",
+      "fields": {
+        "id": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Stable author id.",
+          "ui": {
+            "label": "Id",
+            "component": "text",
+            "readonly": true
+          }
+        },
+        "name": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Author display name.",
+          "ui": {
+            "label": "Name",
+            "component": "text"
+          }
+        },
+        "email": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Author email address.",
+          "unique": true,
+          "ui": {
+            "label": "Email",
+            "component": "email"
+          }
+        }
+      },
+      "description": "Authors that can own CMS pages.",
+      "idField": "id"
+    }
+  },
+  "documents": {}
+}

package/examples/schema-ui/src/generated/db.types.d.ts

@@ -0,0 +1,46 @@
+/* eslint-disable */
+// This file is generated by db. Do not edit by hand.
+
+export type PageStatus = "draft" | "review" | "published";
+
+/** CMS pages rendered by a tiny schema-driven UI example. */
+export type Page = {
+  /** Stable page id. */
+  id: string;
+  /** Page title shown in the CMS list. */
+  title: string;
+  /** Publication state. */
+  status?: PageStatus;
+  /** Page author. */
+  authorId: string;
+  /** Short page summary. */
+  summary?: string;
+  /** Markdown body content. */
+  bodyMarkdown?: string;
+};
+
+/** Authors that can own CMS pages. */
+export type User = {
+  /** Stable author id. */
+  id: string;
+  /** Author display name. */
+  name: string;
+  /** Author email address. */
+  email: string;
+};
+
+export type DbCollections = {
+  pages: Page;
+  users: User;
+};
+
+export type DbDocuments = {
+};
+
+export type DbTypes = {
+  collections: DbCollections;
+  documents: DbDocuments;
+};
+
+export type DbCollectionName = keyof DbCollections;
+export type DbDocumentName = keyof DbDocuments;

package/examples/schema-ui/src/render-admin.mjs

@@ -0,0 +1,175 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const fieldTemplates = [
+  {
+    component: 'text',
+    view({ fieldName, field }) {
+      return `<span data-field="${escapeHtml(fieldName)}">{{ ${escapeHtml(fieldName)} }}</span>${hint(field)}`;
+    },
+    editor({ fieldName, field }) {
+      return `<input name="${escapeHtml(fieldName)}" type="text" ${required(field)}>${hint(field)}`;
+    },
+  },
+  {
+    component: 'email',
+    view({ fieldName, field }) {
+      return `<a href="mailto:{{ ${escapeHtml(fieldName)} }}">{{ ${escapeHtml(fieldName)} }}</a>${hint(field)}`;
+    },
+    editor({ fieldName, field }) {
+      return `<input name="${escapeHtml(fieldName)}" type="email" ${required(field)}>${hint(field)}`;
+    },
+  },
+  {
+    component: 'textarea',
+    view({ fieldName, field }) {
+      return `<p data-field="${escapeHtml(fieldName)}">{{ ${escapeHtml(fieldName)} }}</p>${hint(field)}`;
+    },
+    editor({ fieldName, field }) {
+      return `<textarea name="${escapeHtml(fieldName)}" ${required(field)}></textarea>${hint(field)}`;
+    },
+  },
+  {
+    component: 'markdown',
+    view({ fieldName, field }) {
+      return `<article data-field="${escapeHtml(fieldName)}">{{ rendered ${escapeHtml(fieldName)} }}</article>${hint(field)}`;
+    },
+    editor({ fieldName, field }) {
+      return `<textarea name="${escapeHtml(fieldName)}" data-editor="markdown" ${required(field)}></textarea>${hint(field)}`;
+    },
+  },
+  {
+    component: 'segmented-control',
+    view({ fieldName, field }) {
+      return `<span data-field="${escapeHtml(fieldName)}">{{ ${escapeHtml(fieldName)} }}</span>${hint(field)}`;
+    },
+    editor({ fieldName, field }) {
+      return `<fieldset>${legend(field)}${options(field).map((value) => (
+        `<label><input type="radio" name="${escapeHtml(fieldName)}" value="${escapeHtml(value)}"> ${escapeHtml(value)}</label>`
+      )).join('')}</fieldset>${hint(field)}`;
+    },
+  },
+  {
+    component: 'relationSelect',
+    view({ fieldName, field }) {
+      const relation = field.relation?.name ?? fieldName;
+      return `<a href="#${escapeHtml(relation)}-{{ ${escapeHtml(fieldName)} }}">{{ ${escapeHtml(relation)} label }}</a>${hint(field)}`;
+    },
+    editor({ fieldName, field }) {
+      const source = field.ui?.optionsFrom ?? field.relation?.to ?? 'records';
+      return `<select name="${escapeHtml(fieldName)}" data-options-from="${escapeHtml(source)}" ${required(field)}></select>${hint(field)}`;
+    },
+  },
+];
+
+const templateByComponent = new Map(fieldTemplates.map((template) => [template.component, template]));
+const fallbackTemplate = templateByComponent.get('text');
+
+/** @param {unknown} schemaManifest */
+export function renderSchemaUiHtml(schemaManifest) {
+  return renderCms(schemaManifest);
+}
+
+/** @param {URL | string} manifestUrl */
+export async function readManifest(manifestUrl) {
+  const raw = await readFile(manifestUrl, 'utf8');
+  return JSON.parse(raw);
+}
+
+function renderCms(schemaManifest) {
+  const collections = Object.values(schemaManifest.collections ?? {});
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Schema UI Example</title>
+</head>
+<body>
+  <main>
+    <h1>Schema UI Example</h1>
+    <p>This HTML is generated from src/generated/db.schema.json.</p>
+${collections.map(renderCollection).join('\n')}
+  </main>
+</body>
+</html>`;
+}
+
+function renderCollection(resource) {
+  const title = resource.editor?.title ?? resource.name;
+  const description = resource.editor?.description ?? resource.description ?? '';
+  const fields = Object.entries(resource.fields ?? {});
+  return `    <section data-resource="${escapeHtml(resource.name)}">
+      <header>
+        <h2>${escapeHtml(title)}</h2>
+        ${description ? `<p>${escapeHtml(description)}</p>` : ''}
+      </header>
+      <div class="cms-view">
+        <h3>View template</h3>
+${fields.map(([fieldName, field]) => renderField('view', fieldName, field)).join('\n')}
+      </div>
+      <form class="cms-editor">
+        <h3>Editor template</h3>
+${fields.map(([fieldName, field]) => renderField('editor', fieldName, field)).join('\n')}
+      </form>
+    </section>`;
+}
+
+function renderField(mode, fieldName, field) {
+  const component = field.ui?.component ?? 'text';
+  const template = templateByComponent.get(component) ?? fallbackTemplate;
+  const label = field.ui?.label ?? labelFromFieldName(fieldName);
+  const body = template[mode]({ fieldName, field });
+
+  return `        <template data-mode="${mode}" data-component="${escapeHtml(component)}" data-field="${escapeHtml(fieldName)}">
+          <label>${escapeHtml(label)}</label>
+          ${body}
+        </template>`;
+}
+
+function required(field) {
+  return field.required ? 'required' : '';
+}
+
+function legend(field) {
+  return `<legend>${escapeHtml(field.ui?.label ?? 'Choose one')}</legend>`;
+}
+
+function options(field) {
+  return Array.isArray(field.values) ? field.values : [];
+}
+
+function hint(field) {
+  return field.description ? `<small>${escapeHtml(field.description)}</small>` : '';
+}
+
+function labelFromFieldName(fieldName) {
+  return fieldName
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#039;');
+}
+
+function isPrimaryModule() {
+  const entry = process.argv[1];
+  if (!entry) {
+    return false;
+  }
+  return path.resolve(entry) === path.resolve(fileURLToPath(import.meta.url));
+}
+
+if (isPrimaryModule()) {
+  const manifestUrl = new URL('./generated/db.schema.json', import.meta.url);
+  const manifest = await readManifest(manifestUrl);
+  console.log(renderSchemaUiHtml(manifest));
+}