@fabrika/platform 0.2.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/platform",
-	"version": "0.2.0",
+	"version": "0.3.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -19,6 +19,11 @@
 			"bun": "./src/index.ts",
 			"types": "./src/index.ts",
 			"default": "./src/index.ts"
+		},
+		"./testing": {
+			"bun": "./src/testing.ts",
+			"types": "./src/testing.ts",
+			"default": "./src/testing.ts"
 		}
 	},
 	"scripts": {

package/src/deploy-locks-sql.ts

@@ -42,6 +42,7 @@ const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
 
 export class SqlDeployLocks implements DeployLocks {
 	private readonly acquireSql: string
+	private readonly renewSql: string
 	private readonly releaseSql: string
 	private readonly now: () => number
 
@@ -55,6 +56,7 @@ export class SqlDeployLocks implements DeployLocks {
 			ON CONFLICT (lock_key) DO UPDATE SET holder = excluded.holder, expires_at = excluded.expires_at
 			WHERE ${table}.expires_at <= ?`
 		this.releaseSql = `DELETE FROM ${table} WHERE lock_key = ? AND holder = ?`
+		this.renewSql = `UPDATE ${table} SET expires_at = ? WHERE lock_key = ? AND holder = ? AND expires_at > ?`
 	}
 
 	async acquire(key: string, holder: string, ttlMs: number): Promise<boolean> {
@@ -63,6 +65,12 @@ export class SqlDeployLocks implements DeployLocks {
 		return (result.meta.changes ?? 0) > 0
 	}
 
+	async renew(key: string, holder: string, ttlMs: number): Promise<boolean> {
+		const now = this.now()
+		const result = await this.db.prepare(this.renewSql).bind(now + ttlMs, key, holder, now).run()
+		return (result.meta.changes ?? 0) > 0
+	}
+
 	async release(key: string, holder: string): Promise<void> {
 		// Deleting the row is what "free" means. The holder predicate makes this a no-op for a run whose
 		// lease already expired and was taken over — it cannot delete the newer holder's row.

package/src/index.ts

@@ -11,3 +11,4 @@
 export { SqlDeployLocks, type SqlDeployLocksOptions } from './deploy-locks-sql'
 export type { AssetServer, BlobStore, DeployLocks, HttpService, JobQueue, WaitUntil } from './ports'
 export type { SqlDatabase, SqlQueryResult, SqlRunResult, SqlStatement } from './sql'
+export { uuidv7 } from './uuid'

package/src/ports.ts

@@ -39,6 +39,8 @@ export interface JobQueue<T> {
 export interface DeployLocks {
 	/** Take the lease for `key`. `true` when acquired (free or expired), `false` when live elsewhere. */
 	acquire(key: string, holder: string, ttlMs: number): Promise<boolean>
+	/** Extend a live lease owned by `holder`; an expired or replaced lease cannot be renewed. */
+	renew(key: string, holder: string, ttlMs: number): Promise<boolean>
 	/** Release the lease iff `holder` still owns it. Idempotent; a stale holder's call is a no-op. */
 	release(key: string, holder: string): Promise<void>
 }

package/src/testing.ts

@@ -0,0 +1,51 @@
+import type { BlobStore, JobQueue } from './ports'
+import type { SqlDatabase } from './sql'
+
+/** A blob store that keeps string values in memory. */
+export class MemoryBlobs implements BlobStore {
+	readonly values = new Map<string, string>()
+
+	put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void> {
+		if (typeof value !== 'string') throw new Error('test blob store accepts strings only')
+		this.values.set(key, value)
+		return Promise.resolve()
+	}
+
+	get(key: string): Promise<{ body: ReadableStream; text(): Promise<string> } | null> {
+		const value = this.values.get(key)
+		if (value === undefined) return Promise.resolve(null)
+		return Promise.resolve({ body: new Blob([value]).stream(), text: () => Promise.resolve(value) })
+	}
+
+	delete(key: string): Promise<void> {
+		this.values.delete(key)
+		return Promise.resolve()
+	}
+}
+
+/** A queue that records every sent message. */
+export class MemoryQueue<T> implements JobQueue<T> {
+	readonly messages: T[] = []
+
+	send(message: T): Promise<void> {
+		this.messages.push(message)
+		return Promise.resolve()
+	}
+}
+
+/** A queue that accepts and discards every message. */
+export class EmptyQueue<T> implements JobQueue<T> {
+	send(): Promise<void> {
+		return Promise.resolve()
+	}
+}
+
+/** A database for code paths that must not query it. */
+export const unusedDatabase: SqlDatabase = {
+	prepare() {
+		throw new Error('database access was not expected')
+	},
+	batch() {
+		return Promise.reject(new Error('database access was not expected'))
+	},
+}

package/src/uuid.ts

@@ -0,0 +1,90 @@
+/**
+ * UUIDv7 generator — time-ordered ids, so a 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). Runtime-neutral: Web Crypto's `crypto.getRandomValues` exists on Workers and Bun alike.
+ *
+ * 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, one Worker isolate. Two ids minted in the same
+ * millisecond by two generators tie only if their independently seeded counters collide (~1/256), and
+ * the 62 random bits break that; within one generator 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 (a job queue, a repository) 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.
+ */
+
+/** `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)}`
+}