Alchemy R2Bucket types vs `@cloudflare/workers-types`

[shellscape]

Ahoy hoy 👋

The crux of this issue is that the exported R2Bucket type which is exported and typed to the bindings in Env is a custom type rather than the type exported by @cloudflare/workers-types. Please see here:

alchemy/alchemy/src/cloudflare/bucket.ts

Lines 308 to 325 in 217542d

	export type R2Bucket = _R2Bucket & {
	head(key: string): Promise<R2ObjectMetadata | null>;
	get(key: string): Promise<R2ObjectContent | null>;
	put(
	key: string,
	value:
	| ReadableStream
	| ArrayBuffer
	| ArrayBufferView
	| string
	| null
	| Blob,
	options?: Pick<R2PutOptions, "httpMetadata">,
	): Promise<PutR2ObjectResponse>;
	delete(key: string): Promise<Response>;
	list(options?: R2ListOptions): Promise<R2Objects>;
	};

For the sake of the rest of the issue and our sanity, let us assume that AlchemyR2Bucket is an alias for the R2Bucket type that Alchemy exports, and CloudflareR2Bucket is an alias for the R2Bucket type that @cloudflare/workers-types exports.

What that results in, is any TypeScript code using the AlchemyR2Bucket from bindings with code which expects an CloudflareR2Bucket type results in a TS error, and as unknown as CloudflareR2Bucket because the signatures of get, put, etc are incompatible.

I tried going through the blame for reasoning as to why this was chosen, but couldn't find anything that was a direct reason a custom type was created rather than using what Cloudflare provided. That said, I'm sure there was a good reason. For ref, it looks like the type was added to the workers-types package on or about Oct 15, 2022.

Also of concern is the use of experimental types for the R2PutOptions which are also incompatible with a strict tsconfig, and requires casting

alchemy/alchemy/src/cloudflare/bucket-object.ts

Line 1 in 217542d

import type { R2PutOptions } from "@cloudflare/workers-types/experimental/index.ts";

That line was added in #1024. Curiously, in v4.20251202.0 of @cloudflare/workers-types the R2PutOptions type is identical on the root export to the experimental export that the code is currently using.

All in all, I'm wondering if there's a reason that the custom type direction was taken versus using the types that cloudflare provides for us, and if not, if there's openness to consolidating types and using the official set.

[john-royal]

Hey @shellscape - you're right. There is a reason, but not a very good one - the types were different because we were emulating the runtime API instead of just passing through the real thing. The PR I just linked should fix it.

You can try it out in the meantime using this preview package:

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

[shellscape]

Awesome thanks for doing that!