@b9g/platform-cloudflare 0.1.10 → 0.1.11

package/README.md

@@ -1,14 +1,6 @@
 # @b9g/platform-cloudflare
 
-Cloudflare Workers platform adapter for Shovel. Runs ServiceWorker applications on Cloudflare's edge network with KV storage and Durable Objects support.
-
-## Features
-
-- Cloudflare Workers integration
-- KV storage for caching
-- R2 bucket support for assets
-- Durable Objects for stateful apps
-- Standards-compliant ServiceWorker API
+Cloudflare Workers platform adapter for Shovel. Runs ServiceWorker applications on Cloudflare's edge network with R2 storage and static assets support.
 
 ## Installation
 
@@ -16,95 +8,106 @@ Cloudflare Workers platform adapter for Shovel. Runs ServiceWorker applications
 npm install @b9g/platform-cloudflare
 ```
 
-## Usage
+## Module Structure
 
-```javascript
-import CloudflarePlatform from '@b9g/platform-cloudflare';
-
-const platform = new CloudflarePlatform({
-  cache: { type: 'kv', binding: 'CACHE_KV' },
-  filesystem: { type: 'r2', binding: 'ASSETS_R2' }
-});
+```
+@b9g/platform-cloudflare
+├── /caches      # CloudflareNativeCache (Cloudflare Cache API wrapper)
+├── /directories # CloudflareR2Directory, CloudflareAssetsDirectory
+├── /variables   # envStorage (per-request Cloudflare env access)
+└── /runtime     # Worker bootstrap (initializeRuntime, createFetchHandler)
+```
 
