@fabrika/platform-node 0.0.1

package/src/sql-postgres.ts

@@ -0,0 +1,176 @@
+// `SqlDatabase` over Postgres, using Bun's BUILT-IN SQL client (`Bun.SQL`).
+//
+// No driver dependency: `postgres`/`pg` would add a package, a second connection pool implementation
+// and a second set of type-coercion rules for nothing — `Bun.SQL` already gives a pooled client,
+// `unsafe(text, values)` for pre-built parameterised statements (which is exactly what a D1-shaped
+// port needs — `prepare()` then `bind()`, not a tagged template) and `begin()` for real transactions.
+// The runtime is Bun (ADR-0003: the control plane itself executes deploys on Zerops), so the built-in
+// is available by construction.
+//
+// WHERE POSTGRES DIVERGES FROM D1 — the port hides the API, not the engine. Read this before moving
+// an existing service onto this driver:
+//
+//  * `meta.changes` — Bun reports `count` on the result. For a SELECT that is the ROW COUNT, which D1
+//    reports as 0, so `run()` maps `count` to `changes` only for INSERT/UPDATE/DELETE/MERGE and
+//    reports 0 otherwise. The guarded-UPDATE idiom (`changes === 0` means the guard did not match) is
+//    therefore accurate on both, including for `… RETURNING`, where `count` is the affected-row count.
+//  * BIGINT / NUMERIC COLUMNS COME BACK AS STRINGS. Bun decodes by column type, not by value: `int8`
+//    and `numeric` are `string` (or `bigint` with `{ bigint: true }`), never `number`, even for a
+//    value of 5. SQLite/D1 hand back a `number`. Any column a row shape types as `number` must be
+//    `INTEGER` (int4) in the Postgres migration, or the caller must coerce. int4 tops out at
+//    2147483647 — fine for the unix-SECONDS timestamps this codebase uses, NOT for unix millis.
+//  * PARAMETER TYPES ARE CHECKED. `WHERE text_col = $1` bound with a number fails with
+//    `operator does not exist: text = integer`; SQLite would have compared them happily (and returned
+//    no rows). This surfaces latent bind-type bugs as loud errors rather than silent empty results.
+//  * `undefined` binds as NULL (D1 throws). Kept deliberately: both existing bun:sqlite test harnesses
+//    already coerce `undefined` → null, so this matches what the services are tested against.
+//  * SQLite-only SQL still fails, obviously: `unixepoch()` does not exist in Postgres. Several
+//    statements in `@fabrika/control` and `@fabrika/iam` use it today.
+//  * Prepared statements are cached per connection by default. Behind a transaction-mode pooler
+//    (pgbouncer) construct the client with `{ prepare: false }`.
+
+import type { SqlDatabase, SqlQueryResult, SqlRunResult, SqlStatement } from '@fabrika/platform'
+import { rewritePlaceholders, type RewrittenSql } from './placeholders'
+
+/** Command tags whose row count IS an affected-row count. Anything else reports `changes: 0`, as D1 does. */
+const MUTATING_COMMANDS = new Set(['INSERT', 'UPDATE', 'DELETE', 'MERGE'])
+
+/** What a bound value may be. Anything else is a programming error and throws at bind time, as D1 does. */
+export type SqlBindValue = string | number | bigint | boolean | Date | Uint8Array | null
+
+/**
+ * One prepared statement. IMMUTABLE: `bind()` returns a NEW statement carrying the values and leaves
+ * the receiver untouched, which is D1's contract and what call sites rely on when they prepare once
+ * and bind in a loop.
+ */
+export class PostgresStatement implements SqlStatement {
+	constructor(
+		private readonly sql: Bun.SQL,
+		private readonly text: string,
+		private readonly placeholders: number,
+		private readonly values: readonly SqlBindValue[],
+	) {}
+
+	bind(...values: unknown[]): SqlStatement {
+		return new PostgresStatement(this.sql, this.text, this.placeholders, values.map(toBindValue))
+	}
+
+	async first<T = Record<string, unknown>>(): Promise<T | null> {
+		const rows = await this.rows<T>(this.sql)
+		return rows[0] ?? null
+	}
+
+	async all<T = Record<string, unknown>>(): Promise<SqlQueryResult<T>> {
+		return { results: await this.rows<T>(this.sql) }
+	}
+
+	async run(): Promise<SqlRunResult> {
+		const result: unknown = await this.execute<Record<string, unknown>>(this.sql)
+		return { meta: { changes: changesOf(result) } }
+	}
+
+	/**
+	 * Run this statement on a specific handle — the pool, or the transaction-scoped handle `batch()`
+	 * opens. Internal to the package; the port only ever sees `first`/`all`/`run`.
+	 */
+	async rows<T>(handle: Bun.SQL): Promise<T[]> {
+		return this.execute<T>(handle)
+	}
+
+	private execute<T>(handle: Bun.SQL): Promise<T[]> {
+		if (this.values.length !== this.placeholders) {
+			throw new Error(`statement expects ${this.placeholders} bound value(s), got ${this.values.length}`)
+		}
+		return handle.unsafe<T[]>(this.text, [...this.values])
+	}
+}
+
+/**
+ * A Postgres-backed `SqlDatabase`. Rewritten statement text is memoised per SQL string, so the
+ * prepare-once/bind-many idiom tokenises each statement exactly once.
+ */
+export class PostgresDatabase implements SqlDatabase {
+	private readonly rewrites = new Map<string, RewrittenSql>()
+
+	constructor(private readonly sql: Bun.SQL) {}
+
+	/**
+	 * Open a pooled client. The URL is a CREDENTIAL — it is never logged, and never included in an
+	 * error message raised here.
+	 */
+	static connect(url: string, options: Omit<Bun.SQL.PostgresOrMySQLOptions, 'url' | 'adapter'> = {}): PostgresDatabase {
+		return new PostgresDatabase(new Bun.SQL({ ...options, url, adapter: 'postgres' }))
+	}
+
+	prepare(sql: string): SqlStatement {
+		let rewritten = this.rewrites.get(sql)
+		if (rewritten === undefined) {
+			rewritten = rewritePlaceholders(sql)
+			this.rewrites.set(sql, rewritten)
+		}
+		return new PostgresStatement(this.sql, rewritten.text, rewritten.count, [])
+	}
+
+	/** Run every statement in ONE transaction, in order. A throw rolls the whole batch back. */
+	async batch<T = Record<string, unknown>>(statements: SqlStatement[]): Promise<SqlQueryResult<T>[]> {
+		const run = async (tx: Bun.SQL): Promise<SqlQueryResult<T>[]> => {
+			const out: SqlQueryResult<T>[] = []
+			for (const statement of statements) {
+				if (!(statement instanceof PostgresStatement)) {
+					throw new Error('batch() accepts only statements created by this database')
+				}
+				out.push({ results: await statement.rows<T>(tx) })
+			}
+			return out
+		}
+		return this.sql.begin(run)
+	}
+
+	/** Close the pool. Waits for in-flight queries unless a timeout is given. */
+	async close(options?: { timeout?: number }): Promise<void> {
+		await this.sql.close(options)
+	}
+}
+
+/** The rows-affected count D1 would report, or 0 for a statement that changes nothing. */
+function changesOf(result: unknown): number {
+	const command: unknown = readProperty(result, 'command')
+	if (typeof command === 'string' && !MUTATING_COMMANDS.has(command)) {
+		return 0
+	}
+	const count: unknown = readProperty(result, 'count')
+	return typeof count === 'number' ? count : 0
+}
+
+function readProperty(value: unknown, key: string): unknown {
+	if (typeof value !== 'object' || value === null) {
+		return undefined
+	}
+	return Reflect.get(value, key)
+}
+
+/**
+ * Narrow a bound value to something the driver can send. `undefined` becomes NULL (see the divergence
+ * note at the top); anything else non-scalar is a bug in the call site and throws immediately, rather
+ * than being silently JSON-ified into a column.
+ */
+function toBindValue(value: unknown): SqlBindValue {
+	if (value === undefined) {
+		return null
+	}
+	if (
+		value === null
+		|| typeof value === 'string'
+		|| typeof value === 'number'
+		|| typeof value === 'bigint'
+		|| typeof value === 'boolean'
+		|| value instanceof Date
+		|| value instanceof Uint8Array
+	) {
+		return value
+	}
+	if (value instanceof ArrayBuffer) {
+		return new Uint8Array(value)
+	}
+	throw new Error(`unsupported bind value of type ${typeof value}`)
+}

