@fabrika/platform 0.9.0-dev.1 → 0.9.0-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/platform",
-	"version": "0.9.0-dev.1",
+	"version": "0.9.0-dev.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,17 +12,18 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		},
 		"./testing": {
 			"bun": "./src/testing.ts",
-			"types": "./src/testing.ts",
+			"types": "./types/src/testing.d.ts",
 			"default": "./src/testing.ts"
 		}
 	},

package/types/src/deploy-locks-sql.d.ts

@@ -0,0 +1,19 @@
+import type { DeployLocks } from './ports';
+import type { SqlDatabase } from './sql';
+export interface SqlDeployLocksOptions {
+    /** Table holding the leases. Must already exist; the DDL is the owning service's migration. */
+    table?: string;
+    /** Injectable clock so lease expiry is testable without sleeping. */
+    now?: () => number;
+}
+export declare class SqlDeployLocks implements DeployLocks {
+    private readonly db;
+    private readonly acquireSql;
+    private readonly renewSql;
+    private readonly releaseSql;
+    private readonly now;
+    constructor(db: SqlDatabase, options?: SqlDeployLocksOptions);
+    acquire(key: string, holder: string, ttlMs: number): Promise<boolean>;
+    renew(key: string, holder: string, ttlMs: number): Promise<boolean>;
+    release(key: string, holder: string): Promise<void>;
+}

package/types/src/index.d.ts

@@ -0,0 +1,5 @@
+export { SqlDeployLocks, type SqlDeployLocksOptions } from './deploy-locks-sql';
+export { ObjectExistsError, ObjectTooLargeError } from './ports';
+export type { AssetServer, BlobStore, DeployLocks, FileObjectStore, HttpService, JobQueue, ObjectMetadata, ObjectWriteOptions, StoredObject, WaitUntil, } from './ports';
+export type { SqlDatabase, SqlQueryResult, SqlRunResult, SqlStatement } from './sql';
+export { uuidv7 } from './uuid';

package/types/src/ports.d.ts

@@ -0,0 +1,97 @@
+/** Bytes written to blob storage (run logs). Both R2 and S3/MinIO satisfy this. */
+export interface BlobStore {
+    put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void>;
+    get(key: string): Promise<{
+        body: ReadableStream;
+        text(): Promise<string>;
+    } | null>;
+    delete(key: string): Promise<void>;
+}
+/** What the store recorded for an object. `contentType` is what the writer declared, or null. */
+export interface ObjectMetadata {
+    readonly size: number;
+    readonly contentType: string | null;
+}
+export interface StoredObject extends ObjectMetadata {
+    /** One stream, consumable once. */
+    readonly body: ReadableStream<Uint8Array>;
+    /** These exact bytes' version, from the same answer as the body: an S3 ETag. It changes when the object is replaced. */
+    readonly version: string;
+}
+export interface ObjectWriteOptions {
+    readonly contentType: string;
+    /** The most bytes the object may have. The write stops reading `body` once more arrive. */
+    readonly maxBytes: number;
+}
+/** A write named a key that already holds an object: a file's object is written once. Read by `name`. */
+export declare class ObjectExistsError extends Error {
+    readonly name = "ObjectExistsError";
+    constructor();
+}
+/** The body of a write was longer than its `maxBytes`. Read by `name`, never by a cross-package `instanceof`. */
+export declare class ObjectTooLargeError extends Error {
+    readonly name = "ObjectTooLargeError";
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+}
+/**
+ * The objects of an application's file collections (S3/MinIO). Separate from `BlobStore` because its callers
+ * need a size bound enforced while the bytes stream and the metadata read back; an R2 adapter that ignored
+ * either would silently drop a limit.
+ */
+export interface FileObjectStore {
+    /**
+     * Streams `body` to a new `key`. A key that already holds an object is refused with `ObjectExistsError`, and nothing
+     * is written. Past `options.maxBytes` it stops reading, keeps nothing under `key` and rejects with
+     * `ObjectTooLargeError`. Any other failure also leaves nothing stored.
+     */
+    write(key: string, body: ReadableStream<Uint8Array>, options: ObjectWriteOptions): Promise<ObjectMetadata>;
+    /** The object with its metadata and version, in one answer, or `null` for a missing key. `signal` stops it. */
+    read(key: string, signal?: AbortSignal): Promise<StoredObject | null>;
+    /** The object only while it is still `version`, in one answer; `null` when it is missing or was replaced. */
+    readVersion(key: string, version: string, signal?: AbortSignal): Promise<StoredObject | null>;
+    /** Idempotent: a missing key is not an error. */
+    delete(key: string): Promise<void>;
+}
+/** Enqueue a deploy job. The CONSUMER side is platform-specific and deliberately not modelled here. */
+export interface JobQueue<T> {
+    send(message: T, options?: {
+        delaySeconds?: number;
+    }): Promise<void>;
+}
+/**
+ * Per-target mutual exclusion, keyed by `<app>:<env>`. Matches the seam the control plane already
+ * had around its Durable Object, so swapping the implementation touches no call site.
+ *
+ * Contract, unchanged from the DO it replaces:
+ *  - NON-REENTRANT — a live lease returns false even to the same holder, so a redelivered message
+ *    defers rather than double-running.
+ *  - TTL-BOUNDED — a consumer that dies mid-deploy self-heals when the lease expires, instead of
+ *    wedging that app-env forever.
+ *  - HOLDER-CHECKED release — a late release from a superseded run can never free a lease that a
+ *    newer run has since taken.
+ *
+ * The database-backed implementation expresses all three as one conditional UPDATE, which is atomic
+ * on SQLite and Postgres alike — so this port has ONE implementation on every platform.
+ */
+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>;
+}
+/** One HTTP-speaking service behind a platform-native or network transport. */
+export interface HttpService {
+    fetch(request: Request): Promise<Response>;
+}
+/** Serves the built SPA for non-API paths. */
+export interface AssetServer extends HttpService {
+}
+/**
+ * Keep work alive past the response. On Workers this is `ctx.waitUntil`; in a long-running process
+ * it is a supervised background promise. Implementations MUST swallow-and-log rejections — a
+ * background failure must never take the process down.
+ */
+export type WaitUntil = (promise: Promise<unknown>) => void;

