@pluv/persistence-cloudflare-transactional-storage 0.41.7 → 0.42.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @pluv/persistence-cloudflare-transactional-storage@0.41.7 build /home/runner/work/pluv/pluv/packages/persistence-cloudflare-transactional-storage
+> @pluv/persistence-cloudflare-transactional-storage@0.42.0 build /home/runner/work/pluv/pluv/packages/persistence-cloudflare-transactional-storage
 > tsup src/index.ts --format esm,cjs --dts
 
 CLI Building entry: src/index.ts
@@ -8,11 +8,11 @@
 CLI Target: es6
 ESM Build start
 CJS Build start
-CJS dist/index.js 4.64 KB
+CJS dist/index.js 10.29 KB
 CJS ⚡️ Build success in 81ms
-ESM dist/index.mjs 3.58 KB
-ESM ⚡️ Build success in 85ms
+ESM dist/index.mjs 9.23 KB
+ESM ⚡️ Build success in 100ms
 DTS Build start
-DTS ⚡️ Build success in 2575ms
-DTS dist/index.d.mts 1.08 KB
-DTS dist/index.d.ts  1.08 KB
+DTS ⚡️ Build success in 2969ms
+DTS dist/index.d.mts 1.21 KB
+DTS dist/index.d.ts  1.21 KB

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @pluv/persistence-cloudflare-transactional-storage
 
