@signe/room 3.0.0 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signe/room",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "PartyKit room primitives with synchronized state, sessions, guards, and HTTP handlers.",
   "main": "./dist/index.js",
   "keywords": [
@@ -31,7 +31,7 @@
     "dset": "^3.1.3",
     "partysocket": "^1.0.1",
     "zod": "^3.23.8",
-    "@signe/sync": "3.0.0"
+    "@signe/sync": "3.0.1"
   },
   "publishConfig": {
     "access": "public"

package/readme.md

@@ -299,6 +299,47 @@ const hydrated = { ...snapshot, items };
 load(user, hydrated, true);
 ```
 
+### Storage Restore Hydration
+
+Room storage is loaded automatically when a room starts. If persisted snapshots
+contain complex values that must become runtime instances again, implement
+`onStorageRestore` or `onUserStorageRestore` on the room.
+
+Use `onStorageRestore` to transform the full room snapshot before it is loaded:
+
+```ts
+class GameRoom {
+  async onStorageRestore({ snapshot, room, legacy }) {
+    return {
+      ...snapshot,
+      status: snapshot.status ?? "waiting",
+    };
+  }
+}
+```
+
+Use `onUserStorageRestore` to transform each persisted entry in the room's
+`@users()` collection. The hook receives a fresh user helper instance so you can
+reuse instance methods to hydrate nested data before the snapshot is loaded.
+
+```ts
+class GameRoom {
+  @users(Player) players = signal({});
+
+  async onUserStorageRestore({ userSnapshot, user, publicId }) {
+    return {
+      ...userSnapshot,
+      items: await user.resolveItems(userSnapshot.items),
+      skills: await user.resolveSkills(userSnapshot.skills),
+    };
+  }
+}
+```
+
+Returning `undefined` keeps the original snapshot unchanged. The `legacy` flag is
+`true` only when loading data from the pre-`state:` storage layout during
+automatic migration.
+
 ### Room Configuration
 
 The `@Room` decorator accepts various configuration options:
@@ -955,6 +996,12 @@ The SQLite helper enables `PRAGMA busy_timeout = 5000` and `PRAGMA journal_mode
 write contention. You can override those defaults with `busyTimeoutMs`,
 `journalMode`, and `busyRetries`.
 
+Room state is stored as incremental `state:` entries. When a persisted delete is
+encountered, the server compacts the room state by materializing the current
+snapshot and removing durable delete markers. This keeps long-running SQLite
+storage from accumulating `"$delete"` tombstones after objects or users are
+removed.
+
 To create your own storage backend, implement the key-value methods used by
 `@signe/room`: `get`, `put`, `delete`, and `list`, then return it from a storage
 provider.

package/src/index.ts

@@ -1,9 +1,9 @@
 export * from './decorators';
 export { ClientIo, MockConnection, ServerIo } from './mock';
-export { Server } from './server';
+export { Server, type StorageRestoreContext, type UserStorageRestoreContext } from './server';
 export * from './testing';
 export * from './shard';
 export * from './world';
 export * from './interfaces';
 export * from './request/response';
-export { requireSession, createRequireSessionGuard } from './session.guard';
+export { requireSession, createRequireSessionGuard } from './session.guard';

package/src/server.ts

@@ -33,6 +33,23 @@ type CreateRoomOptions = {
   throttleStorage?: number;
 };
 
+export type StorageRestoreContext<TSnapshot = any> = {
+  snapshot: TSnapshot;
+  room: Party.Room;
+  server: Server;
+  legacy: boolean;
+};
+
+export type UserStorageRestoreContext<TUser = any, TSnapshot = any> = {
+  userSnapshot: TSnapshot;
+  user: TUser | undefined;
+  publicId: string;
+  usersPropName: string;
+  room: Party.Room;
+  server: Server;
+  legacy: boolean;
+};
+
 type SessionData = {
   publicId: string;
   state?: any;
@@ -52,6 +69,8 @@ type StorageMetrics = {
   loadMs: number;
   loadStateKeys: number;
   loadLegacyKeys: number;
+  stateCompactions: number;
+  stateCompactionDeletes: number;
   persistFlushes: number;
   persistWrites: number;
   persistDeletes: number;
@@ -195,16 +214,139 @@ export class Server implements Party.Server {
     const descendantEntries = await this.listStorage(`${stateKey}.`);
     await this.deleteStorageKeys([
       ...Array.from(descendantEntries.keys()),
-      path,
+      stateKey,
     ]);
     await this.saveStatePath(path, DELETE_TOKEN);
   }
 
+  private containsDeleteToken(value: any): boolean {
+    if (value === DELETE_TOKEN) {
+      return true;
+    }
+    if (!value || typeof value !== "object") {
+      return false;
+    }
+    if (Array.isArray(value)) {
+      return value.some((item) => this.containsDeleteToken(item));
+    }
+    return Object.values(value).some((item) => this.containsDeleteToken(item));
+  }
+
+  private async compactStateStorage(instance: any) {
+    const entries = await this.listStorage(STATE_PREFIX);
+    const keys = Array.from(entries.keys());
+    if (keys.length === 0) {
+      return;
+    }
+
+    const snapshot = createStatesSnapshotDeep(instance);
+    await this.deleteStorageKeys(keys);
+    await this.saveStatePath(".", snapshot);
+
+    const metrics = instance.$storageMetrics as StorageMetrics | undefined;
+    if (metrics) {
+      metrics.stateCompactions += 1;
+      metrics.stateCompactionDeletes += keys.length;
+    }
+  }
+
+  private createUserFromClassType(classType: any, ...args: any[]) {
+    if (!classType) {
+      return undefined;
+    }
+    return isClass(classType) ? new classType() : classType(...args);
+  }
+
+  private async restoreUsersStorageSnapshot(
+    instance: any,
+    snapshot: any,
+    options: { legacy: boolean }
+  ) {
+    if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) {
+      return snapshot;
+    }
+
+    const restoreUser = instance["onUserStorageRestore"];
+    if (typeof restoreUser !== "function") {
+      return snapshot;
+    }
+
+    const signal = this.getUsersProperty(instance);
+    const usersPropName = this.getUsersPropName(instance);
+    if (!signal || !usersPropName) {
+      return snapshot;
+    }
+
+    const usersSnapshot = snapshot[usersPropName];
+    if (!usersSnapshot || typeof usersSnapshot !== "object" || Array.isArray(usersSnapshot)) {
+      return snapshot;
+    }
+
+    const { classType } = signal.options || {};
+    let nextSnapshot = snapshot;
+    let nextUsersSnapshot = usersSnapshot;
+
+    for (const [publicId, userSnapshot] of Object.entries(usersSnapshot)) {
+      const user = this.createUserFromClassType(classType, publicId);
+      const restoredUserSnapshot = await awaitReturn(
+        restoreUser.call(instance, {
+          userSnapshot,
+          user,
+          publicId,
+          usersPropName,
+          room: this.room,
+          server: this,
+          legacy: options.legacy,
+        } satisfies UserStorageRestoreContext)
+      );
+
+      if (restoredUserSnapshot !== undefined && restoredUserSnapshot !== userSnapshot) {
+        if (nextSnapshot === snapshot) {
+          nextSnapshot = { ...snapshot };
+        }
+        if (nextUsersSnapshot === usersSnapshot) {
+          nextUsersSnapshot = { ...usersSnapshot };
+          nextSnapshot[usersPropName] = nextUsersSnapshot;
+        }
+        nextUsersSnapshot[publicId] = restoredUserSnapshot;
+      }
+    }
+
+    return nextSnapshot;
+  }
+
+  private async restoreStorageSnapshot(
+    instance: any,
+    snapshot: any,
+    options: { legacy: boolean }
+  ) {
+    const restoreSnapshot = instance["onStorageRestore"];
+    let restoredSnapshot = snapshot;
+
+    if (typeof restoreSnapshot === "function") {
+      const result = await awaitReturn(
+        restoreSnapshot.call(instance, {
+          snapshot,
+          room: this.room,
+          server: this,
+          legacy: options.legacy,
+        } satisfies StorageRestoreContext)
+      );
+      if (result !== undefined) {
+        restoredSnapshot = result;
+      }
+    }
+
+    return this.restoreUsersStorageSnapshot(instance, restoredSnapshot, options);
+  }
+
   private createStorageMetrics(): StorageMetrics {
     return {
       loadMs: 0,
       loadStateKeys: 0,
       loadLegacyKeys: 0,
+      stateCompactions: 0,
+      stateCompactionDeletes: 0,
       persistFlushes: 0,
       persistWrites: 0,
       persistDeletes: 0,
@@ -603,15 +745,27 @@ export class Server implements Party.Server {
             migratedEntries.map(([path, value]) => [this.stateKey(path), value])
           )
         );
-        if (legacyRoot !== undefined) {
+        if (legacyDeleteKeys.length > 0) {
           await this.deleteStorageKeys(legacyDeleteKeys);
         }
-        load(instance, legacyObject, true);
+        const restoredLegacyObject = await this.restoreStorageSnapshot(instance, legacyObject, {
+          legacy: true,
+        });
+        load(instance, restoredLegacyObject, true);
+        if (this.containsDeleteToken(restoredLegacyObject)) {
+          await this.compactStateStorage(instance);
+        }
         metrics.loadMs = Date.now() - startedAt;
         return;
       }
 
-      load(instance, tmpObject, true);
+      const restoredObject = await this.restoreStorageSnapshot(instance, tmpObject, {
+        legacy: false,
+      });
+      load(instance, restoredObject, true);
+      if (this.containsDeleteToken(restoredObject)) {
+        await this.compactStateStorage(instance);
+      }
       metrics.loadMs = Date.now() - startedAt;
     };
 
@@ -784,19 +938,16 @@ export class Server implements Party.Server {
       values.clear();
     }
 
-    // Persist callback: Save changes to storage
-    const persistCb = async (values: Map<string, any>) => {
-      if (initPersist) {
-        values.clear();
-        return;
-      }
+    const flushPersist = async (values: Map<string, any>) => {
       const startedAt = Date.now();
       const stateWrites: Record<string, any> = {};
       const deleteTasks: Promise<void>[] = [];
+      let hasDeletes = false;
       for (let [path, value] of values) {
         const _instance =
           path == "." ? instance : getByPath(instance, path);
         if (value == DELETE_TOKEN) {
+          hasDeletes = true;
           deleteTasks.push(this.deleteStatePath(path));
         } else {
           const itemValue = _instance?.$snapshot
@@ -809,6 +960,9 @@ export class Server implements Party.Server {
         this.putStorageEntries(stateWrites),
         ...deleteTasks,
       ]);
+      if (hasDeletes) {
+        await this.compactStateStorage(instance);
+      }
       const metrics = instance.$storageMetrics as StorageMetrics | undefined;
       if (metrics) {
         metrics.persistFlushes += 1;
@@ -816,7 +970,25 @@ export class Server implements Party.Server {
         metrics.persistDeletes += deleteTasks.length;
         metrics.persistLastFlushMs = Date.now() - startedAt;
       }
+    }
+
+    let persistQueue = Promise.resolve();
+
+    // Persist callback: Save changes to storage
+    const persistCb = async (values: Map<string, any>) => {
+      if (initPersist) {
+        values.clear();
+        return;
+      }
+
+      const valuesSnapshot = new Map(values);
       values.clear();
+
+      persistQueue = persistQueue.then(
+        () => flushPersist(valuesSnapshot),
+        () => flushPersist(valuesSnapshot)
+      );
+      await persistQueue;
     }
 
     const debouncePersist = (wait: number) => {
@@ -1188,7 +1360,7 @@ export class Server implements Party.Server {
         if (transferData?.restored && signal()[publicId]) {
           user = signal()[publicId];
         } else {
-          user = isClass(classType) ? new classType() : classType(conn, ctx);
+          user = this.createUserFromClassType(classType, conn, ctx);
           signal()[publicId] = user;
           const snapshot = createStatesSnapshotDeep(user);
           await this.saveStatePath(`${usersPropName}.${publicId}`, snapshot);
@@ -1743,7 +1915,7 @@ export class Server implements Party.Server {
           const { classType } = signal.options;
           
           // Create new user instance
-          const user = isClass(classType) ? new classType() : classType();
+          const user = this.createUserFromClassType(classType);
 
           const hydratedSnapshot =
             (await awaitReturn(

package/src/types/party.ts

@@ -253,6 +253,32 @@ import type {
      * @param conn The connection object
      */
     onLeave?(user: TUser, conn: Connection): void | Promise<void>;
+
+    /**
+     * Called before persisted room state is loaded into the room instance.
+     * Return a replacement snapshot to hydrate serialized values before load.
+     */
+    onStorageRestore?(context: {
+      snapshot: any;
+      room: Room;
+      server: Server;
+      legacy: boolean;
+    }): any | Promise<any>;
+
+    /**
+     * Called for each restored entry in the room's @users() collection before
+     * persisted room state is loaded. Return a replacement user snapshot to
+     * hydrate serialized nested values before load.
+     */
+    onUserStorageRestore?(context: {
+      userSnapshot: any;
+      user: TUser | undefined;
+      publicId: string;
+      usersPropName: string;
+      room: Room;
+      server: Server;
+      legacy: boolean;
+    }): any | Promise<any>;
   }
   
   /** @deprecated Use `Party.Room` instead */

package/tests/storage-restore.spec.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { signal } from "@signe/reactive";
+import { sync, users } from "@signe/sync";
+import { Room, Server, ServerIo } from "../src";
+
+class Item {
+  id = signal("");
+}
+
+class Player {
+  items = signal<any[]>([]);
+}
+
+describe("storage restore hooks", () => {
+  it("allows a room to hydrate the persisted root snapshot before load", async () => {
+    @Room({ path: "demo" })
+    class DemoRoom {
+      @sync()
+      title = signal("");
+
+      onStorageRestore({ snapshot }: { snapshot: any }) {
+        return {
+          ...snapshot,
+          title: `${snapshot.title}:hydrated`,
+        };
+      }
+    }
+
+    class DemoServer extends Server {
+      rooms = [DemoRoom];
+    }
+
+    const io = new ServerIo("demo");
+    await io.storage.put("state:title", "saved");
+
+    const server = new DemoServer(io as any);
+    await server.onStart();
+
+    expect((server.subRoom as any).title()).toBe("saved:hydrated");
+  });
+
+  it("allows a room to hydrate persisted user snapshots before load", async () => {
+    @Room({ path: "demo" })
+    class DemoRoom {
+      @users(Player)
+      players = signal<Record<string, Player>>({});
+
+      async onUserStorageRestore({ userSnapshot, user }: { userSnapshot: any; user?: Player }) {
+        return {
+          ...userSnapshot,
+          items: userSnapshot.items.map((entry: any) => {
+            const item = new Item();
+            item.id.set(entry.id);
+            return item;
+          }),
+          usedHelperInstance: user instanceof Player,
+        };
+      }
+    }
+
+    class DemoServer extends Server {
+      rooms = [DemoRoom];
+    }
+
+    const io = new ServerIo("demo");
+    await io.storage.put("state:players.public-1.items", [{ id: "potion" }]);
+
+    const server = new DemoServer(io as any);
+    await server.onStart();
+
+    const restoredPlayer = (server.subRoom as any).players()["public-1"];
+    expect(restoredPlayer).toBeInstanceOf(Player);
+    expect(restoredPlayer.items()[0]).toBeInstanceOf(Item);
+    expect(restoredPlayer.items()[0].id()).toBe("potion");
+    expect((restoredPlayer as any).usedHelperInstance).toBe(true);
+  });
+
+  it("compacts persisted delete markers when loading room storage", async () => {
+    @Room({ path: "demo" })
+    class DemoRoom {
+      @sync()
+      items = signal<Record<string, number>>({});
+    }
+
+    class DemoServer extends Server {
+      rooms = [DemoRoom];
+    }
+
+    const io = new ServerIo("demo");
+    await io.storage.put("state:items.a", "$delete");
+
+    const server = new DemoServer(io as any);
+    await server.onStart();
+
+    const storageEntries = await io.storage.list({ prefix: "state:" });
+    expect(storageEntries.get("state:items.a")).toBeUndefined();
+    expect(storageEntries.get("state:.")).toEqual({ items: {} });
+  });
+
+  it("compacts runtime deletes instead of leaving delete markers in storage", async () => {
+    @Room({ path: "demo" })
+    class DemoRoom {
+      @sync()
+      items = signal<Record<string, number>>({ a: 1, b: 2 });
+    }
+
+    class DemoServer extends Server {
+      rooms = [DemoRoom];
+    }
+
+    const io = new ServerIo("demo");
+    const server = new DemoServer(io as any);
+    await server.onStart();
+
+    delete (server.subRoom as any).items().a;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    const storageEntries = await io.storage.list({ prefix: "state:" });
+    expect(storageEntries.get("state:items.a")).toBeUndefined();
+    expect(storageEntries.get("state:.")).toEqual({ items: { b: 2 } });
+  });
+});