package/src/uuid.ts

@@ -0,0 +1,94 @@
+/**
+ * UUIDv7 generator — time-ordered ids, so a jobs table orders by id chronologically and a keyset
+ * cursor works, monotonic WITHIN a millisecond as well as across one. Ids are minted CALLER-SIDE,
+ * never by SQL (the repo-wide convention, and the one thing that keeps inserts identical across
+ * SQLite and Postgres). Self-contained so this package has no dependencies beyond the port it
+ * implements.
+ *
+ * RFC 9562 layout, with §6.2's "fixed bit-length dedicated counter" monotonic variant:
+ *
+ *   bytes 0..5   48-bit big-endian Unix-millis timestamp
+ *   byte  6      version nibble `7` + the high 4 bits of a 12-bit counter (`rand_a`)
+ *   byte  7      the low 8 bits of that counter
+ *   byte  8      variant bits `10` + 6 random bits
+ *   bytes 9..15  56 random bits
+ *
+ * so **62 random bits per id** — down from the 74 of the unguarded Method 0 this used to be — plus 8
+ * fresh random bits seeding the counter at each new millisecond.
+ *
+ * The counter is re-seeded from 8 random bits (the top 4 left zero, the RFC's rollover guard, so at
+ * least 3840 ids per millisecond are guaranteed) whenever the millisecond advances, and incremented
+ * otherwise. `rand_a` sits immediately after the timestamp and the version nibble in the canonical
+ * string, so two ids minted in the same millisecond differ there and a TEXT `ORDER BY` puts them in
+ * mint order, strictly.
+ *
+ * Two clock hazards are handled explicitly rather than by wrapping:
+ *   - counter exhausted inside one millisecond → borrow one millisecond from the future (RFC 9562
+ *     §6.2) and re-seed; the borrowed time is repaid as soon as the clock catches up.
+ *   - the timestamp goes BACKWARDS → keep the last effective millisecond and keep counting, so the
+ *     sequence never repeats and never decreases.
+ *
+ * The counter is per GENERATOR — one process. Two ids minted in the same millisecond by two processes
+ * tie only if their independently seeded counters collide (~1/256), and the 62 random bits break
+ * that; within one process the order is exact. That is the whole promise: strictly increasing per
+ * generator, chronological to the millisecond across generators.
+ *
+ * `millis` is injectable so a caller that already has a clock (the job queue does) mints ids on THAT
+ * clock, keeping id order and row order consistent. Because the generator is monotonic, the timestamp
+ * actually embedded is `max(millis, last embedded)`: a supplied millisecond BEHIND one already used
+ * is clamped, and the counter carries the ordering instead. Ordering is the promise; an exact
+ * round-trip of an arbitrary past `millis` is not.
+ *
+ * `@fabrika/auth-core` and `@fabrika/control` carry deliberate copies of this same algorithm — see
+ * the note in each.
+ */
+
+/** `rand_a` is 12 bits, all of it counter. */
+const COUNTER_MAX = 0xfff
+/** Seed from 8 random bits only — the leading 4 stay zero so a millisecond has room to count. */
+const COUNTER_SEED_MASK = 0xff
+
+/** Effective millisecond of the last id. NEVER decreases; a backwards clock is absorbed here. */
+let lastMillis = -1
+let counter = 0
+
+export function uuidv7(millis: number = Date.now()): string {
+	const bytes = new Uint8Array(16)
+	crypto.getRandomValues(bytes)
+
+	// Byte 7 is read as the counter seed BEFORE the counter overwrites it, so the seed costs no extra
+	// randomness.
+	const seed = (bytes[7] ?? 0) & COUNTER_SEED_MASK
+	if (millis > lastMillis) {
+		lastMillis = millis
+		counter = seed
+	} else if (counter < COUNTER_MAX) {
+		// Same millisecond, or a clock that went backwards: hold the effective timestamp, count on.
+		counter += 1
+	} else {
+		// Exhausted — borrow a millisecond from the future rather than wrap back under the last id.
+		lastMillis += 1
+		counter = seed
+	}
+
+	// 48-bit big-endian timestamp in bytes 0..5.
+	bytes[0] = (lastMillis / 2 ** 40) & 0xff
+	bytes[1] = (lastMillis / 2 ** 32) & 0xff
+	bytes[2] = (lastMillis / 2 ** 24) & 0xff
+	bytes[3] = (lastMillis / 2 ** 16) & 0xff
+	bytes[4] = (lastMillis / 2 ** 8) & 0xff
+	bytes[5] = lastMillis & 0xff
+
+	// Version 7 in the high nibble of byte 6, the counter in the remaining 12 bits of `rand_a`;
+	// variant (10xx) in the high bits of byte 8.
+	bytes[6] = 0x70 | (counter >>> 8)
+	bytes[7] = counter & 0xff
+	bytes[8] = (bytes[8] ?? 0) & 0x3f | 0x80
+
+	const hex: string[] = []
+	for (const b of bytes) {
+		hex.push(b.toString(16).padStart(2, '0'))
+	}
+	const s = hex.join('')
+	return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20)}`
+}

package/src/wait-until.ts

@@ -0,0 +1,69 @@
+// `WaitUntil` for a long-running process — the seam that stops call sites branching on the runtime.
+//
+// On Workers `ctx.waitUntil` keeps the isolate alive past the response. A Bun process is already
+// alive, so all this has to do is SUPERVISE: hold a reference so a graceful shutdown can wait for the
+// work, and — the part that actually matters — swallow rejections. An unhandled rejection from a
+// background promise terminates the process by default, which would turn a failed log flush into an
+// outage. Every rejection is logged as a short message and dropped.
+//
+// `drain()` exists for the two moments a process needs it: shutdown (finish what was promised before
+// exiting) and tests (assert on the effect of background work without sleeping).
+
+import type { WaitUntil } from '@fabrika/platform'
+
+export interface BackgroundTasks {
+	/** The port itself. Hand it a promise and forget it; it never throws and never rejects. */
+	readonly waitUntil: WaitUntil
+	/** How many supervised promises are still in flight. */
+	readonly pending: number
+	/** Settle once every supervised promise has finished, including ones added while draining. */
+	drain(): Promise<void>
+}
+
+export interface BackgroundTasksOptions {
+	/**
+	 * Called for every rejection instead of the default log. Keep it cheap and non-throwing — a throw
+	 * here is itself swallowed. NEVER log the error object: it may quote a clone URL with an embedded
+	 * token.
+	 */
+	onError?: (error: unknown) => void
+	/** Prefix for the default log line, so a process running several of these can tell them apart. */
+	label?: string
+}
+
+export function createBackgroundTasks(options: BackgroundTasksOptions = {}): BackgroundTasks {
+	const label = options.label ?? 'background task'
+	const onError = options.onError ?? ((error: unknown) => {
+		console.error(`${label} failed:`, error instanceof Error ? error.message : 'unknown error')
+	})
+	const inFlight = new Set<Promise<void>>()
+
+	const waitUntil: WaitUntil = (promise) => {
+		const supervised = Promise.resolve(promise).then(
+			() => {},
+			(error: unknown) => {
+				try {
+					onError(error)
+				} catch {
+					// A reporter that throws must not resurrect the failure it was meant to absorb.
+				}
+			},
+		).finally(() => {
+			inFlight.delete(supervised)
+		})
+		inFlight.add(supervised)
+	}
+
+	return {
+		waitUntil,
+		get pending(): number {
+			return inFlight.size
+		},
+		async drain(): Promise<void> {
+			// A task may enqueue another task, so keep going until the set is genuinely empty.
+			while (inFlight.size > 0) {
+				await Promise.all([...inFlight])
+			}
+		},
+	}
+}