+## 0.42.0
+
+### Minor Changes
+
+- 5c2c71d: **BREAKING** Updated the `PersistenceCloudflareTransactionalStorage` constructor so require a new property `mode` (either `kv` or `sqlite`). `sqlite` makes use of `DurableObject` SQLite storage, and `kv` makes use of their key-value storage. `platformCloudflare` now sets the underlying `PersistenceCloudflareTransactionalStorage` to use the `sqlite` mode by default (was previously using `kv`). For more information on the differences, please refer to [Cloudflare's documentation](https://developers.cloudflare.com/durable-objects/api/storage-api/#sql-api).
+
+  To continue using the `kv` mode, you will need to install `@pluv/persistence-cloudflare-transactional-storage` and provide it manually to `platformCloudflare` with your desired mode.
+
+  ```ts
+  platformCloudflare({
+    // ...
+    persistence: new PersistenceCloudflareTransactionalStorage({ mode: "kv" }),
+    // ...
+  });
+  ```
+
+- 4ce32ee: **BREAKING** `Persistence.getUsers` now returns a map of connection id strings to user JSON objects instead of an array of user JSON objects. This change is intended to be internal only and generally non-breaking.
+
+### Patch Changes
+
+- Updated dependencies [cf1529a]
+  - @pluv/io@0.42.0
+  - @pluv/types@0.42.0
+
 ## 0.41.7
 
 ### Patch Changes

package/dist/index.d.mts

@@ -2,10 +2,12 @@ import { AbstractPersistence } from '@pluv/io';
 import { JsonObject } from '@pluv/types';
 
 interface PersistenceCloudflareTransactionalStorageConfig {
-    state: DurableObjectState;
+    mode: "kv" | "sqlite";
 }
 declare class PersistenceCloudflareTransactionalStorage extends AbstractPersistence {
+    private _mode;
     private _state;
+    private _initialized;
     constructor(config: PersistenceCloudflareTransactionalStorageConfig);
     addUser(room: string, connectionId: string, user: JsonObject | null): Promise<void>;
     deleteStorageState(room: string): Promise<void>;
@@ -13,8 +15,11 @@ declare class PersistenceCloudflareTransactionalStorage extends AbstractPersiste
     deleteUsers(room: string): Promise<void>;
     getStorageState(room: string): Promise<string | null>;
     getUser(room: string, connectionId: string): Promise<JsonObject | null>;
-    getUsers(room: string): Promise<readonly (JsonObject | null)[]>;
+    getUsers(room: string): Promise<Map<[connectionId: string][0], JsonObject | null>>;
     getUsersSize(room: string): Promise<number>;
+    initialize(roomContext: {
+        state: DurableObjectState;
+    }): this;
     setStorageState(room: string, state: string): Promise<void>;
     private _getStorageKey;
     private _getUserKey;

package/dist/index.d.ts

@@ -2,10 +2,12 @@ import { AbstractPersistence } from '@pluv/io';
 import { JsonObject } from '@pluv/types';
 
 interface PersistenceCloudflareTransactionalStorageConfig {
-    state: DurableObjectState;
+    mode: "kv" | "sqlite";
 }
 declare class PersistenceCloudflareTransactionalStorage extends AbstractPersistence {
+    private _mode;
     private _state;
+    private _initialized;
     constructor(config: PersistenceCloudflareTransactionalStorageConfig);
     addUser(room: string, connectionId: string, user: JsonObject | null): Promise<void>;
     deleteStorageState(room: string): Promise<void>;
@@ -13,8 +15,11 @@ declare class PersistenceCloudflareTransactionalStorage extends AbstractPersiste
     deleteUsers(room: string): Promise<void>;
     getStorageState(room: string): Promise<string | null>;
     getUser(room: string, connectionId: string): Promise<JsonObject | null>;
-    getUsers(room: string): Promise<readonly (JsonObject | null)[]>;
+    getUsers(room: string): Promise<Map<[connectionId: string][0], JsonObject | null>>;
     getUsersSize(room: string): Promise<number>;
+    initialize(roomContext: {
+        state: DurableObjectState;
+    }): this;
     setStorageState(room: string, state: string): Promise<void>;
     private _getStorageKey;
     private _getUserKey;

package/dist/index.js

@@ -47,6 +47,11 @@ module.exports = __toCommonJS(index_exports);
 // src/PersistenceCloudflareTransactionalStorage.ts
 var import_io = require("@pluv/io");
 
+// src/utils/castNumber.ts
+var castNumber = (value) => {
+  return typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : Number(value);
+};
+
 // src/utils/partitionByLength.ts
 var partitionByLength = (arr, length) => {
   if (!arr.length) return [];
@@ -55,86 +60,275 @@ var partitionByLength = (arr, length) => {
   return [head, ...partitionByLength(tail, length)];
 };
 
+// src/utils/sql.ts
+var sql = (strings, ...values) => {
+  return strings.reduce((result, str, i) => {
+    const cleaned = str.replace(/(\n[ \t]*)+/g, " ");
+    return result + cleaned + (i < values.length ? values[i] : "");
+  }, "").trim();
+};
+
 // src/PersistenceCloudflareTransactionalStorage.ts
-var CLOUDFLARE_DELETE_BATCH_LIMIT = 128;
-var STORAGE_PREFIX = "$PLUV_STORAGE;";
-var USER_PREFIX = "$PLUV_USER";
+var KV_CLOUDFLARE_DELETE_BATCH_LIMIT = 128;
+var KV_STORAGE_PREFIX = "$PLUV_STORAGE;";
+var KV_USER_PREFIX = "$PLUV_USER";
+var SQLITE_STORAGE_TABLE = "__pluv_storage";
+var SQLITE_USER_TABLE = "__pluv_user";
 var PersistenceCloudflareTransactionalStorage = class extends import_io.AbstractPersistence {
   constructor(config) {
     super();
-    const { state } = config;
-    this._state = state;
+    this._state = null;
+    this._initialized = null;
+    const { mode } = config;
+    this._mode = mode;
   }
   addUser(room, connectionId, user) {
     return __async(this, null, function* () {
-      yield this._state.storage.put(this._getUserKey(room, connectionId), user);
+      if (!this._initialized) return;
+      if (!this._state) return;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        yield this._state.storage.put(this._getUserKey(room, connectionId), user);
+        return;
+      }
+      this._state.storage.sql.exec(
+        sql`
+                INSERT INTO ${SQLITE_USER_TABLE} VALUES (?, ?, ?);
+            `,
+        connectionId,
+        JSON.stringify(user),
+        room
+      );
     });
   }
   deleteStorageState(room) {
     return __async(this, null, function* () {
-      yield this._state.storage.delete(this._getStorageKey(room));
+      if (!this._initialized) return;
+      if (!this._state) return;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        yield this._state.storage.delete(this._getStorageKey(room));
+        return;
+      }
+      this._state.storage.sql.exec(
+        sql`
+                DELETE FROM ${SQLITE_STORAGE_TABLE}
+                WHERE room = ?;
+            `,
+        room
+      );
     });
   }
   deleteUser(room, connectionId) {
     return __async(this, null, function* () {
-      yield this._state.storage.delete(this._getUserKey(room, connectionId));
+      if (!this._initialized) return;
+      if (!this._state) return;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        yield this._state.storage.delete(this._getUserKey(room, connectionId));
+        return;
+      }
+      this._state.storage.sql.exec(
+        sql`
+                DELETE FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?
+                AND id = ?;
+            `,
+        room,
+        connectionId
+      );
     });
   }
   deleteUsers(room) {
     return __async(this, null, function* () {
-      const map = yield this._state.storage.list({
-        allowConcurrency: true,
-        noCache: true,
-        prefix: USER_PREFIX
-      });
-      const partitions = partitionByLength(Array.from(map.keys()), CLOUDFLARE_DELETE_BATCH_LIMIT);
-      yield this._state.storage.transaction((tx) => __async(this, null, function* () {
-        yield partitions.reduce((promise, partition) => __async(this, null, function* () {
-          return yield promise.then(() => __async(this, null, function* () {
+      if (!this._initialized) return;
+      if (!this._state) return;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        const map = yield this._state.storage.list({
+          allowConcurrency: true,
+          noCache: true,
+          prefix: `${KV_USER_PREFIX}::${room}`
+        });
+        const partitions = partitionByLength(Array.from(map.keys()), KV_CLOUDFLARE_DELETE_BATCH_LIMIT);
+        yield this._state.storage.transaction((tx) => __async(this, null, function* () {
+          yield partitions.reduce((promise, partition) => __async(this, null, function* () {
+            yield promise;
             yield tx.delete(partition);
-          }));
-        }), Promise.resolve());
-      }));
+          }), Promise.resolve());
+        }));
+        return;
+      }
+      this._state.storage.sql.exec(
+        sql`
+                DELETE FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?;
+            `,
+        room
+      );
     });
   }
   getStorageState(room) {
     return __async(this, null, function* () {
-      const storage = yield this._state.storage.get(this._getStorageKey(room));
-      return storage != null ? storage : null;
+      if (!this._initialized) return null;
+      if (!this._state) return null;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        const storage = yield this._state.storage.get(this._getStorageKey(room));
+        return storage != null ? storage : null;
+      }
+      const cursor = this._state.storage.sql.exec(
+        sql`
+                SELECT room, data
+                FROM ${SQLITE_STORAGE_TABLE}
+                WHERE room = ?;
+            `,
+        room
+      );
+      try {
+        const result = cursor.one();
+        return result.data;
+      } catch (e) {
+        return null;
+      }
     });
   }
   getUser(room, connectionId) {
     return __async(this, null, function* () {
-      const user = yield this._state.storage.get(this._getUserKey(room, connectionId));
-      return user != null ? user : null;
+      if (!this._initialized) return null;
+      if (!this._state) return null;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        const user = yield this._state.storage.get(this._getUserKey(room, connectionId));
+        return user != null ? user : null;
+      }
+      const cursor = this._state.storage.sql.exec(
+        sql`
+                SELECT id, data, room
+                FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?
+                AND id = ?;
+            `,
+        room,
+        connectionId
+      );
+      try {
+        const result = cursor.one();
+        const user = JSON.parse(result.data);
+        return user;
+      } catch (e) {
+        return null;
+      }
     });
   }
   getUsers(room) {
     return __async(this, null, function* () {
-      const storage = yield this._state.storage.list({
-        prefix: USER_PREFIX
-      });
-      return Array.from(storage.values());
+      if (!this._initialized) return /* @__PURE__ */ new Map();
+      if (!this._state) return /* @__PURE__ */ new Map();
+      yield this._initialized;
+      if (this._mode === "kv") {
+        const entries = yield this._state.storage.list({
+          prefix: `${KV_USER_PREFIX}::${room}`
+        }).then((map) => Array.from(map.entries()));
+        return entries.reduce((map, [key, user]) => {
+          const connectionId = key.split("::").slice(-1)[0];
+          return !!connectionId ? map.set(connectionId, user) : map;
+        }, /* @__PURE__ */ new Map());
+      }
+      const cursor = this._state.storage.sql.exec(
+        sql`
+                SELECT id, room, data
+                FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?;
+            `,
+        room
+      );
+      return cursor.toArray().reduce((map, { id, data }) => {
+        try {
+          const user = JSON.parse(data);
+          return map.set(id, user);
+        } catch (e) {
+          return map;
+        }
+      }, /* @__PURE__ */ new Map());
     });
   }
   getUsersSize(room) {
     return __async(this, null, function* () {
-      const storage = yield this._state.storage.list({ prefix: USER_PREFIX });
-      return storage.size;
+      if (!this._initialized) return 0;
+      if (!this._state) return 0;
+      yield this._initialized;
+      if (this._mode) {
+        const storage = yield this._state.storage.list({ prefix: `${KV_USER_PREFIX}::${room}` });
+        return storage.size;
+      }
+      const cursor = this._state.storage.sql.exec(
+        sql`
+                SELECT COUNT(*) count
+                FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?;
+            `,
+        room
+      );
+      try {
+        const result = cursor.one();
+        return castNumber(result.count);
+      } catch (e) {
+        return 0;
+      }
     });
   }
