@lambdot/host-cloudflare 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.0](https://github.com/Embers-of-the-Fire/lambdot/compare/host-cloudflare-v0.0.1...host-cloudflare-v0.1.0) (2026-08-29)
+
+
+### Features
+
+* **host-cloudflare:** named KV/D1/R2 binding capabilities with hono+miniflare example ([fe2d527](https://github.com/Embers-of-the-Fire/lambdot/commit/fe2d527f7b40380df4d05ab643814987a004566d))
+* **host-cloudflare:** worker environment variables as a typed capability ([7319c5f](https://github.com/Embers-of-the-Fire/lambdot/commit/7319c5f0d656c2dd7e32c33c2be26b384f7e398e))

package/package.json

@@ -0,0 +1,14 @@
+{
+    "name": "@lambdot/host-cloudflare",
+    "version": "0.1.0",
+    "type": "module",
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@lambdot/core": "workspace:*"
+    }
+}

package/src/bindings.ts

@@ -0,0 +1,138 @@
+/**
+ * Structural subsets of Cloudflare's worker binding types (normally supplied
+ * by `@cloudflare/workers-types`). Declared locally so the package stays
+ * dependency-free: real bindings from a worker's `env` are assignable to
+ * these interfaces structurally, and anything the platform adds beyond them
+ * (sessions, metadata options, ...) stays available to consumers through
+ * their own types.
+ */
+
+/* ------------------------------ Workers KV ------------------------------- */
+
+/** Options accepted by {@link KVNamespace.list}. */
+export interface KVListOptions {
+    readonly prefix?: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+
+/** One entry returned by {@link KVNamespace.list}. */
+export interface KVListKey {
+    readonly name: string;
+    readonly expiration?: number;
+}
+
+/** One page from {@link KVNamespace.list}. */
+export interface KVListResult {
+    readonly keys: readonly KVListKey[];
+    readonly list_complete: boolean;
+    /** Present only while more pages remain. */
+    readonly cursor?: string;
+}
+
+/** Write options accepted by {@link KVNamespace.put}. */
+export interface KVPutOptions {
+    /** Relative TTL in seconds. Cloudflare enforces a 60-second minimum. */
+    readonly expirationTtl?: number;
+    /** Absolute expiry, seconds since the epoch. Same 60-second floor. */
+    readonly expiration?: number;
+}
+
+/**
+ * The fundamental slice of a Workers KV namespace: JSON and text reads,
+ * string writes with optional expiry, delete, and listing.
+ */
+export interface KVNamespace {
+    /** Read a key, parsing the stored value as JSON. `null` on a miss. */
+    get(key: string, options: { type: "json" }): Promise<unknown>;
+    /** Read a key as text. `null` on a miss. */
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: KVPutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: KVListOptions): Promise<KVListResult>;
+}
+
+/* ---------------------------------- D1 ----------------------------------- */
+
+/** The outcome of a D1 statement that returns rows. */
+export interface D1Result<T = unknown> {
+    readonly results: T[];
+    readonly success: boolean;
+    readonly meta: Record<string, unknown>;
+    readonly error?: string;
+}
+
+/** The outcome of `D1Database.exec` (schema migrations, bulk statements). */
+export interface D1ExecResult {
+    readonly count: number;
+    readonly duration: number;
+}
+
+/** A prepared D1 statement. */
+export interface D1PreparedStatement {
+    bind(...values: unknown[]): D1PreparedStatement;
+    /** The first row (or one column of it), `null` when the statement matched nothing. */
+    first<T = unknown>(column?: string): Promise<T | null>;
+    run<T = unknown>(): Promise<D1Result<T>>;
+    all<T = unknown>(): Promise<D1Result<T>>;
+    raw<T = unknown>(): Promise<T[]>;
+}
+
+/** The fundamental slice of a D1 database. */
+export interface D1Database {
+    prepare(query: string): D1PreparedStatement;
+    batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
+    exec(query: string): Promise<D1ExecResult>;
+}
+
+/* ---------------------------------- R2 ----------------------------------- */
+
+/** Values an R2 bucket accepts on `put`. */
+export type R2PutValue = string | ArrayBuffer | ArrayBufferView | ReadableStream | Blob;
+
+/** Write options accepted by {@link R2Bucket.put}. */
+export interface R2PutOptions {
+    readonly customMetadata?: Record<string, string>;
+}
+
+/** Metadata of an object stored in R2. */
+export interface R2Object {
+    readonly key: string;
+    readonly size: number;
+    readonly etag: string;
+    readonly uploaded: Date;
+    readonly customMetadata?: Record<string, string>;
+}
+
+/** An R2 object together with its body. */
+export interface R2ObjectBody extends R2Object {
+    readonly body: ReadableStream;
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+
+/** Options accepted by {@link R2Bucket.list}. */
+export interface R2ListOptions {
+    readonly prefix?: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly delimiter?: string;
+}
+
+/** One page from {@link R2Bucket.list}. */
+export interface R2Objects {
+    readonly objects: readonly R2Object[];
+    readonly truncated: boolean;
+    /** Present only while more pages remain. */
+    readonly cursor?: string;
+    readonly delimitedPrefixes: readonly string[];
+}
+
+/** The fundamental slice of an R2 bucket. */
+export interface R2Bucket {
+    get(key: string): Promise<R2ObjectBody | null>;
+    put(key: string, value: R2PutValue, options?: R2PutOptions): Promise<R2Object | null>;
+    delete(keys: string | readonly string[]): Promise<void>;
+    list(options?: R2ListOptions): Promise<R2Objects>;
+}

package/src/index.ts

@@ -0,0 +1,234 @@
+import type { Disposer, FeaturePlugin, StateBackend } from "@lambdot/core";
+
+import type { D1Database, KVNamespace, KVPutOptions, R2Bucket } from "./bindings.ts";
+
+export type {
+    D1Database,
+    D1ExecResult,
+    D1PreparedStatement,
+    D1Result,
+    KVListKey,
+    KVListOptions,
+    KVListResult,
+    KVNamespace,
+    KVPutOptions,
+    R2Bucket,
+    R2ListOptions,
+    R2Object,
+    R2ObjectBody,
+    R2Objects,
+    R2PutOptions,
+    R2PutValue,
+} from "./bindings.ts";
+
+/**
+ * The typed capability contracts shared by a binding provider and its
+ * consumers, parameterized by capability name: the provider declares it as
+ * `TProvides`, consumers as `TInjects`. Cloudflare bindings are named — a
+ * worker binds several KV namespaces, D1 databases, and R2 buckets under
+ * distinct names — so each provider instance takes its own capability name
+ * and distinct names fold side by side
+ * (`KVCapability<"sessions"> & KVCapability<"cache">`), exactly like
+ * `WsCapability` in `@lambdot/websocket`.
+ */
+export type KVCapability<TCap extends string> = { readonly [K in TCap]: KVNamespace };
+export type D1Capability<TCap extends string> = { readonly [K in TCap]: D1Database };
+export type R2Capability<TCap extends string> = { readonly [K in TCap]: R2Bucket };
+
+/**
+ * The typed capability contract shared by an environment provider and its
+ * consumers — the same shape as `EnvCapability` in `@lambdot/env`, declared
+ * locally so the package stays dependency-free. The two are structurally
+ * identical, so a consumer typed against either accepts both providers.
+ */
+export type EnvCapability<TCap extends string, TKey extends string> = {
+    readonly [K in TCap]: Readonly<Record<TKey, string>>;
+};
+
+/** Config for {@link kvNamespace}: the binding as it arrives on the worker's `env`. */
+export interface KVNamespaceConfig {
+    readonly binding: KVNamespace;
+}
+
+/** Config for {@link d1Database}: the binding as it arrives on the worker's `env`. */
+export interface D1DatabaseConfig {
+    readonly binding: D1Database;
+}
+
+/** Config for {@link r2Bucket}: the binding as it arrives on the worker's `env`. */
+export interface R2BucketConfig {
+    readonly binding: R2Bucket;
+}
+
+/**
+ * Config for {@link envVars}: the worker's bindings object as it arrives on
+ * the fetch handler's `env` argument, carrying plain vars and secrets next
+ * to the resource bindings.
+ */
+export interface EnvVarsConfig {
+    readonly source: Record<string, unknown>;
+}
+
+/**
+ * Provide one named Workers KV namespace as a typed capability. Instances
+ * multiply by capability name: register `kvNamespace("sessions")` and
+ * `kvNamespace("cache")` side by side, and each consumer injects its own.
+ *
+ * ```ts
+ * createKernel()
+ *     .use(kvNamespace("sessions"), { binding: env.SESSIONS })
+ *     .use(kvNamespace("cache"), { binding: env.CACHE });
+ * // ctx.sessions: KVNamespace, ctx.cache: KVNamespace
+ * ```
+ */
+export function kvNamespace<TCap extends string>(
+    capability: TCap,
+): FeaturePlugin<{}, {}, undefined, KVNamespaceConfig, `kv:${TCap}`, KVCapability<TCap>> {
+    return {
+        name: `kv:${capability}`,
+        apply(ctx, config) {
+            // The kernel's `provide` keeps its value parameter behind a
+            // conditional type that stays deferred for a generic capability
+            // name; `KVCapability<TCap>` already ties this name to
+            // `KVNamespace`, so pin the call down here.
+            return (ctx.provide as (name: TCap, value: KVNamespace) => Disposer).call(
+                ctx,
+                capability,
+                config.binding,
+            );
+        },
+    };
+}
+
+/**
+ * Provide one named D1 database as a typed capability. Instances multiply
+ * by capability name, exactly like {@link kvNamespace}.
+ *
+ * ```ts
+ * createKernel().use(d1Database("db"), { binding: env.DB });
+ * // ctx.db: D1Database
+ * ```
+ */
+export function d1Database<TCap extends string>(
+    capability: TCap,
+): FeaturePlugin<{}, {}, undefined, D1DatabaseConfig, `d1:${TCap}`, D1Capability<TCap>> {
+    return {
+        name: `d1:${capability}`,
+        apply(ctx, config) {
+            // See `kvNamespace` for why `provide` is pinned here.
+            return (ctx.provide as (name: TCap, value: D1Database) => Disposer).call(
+                ctx,
+                capability,
+                config.binding,
+            );
+        },
+    };
+}
+
+/**
+ * Provide one named R2 bucket as a typed capability. Instances multiply by
+ * capability name, exactly like {@link kvNamespace}.
+ *
+ * ```ts
+ * createKernel().use(r2Bucket("uploads"), { binding: env.UPLOADS });
+ * // ctx.uploads: R2Bucket
+ * ```
+ */
+export function r2Bucket<TCap extends string>(
+    capability: TCap,
+): FeaturePlugin<{}, {}, undefined, R2BucketConfig, `r2:${TCap}`, R2Capability<TCap>> {
+    return {
+        name: `r2:${capability}`,
+        apply(ctx, config) {
+            // See `kvNamespace` for why `provide` is pinned here.
+            return (ctx.provide as (name: TCap, value: R2Bucket) => Disposer).call(
+                ctx,
+                capability,
+                config.binding,
+            );
+        },
+    };
+}
+
+/**
+ * Read variables from a worker's bindings object and provide them as a
+ * typed capability — the Cloudflare counterpart of `envVars` in
+ * `@lambdot/env`: workers have no `process.env`, so plain vars and secrets
+ * arrive on `env` next to the resource bindings. A missing, empty, or
+ * non-string variable fails activation loudly at kernel start, so a
+ * misconfigured deployment surfaces before any consumer activates.
+ *
+ * ```ts
+ * createKernel().use(envVars("bot-env", ["BOT_TOKEN"]), { source: env });
+ * // ctx["bot-env"].BOT_TOKEN: string
+ * ```
+ */
+export function envVars<TCap extends string, TKey extends string>(
+    capability: TCap,
+    keys: readonly TKey[],
+): FeaturePlugin<{}, {}, undefined, EnvVarsConfig, `env:${TCap}`, EnvCapability<TCap, TKey>> {
+    return {
+        name: `env:${capability}`,
+        apply(ctx, config) {
+            const values: Record<string, string> = {};
+            for (const key of keys) {
+                const value = config.source[key];
+                if (typeof value !== "string" || value === "")
+                    throw new Error(
+                        `env:${capability}: required environment variable "${key}" is not set`,
+                    );
+                values[key] = value;
+            }
+            // See `kvNamespace` for why `provide` is pinned here.
+            return (
+                ctx.provide as (name: TCap, value: Readonly<Record<TKey, string>>) => Disposer
+            ).call(ctx, capability, values as Readonly<Record<TKey, string>>);
+        },
+    };
+}
+
+/**
+ * Bridge a named Workers KV namespace into the framework's pluggable state
+ * slot, so feature plugins reach it through `ctx.state`. Injects the
+ * capability provided by {@link kvNamespace} — the fold enforces
+ * registration order at compile time:
+ *
+ * ```ts
+ * createKernel()
+ *     .use(kvNamespace("kv"), { binding: env.BOT_KV })
+ *     .use(kvState("kv"))
+ *     .use(myStatefulFeature);
+ * ```
+ *
+ * Values are stored as JSON under `<plugin-namespace>:<key>`. KV expiries
+ * are whole seconds with a 60-second minimum, so `ttlMs` is rounded up and
+ * clamped to that floor.
+ */
+export function kvState<TCap extends string>(
+    capability: TCap,
+): FeaturePlugin<{}, {}, undefined, void, `state-kv:${TCap}`, {}, KVCapability<TCap>> {
+    return {
+        name: `state-kv:${capability}`,
+        inject: [capability],
+        apply(ctx) {
+            const binding = ctx[capability];
+            const backend: StateBackend = {
+                async get(ns, key) {
+                    const value = await binding.get(`${ns}:${key}`, { type: "json" });
+                    return value === null ? undefined : value;
+                },
+                async set(ns, key, value, ttlMs) {
+                    const options: KVPutOptions =
+                        ttlMs === undefined
+                            ? {}
+                            : { expirationTtl: Math.max(60, Math.ceil(ttlMs / 1000)) };
+                    await binding.put(`${ns}:${key}`, JSON.stringify(value), options);
+                },
+                async delete(ns, key) {
+                    await binding.delete(`${ns}:${key}`);
+                },
+            };
+            return ctx.provide("state", backend);
+        },
+    };
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tsconfig.base.json",
+    "include": ["src"]
+}