Merge pull request #3224 from cloudflare/jlee/add-alarm-param-type

Add optional AlarmInvocationInfo parameter to Durable Object alarm() method
cloudflare · Dec 10, 2024 · a6423f2 · a6423f2
2 parents 392825f + d0e1bd5
commit a6423f2
Show file tree

Hide file tree

Showing 23 changed files with 54 additions and 32 deletions.
diff --git a/src/workerd/api/actor.h b/src/workerd/api/actor.h
@@ -106,7 +106,7 @@ class DurableObject final: public Fetcher {
 
     JSG_TS_DEFINE(interface DurableObject {
       fetch(request: Request): Response | Promise<Response>;
-      alarm?(): void | Promise<void>;
+      alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
       webSocketMessage?(ws: WebSocket, message: string | ArrayBuffer): void | Promise<void>;
       webSocketClose?(ws: WebSocket, code: number, reason: string, wasClean: boolean): void | Promise<void>;
       webSocketError?(ws: WebSocket, error: unknown): void | Promise<void>;

diff --git a/types/defines/rpc.d.ts b/types/defines/rpc.d.ts
@@ -190,7 +190,7 @@ declare module "cloudflare:workers" {
     constructor(ctx: DurableObjectState, env: Env);
 
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer

diff --git a/types/generated-snapshot/2021-11-03/index.d.ts b/types/generated-snapshot/2021-11-03/index.d.ts
@@ -467,7 +467,7 @@ interface Cloudflare {
 }
 interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,
@@ -5312,7 +5312,7 @@ declare module "cloudflare:workers" {
     protected env: Env;
     constructor(ctx: DurableObjectState, env: Env);
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2021-11-03/index.ts b/types/generated-snapshot/2021-11-03/index.ts
@@ -472,7 +472,7 @@ export interface Cloudflare {
 }
 export interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2022-01-31/index.d.ts b/types/generated-snapshot/2022-01-31/index.d.ts
@@ -467,7 +467,7 @@ interface Cloudflare {
 }
 interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,
@@ -5338,7 +5338,7 @@ declare module "cloudflare:workers" {
     protected env: Env;
     constructor(ctx: DurableObjectState, env: Env);
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2022-01-31/index.ts b/types/generated-snapshot/2022-01-31/index.ts
@@ -472,7 +472,7 @@ export interface Cloudflare {
 }
 export interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2022-03-21/index.d.ts b/types/generated-snapshot/2022-03-21/index.d.ts
@@ -485,7 +485,7 @@ interface Cloudflare {
 }
 interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,
@@ -5363,7 +5363,7 @@ declare module "cloudflare:workers" {
     protected env: Env;
     constructor(ctx: DurableObjectState, env: Env);
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2022-03-21/index.ts b/types/generated-snapshot/2022-03-21/index.ts
@@ -490,7 +490,7 @@ export interface Cloudflare {
 }
 export interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2022-08-04/index.d.ts b/types/generated-snapshot/2022-08-04/index.d.ts
@@ -485,7 +485,7 @@ interface Cloudflare {
 }
 interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,
@@ -5364,7 +5364,7 @@ declare module "cloudflare:workers" {
     protected env: Env;
     constructor(ctx: DurableObjectState, env: Env);
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2022-08-04/index.ts b/types/generated-snapshot/2022-08-04/index.ts
@@ -490,7 +490,7 @@ export interface Cloudflare {
 }
 export interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2022-10-31/index.d.ts b/types/generated-snapshot/2022-10-31/index.d.ts
@@ -485,7 +485,7 @@ interface Cloudflare {
 }
 interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,
@@ -5367,7 +5367,7 @@ declare module "cloudflare:workers" {
     protected env: Env;
     constructor(ctx: DurableObjectState, env: Env);
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2022-10-31/index.ts b/types/generated-snapshot/2022-10-31/index.ts
@@ -490,7 +490,7 @@ export interface Cloudflare {
 }
 export interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2022-11-30/index.d.ts b/types/generated-snapshot/2022-11-30/index.d.ts
@@ -490,7 +490,7 @@ interface Cloudflare {
 }
 interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,
@@ -5372,7 +5372,7 @@ declare module "cloudflare:workers" {
     protected env: Env;
     constructor(ctx: DurableObjectState, env: Env);
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2022-11-30/index.ts b/types/generated-snapshot/2022-11-30/index.ts
@@ -495,7 +495,7 @@ export interface Cloudflare {
 }
 export interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2023-03-01/index.d.ts b/types/generated-snapshot/2023-03-01/index.d.ts
@@ -490,7 +490,7 @@ interface Cloudflare {
 }
 interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,
@@ -5374,7 +5374,7 @@ declare module "cloudflare:workers" {
     protected env: Env;
     constructor(ctx: DurableObjectState, env: Env);
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2023-03-01/index.ts b/types/generated-snapshot/2023-03-01/index.ts
@@ -495,7 +495,7 @@ export interface Cloudflare {
 }
 export interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2023-07-01/index.d.ts b/types/generated-snapshot/2023-07-01/index.d.ts
@@ -490,7 +490,7 @@ interface Cloudflare {
 }
 interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,
@@ -5374,7 +5374,7 @@ declare module "cloudflare:workers" {
     protected env: Env;
     constructor(ctx: DurableObjectState, env: Env);
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/2023-07-01/index.ts b/types/generated-snapshot/2023-07-01/index.ts
@@ -495,7 +495,7 @@ export interface Cloudflare {
 }
 export interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/experimental/index.d.ts b/types/generated-snapshot/experimental/index.d.ts
@@ -491,7 +491,7 @@ interface Cloudflare {
 }
 interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,
@@ -5440,7 +5440,7 @@ declare module "cloudflare:workers" {
     protected env: Env;
     constructor(ctx: DurableObjectState, env: Env);
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/experimental/index.ts b/types/generated-snapshot/experimental/index.ts
@@ -496,7 +496,7 @@ export interface Cloudflare {
 }
 export interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/oldest/index.d.ts b/types/generated-snapshot/oldest/index.d.ts
@@ -467,7 +467,7 @@ interface Cloudflare {
 }
 interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,
@@ -5312,7 +5312,7 @@ declare module "cloudflare:workers" {
     protected env: Env;
     constructor(ctx: DurableObjectState, env: Env);
     fetch?(request: Request): Response | Promise<Response>;
-    alarm?(): void | Promise<void>;
+    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
     webSocketMessage?(
       ws: WebSocket,
       message: string | ArrayBuffer,

diff --git a/types/generated-snapshot/oldest/index.ts b/types/generated-snapshot/oldest/index.ts
@@ -472,7 +472,7 @@ export interface Cloudflare {
 }
 export interface DurableObject {
   fetch(request: Request): Response | Promise<Response>;
-  alarm?(): void | Promise<void>;
+  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
   webSocketMessage?(
     ws: WebSocket,
     message: string | ArrayBuffer,

diff --git a/types/test/types/rpc.ts b/types/test/types/rpc.ts
@@ -306,6 +306,27 @@ class TestObject extends DurableObject {
   }
 }
 
+class TestAlarmObject extends DurableObject {
+  // Can declare alarm method consuming optional alarmInfo parameter
+  async alarm(alarmInfo?: AlarmInvocationInfo) {
+    if (alarmInfo !== undefined) {
+      const _isRetry: boolean = alarmInfo.isRetry;
+      const _retryCount: number = alarmInfo.retryCount;
+    }
+  }
+
+  // User code can invoke alarm() directly, if desired.
+  async runAlarmVoid(): Promise<void> {
+    return await this.alarm();
+  }
+  async runAlarmInfo(): Promise<void> {
+    return await this.alarm({
+      isRetry: true,
+      retryCount: 1,
+    });
+  }
+}
+
 class TestNaughtyEntrypoint extends WorkerEntrypoint {
   // Check incorrectly typed methods
   // @ts-expect-error
@@ -351,6 +372,7 @@ interface Env {
 
   REGULAR_OBJECT: DurableObjectNamespace;
   RPC_OBJECT: DurableObjectNamespace<TestObject>;
+  ALARM_OBJECT: DurableObjectNamespace<TestAlarmObject>;
   NAUGHTY_OBJECT: DurableObjectNamespace<TestNaughtyObject>;
   // @ts-expect-error `BoringClass` isn't an RPC capable type
   __INVALID_OBJECT_1: DurableObjectNamespace<BoringClass>;