+  initialize(roomContext) {
+    this._initialized = (() => __async(this, null, function* () {
+      const { state } = roomContext;
+      this._state = state;
+      if (this._mode === "sqlite") {
+        this._state.storage.sql.exec(sql`
+                    CREATE TABLE IF NOT EXISTS ${SQLITE_STORAGE_TABLE}(
+                        room TEXT PRIMARY KEY,
+                        data TEXT NOT NULL
+                    );
+                    CREATE TABLE IF NOT EXISTS ${SQLITE_USER_TABLE}(
+                        id   TEXT PRIMARY KEY,
+                        data TEXT NOT NULL,
+                        room TEXT NOT NULL
+                    );
+                    CREATE INDEX IF NOT EXISTS ${SQLITE_USER_TABLE}_room ON ${SQLITE_USER_TABLE}(room);
+                `);
+      }
+      return true;
+    }))();
+    return this;
+  }
   setStorageState(room, state) {
     return __async(this, null, function* () {
-      yield this._state.storage.put(this._getStorageKey(room), state, {
-        allowConcurrency: true
-      });
+      if (!this._initialized) return;
+      if (!this._state) return;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        yield this._state.storage.put(this._getStorageKey(room), state, { allowConcurrency: true });
+        return;
+      }
+      this._state.storage.sql.exec(
+        sql`
+                INSERT INTO ${SQLITE_STORAGE_TABLE} VALUES (?, ?);
+            `,
+        room,
+        state
+      );
     });
   }
   _getStorageKey(room) {
-    return `${STORAGE_PREFIX}::${room}`;
+    if (this._mode === "sqlite") {
+      throw new Error("Attempted to get kv key for sqlite storage");
+    }
+    return `${KV_STORAGE_PREFIX}::${room}`;
   }
   _getUserKey(room, connectionId) {
-    return `${USER_PREFIX}::${room}::${connectionId}`;
+    if (this._mode === "sqlite") {
+      throw new Error("Attempted to get kv key for sqlite storage");
+    }
+    return `${KV_USER_PREFIX}::${room}::${connectionId}`;
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -22,6 +22,11 @@ var __async = (__this, __arguments, generator) => {
 // src/PersistenceCloudflareTransactionalStorage.ts
 import { AbstractPersistence } from "@pluv/io";
 
+// src/utils/castNumber.ts
+var castNumber = (value) => {
+  return typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : Number(value);
+};
+
 // src/utils/partitionByLength.ts
 var partitionByLength = (arr, length) => {
   if (!arr.length) return [];
@@ -30,86 +35,275 @@ var partitionByLength = (arr, length) => {
   return [head, ...partitionByLength(tail, length)];
 };
 
+// src/utils/sql.ts
+var sql = (strings, ...values) => {
+  return strings.reduce((result, str, i) => {
+    const cleaned = str.replace(/(\n[ \t]*)+/g, " ");
+    return result + cleaned + (i < values.length ? values[i] : "");
+  }, "").trim();
+};
+
 // src/PersistenceCloudflareTransactionalStorage.ts
-var CLOUDFLARE_DELETE_BATCH_LIMIT = 128;
-var STORAGE_PREFIX = "$PLUV_STORAGE;";
-var USER_PREFIX = "$PLUV_USER";
+var KV_CLOUDFLARE_DELETE_BATCH_LIMIT = 128;
+var KV_STORAGE_PREFIX = "$PLUV_STORAGE;";
+var KV_USER_PREFIX = "$PLUV_USER";
+var SQLITE_STORAGE_TABLE = "__pluv_storage";
+var SQLITE_USER_TABLE = "__pluv_user";
 var PersistenceCloudflareTransactionalStorage = class extends AbstractPersistence {
   constructor(config) {
     super();
-    const { state } = config;
-    this._state = state;
+    this._state = null;
+    this._initialized = null;
+    const { mode } = config;
+    this._mode = mode;
   }
   addUser(room, connectionId, user) {
     return __async(this, null, function* () {
-      yield this._state.storage.put(this._getUserKey(room, connectionId), user);
+      if (!this._initialized) return;
+      if (!this._state) return;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        yield this._state.storage.put(this._getUserKey(room, connectionId), user);
+        return;
+      }
+      this._state.storage.sql.exec(
+        sql`
+                INSERT INTO ${SQLITE_USER_TABLE} VALUES (?, ?, ?);
+            `,
+        connectionId,
+        JSON.stringify(user),
+        room
+      );
     });
   }
   deleteStorageState(room) {
     return __async(this, null, function* () {
-      yield this._state.storage.delete(this._getStorageKey(room));
+      if (!this._initialized) return;
+      if (!this._state) return;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        yield this._state.storage.delete(this._getStorageKey(room));
+        return;
+      }
+      this._state.storage.sql.exec(
+        sql`
+                DELETE FROM ${SQLITE_STORAGE_TABLE}
+                WHERE room = ?;
+            `,
+        room
+      );
     });
   }
   deleteUser(room, connectionId) {
     return __async(this, null, function* () {
-      yield this._state.storage.delete(this._getUserKey(room, connectionId));
+      if (!this._initialized) return;
+      if (!this._state) return;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        yield this._state.storage.delete(this._getUserKey(room, connectionId));
+        return;
+      }
+      this._state.storage.sql.exec(
+        sql`
+                DELETE FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?
+                AND id = ?;
+            `,
+        room,
+        connectionId
+      );
     });
   }
   deleteUsers(room) {
     return __async(this, null, function* () {
-      const map = yield this._state.storage.list({
-        allowConcurrency: true,
-        noCache: true,
-        prefix: USER_PREFIX
-      });
-      const partitions = partitionByLength(Array.from(map.keys()), CLOUDFLARE_DELETE_BATCH_LIMIT);
-      yield this._state.storage.transaction((tx) => __async(this, null, function* () {
-        yield partitions.reduce((promise, partition) => __async(this, null, function* () {
-          return yield promise.then(() => __async(this, null, function* () {
+      if (!this._initialized) return;
+      if (!this._state) return;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        const map = yield this._state.storage.list({
+          allowConcurrency: true,
+          noCache: true,
+          prefix: `${KV_USER_PREFIX}::${room}`
+        });
+        const partitions = partitionByLength(Array.from(map.keys()), KV_CLOUDFLARE_DELETE_BATCH_LIMIT);
+        yield this._state.storage.transaction((tx) => __async(this, null, function* () {
+          yield partitions.reduce((promise, partition) => __async(this, null, function* () {
+            yield promise;
             yield tx.delete(partition);
-          }));
-        }), Promise.resolve());
-      }));
+          }), Promise.resolve());
+        }));
+        return;
+      }
+      this._state.storage.sql.exec(
+        sql`
+                DELETE FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?;
+            `,
+        room
+      );
     });
   }
   getStorageState(room) {
     return __async(this, null, function* () {
-      const storage = yield this._state.storage.get(this._getStorageKey(room));
-      return storage != null ? storage : null;
+      if (!this._initialized) return null;
+      if (!this._state) return null;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        const storage = yield this._state.storage.get(this._getStorageKey(room));
+        return storage != null ? storage : null;
+      }
+      const cursor = this._state.storage.sql.exec(
+        sql`
+                SELECT room, data
+                FROM ${SQLITE_STORAGE_TABLE}
+                WHERE room = ?;
+            `,
+        room
+      );
+      try {
+        const result = cursor.one();
+        return result.data;
+      } catch (e) {
+        return null;
+      }
     });
   }
   getUser(room, connectionId) {
     return __async(this, null, function* () {
-      const user = yield this._state.storage.get(this._getUserKey(room, connectionId));
-      return user != null ? user : null;
+      if (!this._initialized) return null;
+      if (!this._state) return null;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        const user = yield this._state.storage.get(this._getUserKey(room, connectionId));
+        return user != null ? user : null;
+      }
+      const cursor = this._state.storage.sql.exec(
+        sql`
+                SELECT id, data, room
+                FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?
+                AND id = ?;
+            `,
+        room,
+        connectionId
+      );
+      try {
+        const result = cursor.one();
+        const user = JSON.parse(result.data);
+        return user;
+      } catch (e) {
+        return null;
+      }
     });
   }
   getUsers(room) {
     return __async(this, null, function* () {
-      const storage = yield this._state.storage.list({
-        prefix: USER_PREFIX
-      });
-      return Array.from(storage.values());
+      if (!this._initialized) return /* @__PURE__ */ new Map();
+      if (!this._state) return /* @__PURE__ */ new Map();
+      yield this._initialized;
+      if (this._mode === "kv") {
+        const entries = yield this._state.storage.list({
+          prefix: `${KV_USER_PREFIX}::${room}`
+        }).then((map) => Array.from(map.entries()));
+        return entries.reduce((map, [key, user]) => {
+          const connectionId = key.split("::").slice(-1)[0];
+          return !!connectionId ? map.set(connectionId, user) : map;
+        }, /* @__PURE__ */ new Map());
+      }
+      const cursor = this._state.storage.sql.exec(
+        sql`
+                SELECT id, room, data
+                FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?;
+            `,
+        room
+      );
+      return cursor.toArray().reduce((map, { id, data }) => {
+        try {
+          const user = JSON.parse(data);
+          return map.set(id, user);
+        } catch (e) {
+          return map;
+        }
+      }, /* @__PURE__ */ new Map());
     });
   }
   getUsersSize(room) {
     return __async(this, null, function* () {
-      const storage = yield this._state.storage.list({ prefix: USER_PREFIX });
-      return storage.size;
+      if (!this._initialized) return 0;
+      if (!this._state) return 0;
+      yield this._initialized;
+      if (this._mode) {
+        const storage = yield this._state.storage.list({ prefix: `${KV_USER_PREFIX}::${room}` });
+        return storage.size;
+      }
+      const cursor = this._state.storage.sql.exec(
+        sql`
+                SELECT COUNT(*) count
+                FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?;
+            `,
+        room
+      );
+      try {
+        const result = cursor.one();
+        return castNumber(result.count);
+      } catch (e) {
+        return 0;
+      }
     });
   }
