@flaghoist/adapter-cloudflare-kv 0.2.1 → 0.3.0

package/README.md

@@ -41,6 +41,9 @@ than showing up as broken rows, so nothing breaks, but you pay a read for each o
 Changing the prefix on a running deployment hides the flags written under the old one. They are
 still in KV, the adapter is just no longer looking there.
 
+Webhook endpoints (if you use them) live in the same namespace, under a separate `webhook:` prefix
+by default. Change it with `{ webhookPrefix: '...' }`.
+
 Worth knowing: KV is eventually consistent. A flag you just changed can take a few seconds to reach
 every edge location, which is fine for flags and would not be fine for a bank balance.
 

package/dist/index.cjs

@@ -24,6 +24,8 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_core = require("@flaghoist/core");
+var markAs = (kind) => ({ metadata: { flaghoist: kind } });
+var isMarkedNonFlag = (metadata) => typeof metadata === "object" && metadata !== null && (metadata.flaghoist === "webhook" || metadata.flaghoist === "record");
 function safeParse(raw) {
   if (raw == null) return null;
   try {
@@ -32,8 +34,40 @@ function safeParse(raw) {
     return null;
   }
 }
+function safeParseWebhook(raw) {
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+var wrapRecord = (value) => JSON.stringify({ flaghoistRecord: 1, value });
+function unwrapRecord(raw) {
+  if (raw == null) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || parsed.flaghoistRecord !== 1) return null;
+    return parsed.value ?? null;
+  } catch {
+    return null;
+  }
+}
+async function listAll(kv, prefix) {
+  const keys = [];
+  let cursor;
+  do {
+    const page = await kv.list({ prefix, cursor });
+    keys.push(...page.keys);
+    cursor = page.list_complete ? void 0 : page.cursor;
+  } while (cursor);
+  return keys;
+}
 function cloudflareKV(kv, options = {}) {
   const prefix = options.prefix ?? "";
+  const whPrefix = options.webhookPrefix ?? "webhook:";
+  const recPrefix = options.recordPrefix ?? "record:";
+  const recordKey = (collection, id) => `${recPrefix}${collection}:${id}`;
   return {
     async get(key) {
       return safeParse(await kv.get(prefix + key, { type: "text" }));
@@ -45,20 +79,57 @@ function cloudflareKV(kv, options = {}) {
       await kv.delete(prefix + key);
     },
     async list() {
+      const keys = (await listAll(kv, prefix)).filter((k) => !isMarkedNonFlag(k.metadata));
+      const raws = await Promise.all(keys.map((k) => kv.get(k.name, { type: "text" })));
       const flags = [];
-      let cursor;
-      do {
-        const page = await kv.list({ prefix, cursor });
-        const raws = await Promise.all(
-          page.keys.map((entry) => kv.get(entry.name, { type: "text" }))
-        );
-        for (const raw of raws) {
-          const flag = safeParse(raw);
-          if (flag) flags.push(flag);
-        }
-        cursor = page.list_complete ? void 0 : page.cursor;
-      } while (cursor);
+      for (const raw of raws) {
+        const flag = safeParse(raw);
+        if (flag) flags.push(flag);
+      }
       return flags;
+    },
+    async putWebhook(id, webhook) {
+      await kv.put(whPrefix + id, JSON.stringify(webhook), markAs("webhook"));
+    },
+    async getWebhook(id) {
+      return safeParseWebhook(await kv.get(whPrefix + id, { type: "text" }));
+    },
+    async deleteWebhook(id) {
+      await kv.delete(whPrefix + id);
+    },
+    async listWebhooks() {
+      const keys = await listAll(kv, whPrefix);
+      const raws = await Promise.all(keys.map((k) => kv.get(k.name, { type: "text" })));
+      const hooks = [];
+      for (const raw of raws) {
+        const hook = safeParseWebhook(raw);
+        if (hook) hooks.push(hook);
+      }
+      return hooks;
+    },
+    async getRecord(collection, id) {
+      (0, import_core.assertRecordAddress)(collection, id);
+      return unwrapRecord(await kv.get(recordKey(collection, id), { type: "text" }));
+    },
+    async putRecord(collection, id, value) {
+      (0, import_core.assertRecordAddress)(collection, id);
+      await kv.put(recordKey(collection, id), wrapRecord(value), markAs("record"));
+    },
+    async deleteRecord(collection, id) {
+      (0, import_core.assertRecordAddress)(collection, id);
+      await kv.delete(recordKey(collection, id));
+    },
+    async listRecords(collection) {
+      (0, import_core.assertRecordAddress)(collection);
+      const keyPrefix = `${recPrefix}${collection}:`;
+      const keys = await listAll(kv, keyPrefix);
+      const raws = await Promise.all(keys.map((k) => kv.get(k.name, { type: "text" })));
+      const entries = [];
+      keys.forEach((k, i) => {
+        const value = unwrapRecord(raws[i] ?? null);
+        if (value !== null) entries.push({ id: k.name.slice(keyPrefix.length), value });
+      });
+      return entries;
     }
   };
 }

package/dist/index.d.cts

@@ -9,7 +9,9 @@ interface KVNamespaceLike {
     get(key: string, options?: {
         type?: 'text';
     }): Promise<string | null>;
-    put(key: string, value: string): Promise<void>;
+    put(key: string, value: string, options?: {
+        metadata?: unknown;
+    }): Promise<void>;
     delete(key: string): Promise<void>;
     list(options?: {
         prefix?: string;
@@ -18,6 +20,7 @@ interface KVNamespaceLike {
     }): Promise<{
         keys: Array<{
             name: string;
+            metadata?: unknown;
         }>;
         list_complete: boolean;
         cursor?: string;
@@ -36,6 +39,10 @@ interface CloudflareKVOptions {
      * @example cloudflareKV(env.FLAGS, { prefix: 'flag:' })
      */
     prefix?: string;
+    /** Key prefix for webhook entries. Default: `"webhook:"`. */
+    webhookPrefix?: string;
+    /** Key prefix for record-store entries, stored as `<prefix><collection>:<id>`. Default: `"record:"`. */
+    recordPrefix?: string;
 }
 /**
  * A StorageAdapter backed by Cloudflare Workers KV, the default Flaghoist storage backend.

package/dist/index.d.ts

@@ -9,7 +9,9 @@ interface KVNamespaceLike {
     get(key: string, options?: {
         type?: 'text';
     }): Promise<string | null>;
-    put(key: string, value: string): Promise<void>;
+    put(key: string, value: string, options?: {
+        metadata?: unknown;
+    }): Promise<void>;
     delete(key: string): Promise<void>;
     list(options?: {
         prefix?: string;
@@ -18,6 +20,7 @@ interface KVNamespaceLike {
     }): Promise<{
         keys: Array<{
             name: string;
+            metadata?: unknown;
         }>;
         list_complete: boolean;
         cursor?: string;
@@ -36,6 +39,10 @@ interface CloudflareKVOptions {
      * @example cloudflareKV(env.FLAGS, { prefix: 'flag:' })
      */
     prefix?: string;
+    /** Key prefix for webhook entries. Default: `"webhook:"`. */
+    webhookPrefix?: string;
+    /** Key prefix for record-store entries, stored as `<prefix><collection>:<id>`. Default: `"record:"`. */
+    recordPrefix?: string;
 }
 /**
  * A StorageAdapter backed by Cloudflare Workers KV, the default Flaghoist storage backend.

package/dist/index.js

@@ -1,5 +1,10 @@
 // src/index.ts
-import { parseFlag } from "@flaghoist/core";
+import {
+  assertRecordAddress,
+  parseFlag
+} from "@flaghoist/core";
+var markAs = (kind) => ({ metadata: { flaghoist: kind } });
+var isMarkedNonFlag = (metadata) => typeof metadata === "object" && metadata !== null && (metadata.flaghoist === "webhook" || metadata.flaghoist === "record");
 function safeParse(raw) {
   if (raw == null) return null;
   try {
@@ -8,8 +13,40 @@ function safeParse(raw) {
     return null;
   }
 }
+function safeParseWebhook(raw) {
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+var wrapRecord = (value) => JSON.stringify({ flaghoistRecord: 1, value });
+function unwrapRecord(raw) {
+  if (raw == null) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || parsed.flaghoistRecord !== 1) return null;
+    return parsed.value ?? null;
+  } catch {
+    return null;
+  }
+}
+async function listAll(kv, prefix) {
+  const keys = [];
+  let cursor;
+  do {
+    const page = await kv.list({ prefix, cursor });
+    keys.push(...page.keys);
+    cursor = page.list_complete ? void 0 : page.cursor;
+  } while (cursor);
+  return keys;
+}
 function cloudflareKV(kv, options = {}) {
   const prefix = options.prefix ?? "";
+  const whPrefix = options.webhookPrefix ?? "webhook:";
+  const recPrefix = options.recordPrefix ?? "record:";
+  const recordKey = (collection, id) => `${recPrefix}${collection}:${id}`;
   return {
     async get(key) {
       return safeParse(await kv.get(prefix + key, { type: "text" }));
@@ -21,20 +58,57 @@ function cloudflareKV(kv, options = {}) {
       await kv.delete(prefix + key);
     },
     async list() {
+      const keys = (await listAll(kv, prefix)).filter((k) => !isMarkedNonFlag(k.metadata));
+      const raws = await Promise.all(keys.map((k) => kv.get(k.name, { type: "text" })));
       const flags = [];
-      let cursor;
-      do {
-        const page = await kv.list({ prefix, cursor });
-        const raws = await Promise.all(
-          page.keys.map((entry) => kv.get(entry.name, { type: "text" }))
-        );
-        for (const raw of raws) {
-          const flag = safeParse(raw);
-          if (flag) flags.push(flag);
-        }
-        cursor = page.list_complete ? void 0 : page.cursor;
-      } while (cursor);
+      for (const raw of raws) {
+        const flag = safeParse(raw);
+        if (flag) flags.push(flag);
+      }
       return flags;
+    },
+    async putWebhook(id, webhook) {
+      await kv.put(whPrefix + id, JSON.stringify(webhook), markAs("webhook"));
+    },
+    async getWebhook(id) {
+      return safeParseWebhook(await kv.get(whPrefix + id, { type: "text" }));
+    },
+    async deleteWebhook(id) {
+      await kv.delete(whPrefix + id);
+    },
+    async listWebhooks() {
+      const keys = await listAll(kv, whPrefix);
+      const raws = await Promise.all(keys.map((k) => kv.get(k.name, { type: "text" })));
+      const hooks = [];
+      for (const raw of raws) {
+        const hook = safeParseWebhook(raw);
+        if (hook) hooks.push(hook);
+      }
+      return hooks;
+    },
+    async getRecord(collection, id) {
+      assertRecordAddress(collection, id);
+      return unwrapRecord(await kv.get(recordKey(collection, id), { type: "text" }));
+    },
+    async putRecord(collection, id, value) {
+      assertRecordAddress(collection, id);
+      await kv.put(recordKey(collection, id), wrapRecord(value), markAs("record"));
+    },
+    async deleteRecord(collection, id) {
+      assertRecordAddress(collection, id);
+      await kv.delete(recordKey(collection, id));
+    },
+    async listRecords(collection) {
+      assertRecordAddress(collection);
+      const keyPrefix = `${recPrefix}${collection}:`;
+      const keys = await listAll(kv, keyPrefix);
+      const raws = await Promise.all(keys.map((k) => kv.get(k.name, { type: "text" })));
+      const entries = [];
+      keys.forEach((k, i) => {
+        const value = unwrapRecord(raws[i] ?? null);
+        if (value !== null) entries.push({ id: k.name.slice(keyPrefix.length), value });
+      });
+      return entries;
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flaghoist/adapter-cloudflare-kv",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Cloudflare Workers KV StorageAdapter for Flaghoist — the default storage backend.",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@flaghoist/core": "0.1.2"
+    "@flaghoist/core": "0.2.0"
   },
   "devDependencies": {
     "@flaghoist/adapter-conformance": "0.0.0"