@flaghoist/adapter-cloudflare-kv 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,56 @@
+# @flaghoist/adapter-cloudflare-kv
+
+Store Flaghoist flags in Cloudflare Workers KV. This is the default storage for a Flaghoist deploy,
+and the one the CLI picks unless you tell it otherwise.
+
+```bash
+npm install @flaghoist/adapter-cloudflare-kv
+```
+
+```ts
+import { cloudflareKV } from '@flaghoist/adapter-cloudflare-kv'
+import { createFlagServer } from '@flaghoist/server'
+
+export default createFlagServer((env) => ({
+  storage: cloudflareKV(env.FLAGS),
+  auth: {/* ... */},
+}))
+```
+
+`FLAGS` is a KV namespace binding in your `wrangler.toml`. If you are using the CLI, `flaghoist
+deploy` creates the namespace and fills in its id for you. By hand it is:
+
+```bash
+npx wrangler kv namespace create FLAGS
+```
+
+## Sharing a namespace
+
+By default Flaghoist writes each flag under its own key, so a flag called `checkout` is stored as
+`checkout`. That keeps the namespace readable when you browse it in the Cloudflare dashboard.
+
+If the namespace holds anything besides Flaghoist's flags, give it a prefix:
+
+```ts
+cloudflareKV(env.FLAGS, { prefix: 'flag:' })
+```
+
+Without one, `list()` reads every key in the namespace. Values that are not flags are skipped rather
+than showing up as broken rows, so nothing breaks, but you pay a read for each one.
+
+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.
+
+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.
+
+Storage is an interface, so moving to Redis or Postgres later is a one line change in your server
+config.
+
+## Status
+
+Pre-alpha, built and maintained by one person. The API can still change without notice, and
+production use is not recommended yet. If you try it and something breaks, an issue is genuinely
+useful.
+
+Apache-2.0. Part of [Flaghoist](https://github.com/flaghoist/flaghoist).

package/dist/index.cjs

@@ -33,7 +33,7 @@ function safeParse(raw) {
   }
 }
 function cloudflareKV(kv, options = {}) {
-  const prefix = options.prefix ?? "flag:";
+  const prefix = options.prefix ?? "";
   return {
     async get(key) {
       return safeParse(await kv.get(prefix + key, { type: "text" }));

package/dist/index.d.cts

@@ -24,11 +24,21 @@ interface KVNamespaceLike {
     }>;
 }
 interface CloudflareKVOptions {
-    /** Key prefix used to namespace flags within the KV store. Default: `"flag:"`. */
+    /**
+     * Namespace every key Flaghoist writes, and ignore anything without it when listing.
+     *
+     * Empty by default, so a flag called `checkout` is stored under `checkout` and the namespace
+     * reads the way you expect when browsing it in the Cloudflare dashboard. Set this when the
+     * namespace holds anything besides Flaghoist's flags: without it `list()` reads every key in the
+     * namespace. Values that are not flags are skipped rather than surfacing as broken rows, but you
+     * still pay a read for each one.
+     *
+     * @example cloudflareKV(env.FLAGS, { prefix: 'flag:' })
+     */
     prefix?: string;
 }
 /**
- * A StorageAdapter backed by Cloudflare Workers KV — the default Flaghoist storage backend.
+ * A StorageAdapter backed by Cloudflare Workers KV, the default Flaghoist storage backend.
  * Flags are stored as JSON under a configurable key prefix, and every read is re-validated
  * through `parseFlag`, so tampered or corrupted data degrades to "flag ignored" rather than a
  * crash or a malformed evaluation.

package/dist/index.d.ts

@@ -24,11 +24,21 @@ interface KVNamespaceLike {
     }>;
 }
 interface CloudflareKVOptions {
-    /** Key prefix used to namespace flags within the KV store. Default: `"flag:"`. */
+    /**
+     * Namespace every key Flaghoist writes, and ignore anything without it when listing.
+     *
+     * Empty by default, so a flag called `checkout` is stored under `checkout` and the namespace
+     * reads the way you expect when browsing it in the Cloudflare dashboard. Set this when the
+     * namespace holds anything besides Flaghoist's flags: without it `list()` reads every key in the
+     * namespace. Values that are not flags are skipped rather than surfacing as broken rows, but you
+     * still pay a read for each one.
+     *
+     * @example cloudflareKV(env.FLAGS, { prefix: 'flag:' })
+     */
     prefix?: string;
 }
 /**
- * A StorageAdapter backed by Cloudflare Workers KV — the default Flaghoist storage backend.
+ * A StorageAdapter backed by Cloudflare Workers KV, the default Flaghoist storage backend.
  * Flags are stored as JSON under a configurable key prefix, and every read is re-validated
  * through `parseFlag`, so tampered or corrupted data degrades to "flag ignored" rather than a
  * crash or a malformed evaluation.

package/dist/index.js

@@ -9,7 +9,7 @@ function safeParse(raw) {
   }
 }
 function cloudflareKV(kv, options = {}) {
-  const prefix = options.prefix ?? "flag:";
+  const prefix = options.prefix ?? "";
   return {
     async get(key) {
       return safeParse(await kv.get(prefix + key, { type: "text" }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flaghoist/adapter-cloudflare-kv",
-  "version": "0.1.0",
+  "version": "0.2.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.0"
+    "@flaghoist/core": "0.1.1"
   },
   "devDependencies": {
     "@flaghoist/adapter-conformance": "0.0.0"
@@ -35,6 +35,21 @@
   "publishConfig": {
     "access": "public"
   },
+  "keywords": [
+    "feature-flags",
+    "storage",
+    "cloudflare",
+    "workers-kv"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flaghoist/flaghoist.git",
+    "directory": "packages/adapters/cloudflare-kv"
+  },
+  "homepage": "https://github.com/flaghoist/flaghoist#readme",
+  "bugs": {
+    "url": "https://github.com/flaghoist/flaghoist/issues"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "test": "vitest run --passWithNoTests",