+  initialize(roomContext) {
+    this._initialized = (() => __async(this, null, function* () {
+      const { state } = roomContext;
+      this._state = state;
+      if (this._mode === "sqlite") {
+        this._state.storage.sql.exec(sql`
+                    CREATE TABLE IF NOT EXISTS ${SQLITE_STORAGE_TABLE}(
+                        room TEXT PRIMARY KEY,
+                        data TEXT NOT NULL
+                    );
+                    CREATE TABLE IF NOT EXISTS ${SQLITE_USER_TABLE}(
+                        id   TEXT PRIMARY KEY,
+                        data TEXT NOT NULL,
+                        room TEXT NOT NULL
+                    );
+                    CREATE INDEX IF NOT EXISTS ${SQLITE_USER_TABLE}_room ON ${SQLITE_USER_TABLE}(room);
+                `);
+      }
+      return true;
+    }))();
+    return this;
+  }
   setStorageState(room, state) {
     return __async(this, null, function* () {
-      yield this._state.storage.put(this._getStorageKey(room), state, {
-        allowConcurrency: true
-      });
+      if (!this._initialized) return;
+      if (!this._state) return;
+      yield this._initialized;
+      if (this._mode === "kv") {
+        yield this._state.storage.put(this._getStorageKey(room), state, { allowConcurrency: true });
+        return;
+      }
+      this._state.storage.sql.exec(
+        sql`
+                INSERT INTO ${SQLITE_STORAGE_TABLE} VALUES (?, ?);
+            `,
+        room,
+        state
+      );
     });
   }
   _getStorageKey(room) {
-    return `${STORAGE_PREFIX}::${room}`;
+    if (this._mode === "sqlite") {
+      throw new Error("Attempted to get kv key for sqlite storage");
+    }
+    return `${KV_STORAGE_PREFIX}::${room}`;
   }
   _getUserKey(room, connectionId) {
-    return `${USER_PREFIX}::${room}::${connectionId}`;
+    if (this._mode === "sqlite") {
+      throw new Error("Attempted to get kv key for sqlite storage");
+    }
+    return `${KV_USER_PREFIX}::${room}::${connectionId}`;
   }
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pluv/persistence-cloudflare-transactional-storage",
-  "version": "0.41.7",
+  "version": "0.42.0",
   "description": "@pluv/io crdt storage persistence for cloudflare via transactional storage",
   "author": "leedavidcs",
   "license": "MIT",
