@sdxc/flags-engine 0.0.0-pre.1

package/dist/testing/conformance.js

@@ -0,0 +1,117 @@
+/**
+ * The suite that says what a flag store is, registered as Vitest tests against
+ * whatever the caller constructs. Every store runs it, the one an application
+ * writes against its own tables included, which is what makes them substitutes.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isSuccess, unwrap } from "@sdxc/result";
+import { describe, expect, test } from "vitest";
+import { FlagStoreError } from "../store/index.js";
+/** A set carrying every field a store round trips, so each one is asserted on. */
+const FLAG_SET = {
+    flags: {
+        "new-checkout": {
+            variants: { on: true, off: false },
+            defaultVariant: "off",
+            targeting: [{ when: { op: "segment", name: "internal" }, serve: "on" }],
+        },
+    },
+    segments: { internal: { op: "endsWith", field: "email", value: "@example.com" } },
+    version: "17",
+};
+/** A second set, so a write can be asserted to replace rather than to merge. */
+const OTHER_FLAG_SET = {
+    flags: { "welcome-banner": { variants: { on: true, off: false } } },
+    version: "18",
+};
+/** Text no store wrote, which is how a set arrives unreadable in practice. */
+const NOT_JSON = "{oops";
+/** JSON holding something other than a set, the other way a value goes wrong. */
+const NOT_AN_OBJECT = "[]";
+/**
+ * Registers the suite every flag store has to pass.
+ *
+ * @param options The store under test, and the capabilities it has beyond reading.
+ * @example conformance({ name: "worker-kv", create: () => new WorkerKVFlagStore(env.FLAGS), seed })
+ */
+export function conformance({ name, create, seed, write, writeText, }) {
+    /** The error a read answered with, asserting that it answered with one. */
+    let errorOf = (result) => {
+        if (isSuccess(result))
+            throw new Error("expected a failure, got a success");
+        return result.error;
+    };
+    describe(`${name} conformance`, () => {
+        test("reads a store holding nothing as an empty set", async () => {
+            let store = await create();
+            expect(unwrap(await store.read()).flags).toStrictEqual({});
+        });
+        test("reads back the flags and segments it holds", async () => {
+            let store = await create();
+            await seed(store, FLAG_SET);
+            let set = unwrap(await store.read());
+            expect(set.flags).toStrictEqual(FLAG_SET.flags);
+            expect(set.segments).toStrictEqual(FLAG_SET.segments);
+        });
+        test("carries the version the set was stored with", async () => {
+            let store = await create();
+            await seed(store, FLAG_SET);
+            expect(unwrap(await store.read()).version).toBe(FLAG_SET.version);
+        });
+        test("answers every read with the same set", async () => {
+            let store = await create();
+            await seed(store, FLAG_SET);
+            let first = unwrap(await store.read());
+            let second = unwrap(await store.read());
+            expect(second).toStrictEqual(first);
+        });
+        test("hands over a set the caller owns", async () => {
+            let store = await create();
+            await seed(store, FLAG_SET);
+            let read = unwrap(await store.read());
+            read.flags["injected"] = { variants: { on: true } };
+            expect(unwrap(await store.read()).flags).toStrictEqual(FLAG_SET.flags);
+        });
+        if (write !== undefined) {
+            test("reads back exactly what it wrote", async () => {
+                let store = await create();
+                await write(store, FLAG_SET);
+                expect(unwrap(await store.read())).toStrictEqual(FLAG_SET);
+            });
+            test("replaces the set it was already holding", async () => {
+                let store = await create();
+                await seed(store, FLAG_SET);
+                await write(store, OTHER_FLAG_SET);
+                expect(unwrap(await store.read())).toStrictEqual(OTHER_FLAG_SET);
+            });
+            test("reads an empty set back once it writes one", async () => {
+                let store = await create();
+                await seed(store, FLAG_SET);
+                await write(store, { flags: {} });
+                expect(unwrap(await store.read()).flags).toStrictEqual({});
+            });
+        }
+        if (writeText === undefined)
+            return;
+        test("reports a stored value that is not JSON", async () => {
+            let store = await create();
+            await writeText(store, NOT_JSON);
+            let error = errorOf(await store.read());
+            expect(error).toBeInstanceOf(FlagStoreError);
+            expect(error.code).toBe("invalid_value");
+        });
+        test("reports stored JSON that is not a set", async () => {
+            let store = await create();
+            await writeText(store, NOT_AN_OBJECT);
+            expect(errorOf(await store.read()).code).toBe("invalid_value");
+        });
+        test("reads normally again once the value is replaced", async () => {
+            let store = await create();
+            await writeText(store, NOT_JSON);
+            await seed(store, FLAG_SET);
+            expect(unwrap(await store.read()).flags).toStrictEqual(FLAG_SET.flags);
+        });
+    });
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@sdxc/flags-engine",
+	"version": "0.0.0-pre.1",
+	"description": "Flag evaluation engine: typed targeting rules, percentage splits and pluggable stores",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js",
+		"./store": "./dist/store/index.js",
+		"./store/memory": "./dist/store/memory.js",
+		"./store/worker-kv": "./dist/store/worker-kv.js",
+		"./conformance": "./dist/testing/conformance.js",
+		"./provider": "./dist/provider/index.js"
+	},
+	"dependencies": {
+		"@sdxc/duration": "2026.9.11",
+		"@sdxc/flags": "0.0.0-pre.1",
+		"@sdxc/result": "2026.9.11",
+		"@sdxc/semver": "0.0.0-pre.1",
+		"@sdxc/types": "2026.9.11",
+		"remix": "3.0.0-rc.2"
+	},
+	"peerDependencies": {
+		"vitest": "^4.0.0"
+	},
+	"peerDependenciesMeta": {
+		"vitest": {
+			"optional": true
+		}
+	},
+	"gitHead": "d56f75a79171aab3be101d8fa624d51972cd6028",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/flags-engine"
+	}
+}