Actors library alpha changelog

src/content/changelog/durable-objects/2025-06-25-actors-package-alpha.mdx

@@ -0,0 +1,76 @@
+---
+title: @cloudflare/actors library: SDK for Durable Objects in alpha
+description: @cloudflare/actors library with Durable Objects helpers and patterns.
+products:
+  - durable-objects
+  - workers
+date: 2025-06-25T06:00:00Z
+---
+
+[@cloudflare/actors](https://www.npmjs.com/package/@cloudflare/actors) package is in alpha and provides a SDK for Durable Objects, in addition to Durable Objects [Workers API](https://developers.cloudflare.com/durable-objects/api/base/). "Actors" originates from the [actor programming model](/durable-objects/what-are-durable-objects/#actor-programming-model), which is a close analogy for Durable Objects.
+
+For alpha, `/actors` library includes:
+
+* Storage helpers for using embeddeded, per-object SQLite storage, including SQL schema migrations and query template literals
+* Alarm helpers for scheduling multiple alarms provided a date, delay in seconds, or cron expression
+* `Actor` class for using Durable Objects with a defined pattern
+
+Storage and alarm helper methods can be combined with [any Javascript class](https://github.com/cloudflare/actors?tab=readme-ov-file#storage--alarms-with-durableobject-class) that defines your Durable Object, i.e, ones that extend `DurableObject` including the `Actor` class.
+
+```js
+import { Storage } from "@cloudflare/actors/storage";
+
+export class ChatRoom extends DurableObject<Env> {
+    storage: Storage;
+
+    constructor(ctx: DurableObjectState, env: Env) {
+        super(ctx, env)
+        this.storage = new Storage(ctx.storage);
+        this.storage.migrations = [{
+            idMonotonicInc: 1,
+            description: "Create users table",
+            sql: "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY)"
+        }]
+    }
+    async fetch(request: Request): Promise<Response> {
+        // Run migrations before executing SQL query
+        await this.storage.runMigrations();
+
+        // Query with SQL template
+        let userId = new URL(request.url).searchParams.get("userId");
+        const query = this.storage.sql`SELECT * FROM users WHERE id = ${userId};`
+        return new Response(`${JSON.stringify(query)}`);
+    }
+}
+```
+
+`/actors` library introduces the `Actor` class pattern. `Actor` lets you access Durable Objects without writing the Worker that communicates with your Durable Object (the Worker is created for you). By default, requests are routed to a Durable Object named "default". 
+
+```js
+export class MyActor extends Actor<Env> {
+    async fetch(request: Request): Promise<Response> {
+        return new Response('Hello, World!')
+    }
+}
+
+export default handler(MyActor);
+```
+
+You can [route](/durable-objects/get-started/#3-instantiate-and-communicate-with-a-durable-object) to different Durable Objects by name within your `Actor` class using [`nameFromRequest`](https://github.com/cloudflare/actors?tab=readme-ov-file#actor-with-custom-name).
+
+```js
+export class MyActor extends Actor<Env> {
+    static nameFromRequest(request: Request): string {
+        let url = new URL(request.url);
+        return url.searchParams.get("userId") ?? "foo";
+    }
+
+    async fetch(request: Request): Promise<Response> {
+        return new Response(`Actor identifier (Durable Object name): ${this.identifier}`);
+    }
+}
+
+export default handler(MyActor);
+```
+
+For more examples, check out the library [README](https://github.com/cloudflare/actors?tab=readme-ov-file#getting-started). `/actors` library is a place for more helpers and built-in patterns, e.g. retry handling and websocket helpers, to reduce development overhead for common Durable Objects functionality. Please share feedback and what more you would like to see on our [Discord channel](https://discord.com/channels/595317990191398933/773219443911819284).