@@ -17,16 +17,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@pluv/io": "^0.41.7",
-    "@pluv/types": "^0.41.7"
+    "@pluv/io": "^0.42.0",
+    "@pluv/types": "^0.42.0"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20250418.0",
-    "eslint": "^9.25.0",
+    "@cloudflare/workers-types": "^4.20250427.0",
+    "eslint": "^9.25.1",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
-    "@pluv/tsconfig": "^0.41.7",
-    "eslint-config-pluv": "^0.41.7"
+    "@pluv/tsconfig": "^0.42.0",
+    "eslint-config-pluv": "^0.42.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",

package/src/PersistenceCloudflareTransactionalStorage.ts

@@ -1,6 +1,6 @@
 import { AbstractPersistence } from "@pluv/io";
 import type { JsonObject } from "@pluv/types";
-import { partitionByLength } from "./utils";
+import { castNumber, partitionByLength, sql } from "./utils";
 
 /**
  * !HACK
@@ -8,92 +8,319 @@ import { partitionByLength } from "./utils";
  * @see https://developers.cloudflare.com/durable-objects/api/transactional-storage-api/#delete
  * @date July 8, 2024
  */
-const CLOUDFLARE_DELETE_BATCH_LIMIT = 128;
-const STORAGE_PREFIX = "$PLUV_STORAGE;";
-const USER_PREFIX = "$PLUV_USER";
+const KV_CLOUDFLARE_DELETE_BATCH_LIMIT = 128;
+const KV_STORAGE_PREFIX = "$PLUV_STORAGE;";
+const KV_USER_PREFIX = "$PLUV_USER";
+
+const SQLITE_STORAGE_TABLE = "__pluv_storage";
+const SQLITE_USER_TABLE = "__pluv_user";
 
 export interface PersistenceCloudflareTransactionalStorageConfig {
-    state: DurableObjectState;
+    mode: "kv" | "sqlite";
 }
