feat(cloudflare): node bindings for kv, d1, r2, and queue #1255

john-royal · 2025-12-11T20:21:46Z

Provides access to runtime APIs for KV, D1, R2, and Queue resources. Uses a proxy to lazily initialize a Miniflare instance with either the remote binding or the local one.

Not sure if "node binding" is the right way to describe this - let me know if you have any other ideas.

pkg-pr-new · 2025-12-11T20:22:44Z

Open in StackBlitz

npm i https://pkg.pr.new/alchemy-run/alchemy@1255

commit: 208f81d

github-actions · 2025-12-11T20:26:28Z

🚀 Website Preview Deployed

Your website preview is ready!

Preview URL: https://611c68fb-alchemy-website.alchemy-run.workers.dev

This preview was built from commit b2e805c

_{🤖 This comment will be updated automatically when you push new commits to this PR.}

john-royal · 2025-12-11T23:31:56Z

alchemy/src/cloudflare/bucket-object.ts

@@ -1,4 +1,3 @@
-import type { R2PutOptions } from "@cloudflare/workers-types/experimental/index.ts";


Removed because it was causing a type error. Now it relies on the global from @cloudflare/workers-types.

john-royal · 2025-12-11T23:36:48Z

alchemy/src/cloudflare/bucket.ts

+      resumeMultipartUpload: (promise) => (key: string, uploadId: string) =>
+        makeAsyncProxy(
+          { key, uploadId },
+          promise.then((bucket) => bucket.resumeMultipartUpload(key, uploadId)),
+          {
+            uploadPart: true,
+            abort: true,
+            complete: true,
+          },
+        ),


resumeMultipartUpload does not return a promise. To match the type of the runtime API, we make this synchronous by returning another proxy.

This is also done for D1 prepared statements and sessions.

Can you show me an example of what the proxy fixes? Are all the properties Promise<T> or functions returning Promises?

john-royal · 2025-12-11T23:37:54Z

alchemy/test/cloudflare/bucket.test.ts

+      // TODO(john): this is a problem with @cloudflare/workers-types, it should not be nullable unless options.onlyIf is used
+      let putObj = (await bucket.put(testKey, testContent)) as R2Object;


Don't merge this PR until I report this to the CF team - this is a weird one

Why not merge it? Is it unusable?

sam-goodwin · 2025-12-13T09:25:58Z

Node bindings doesn't make sense to me. These are just APIs

sam-goodwin · 2025-12-13T09:29:12Z

alchemy/src/cloudflare/d1-database.ts

+      withSession: (promise) => (constraintOrBookmark) =>
+        makeAsyncProxy(
+          {},
+          promise.then((database) =>
+            database.withSession(constraintOrBookmark),
+          ),
+          {
+            prepare: (session) => (query) =>
+              makePreparedStatementProxy(
+                session.then((session) => session.prepare(query)),
+              ),
+            batch: true,
+            getBookmark: () => () => {
+              throw new Error(
+                "D1DatabaseSession.getBookmark is not implemented",
+              );
+            },
+          },
+        ),


We will need to add some tests for each of these APIs on all the resources given how much custom logic there is. Please add tests

shellscape · 2025-12-15T00:21:13Z

Really looking forward to this one. We've got a fairly decent amount of typing shenanigans to make Alchemy binding types play nice with @cloudflare/workers-types.

shellscape · 2025-12-15T00:39:23Z

alchemy/src/cloudflare/bucket.ts

@@ -1,10 +1,8 @@
 import type { R2PutOptions } from "@cloudflare/workers-types/experimental/index.ts";


The R2PutOptions type from experimental is identical to the non-experimental type. I'm not sure the experimental type is needed any longer.

shellscape · 2025-12-15T00:45:51Z

Just gave this one a shot locally. When using import { R2Bucket } from '@cloudflare/workers-types and trying to assign a bucket binding to an R2Bucket typed variable, we get the following error:

error TS2322: Type 'R2Bucket' is not assignable to type 'import("/Users/code/node_modules/.bun/@[email protected]/node_modules/@cloudflare/workers-types/index").R2Bucket'.
  The types returned by 'head(...)' are incompatible between these types.
    Type 'Promise<R2Object | null>' is not assignable to type 'Promise<import("/Users/code/node_modules/.bun/@[email protected]/node_modules/@cloudflare/workers-types/index").R2Object | null>'.
      Type 'R2Object | null' is not assignable to type 'import("/Users/code/node_modules/.bun/@[email protected]/node_modules/@cloudflare/workers-types/index").R2Object | null'.
        Type 'R2Object' is not assignable to type 'import("/Users/code/node_modules/.bun/@[email protected]/node_modules/@cloudflare/workers-types/index").R2Object'.
          Types of property 'writeHttpMetadata' are incompatible.
            Type '(headers: Headers) => void' is not assignable to type '(headers: import("/Users/code/node_modules/.bun/@[email protected]/node_modules/@cloudflare/workers-types/index").Headers) => void'.
              Types of parameters 'headers' and 'headers' are incompatible.
                Property 'getSetCookie' is missing in type 'import("/Users/code/node_modules/.bun/@[email protected]/node_modules/@cloudflare/workers-types/index").Headers' but required in type 'Headers'.

Fwiw our tsconfig is setup for strict.

feat(cloudflare): node bindings for kv, d1, r2, and queue

56b9e3f

john-royal mentioned this pull request Dec 11, 2025

fix(cloudflare): handle large d1 migrations in local dev #1246

Closed

john-royal marked this pull request as ready for review December 11, 2025 20:48

john-royal added 3 commits December 11, 2025 18:07

match runtime types

2e0b7d9

fix missing sockets

c0b43be

make runtime types consistent

4243ce1

john-royal commented Dec 11, 2025

View reviewed changes

fix

208f81d

john-royal commented Dec 11, 2025

View reviewed changes

john-royal linked an issue Dec 11, 2025 that may be closed by this pull request

Alchemy R2Bucket types vs @cloudflare/workers-types #1242

Open

john-royal requested a review from sam-goodwin December 12, 2025 20:42

sam-goodwin reviewed Dec 13, 2025

View reviewed changes

shellscape reviewed Dec 15, 2025

View reviewed changes

		@@ -1,4 +1,3 @@
		import type { R2PutOptions } from "@cloudflare/workers-types/experimental/index.ts";

		// TODO(john): this is a problem with @cloudflare/workers-types, it should not be nullable unless options.onlyIf is used
		let putObj = (await bucket.put(testKey, testContent)) as R2Object;

		@@ -1,10 +1,8 @@
		import type { R2PutOptions } from "@cloudflare/workers-types/experimental/index.ts";

feat(cloudflare): node bindings for kv, d1, r2, and queue #1255

Are you sure you want to change the base?

feat(cloudflare): node bindings for kv, d1, r2, and queue #1255

Uh oh!

Conversation

john-royal commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Website Preview Deployed

Uh oh!

john-royal Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

john-royal Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

sam-goodwin Dec 13, 2025

Choose a reason for hiding this comment

Uh oh!

john-royal Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sam-goodwin Dec 13, 2025

Choose a reason for hiding this comment

Uh oh!

sam-goodwin commented Dec 13, 2025

Uh oh!

sam-goodwin Dec 13, 2025

Choose a reason for hiding this comment

Uh oh!

shellscape commented Dec 15, 2025

Uh oh!

shellscape Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

shellscape commented Dec 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

john-royal commented Dec 11, 2025 •

edited

Loading

pkg-pr-new bot commented Dec 11, 2025 •

edited

Loading

github-actions bot commented Dec 11, 2025 •

edited

Loading

john-royal Dec 11, 2025 •

edited

Loading