@fedify/cfworkers 2.2.0-dev.671 → 2.2.0-dev.681

package/README.md

@@ -16,7 +16,7 @@ implementations for [Cloudflare Workers]:
  -  [`WorkersMessageQueue`]
 
 ~~~~ typescript
-import type { Federation } from "@fedify/fedify";
+import { createFederation, type Message } from "@fedify/fedify";
 import { WorkersKvStore, WorkersMessageQueue } from "@fedify/cfworkers";
 
 export default {
@@ -26,22 +26,25 @@ export default {
       queue: new WorkersMessageQueue(env.QUEUE_BINDING),
       // ... other options
     });
-    
-    return federation.handle(request, { contextData: env });
+
+    return federation.fetch(request, { contextData: env });
   },
-  
+
   async queue(batch, env, ctx) {
     const federation = createFederation({
       kv: new WorkersKvStore(env.KV_BINDING),
       queue: new WorkersMessageQueue(env.QUEUE_BINDING),
       // ... other options
     });
-    
+
     for (const message of batch.messages) {
-      await federation.processQueuedTask(message.body);
+      await federation.processQueuedTask(
+        env,
+        message.body as unknown as Message,
+      );
     }
   }
-} satisfies ExportedHandler<{ 
+} satisfies ExportedHandler<{
   KV_BINDING: KVNamespace<string>;
   QUEUE_BINDING: Queue;
 }>;
@@ -101,6 +104,14 @@ management.
 > process the messages.  The `queue()` method is the only way to consume
 > messages from the queue in Cloudflare Workers.
 
+> [!NOTE]
+> If you use `orderingKey` when enqueueing messages, construct
+> `WorkersMessageQueue` with an `orderingKv` namespace and pass each raw queue
+> message through `WorkersMessageQueue.processMessage()` before calling
+> `Federation.processQueuedTask()`.  This acquires and releases the best-effort
+> ordering lock for that key.  You can also customize the lock behavior with
+> the `orderingKeyPrefix` and `orderingLockTtl` options.
+
 [Cloudflare Queues]: https://developers.cloudflare.com/queues/
 
 

package/dist/mod.d.ts

@@ -1,7 +1,46 @@
-import { KVNamespace, Queue } from "@cloudflare/workers-types";
+import { Queue } from "@cloudflare/workers-types";
 import { KvKey, KvStore, KvStoreListEntry, KvStoreSetOptions, MessageQueue, MessageQueueEnqueueOptions, MessageQueueListenOptions } from "@fedify/fedify/federation";
 
 //#region src/mod.d.ts
+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
+*/
+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>>;
+}
 /**
 * Result from {@link WorkersMessageQueue.processMessage}.
 * @since 2.0.0
@@ -39,7 +78,7 @@ interface ProcessMessageResult {
 */
 declare class WorkersKvStore implements KvStore {
   #private;
-  constructor(namespace: KVNamespace<string>);
+  constructor(namespace: WorkersKvNamespaceLike<string>);
   get<T = unknown>(key: KvKey): Promise<T | undefined>;
   set(key: KvKey, value: unknown, options?: KvStoreSetOptions): Promise<void>;
   delete(key: KvKey): Promise<void>;
@@ -62,7 +101,7 @@ 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_"`.
   * @default `"__fedify_ordering_"`
@@ -145,4 +184,4 @@ declare class WorkersMessageQueue implements MessageQueue {
   listen(_handler: (message: any) => Promise<void> | void, _options?: MessageQueueListenOptions): Promise<void>;
 }
 //#endregion
-export { ProcessMessageResult, WorkersKvStore, WorkersMessageQueue, WorkersMessageQueueOptions };
+export { ProcessMessageResult, WorkersKvNamespaceLike, WorkersKvStore, WorkersMessageQueue, WorkersMessageQueueOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/cfworkers",
-  "version": "2.2.0-dev.671+61141c60",
+  "version": "2.2.0-dev.681+db2766de",
   "description": "Adapt Fedify with Cloudflare Workers",
   "keywords": [
     "Fedify",
@@ -52,7 +52,7 @@
   ],
   "peerDependencies": {
     "@cloudflare/workers-types": "^4.20250906.0",
-    "@fedify/fedify": "^2.2.0-dev.671+61141c60"
+    "@fedify/fedify": "^2.2.0-dev.681+db2766de"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.8.31",
@@ -65,6 +65,7 @@
     "build:self": "tsdown",
     "build": "pnpm --filter @fedify/cfworkers... run build:self",
     "prepublish": "pnpm build",
-    "test": "vitest run"
+    "pretest": "pnpm build",
+    "test": "tsc -p test/typecheck/tsconfig.json --noEmit && vitest run"
   }
 }