-export default {
-  async fetch(request, env, ctx) {
-    return await platform.handleRequest(request);
+## Configuration
+
+Configure in `shovel.json`:
+
+```json
+{
+  "platform": "cloudflare",
+  "caches": {
+    "default": {
+      "module": "@b9g/platform-cloudflare/caches"
+    }
+  },
+  "directories": {
+    "public": {
+      "module": "@b9g/platform-cloudflare/directories",
+      "export": "CloudflareAssetsDirectory"
+    },
+    "uploads": {
+      "module": "@b9g/platform-cloudflare/directories",
+      "binding": "uploads_r2"
+    }
   }
-};
+}
 ```
 
 ## Requirements
 
-Shovel requires Node.js compatibility for AsyncLocalStorage (used by AsyncContext polyfill for `self.cookieStore`). Add to your `wrangler.toml`:
+Shovel requires Node.js compatibility for AsyncLocalStorage and process.env support. Add to your `wrangler.toml`:
 
 ```toml
-compatibility_date = "2024-09-23"
+compatibility_date = "2025-04-01"
 compatibility_flags = ["nodejs_compat"]
 ```
 
-## Exports
-
-### Classes
+With `compatibility_date` of 2025-04-01 or later, `process.env` is automatically populated with your environment variables and secrets at module load time. For earlier dates, add `nodejs_compat_populate_process_env` to compatibility_flags.
 
-- `CloudflarePlatform` - Cloudflare Workers platform implementation (extends BasePlatform)
-- `CFAssetsDirectoryHandle` - FileSystemDirectoryHandle for Cloudflare Workers Static Assets
-- `CFAssetsFileHandle` - FileSystemFileHandle for Cloudflare Workers Static Assets
-
-### Functions
-
-- `createOptionsFromEnv(env)` - Create platform options from Cloudflare env bindings
-- `generateWranglerConfig(options)` - Generate wrangler.toml configuration
+## Exports
 
-### Types
+### Main Package (`@b9g/platform-cloudflare`)
 
-- `CloudflarePlatformOptions` - Configuration options for CloudflarePlatform
-- `CFAssetsBinding` - Type for Cloudflare Workers Static Assets binding
+- `CloudflarePlatform` - Platform adapter (default export)
 
-### Constants
+### Caches (`@b9g/platform-cloudflare/caches`)
 
-- `cloudflareWorkerBanner` - ES Module wrapper banner for Cloudflare Workers
-- `cloudflareWorkerFooter` - ES Module wrapper footer
+- `CloudflareNativeCache` - Wrapper around Cloudflare's Cache API (default export)
 
-### Default Export
+### Directories (`@b9g/platform-cloudflare/directories`)
 
-- `CloudflarePlatform` - The platform class
+- `CloudflareR2Directory` - FileSystemDirectoryHandle for R2 buckets (default export)
+- `CloudflareAssetsDirectory` - FileSystemDirectoryHandle for static assets
+- `R2FileSystemDirectoryHandle` - Base R2 directory implementation
+- `R2FileSystemFileHandle` - Base R2 file implementation
+- `CFAssetsDirectoryHandle` - Base assets directory implementation
+- `CFAssetsFileHandle` - Base assets file implementation
 
-## API
+### Runtime (`@b9g/platform-cloudflare/runtime`)
 
-### `new CloudflarePlatform(options?)`
+- `initializeRuntime(config)` - Initialize worker runtime
+- `createFetchHandler(registration)` - Create ES module fetch handler
+- `CloudflareFetchEvent` - Extended FetchEvent with env bindings
 
-Creates a new Cloudflare platform instance.
+### Variables (`@b9g/platform-cloudflare/variables`)
 
-**Options:**
-- `cache`: Cache configuration (KV binding)
-- `filesystem`: Filesystem configuration (R2 binding)
-- `env`: Cloudflare environment bindings
+- `envStorage` - AsyncContext for per-request Cloudflare env access
+- `getEnv()` - Get current request's env bindings
 
-### Bindings
+## Bindings
 
-Configure bindings in `wrangler.toml`:
+Configure bindings in `wrangler.toml`. Use lowercase binding names to avoid env expression parsing issues:
 
 ```toml
 compatibility_date = "2024-09-23"
 compatibility_flags = ["nodejs_compat"]
 
-[[kv_namespaces]]
-binding = "CACHE_KV"
-id = "your-kv-namespace-id"
-
+# R2 bucket for uploads directory
 [[r2_buckets]]
-binding = "ASSETS_R2"
-bucket_name = "your-bucket-name"
-```
-
-## Cache Backends
+binding = "uploads_r2"
+bucket_name = "my-uploads-bucket"
 
-- `kv`: Cloudflare KV storage
-- `cache-api`: Cloudflare Cache API (default)
+# Static assets (always uses ASSETS binding)
+[assets]
+directory = "./public"
+```
 
-## Filesystem Backends
+## Directory Types
 
-- `r2`: Cloudflare R2 bucket storage
+| Type | Use Case | Read/Write | Binding |
+|------|----------|------------|---------|
+| R2 | User uploads, dynamic storage | Both | User-defined |
+| Assets | Static files deployed with worker | Read-only | Always `ASSETS` |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/platform-cloudflare",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Cloudflare Workers platform adapter for Shovel - already ServiceWorker-based!",
   "keywords": [
     "shovel",
@@ -11,16 +11,17 @@
     "serviceworker"
   ],
   "dependencies": {
-    "@b9g/assets": "^0.1.15",
-    "@b9g/cache": "^0.1.5",
-    "@b9g/platform": "^0.1.12",
+    "@b9g/assets": "^0.2.0-beta.0",
+    "@b9g/async-context": "^0.2.0-beta.0",
+    "@b9g/cache": "^0.2.0-beta.0",
+    "@b9g/filesystem": "^0.1.8",
+    "@b9g/platform": "^0.1.13",
     "@logtape/logtape": "^1.2.0",
     "mime": "^4.0.4",
     "miniflare": "^4.20251118.1"
   },
   "devDependencies": {
-    "@b9g/libuild": "^0.1.18",
-    "bun-types": "latest"
+    "@b9g/libuild": "^0.1.18"
   },
   "type": "module",
   "types": "src/index.d.ts",
@@ -39,29 +40,37 @@
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
     },
-    "./filesystem-assets": {
-      "types": "./src/filesystem-assets.d.ts",
-      "import": "./src/filesystem-assets.js"
+    "./runtime": {
+      "types": "./src/runtime.d.ts",
+      "import": "./src/runtime.js"
     },
-    "./filesystem-assets.js": {
-      "types": "./src/filesystem-assets.d.ts",
-      "import": "./src/filesystem-assets.js"
+    "./runtime.js": {
+      "types": "./src/runtime.d.ts",
+      "import": "./src/runtime.js"
     },
-    "./cloudflare-runtime": {
-      "types": "./src/cloudflare-runtime.d.ts",
-      "import": "./src/cloudflare-runtime.js"
+    "./variables": {
+      "types": "./src/variables.d.ts",
+      "import": "./src/variables.js"
     },
-    "./cloudflare-runtime.js": {
-      "types": "./src/cloudflare-runtime.d.ts",
-      "import": "./src/cloudflare-runtime.js"
+    "./variables.js": {
+      "types": "./src/variables.d.ts",
+      "import": "./src/variables.js"
     },
-    "./filesystem-r2": {
-      "types": "./src/filesystem-r2.d.ts",
-      "import": "./src/filesystem-r2.js"
+    "./caches": {
+      "types": "./src/caches.d.ts",
+      "import": "./src/caches.js"
     },
-    "./filesystem-r2.js": {
-      "types": "./src/filesystem-r2.d.ts",
-      "import": "./src/filesystem-r2.js"
+    "./caches.js": {
+      "types": "./src/caches.d.ts",
+      "import": "./src/caches.js"
+    },
+    "./directories": {
+      "types": "./src/directories.d.ts",
+      "import": "./src/directories.js"
+    },
+    "./directories.js": {
+      "types": "./src/directories.d.ts",
+      "import": "./src/directories.js"
     }
   }
 }

package/src/caches.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Cloudflare Native Cache
+ *
+ * Wrapper around Cloudflare's native Cache API for use with the factory pattern.
+ */
+/**
+ * CloudflareNativeCache - Wrapper around Cloudflare's native Cache API.
+ * This allows the native cache to be used with the factory pattern.
+ *
+ * Note: This must only be used in a Cloudflare Worker context where
+ * globalThis.caches is available.
+ */
+export declare class CloudflareNativeCache implements Cache {
+    #private;
+    constructor(name: string, _options?: Record<string, unknown>);
+    add(request: RequestInfo | URL): Promise<void>;
+    addAll(requests: RequestInfo[]): Promise<void>;
+    delete(request: RequestInfo | URL, options?: CacheQueryOptions): Promise<boolean>;
+    keys(request?: RequestInfo | URL, options?: CacheQueryOptions): Promise<readonly Request[]>;
+    match(request: RequestInfo | URL, options?: CacheQueryOptions): Promise<Response | undefined>;
+    matchAll(request?: RequestInfo | URL, options?: CacheQueryOptions): Promise<readonly Response[]>;
+    put(request: RequestInfo | URL, response: Response): Promise<void>;
+}
+export default CloudflareNativeCache;

package/src/caches.js

@@ -0,0 +1,52 @@
+/// <reference types="./caches.d.ts" />
+// src/caches.ts
+var CloudflareNativeCache = class {
+  #name;
+  #cachePromise;
+  constructor(name, _options) {
+    this.#name = name;
+    this.#cachePromise = null;
+  }
+  #getCache() {
+    if (!this.#cachePromise) {
+      if (!globalThis.caches) {
+        throw new Error("Cloudflare caches not available in this context");
+      }
+      this.#cachePromise = globalThis.caches.open(this.#name);
+    }
+    return this.#cachePromise;
+  }
+  async add(request) {
+    const cache = await this.#getCache();
+    return cache.add(request);
+  }
+  async addAll(requests) {
+    const cache = await this.#getCache();
+    return cache.addAll(requests);
+  }
+  async delete(request, options) {
+    const cache = await this.#getCache();
+    return cache.delete(request, options);
+  }
+  async keys(request, options) {
+    const cache = await this.#getCache();
+    return cache.keys(request, options);
+  }
+  async match(request, options) {
+    const cache = await this.#getCache();
+    return cache.match(request, options);
+  }
+  async matchAll(request, options) {
+    const cache = await this.#getCache();
+    return cache.matchAll(request, options);
+  }
+  async put(request, response) {
+    const cache = await this.#getCache();
+    return cache.put(request, response);
+  }
+};
+var caches_default = CloudflareNativeCache;
+export {
+  CloudflareNativeCache,
+  caches_default as default
+};

package/src/directories.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Cloudflare Directory Implementations
+ *
+ * Provides FileSystemDirectoryHandle/FileSystemFileHandle implementations
+ * for Cloudflare Workers:
+ *
+ * - R2: Read-write storage backed by Cloudflare R2 buckets
+ * - Assets: Read-only access to static assets deployed with the Worker
+ *
+ * Default export: CloudflareR2Directory (general purpose, user-configurable)
+ * Named export: CloudflareAssetsDirectory (singleton for public assets)
+ */
+/** R2 object metadata */
+export interface R2Object {
+    key: string;
+    uploaded: Date;
+    httpMetadata?: {
+        contentType?: string;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/** R2 list result */
+export interface R2Objects {
+    objects: Array<{
+        key: string;
+    }>;
+    delimitedPrefixes: string[];
+}
+/** R2 bucket interface */
+export interface R2Bucket {
+    get(key: string): Promise<R2Object | null>;
+    head(key: string): Promise<R2Object | null>;
+    put(key: string, value: ArrayBuffer | Uint8Array): Promise<R2Object>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        delimiter?: string;
+    }): Promise<R2Objects>;
+}
+/**
+ * Cloudflare ASSETS binding interface
+ */
+export interface CFAssetsBinding {
+    fetch(request: Request | string): Promise<Response>;
+}
+/**
+ * Cloudflare R2 implementation of FileSystemWritableFileStream
+ */
+export declare class R2FileSystemWritableFileStream extends WritableStream<Uint8Array> {
+    constructor(r2Bucket: R2Bucket, key: string);
+}
+/**
+ * Cloudflare R2 implementation of FileSystemFileHandle
+ */
+export declare class R2FileSystemFileHandle implements FileSystemFileHandle {
+    #private;
+    readonly kind: "file";
+    readonly name: string;
+    constructor(r2Bucket: R2Bucket, key: string);
+    getFile(): Promise<File>;
+    createWritable(): Promise<FileSystemWritableFileStream>;
+    createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>;
+    isSameEntry(other: FileSystemHandle): Promise<boolean>;
+    queryPermission(): Promise<PermissionState>;
+    requestPermission(): Promise<PermissionState>;
+}
+/**
+ * Cloudflare R2 implementation of FileSystemDirectoryHandle
+ */
+export declare class R2FileSystemDirectoryHandle implements FileSystemDirectoryHandle {
+    #private;
+    readonly kind: "directory";
+    readonly name: string;
+    constructor(r2Bucket: R2Bucket, prefix: string);
+    getFileHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<FileSystemFileHandle>;
+    getDirectoryHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<FileSystemDirectoryHandle>;
+    removeEntry(name: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    resolve(_possibleDescendant: FileSystemHandle): Promise<string[] | null>;
+    entries(): AsyncIterableIterator<[string, FileSystemHandle]>;
+    keys(): AsyncIterableIterator<string>;
+    values(): AsyncIterableIterator<FileSystemHandle>;
+    isSameEntry(other: FileSystemHandle): Promise<boolean>;
+    queryPermission(): Promise<PermissionState>;
+    requestPermission(): Promise<PermissionState>;
+}
+/**
+ * FileSystemFileHandle implementation for CF ASSETS binding files.
+ */
+export declare class CFAssetsFileHandle implements FileSystemFileHandle {
+    #private;
+    readonly kind: "file";
+    readonly name: string;
+    constructor(assets: CFAssetsBinding, path: string, name: string);
+    getFile(): Promise<File>;
+    createWritable(_options?: FileSystemCreateWritableOptions): Promise<FileSystemWritableFileStream>;
+    createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>;
+    isSameEntry(other: FileSystemHandle): Promise<boolean>;
+}
+/**
+ * FileSystemDirectoryHandle implementation over Cloudflare ASSETS binding.
+ *
+ * Provides read-only access to static assets deployed with a CF Worker.
+ * Directory listing is not supported (ASSETS binding limitation).
+ */
+export declare class CFAssetsDirectoryHandle implements FileSystemDirectoryHandle {
+    #private;
+    readonly kind: "directory";
+    readonly name: string;
+    constructor(assets: CFAssetsBinding, basePath?: string);
+    getFileHandle(name: string, _options?: FileSystemGetFileOptions): Promise<FileSystemFileHandle>;
+    getDirectoryHandle(name: string, _options?: FileSystemGetDirectoryOptions): Promise<FileSystemDirectoryHandle>;
+    removeEntry(_name: string, _options?: FileSystemRemoveOptions): Promise<void>;
+    resolve(_possibleDescendant: FileSystemHandle): Promise<string[] | null>;
+    entries(): AsyncIterableIterator<[string, FileSystemHandle]>;
+    keys(): AsyncIterableIterator<string>;
+    values(): AsyncIterableIterator<FileSystemHandle>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>;
+    isSameEntry(other: FileSystemHandle): Promise<boolean>;
+}
+export interface CloudflareR2DirectoryOptions {
+    /** R2 binding name (must match wrangler.toml binding). Defaults to "${NAME}_R2" */
+    binding?: string;
+    /** Optional prefix/path within the bucket */
+    path?: string;
+}
+/**
+ * DirectoryClass for Cloudflare R2 buckets.
+ * Uses env bindings to resolve the bucket at runtime.
+ *
+ * Config example:
+ * ```json
+ * { "module": "@b9g/platform-cloudflare/directories", "binding": "uploads_r2" }
+ * ```
+ */
+export declare class CloudflareR2Directory extends R2FileSystemDirectoryHandle {
+    constructor(name: string, options?: CloudflareR2DirectoryOptions);
+}
+export interface CloudflareAssetsDirectoryOptions {
+    /** Base path within assets (defaults to "/") */
+    path?: string;
+}
+/**
+ * DirectoryClass for Cloudflare ASSETS binding (static assets).
+ * Always uses the "ASSETS" binding (Cloudflare convention).
+ *
+ * Config example:
+ * ```json
+ * { "module": "@b9g/platform-cloudflare/directories", "export": "CloudflareAssetsDirectory" }
+ * ```
+ */
+export declare class CloudflareAssetsDirectory extends CFAssetsDirectoryHandle {
+    constructor(_name: string, options?: CloudflareAssetsDirectoryOptions);
+}
+export default CloudflareR2Directory;