feat: decorator support

Author: zebp

biome.json

@@ -20,7 +20,10 @@
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": true
+      "recommended": true,
+      "suspicious": {
+        "noExplicitAny": "off"
+      }
     }
   },
   "javascript": {

src/decorator.ts

@@ -0,0 +1,72 @@
+import type { DurableObject } from "cloudflare:workers";
+import { type SnapshotPolicy, state } from "./index.js";
+import { unreachable } from "./util.js";
+
+type FieldDecoratorFactoryReturn<T> = (
+  value: T,
+  metadata: { kind: string; name: string },
+) => FieldDecoratorReturn<T>;
+
+type FieldDecoratorReturn<T> = (this: DurableObject, initialValue: T) => T;
+
+type DiffableArgs =
+  | []
+  | [DiffableOpts]
+  | [name?: string]
+  | [_: any, { kind: string; name: string }];
+
+type DiffableOpts = {
+  name?: string;
+  snapshotPolicy?: SnapshotPolicy;
+};
+
+export function diffable(
+  _: any,
+  { kind, name }: { kind: string; name: string },
+): FieldDecoratorReturn<any>;
+export function diffable(name?: string): FieldDecoratorFactoryReturn<any>;
+export function diffable(
+  options: DiffableOpts,
+): FieldDecoratorFactoryReturn<any>;
+export function diffable():
+  | FieldDecoratorReturn<any>
+  | FieldDecoratorFactoryReturn<any> {
+  // biome-ignore lint/style/noArguments: <explanation>
+  const args = arguments as unknown as DiffableArgs;
+  const fn =
+    (opts: DiffableOpts = {}) =>
+    (_: any, { kind, name: fieldName }: { kind: string; name: string }) => {
+      if (kind === "field") {
+        return function (this: DurableObject, initialValue: any) {
+          const fieldNameNonPrivate = fieldName.replace(/^#/, "");
+          return state(
+            this.ctx,
+            opts.name ?? fieldNameNonPrivate,
+            initialValue,
+            {
+              snapshotPolicy: opts.snapshotPolicy ?? { changes: 10 },
+            },
+          );
+        };
+      }
+
+      throw new Error("Only fields can be persistable");
+    };
+
+  if (args.length === 0) {
+    return fn();
+  }
+
+  if (args.length === 1) {
+    const [optsOrName] = args;
+
+    if (typeof optsOrName === "object") {
+      return fn(optsOrName);
+    }
+
+    return fn(optsOrName ? { name: optsOrName } : {});
+  }
+
+  const [value, metadata] = args;
+  return fn()(value, metadata ?? unreachable());
+}

src/index.ts

@@ -2,10 +2,12 @@ import { recursivelyObservable } from "./observable.js";
 import { SqliteState } from "./sqlite.js";
 import { unreachable } from "./util.js";
 
+export * from "./decorator.js";
+
 export type SnapshotPolicy = "never" | "every-change" | { changes: number };
 
 export type StateOptions = {
-  snapshotPolicy: SnapshotPolicy;
+  snapshotPolicy?: SnapshotPolicy;
 };
 
 export function state<T extends object>(
@@ -21,7 +23,7 @@ export function state<T extends object>(
   return recursivelyObservable(data, {
     onUpdate(changes, data) {
       state.appendChanges(changes);
-      maybeSnapshot(data, state, options.snapshotPolicy);
+      maybeSnapshot(data, state, options.snapshotPolicy ?? { changes: 10 });
     },
   });
 }

src/util.ts

@@ -1,3 +1,3 @@
 export function unreachable(): never {
-    throw new Error("unreachable");
-}
+  throw new Error("unreachable");
+}

tests/decorator.test.ts

@@ -0,0 +1,142 @@
+import { diffable } from "../src/index.js";
+import { describe, expect } from "vitest";
+import { durableIt, snapshots } from "./helper.js";
+import { DurableObject } from "cloudflare:workers";
+import { env } from "cloudflare:test";
+
+describe("state tracking with decorators", () => {
+  durableIt("should track with no args", (objectState) => {
+    class TestObject extends DurableObject {
+      @diffable
+      state = { count: 0 };
+    }
+
+    const obj = new TestObject(objectState, env);
+    for (let i = 0; i < 20; i++) {
+      obj.state.count++;
+    }
+
+    const snapshowRows = snapshots(objectState.storage.sql);
+    expect(snapshowRows).toMatchInlineSnapshot(`
+      [
+        {
+          "changes_id": 10,
+          "id": 1,
+          "state": "state",
+          "value": {
+            "count": 10,
+          },
+        },
+        {
+          "changes_id": 20,
+          "id": 2,
+          "state": "state",
+          "value": {
+            "count": 20,
+          },
+        },
+      ]
+    `);
+  });
+
+  durableIt("should track with empty args", (objectState) => {
+    class TestObject extends DurableObject {
+      @diffable()
+      state = { count: 0 };
+    }
+
+    const obj = new TestObject(objectState, env);
+    for (let i = 0; i < 20; i++) {
+      obj.state.count++;
+    }
+
+    const snapshowRows = snapshots(objectState.storage.sql);
+    expect(snapshowRows).toMatchInlineSnapshot(`
+      [
+        {
+          "changes_id": 10,
+          "id": 1,
+          "state": "state",
+          "value": {
+            "count": 10,
+          },
+        },
+        {
+          "changes_id": 20,
+          "id": 2,
+          "state": "state",
+          "value": {
+            "count": 20,
+          },
+        },
+      ]
+    `);
+  });
+
+  durableIt("should track with named args", (objectState) => {
+    class TestObject extends DurableObject {
+      @diffable("foo")
+      state = { count: 0 };
+    }
+
+    const obj = new TestObject(objectState, env);
+    for (let i = 0; i < 20; i++) {
+      obj.state.count++;
+    }
+
+    const snapshowRows = snapshots(objectState.storage.sql);
+    expect(snapshowRows).toMatchInlineSnapshot(`
+      [
+        {
+          "changes_id": 10,
+          "id": 1,
+          "state": "foo",
+          "value": {
+            "count": 10,
+          },
+        },
+        {
+          "changes_id": 20,
+          "id": 2,
+          "state": "foo",
+          "value": {
+            "count": 20,
+          },
+        },
+      ]
+    `);
+  });
+
+  durableIt("should track with options", (objectState) => {
+    class TestObject extends DurableObject {
+      @diffable({ name: "foo", snapshotPolicy: "every-change" })
+      state = { count: 0 };
+    }
+
+    const obj = new TestObject(objectState, env);
+    obj.state.count++;
+    obj.state.count++;
+
+    const snapshowRows = snapshots(objectState.storage.sql);
+    expect(snapshowRows).toMatchInlineSnapshot(`
+      [
+        {
+          "changes_id": 1,
+          "id": 1,
+          "state": "foo",
+          "value": {
+            "count": 1,
+          },
+        },
+        {
+          "changes_id": 2,
+          "id": 2,
+          "state": "foo",
+          "value": {
+            "count": 2,
+          },
+        },
+      ]
+    `);
+  });
+});

tests/global.d.ts

@@ -1,5 +1,5 @@
 declare module "cloudflare:test" {
-    interface ProvidedEnv {
-        test: DurableObjectNamespace;
-    }
-}
+  interface ProvidedEnv {
+    test: DurableObjectNamespace;
+  }
+}

tests/helper.ts

@@ -1,16 +1,43 @@
 import { env, runInDurableObject } from "cloudflare:test";
 import { it } from "vitest";
 
-export async function runInTestDurableObject(fn: (objectState: DurableObjectState) => void) {
-    const id = env.test.idFromName("test");
-    const stub = env.test.get(id);
-    await runInDurableObject(stub, async (_, objectState) => {
-        fn(objectState);
-    });
+export async function runInTestDurableObject(
+  fn: (objectState: DurableObjectState) => void,
+) {
+  const id = env.test.idFromName("test");
+  const stub = env.test.get(id);
+  await runInDurableObject(stub, async (_, objectState) => {
+    fn(objectState);
+  });
+}
+
+export function durableIt(
+  name: string,
+  fn: (objectState: DurableObjectState) => void,
+) {
+  it(name, async () => {
+    await runInTestDurableObject(fn);
+  });
 }
 
-export function durableIt(name: string, fn: (objectState: DurableObjectState) => void) {
-    it(name, async () => {
-        await runInTestDurableObject(fn);
+type SnapshotRow = {
+  id: number;
+  state: string;
+  value: string;
+  changes_id: number;
+  created_at?: string;
+};
+
+export function snapshots(sql: SqlStorage) {
+  return sql
+    .exec<SnapshotRow>("SELECT * FROM snapshots")
+    .toArray()
+    .map((row) => {
+      // biome-ignore lint/performance/noDelete: <explanation>
+      delete row.created_at;
+      return {
+        ...row,
+        value: JSON.parse(row.value),
+      };
     });
-}
+}