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: 0275e1a

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

🚀 Website Preview Deployed

Your website preview is ready!

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

This preview was built from commit de7760f

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

alchemy/src/cloudflare/bucket-object.ts

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?

it's usable, just need to report it or figure out what's going on

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

You were right... there are bugs that the test is revealing. This might take a little longer 😅

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.

alchemy/src/cloudflare/bucket.ts

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/@cloudflare+workers-types@4.20251212.0/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/@cloudflare+workers-types@4.20251212.0/node_modules/@cloudflare/workers-types/index").R2Object | null>'.
      Type 'R2Object | null' is not assignable to type 'import("/Users/code/node_modules/.bun/@cloudflare+workers-types@4.20251212.0/node_modules/@cloudflare/workers-types/index").R2Object | null'.
        Type 'R2Object' is not assignable to type 'import("/Users/code/node_modules/.bun/@cloudflare+workers-types@4.20251212.0/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/@cloudflare+workers-types@4.20251212.0/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/@cloudflare+workers-types@4.20251212.0/node_modules/@cloudflare/workers-types/index").Headers' but required in type 'Headers'.

Fwiw our tsconfig is setup for strict.

john-royal · 2025-12-28T18:51:57Z

alchemy/test/cloudflare/bucket.test.ts

+      console.log("8. list objects");
      const listObj = await bucket.list();
+      console.log("9. list objects", listObj);


Found that the scope was finalizing itself around here, which causes this error to be thrown:

Error: Attempted to use poisoned stub. Stubs to runtime objects must be re-created after calling `Miniflare#setOptions()` or `Miniflare#dispose()`. ❯ ProxyStubHandler.#assertSafe node_modules/.bun/miniflare@4.20251011.1+a744fd195f22f642/node_modules/miniflare/src/plugins/core/proxy/client.ts:370:10 ❯ ProxyStubHandler.get node_modules/.bun/miniflare@4.20251011.1+a744fd195f22f642/node_modules/miniflare/src/plugins/core/proxy/client.ts:4

Tempted to abandon ship on this PR... too many footguns

sam-goodwin · 2025-12-29T12:01:49Z

alchemy/test/cloudflare/d1-database.test.ts

+    try {
+      let database = await D1Database(id);
+      expect(database.id).toBeTruthy();
+      const session = database.withSession("first-primary");


Should we add tests that also use .exec and .prepare? These tests only work on sessions

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

alchemy/src/cloudflare/bucket-object.ts Show resolved Hide resolved

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

alchemy/src/cloudflare/bucket.ts Outdated Show resolved Hide resolved

john-royal added 8 commits December 19, 2025 12:36

Merge branch 'main' into john/cf-node-bindings

d786333

remove unused type

91a266f

simplify

64629e0

take 2

3ba2b1a

Merge branch 'john/cf-node-bindings-take-2' into john/cf-node-bindings

96f565b

consolidate

55543dc

revert unnecessary internal change

acde747

progress?

0275e1a

john-royal commented Dec 28, 2025

View reviewed changes

sam-goodwin reviewed Dec 29, 2025

View reviewed changes

		// 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;

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sam-goodwin commented Dec 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shellscape commented Dec 15, 2025

Uh oh!

Uh oh!

shellscape commented Dec 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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