Accept generated KV binding types

wrangler and the Cloudflare Vite plugin can generate local KV
binding declarations whose module identity does not match the
nominal KVNamespace type imported from
@cloudflare/workers-types.  That still made WorkersKvStore and
orderingKv reject otherwise compatible KV bindings after the
earlier experimental-entrypoint fix.

Switch the KV-facing public surface to a minimal structural
binding interface and add a type regression test that compiles
against a generated-like local declaration source.

Fixes #665

Co-Authored-By: OpenAI Codex <noreply@openai.com>

Author: dahlia

CHANGES.md

@@ -8,6 +8,18 @@ Version 2.0.12
 
 To be released.
 
+### @fedify/cfworkers
+
+ -  Fixed a remaining TypeScript type mismatch for Cloudflare Workers users who
+    pass `wrangler types` or `@cloudflare/vite-plugin` generated KV bindings to
+    `WorkersKvStore`.  The package now accepts a minimal structural KV binding
+    interface for `WorkersKvStore` and `WorkersMessageQueue`'s `orderingKv`
+    option instead of requiring the nominal `KVNamespace` type imported from
+    `@cloudflare/workers-types`, so generated local declarations compile
+    without casts or `@ts-expect-error`.  [[#665]]
+
+[#665]: https://github.com/fedify-dev/fedify/issues/665
+
 
 Version 2.0.11
 --------------

packages/cfworkers/package.json

@@ -66,6 +66,7 @@
     "build": "pnpm --filter @fedify/cfworkers... run build:self",
     "prepack": "pnpm build",
     "prepublish": "pnpm build",
-    "test": "vitest run"
+    "pretest": "pnpm build",
+    "test": "tsc -p test/typecheck/tsconfig.json --noEmit && vitest run"
   }
 }

packages/cfworkers/src/mod.ts

@@ -8,11 +8,7 @@
  * @module
  * @since 1.9.0
  */
-import type {
-  KVNamespace,
-  MessageSendRequest,
-  Queue,
-} from "@cloudflare/workers-types";
+import type { MessageSendRequest, Queue } from "@cloudflare/workers-types";
 import type {
   KvKey,
   KvStore,
@@ -27,6 +23,67 @@ interface KvMetadata {
   expires?: number;
 }
 
+interface WorkersKvNamespaceGetWithMetadataResult<Value, Metadata> {
+  readonly value: Value | null;
+  readonly metadata: Metadata | null;
+}
+
+interface WorkersKvNamespaceListKey<Metadata, Key extends string = string> {
+  readonly name: Key;
+  readonly expiration?: number;
+  readonly metadata?: Metadata;
+}
+
+interface WorkersKvNamespaceListResult<Metadata, Key extends string = string> {
+  readonly list_complete: boolean;
+  readonly keys: readonly WorkersKvNamespaceListKey<Metadata, Key>[];
+  readonly cursor?: string;
+}
+
+interface WorkersKvNamespaceListOptions {
+  readonly limit?: number;
+  readonly prefix?: string | null;
+  readonly cursor?: string | null;
+}
+
+interface WorkersKvNamespacePutOptions {
+  readonly expiration?: number;
+  readonly expirationTtl?: number;
+  readonly metadata?: unknown;
+}
+
+/**
+ * Minimal Cloudflare Workers KV binding shape used by this package.
+ * Compatible with both `@cloudflare/workers-types` and `wrangler types`
+ * generated declarations.
+ * @since 2.0.12
+ */
+export interface WorkersKvNamespaceLike<Key extends string = string> {
+  get(key: Key): Promise<string | null>;
+  get<ExpectedValue = unknown>(
+    key: Key,
+    type: "json",
+  ): Promise<ExpectedValue | null>;
+  getWithMetadata<Metadata = unknown>(
+    key: Key,
+  ): Promise<WorkersKvNamespaceGetWithMetadataResult<string, Metadata>>;
+  getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(
+    key: Key,
+    type: "json",
+  ): Promise<
+    WorkersKvNamespaceGetWithMetadataResult<ExpectedValue, Metadata>
+  >;
+  put(
+    key: Key,
+    value: string,
+    options?: WorkersKvNamespacePutOptions,
+  ): Promise<void>;
+  delete(key: Key): Promise<void>;
+  list<Metadata = unknown>(
+    options?: WorkersKvNamespaceListOptions,
+  ): Promise<WorkersKvNamespaceListResult<Metadata, Key>>;
+}
+
 /**
  * Internal message wrapper that includes ordering key metadata.
  */
@@ -74,9 +131,9 @@ export interface ProcessMessageResult {
  * @since 1.9.0
  */
 export class WorkersKvStore implements KvStore {
-  #namespace: KVNamespace<string>;
+  #namespace: WorkersKvNamespaceLike<string>;
 
-  constructor(namespace: KVNamespace<string>) {
+  constructor(namespace: WorkersKvNamespaceLike<string>) {
     this.#namespace = namespace;
   }
 
@@ -202,7 +259,7 @@ export interface WorkersMessageQueueOptions {
    * guarantees are best-effort.  For strict ordering requirements, consider
    * using Durable Objects.
    */
-  readonly orderingKv?: KVNamespace<string>;
+  readonly orderingKv?: WorkersKvNamespaceLike<string>;
 
   /**
    * The prefix for ordering key lock keys.  Defaults to `"__fedify_ordering_"`.
@@ -233,7 +290,7 @@ export interface WorkersMessageQueueOptions {
  */
 export class WorkersMessageQueue implements MessageQueue {
   #queue: Queue;
-  #orderingKv?: KVNamespace<string>;
+  #orderingKv?: WorkersKvNamespaceLike<string>;
   #orderingKeyPrefix: string;
   #orderingLockTtl: number;
 

packages/cfworkers/test/typecheck/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "./**/*.ts"
+  ]
+}

packages/cfworkers/test/typecheck/wrangler-generated-kv.ts

@@ -0,0 +1,69 @@
+import type { Queue } from "@cloudflare/workers-types";
+import { WorkersKvStore, WorkersMessageQueue } from "../../dist/mod.js";
+
+interface GeneratedKvGetWithMetadataResult<Value, Metadata> {
+  readonly value: Value | null;
+  readonly metadata: Metadata | null;
+  readonly cacheStatus: string | null;
+}
+
+interface GeneratedKvListKey<Metadata, Key extends string = string> {
+  readonly name: Key;
+  readonly expiration?: number;
+  readonly metadata?: Metadata;
+}
+
+type GeneratedKvListResult<Metadata, Key extends string = string> =
+  | {
+    readonly list_complete: false;
+    readonly keys: readonly GeneratedKvListKey<Metadata, Key>[];
+    readonly cursor: string;
+    readonly cacheStatus: string | null;
+  }
+  | {
+    readonly list_complete: true;
+    readonly keys: readonly GeneratedKvListKey<Metadata, Key>[];
+    readonly cacheStatus: string | null;
+  };
+
+/**
+ * Mirrors the minimal single-key Cloudflare KV declaration shape emitted by
+ * `wrangler types`, but comes from a distinct local declaration source.
+ */
+interface GeneratedKvNamespace<Key extends string = string> {
+  get(key: Key): Promise<string | null>;
+  get<ExpectedValue = unknown>(
+    key: Key,
+    type: "json",
+  ): Promise<ExpectedValue | null>;
+  getWithMetadata<Metadata = unknown>(
+    key: Key,
+  ): Promise<GeneratedKvGetWithMetadataResult<string, Metadata>>;
+  getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(
+    key: Key,
+    type: "json",
+  ): Promise<GeneratedKvGetWithMetadataResult<ExpectedValue, Metadata>>;
+  put(
+    key: Key,
+    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,
+    options?: {
+      expiration?: number;
+      expirationTtl?: number;
+      metadata?: any | null;
+    },
+  ): Promise<void>;
+  delete(key: Key): Promise<void>;
+  list<Metadata = unknown>(
+    options?: {
+      limit?: number;
+      prefix?: string | null;
+      cursor?: string | null;
+    },
+  ): Promise<GeneratedKvListResult<Metadata, Key>>;
+}
+
+declare const queue: Queue;
+declare const generatedKv: GeneratedKvNamespace<string>;
+
+new WorkersKvStore(generatedKv);
+new WorkersMessageQueue(queue, { orderingKv: generatedKv });