package/types/src/sql.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A prepared statement. `bind()` returns a NEW statement; it never mutates the receiver (D1
+ * semantics) — call sites build a base statement and bind it repeatedly, so a mutating `bind()`
+ * corrupts them silently.
+ *
+ * Two further contracts every driver must honour, both relied on by existing call sites:
+ *  - **`bind()` is optional.** A statement with no placeholders is executed directly, and `bind()`
+ *    may legally be called with zero arguments.
+ *  - **SQL NULL maps to JS `null`, never `undefined`.** Row shapes are checked with `=== null`.
+ */
+export interface SqlStatement {
+    /** Bind positional parameters, left to right, for this statement's `?` placeholders. */
+    bind(...values: unknown[]): SqlStatement;
+    /** First row, or `null` when the query matched nothing. */
+    first<T = Record<string, unknown>>(): Promise<T | null>;
+    /** All matching rows. */
+    all<T = Record<string, unknown>>(): Promise<SqlQueryResult<T>>;
+    /** Execute a write. Read `meta.changes` to learn whether it affected anything. */
+    run(): Promise<SqlRunResult>;
+}
+/** The result of `all()` — wrapped in `{ results }` to match D1 so no call site changes. */
+export interface SqlQueryResult<T> {
+    results: T[];
+}
+/**
+ * The result of `run()`. `changes` is how the guarded-UPDATE idioms across this codebase detect a
+ * no-op, so it is REQUIRED: a driver that left it undefined would turn every successful guarded
+ * write into a silent "not found". `D1Meta.changes` is likewise non-optional, so D1 still satisfies
+ * this structurally.
+ *
+ * It counts rows AFFECTED BY A WRITE. A `SELECT` reports `0` — drivers whose underlying client
+ * returns a row count for reads must map that to `0` rather than passing it through.
+ */
+export interface SqlRunResult {
+    meta: {
+        /** Rows actually affected. `0` means the guard did not match — never treat it as success. */
+        changes: number;
+    };
+}
+/** A database handle. `batch()` executes its statements atomically, in order. */
+export interface SqlDatabase {
+    prepare(sql: string): SqlStatement;
+    batch<T = Record<string, unknown>>(statements: SqlStatement[]): Promise<SqlQueryResult<T>[]>;
+}

package/types/src/testing.d.ts

@@ -0,0 +1,38 @@
+import { type BlobStore, type FileObjectStore, type JobQueue, type ObjectMetadata, type ObjectWriteOptions, type StoredObject } from './ports';
+import type { SqlDatabase } from './sql';
+/** A blob store that keeps string values in memory. */
+export declare class MemoryBlobs implements BlobStore {
+    readonly values: Map<string, string>;
+    put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void>;
+    get(key: string): Promise<{
+        body: ReadableStream;
+        text(): Promise<string>;
+    } | null>;
+    delete(key: string): Promise<void>;
+}
+/** A file object store in memory, with the port's size bound enforced while the body streams. */
+export declare class MemoryFileObjects implements FileObjectStore {
+    #private;
+    readonly objects: Map<string, {
+        readonly bytes: Uint8Array<ArrayBuffer>;
+        readonly contentType: string;
+        readonly version: string;
+    }>;
+    write(key: string, body: ReadableStream<Uint8Array>, options: ObjectWriteOptions): Promise<ObjectMetadata>;
+    /** Puts `bytes` under `key` whatever it held, under a new version: what a write outside the upload path does. */
+    replace(key: string, bytes: Uint8Array<ArrayBuffer>, contentType?: string): void;
+    read(key: string): Promise<StoredObject | null>;
+    readVersion(key: string, version: string): Promise<StoredObject | null>;
+    delete(key: string): Promise<void>;
+}
+/** A queue that records every sent message. */
+export declare class MemoryQueue<T> implements JobQueue<T> {
+    readonly messages: T[];
+    send(message: T): Promise<void>;
+}
+/** A queue that accepts and discards every message. */
+export declare class EmptyQueue<T> implements JobQueue<T> {
+    send(): Promise<void>;
+}
+/** A database for code paths that must not query it. */
+export declare const unusedDatabase: SqlDatabase;

package/types/src/uuid.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+export declare function uuidv7(millis?: number): string;