@edge-base/server 0.1.1

package/src/lib/d1-schema-init.ts

@@ -0,0 +1,255 @@
+/**
+ * D1 lazy schema initializer.
+ *
+ * Mirrors postgres-schema-init.ts but for Cloudflare D1 (SQLite):
+ * 1. Creates _meta table if not exists
+ * 2. For each table: compute schema hash, compare with stored hash
+ * 3. If new: CREATE TABLE + indexes + FTS5
+ * 4. If changed: ADD COLUMN for new fields (non-destructive)
+ * 5. Stores schema hash in _meta
+ *
+ * Called once per Worker lifetime per namespace (cached in memory set).
+ */
+import type { TableConfig, MigrationConfig } from '@edge-base/shared';
+import {
+  META_TABLE_DDL,
+  generateTableDDL,
+  generateAddColumnDDL,
+  generateFTS5DDL,
+  generateFTS5Triggers,
+  generateIndexDDL,
+  buildEffectiveSchema,
+  computeSchemaHashSync,
+} from './schema.js';
+import type { SchemaField } from '@edge-base/shared';
+
+// Track initialized namespaces to avoid redundant checks per Worker process.
+const _initialized = new Set<string>();
+
+/**
+ * Ensure D1 schema is up-to-date for a given namespace.
+ * Called once per Worker lifetime per namespace (cached in memory).
+ */
+export async function ensureD1Schema(
+  db: D1Database,
+  namespace: string,
+  tables: Record<string, TableConfig>,
+): Promise<void> {
+  if (_initialized.has(namespace)) {
+    return;
+  }
+
+  await db.prepare(META_TABLE_DDL).run();
+  await db.prepare('PRAGMA foreign_keys = ON;').run();
+  for (const [tableName, config] of Object.entries(tables)) {
+    await initD1Table(db, tableName, config);
+  }
+  _initialized.add(namespace);
+}
+
+/**
+ * Initialize or update a single D1 table.
+ */
+async function initD1Table(
+  db: D1Database,
+  tableName: string,
+  config: TableConfig,
+): Promise<void> {
+  const currentHash = computeSchemaHashSync(config);
+
+  // Check stored hash
+  const storedHash = await getD1Meta(db, `schemaHash:${tableName}`);
+
+  if (storedHash === currentHash) {
+    // No schema change — still check migrations
+    await ensureD1FTSAndIndexes(db, tableName, config);
+    await runD1Migrations(db, tableName, config);
+    return;
+  }
+
+  if (!storedHash) {
+    // First time — create table + indexes + FTS5
+    const ddls = generateTableDDL(tableName, config);
+    const stmts = ddls.map(ddl => db.prepare(ddl));
+    if (stmts.length > 0) {
+      await db.batch(stmts);
+    }
+
+    // Set initial migration version if migrations exist (skip running them —
+    // fresh table already has the latest schema)
+    if (config.migrations?.length) {
+      const maxVersion = Math.max(...config.migrations.map((m: MigrationConfig) => m.version));
+      await setD1Meta(db, `migration_version:${tableName}`, String(maxVersion));
+    }
+  } else {
+    // Schema changed — detect new columns and add them (non-destructive)
+    await handleD1SchemaUpdate(db, tableName, config);
+    // Re-apply FTS and indexes to pick up new field additions
+    await ensureD1FTSAndIndexes(db, tableName, config);
+    // Run pending migrations after schema update
+    await runD1Migrations(db, tableName, config);
+  }
+
+  // Store new hash
+  await setD1Meta(db, `schemaHash:${tableName}`, currentHash);
+}
+
+/**
+ * Non-destructive schema update: detect new columns and ADD COLUMN.
+ * Does NOT drop columns (data safety) — mirrors database-do.ts handleSchemaUpdate().
+ */
+async function handleD1SchemaUpdate(
+  db: D1Database,
+  tableName: string,
+  config: TableConfig,
+): Promise<void> {
+  // Get existing columns from PRAGMA table_info
+  const colResult = await db.prepare(`PRAGMA table_info("${tableName.replace(/"/g, '""')}")`).all();
+  const existingCols = new Set(
+    (colResult.results ?? []).map((r: Record<string, unknown>) => r.name as string),
+  );
+
+  // Build effective schema with auto-fields
+  const effectiveSchema = buildEffectiveSchema(config.schema);
+
+  // Add missing columns
+  const stmts: D1PreparedStatement[] = [];
+  const indexDDLs: string[] = [];
+  for (const [colName, field] of Object.entries(effectiveSchema)) {
+    if (!existingCols.has(colName)) {
+      const columnField = normalizeD1AddColumnField(field);
+      const ddl = generateAddColumnDDL(tableName, colName, columnField);
+      stmts.push(db.prepare(ddl));
+      if (field.unique) {
+        indexDDLs.push(
+          `CREATE UNIQUE INDEX IF NOT EXISTS "${`idx_${tableName}_${colName}`.replace(/"/g, '""')}" ON "${tableName.replace(/"/g, '""')}"("${colName.replace(/"/g, '""')}");`,
+        );
+      }
+    }
+  }
+  if (stmts.length > 0) {
+    await db.batch(stmts);
+  }
+  if (indexDDLs.length > 0) {
+    await db.batch(indexDDLs.map((ddl) => db.prepare(ddl)));
+  }
+}
+
+function normalizeD1AddColumnField(field: SchemaField): SchemaField {
+  return {
+    ...field,
+    // SQLite/D1 cannot add UNIQUE columns inline via ALTER TABLE.
+    unique: false,
+    // Existing rows make NOT NULL additions fail unless a default is supplied.
+    required: field.required && field.default !== undefined,
+    // Primary keys are also unsupported on ALTER TABLE ADD COLUMN.
+    primaryKey: false,
+  };
+}
+
+/**
+ * Ensure FTS5 and indexes are up-to-date after schema changes.
+ */
+async function ensureD1FTSAndIndexes(
+  db: D1Database,
+  tableName: string,
+  config: TableConfig,
+): Promise<void> {
+  const stmts: D1PreparedStatement[] = [];
+  let needsFtsRebuild = false;
+
+  // Re-apply indexes (CREATE IF NOT EXISTS is idempotent)
+  if (config.indexes?.length) {
+    const indexDDLs = generateIndexDDL(tableName, config.indexes);
+    for (const ddl of indexDDLs) {
+      stmts.push(db.prepare(ddl));
+    }
+  }
+
+  // Re-apply FTS5
+  if (config.fts?.length) {
+    const ftsArtifacts = [`${tableName}_fts`, `${tableName}_ai`, `${tableName}_ad`, `${tableName}_au`];
+    const placeholders = ftsArtifacts.map(() => '?').join(', ');
+    const artifactRows = await db
+      .prepare(`SELECT name FROM sqlite_master WHERE name IN (${placeholders})`)
+      .bind(...ftsArtifacts)
+      .all();
+    const existingArtifacts = new Set(
+      (artifactRows.results ?? []).map((row: Record<string, unknown>) => row.name as string),
+    );
+    needsFtsRebuild = ftsArtifacts.some((name) => !existingArtifacts.has(name));
+
+    stmts.push(db.prepare(generateFTS5DDL(tableName, config.fts)));
+    const triggerDDLs = generateFTS5Triggers(tableName, config.fts);
+    for (const ddl of triggerDDLs) {
+      stmts.push(db.prepare(ddl));
+    }
+  }
+
+  if (stmts.length > 0) {
+    await db.batch(stmts);
+  }
+
+  if (config.fts?.length && needsFtsRebuild) {
+    const ftsTableName = `${tableName}_fts`.replace(/"/g, '""');
+    await db.prepare(`INSERT INTO "${ftsTableName}"("${ftsTableName}") VALUES ('rebuild')`).run();
+  }
+}
+
+// ─── Migration Engine ───
+
+/**
+ * Run pending migrations for a D1 table.
+ * Mirrors database-do.ts runMigrations() — uses SQLite `up` field.
+ */
+async function runD1Migrations(
+  db: D1Database,
+  tableName: string,
+  config: TableConfig,
+): Promise<void> {
+  if (!config.migrations?.length) return;
+
+  const versionKey = `migration_version:${tableName}`;
+  const currentVersionStr = await getD1Meta(db, versionKey);
+  const currentVersion = parseInt(currentVersionStr || '1', 10);
+
+  const pending = config.migrations
+    .filter((m: MigrationConfig) => m.version > currentVersion)
+    .sort((a: MigrationConfig, b: MigrationConfig) => a.version - b.version);
+
+  for (const migration of pending) {
+    try {
+      // D1 uses SQLite — use `up` field (not upPg)
+      await db.prepare(migration.up).run();
+      await setD1Meta(db, versionKey, String(migration.version));
+    } catch (err) {
+      console.error(`D1 Migration v${migration.version} failed for ${tableName}:`, err);
+      throw new Error(`D1 Migration v${migration.version} failed: ${(err as Error).message}`);
+    }
+  }
+}
+
+// ─── _meta Helpers ───
+
+async function getD1Meta(
+  db: D1Database,
+  key: string,
+): Promise<string | null> {
+  const row = await db.prepare('SELECT "value" FROM "_meta" WHERE "key" = ?').bind(key).first<{ value: string }>();
+  return row?.value ?? null;
+}
+
+async function setD1Meta(
+  db: D1Database,
+  key: string,
+  value: string,
+): Promise<void> {
+  await db.prepare(
+    'INSERT INTO "_meta" ("key", "value") VALUES (?, ?) ON CONFLICT ("key") DO UPDATE SET "value" = ?',
+  ).bind(key, value, value).run();
+}
+
+/** Reset initialized state (for testing). */
+export function _resetD1SchemaCache(): void {
+  _initialized.clear();
+}

package/src/lib/d1-sql.ts

@@ -0,0 +1,33 @@
+export interface D1SqlResult {
+  rows: Record<string, unknown>[];
+  rowCount: number;
+}
+
+function isRowsQuery(sql: string): boolean {
+  const normalized = sql.trim().replace(/^\(+/, '').toUpperCase();
+  return /^(SELECT|WITH|PRAGMA|EXPLAIN|VALUES)\b/.test(normalized) || /\bRETURNING\b/i.test(sql);
+}
+
+export async function executeD1Sql(
+  db: D1Database,
+  sql: string,
+  params: unknown[] = [],
+): Promise<D1SqlResult> {
+  const stmt = db.prepare(sql);
+  const bound = params.length > 0 ? stmt.bind(...params) : stmt;
+
+  if (isRowsQuery(sql)) {
+    const result = await bound.all();
+    const rows = (result.results ?? []) as Record<string, unknown>[];
+    return {
+      rows,
+      rowCount: rows.length,
+    };
+  }
+
+  const result = await bound.run();
+  return {
+    rows: [],
+    rowCount: result.meta?.changes ?? 0,
+  };
+}

package/src/lib/database-live-config.ts

@@ -0,0 +1,24 @@
+import type { EdgeBaseConfig } from '@edge-base/shared';
+
+export const DEFAULT_DB_LIVE_AUTH_TIMEOUT_MS = 5000;
+export const DEFAULT_DB_LIVE_BATCH_THRESHOLD = 10;
+
+function normalizePositiveInteger(value: unknown, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  const normalized = Math.floor(value);
+  return normalized > 0 ? normalized : fallback;
+}
+
+export function resolveDbLiveAuthTimeoutMs(config?: EdgeBaseConfig): number {
+  return normalizePositiveInteger(
+    config?.databaseLive?.authTimeoutMs,
+    DEFAULT_DB_LIVE_AUTH_TIMEOUT_MS,
+  );
+}
+
+export function resolveDbLiveBatchThreshold(config?: EdgeBaseConfig): number {
+  return normalizePositiveInteger(
+    config?.databaseLive?.batchThreshold,
+    DEFAULT_DB_LIVE_BATCH_THRESHOLD,
+  );
+}

package/src/lib/database-live-emitter.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared database live event emission helpers.
+ *
+ * Used by d1-handler.ts and postgres-handler.ts for fire-and-forget
+ * event delivery to DatabaseLiveDO after successful CUD operations.
+ *
+ * database-do.ts keeps its own internal version (uses DO env).
+ */
+import type { Env } from '../types.js';
+
+export const DATABASE_LIVE_HUB_DO_NAME = 'database-live:hub';
+
+export function buildDbLiveChannel(
+  namespace: string,
+  table: string,
+  instanceId?: string,
+  docId?: string,
+): string {
+  const base = instanceId
+    ? `dblive:${namespace}:${instanceId}:${table}`
+    : `dblive:${namespace}:${table}`;
+  return docId ? `${base}:${docId}` : base;
+}
+
+export function isDbLiveChannel(channel: string): boolean {
+  if (!channel.startsWith('dblive:')) return false;
+  if (channel.startsWith('dblive:presence:') || channel.startsWith('dblive:broadcast:')) {
+    return false;
+  }
+  const parts = channel.split(':');
+  if (parts.length < 3 || parts.length > 5) return false;
+  return parts.every(part => part.length > 0);
+}
+
+/**
+ * Emit a single CUD event to DatabaseLiveDO.
+ * Mirrors database-do.ts emitDbLiveEvent() — fire-and-forget.
+ */
+export function emitDbLiveEvent(
+  env: Env,
+  namespace: string,
+  table: string,
+  type: 'added' | 'modified' | 'removed',
+  docId: string,
+  data: Record<string, unknown> | null,
+  instanceId?: string,
+): Promise<void> {
+  const tableChannel = buildDbLiveChannel(namespace, table, instanceId);
+  const event = { type, table, docId, data, timestamp: new Date().toISOString() };
+  const deliveries = [
+    sendToDatabaseLiveDO(env, { ...event, channel: tableChannel }),
+  ];
+
+  // Document channel: dblive:{namespace}:{table}:{docId}
+  if (docId !== '_bulk') {
+    const docChannel = buildDbLiveChannel(namespace, table, instanceId, docId);
+    deliveries.push(sendToDatabaseLiveDO(env, { ...event, channel: docChannel }));
+  }
+
+  return Promise.all(deliveries).then(() => undefined);
+}
+
+/**
+ * Emit batch CUD events as a single batch_changes message.
+ * Mirrors database-do.ts emitDbLiveBatchEvent().
+ */
+export function emitDbLiveBatchEvent(
+  env: Env,
+  namespace: string,
+  table: string,
+  changes: Array<{ type: 'added' | 'modified' | 'removed'; docId: string; data: Record<string, unknown> | null }>,
+  instanceId?: string,
+): Promise<void> {
+  const tableChannel = buildDbLiveChannel(namespace, table, instanceId);
+  const event = {
+    type: 'batch_changes' as const,
+    channel: tableChannel,
+    table,
+    changes: changes.map(ch => ({
+      type: ch.type,
+      docId: ch.docId,
+      data: ch.data,
+      timestamp: new Date().toISOString(),
+    })),
+    total: changes.length,
+  };
+  return sendToDatabaseLiveDO(env, event, '/internal/batch-event');
+}
+
+/**
+ * Fire-and-forget: send event to DatabaseLiveDO via stub.fetch().
+ * Never blocks CRUD response — errors are silently ignored.
+ */
+export function sendToDatabaseLiveDO(
+  env: Env,
+  event: Record<string, unknown>,
+  path = '/internal/event',
+): Promise<void> {
+  try {
+    const doId = env.DATABASE_LIVE.idFromName(DATABASE_LIVE_HUB_DO_NAME);
+    const stub = env.DATABASE_LIVE.get(doId);
+    return stub.fetch(`http://internal${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(event),
+    }).then(() => undefined).catch(() => undefined);
+  } catch {
+    // Ignore — database live delivery should not block database operations
+    return Promise.resolve();
+  }
+}

package/src/lib/db-sql.ts

@@ -0,0 +1,66 @@
+/**
+ * db.sql tagged template literal → positional `?` prepared statement.
+ * M1.3 벤치마크 결과: positional `?` 채택 (strings.join('?') 패턴).
+ */
+
+/**
+ * A raw SQL fragment that bypasses parameterization.
+ * Use with extreme caution — only for whitelisted table/column names.
+ */
+export class RawSql {
+  constructor(public readonly value: string) {}
+}
+
+/**
+ * Mark a value as raw SQL (no parameterization).
+ * Warning: potential SQL injection if used with unvalidated input.
+ */
+export function raw(value: string): RawSql {
+  return new RawSql(value);
+}
+
+/**
+ * Build a parameterized query from a tagged template literal.
+ * Returns { query, params } for use with `this.ctx.storage.sql.exec()`.
+ */
+export function buildSqlQuery(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): { query: string; params: unknown[] } {
+  const params: unknown[] = [];
+  let query = strings[0];
+
+  for (let i = 0; i < values.length; i++) {
+    const val = values[i];
+    if (val instanceof RawSql) {
+      // Raw SQL fragment — inject directly (no parameterization)
+      query += val.value + strings[i + 1];
+    } else {
+      query += '?' + strings[i + 1];
+      params.push(val);
+    }
+  }
+
+  return { query, params };
+}
+
+/**
+ * Create a `db.sql` tagged template function bound to a DO's SQLite storage.
+ */
+export function createSqlTaggedTemplate(
+  sqlExec: (query: string, ...params: unknown[]) => SqlStorageCursor,
+) {
+  return function sql(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Record<string, unknown>[] {
+    const { query, params } = buildSqlQuery(strings, ...values);
+    return [...sqlExec(query, ...params)];
+  };
+}
+
+/**
+ * Minimal cursor interface for DO SQLite.
+ * The actual type is provided by @cloudflare/workers-types.
+ */
+type SqlStorageCursor = Iterable<Record<string, unknown>>;

package/src/lib/do-retry.ts

@@ -0,0 +1,36 @@
+/**
+ * Durable Object fetch with single retry on transient failure (DO reset).
+ *
+ * Body must be pre-read as a string — ReadableStream cannot be replayed.
+ * Headers are cloned on retry to avoid mutation issues.
+ *
+ * When `safeToRetry` is false (default), non-idempotent requests are NOT
+ * retried to avoid duplicate writes, side-effect duplication (hooks,
+ * triggers, database-live events), and non-idempotent ops like `$op: increment`.
+ */
+export async function fetchDOWithRetry(
+  stub: { fetch: (input: RequestInfo, init?: RequestInit) => Promise<Response> },
+  url: string,
+  init: { method: string; headers: HeadersInit; body?: string | null },
+  options?: { safeToRetry?: boolean },
+): Promise<Response> {
+  try {
+    return await stub.fetch(url, {
+      method: init.method,
+      headers: init.headers,
+      body: init.body ?? undefined,
+    });
+  } catch (err) {
+    // Only retry if the caller explicitly marked the request as safe to retry.
+    // Non-idempotent writes (POST, PATCH with increment, DELETE with hooks)
+    // must NOT be silently retried — let the error propagate to the client.
+    if (!options?.safeToRetry) throw err;
+
+    // DO may have reset — retry once with cloned headers
+    return stub.fetch(url, {
+      method: init.method,
+      headers: new Headers(init.headers),
+      body: init.body ?? undefined,
+    });
+  }
+}