-
 export class PersistenceCloudflareTransactionalStorage extends AbstractPersistence {
-    private _state: DurableObjectState;
+    private _mode: "kv" | "sqlite";
+    private _state: DurableObjectState | null = null;
+    private _initialized: Promise<true> | null = null;
 
     constructor(config: PersistenceCloudflareTransactionalStorageConfig) {
         super();
 
-        const { state } = config;
+        const { mode } = config;
 
-        this._state = state;
+        this._mode = mode;
     }
 
     public async addUser(room: string, connectionId: string, user: JsonObject | null): Promise<void> {
-        await this._state.storage.put(this._getUserKey(room, connectionId), user);
+        if (!this._initialized) return;
+        if (!this._state) return;
+
+        await this._initialized;
+
+        if (this._mode === "kv") {
+            await this._state.storage.put(this._getUserKey(room, connectionId), user);
+            return;
+        }
+
+        this._state.storage.sql.exec(
+            sql`
+                INSERT INTO ${SQLITE_USER_TABLE} VALUES (?, ?, ?);
+            `,
+            connectionId,
+            JSON.stringify(user),
+            room,
+        );
     }
 
     public async deleteStorageState(room: string): Promise<void> {
-        await this._state.storage.delete(this._getStorageKey(room));
+        if (!this._initialized) return;
+        if (!this._state) return;
+
+        await this._initialized;
+
+        if (this._mode === "kv") {
+            await this._state.storage.delete(this._getStorageKey(room));
+            return;
+        }
+
+        this._state.storage.sql.exec(
+            sql`
+                DELETE FROM ${SQLITE_STORAGE_TABLE}
+                WHERE room = ?;
+            `,
+            room,
+        );
     }
 
     public async deleteUser(room: string, connectionId: string): Promise<void> {
-        await this._state.storage.delete(this._getUserKey(room, connectionId));
+        if (!this._initialized) return;
+        if (!this._state) return;
+
+        await this._initialized;
+
+        if (this._mode === "kv") {
+            await this._state.storage.delete(this._getUserKey(room, connectionId));
+
+            return;
+        }
+
+        this._state.storage.sql.exec(
+            sql`
+                DELETE FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?
+                AND id = ?;
+            `,
+            room,
+            connectionId,
+        );
     }
 
     public async deleteUsers(room: string): Promise<void> {
-        const map = await this._state.storage.list({
-            allowConcurrency: true,
-            noCache: true,
-            prefix: USER_PREFIX,
-        });
+        if (!this._initialized) return;
+        if (!this._state) return;
 
-        const partitions = partitionByLength(Array.from(map.keys()), CLOUDFLARE_DELETE_BATCH_LIMIT);
+        await this._initialized;
 
-        await this._state.storage.transaction(async (tx) => {
-            await partitions.reduce(async (promise, partition) => {
-                return await promise.then(async () => {
+        if (this._mode === "kv") {
+            const map = await this._state.storage.list({
+                allowConcurrency: true,
+                noCache: true,
+                prefix: `${KV_USER_PREFIX}::${room}`,
+            });
+
+            const partitions = partitionByLength(Array.from(map.keys()), KV_CLOUDFLARE_DELETE_BATCH_LIMIT);
+
+            await this._state.storage.transaction(async (tx) => {
+                await partitions.reduce(async (promise, partition) => {
+                    await promise;
                     await tx.delete(partition as string[]);
-                });
-            }, Promise.resolve());
-        });
+                }, Promise.resolve());
+            });
+
+            return;
+        }
+
+        this._state.storage.sql.exec(
+            sql`
+                DELETE FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?;
+            `,
+            room,
+        );
     }
 
     public async getStorageState(room: string): Promise<string | null> {
-        const storage = await this._state.storage.get<string>(this._getStorageKey(room));
+        if (!this._initialized) return null;
+        if (!this._state) return null;
+
+        await this._initialized;
+
+        if (this._mode === "kv") {
+            const storage = await this._state.storage.get<string>(this._getStorageKey(room));
+            return storage ?? null;
+        }
 
-        return storage ?? null;
+        const cursor = this._state.storage.sql.exec<{ room: string; data: string }>(
+            sql`
+                SELECT room, data
+                FROM ${SQLITE_STORAGE_TABLE}
+                WHERE room = ?;
+            `,
+            room,
+        );
+
+        try {
+            const result = cursor.one();
+
+            return result.data;
+        } catch {
+            return null;
+        }
     }
 
     public async getUser(room: string, connectionId: string): Promise<JsonObject | null> {
-        const user = await this._state.storage.get<JsonObject | null>(this._getUserKey(room, connectionId));
+        if (!this._initialized) return null;
+        if (!this._state) return null;
+
+        await this._initialized;
+
+        if (this._mode === "kv") {
+            const user = await this._state.storage.get<JsonObject | null>(this._getUserKey(room, connectionId));
+
+            return user ?? null;
+        }
+
+        const cursor = this._state.storage.sql.exec<{ id: string; data: string; room: string }>(
+            sql`
+                SELECT id, data, room
+                FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?
+                AND id = ?;
+            `,
+            room,
+            connectionId,
+        );
 
-        return user ?? null;
+        try {
+            const result = cursor.one();
+            const user = JSON.parse(result.data);
+
+            return user;
+        } catch {
+            return null;
+        }
     }
 
-    public async getUsers(room: string): Promise<readonly (JsonObject | null)[]> {
-        const storage = await this._state.storage.list({
-            prefix: USER_PREFIX,
-        });
+    public async getUsers(room: string): Promise<Map<[connectionId: string][0], JsonObject | null>> {
+        if (!this._initialized) return new Map();
+        if (!this._state) return new Map();
+
+        await this._initialized;
+
+        if (this._mode === "kv") {
+            const entries = await this._state.storage
+                .list<JsonObject | null>({
+                    prefix: `${KV_USER_PREFIX}::${room}`,
+                })
+                .then((map) => Array.from(map.entries()));
+
+            return entries.reduce((map, [key, user]) => {
+                const connectionId = key.split("::").slice(-1)[0];
+
+                return !!connectionId ? map.set(connectionId, user) : map;
+            }, new Map<string, JsonObject | null>());
+        }
+
+        const cursor = this._state.storage.sql.exec<{ id: string; data: string; room: string }>(
+            sql`
+                SELECT id, room, data
+                FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?;
+            `,
+            room,
+        );
 
-        return Array.from(storage.values()) as (JsonObject | null)[];
+        return cursor.toArray().reduce((map, { id, data }) => {
+            try {
+                const user = JSON.parse(data) as JsonObject;
+
+                return map.set(id, user);
+            } catch {
+                return map;
+            }
+        }, new Map<string, JsonObject | null>());
     }
 
     public async getUsersSize(room: string): Promise<number> {
-        const storage = await this._state.storage.list({ prefix: USER_PREFIX });
+        if (!this._initialized) return 0;
+        if (!this._state) return 0;
+
+        await this._initialized;
+
+        if (this._mode) {
+            const storage = await this._state.storage.list({ prefix: `${KV_USER_PREFIX}::${room}` });
+
+            return storage.size;
+        }
+
+        const cursor = this._state.storage.sql.exec<{ count: number }>(
+            sql`
+                SELECT COUNT(*) count
+                FROM ${SQLITE_USER_TABLE}
+                WHERE room = ?;
+            `,
+            room,
+        );
+
+        try {
+            const result = cursor.one();
 
-        return storage.size;
+            return castNumber(result.count);
+        } catch {
+            return 0;
+        }
+    }
+
+    public initialize(roomContext: { state: DurableObjectState }): this {
+        this._initialized = (async () => {
+            const { state } = roomContext;
+
+            this._state = state;
+
+            if (this._mode === "sqlite") {
+                this._state.storage.sql.exec(sql`
+                    CREATE TABLE IF NOT EXISTS ${SQLITE_STORAGE_TABLE}(
+                        room TEXT PRIMARY KEY,
+                        data TEXT NOT NULL
+                    );
+                    CREATE TABLE IF NOT EXISTS ${SQLITE_USER_TABLE}(
+                        id   TEXT PRIMARY KEY,
+                        data TEXT NOT NULL,
+                        room TEXT NOT NULL
+                    );
+                    CREATE INDEX IF NOT EXISTS ${SQLITE_USER_TABLE}_room ON ${SQLITE_USER_TABLE}(room);
+                `);
+            }
+
+            return true as const;
+        })();
+
+        return this;
     }
 
     public async setStorageState(room: string, state: string): Promise<void> {
-        await this._state.storage.put(this._getStorageKey(room), state, {
-            allowConcurrency: true,
-        });
+        if (!this._initialized) return;
+        if (!this._state) return;
+
+        await this._initialized;
+
+        if (this._mode === "kv") {
+            await this._state.storage.put(this._getStorageKey(room), state, { allowConcurrency: true });
+            return;
+        }
+
+        this._state.storage.sql.exec(
+            sql`
+                INSERT INTO ${SQLITE_STORAGE_TABLE} VALUES (?, ?);
+            `,
+            room,
+            state,
+        );
     }
 
     private _getStorageKey(room: string): string {
-        return `${STORAGE_PREFIX}::${room}`;
+        if (this._mode === "sqlite") {
+            throw new Error("Attempted to get kv key for sqlite storage");
+        }
+
+        return `${KV_STORAGE_PREFIX}::${room}`;
     }
 
     private _getUserKey(room: string, connectionId: string): string {
-        return `${USER_PREFIX}::${room}::${connectionId}`;
+        if (this._mode === "sqlite") {
+            throw new Error("Attempted to get kv key for sqlite storage");
+        }
+
+        return `${KV_USER_PREFIX}::${room}::${connectionId}`;
     }
 }

package/src/utils/castNumber.ts

@@ -0,0 +1,3 @@
+export const castNumber = (value: any): number => {
+    return typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : Number(value);
+};

package/src/utils/index.ts

@@ -1 +1,3 @@
+export { castNumber } from "./castNumber";
 export { partitionByLength } from "./partitionByLength";
+export { sql } from "./sql";

package/src/utils/sql.ts

@@ -0,0 +1,10 @@
+export const sql = (strings: TemplateStringsArray, ...values: any[]): string => {
+    return strings
+        .reduce((result, str, i) => {
+            // Compresses the string to a single line (not including the interpolated values)
+            const cleaned = str.replace(/(\n[ \t]*)+/g, " ");
+
+            return result + cleaned + (i < values.length ? values[i] : "");
+        }, "")
+        .trim();
+};