@lacspace/flags 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data files
+(the "Software"), to deal in the Software without restriction, including without
+limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,107 @@
+<div align="center">
+
+# @lacspace/flags
+
+**Feature flags & A/B experiments with no SaaS and no infrastructure — deterministic, synchronous, zero-dependency.**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/flags?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/flags)
+[![install size](https://packagephobia.com/badge?p=@lacspace/flags)](https://packagephobia.com/result?p=@lacspace/flags)
+[![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/flags?label=minzip)](https://bundlephobia.com/package/@lacspace/flags)
+[![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/flags)
+[![license](https://img.shields.io/npm/l/@lacspace/flags?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> Feature flagging is dominated by hosted vendors (LaunchDarkly, Optimizely, Unleash). But you don't always want a SaaS, a network call, or a monthly bill. **You** own the config — a plain object from JSON, env or a DB row — and this evaluates it: stable rollouts, targeting and A/B tests, synchronously, offline.
+
+- 🎯 **Deterministic** — the same user always gets the same result (no flicker, no round-trip, works offline)
+- 📊 Percentage rollouts + **weighted A/B / multivariate experiments**
+- 🧩 Targeting rules on attributes — `eq` / `in` / `gt` / `contains` / `regex` …
+- ⚡ **Synchronous** (evaluate right in render) · zero dependencies · isomorphic
+
+## Install
+
+```bash
+npm install @lacspace/flags      # or pnpm add / yarn add / bun add
+```
+
+## Define once, evaluate anywhere
+
+```ts
+import { Flags } from "@lacspace/flags";
+
+// Config — load from JSON / env / DB, hot-swap with flags.update(...)
+export const flags = new Flags({
+  "new-dashboard": { rollout: 25 },                              // 25% of users
+  "beta": { rules: [{ when: { plan: "pro" }, value: true }] },   // pro users only
+  "eu-feature": { rules: [{ when: { country: { in: ["DE", "FR"] } }, value: true }] },
+  "checkout-exp": {                                              // A/B test
+    type: "variant",
+    variants: [{ key: "control", weight: 1 }, { key: "one-click", weight: 1 }],
+  },
+});
+
+// Evaluate — synchronous, stable per user
+flags.isEnabled("new-dashboard", { key: user.id });                       // boolean
+flags.isEnabled("beta", { key: user.id, attributes: { plan: user.plan } });
+flags.variant("checkout-exp", { key: user.id });                          // "control" | "one-click"
+```
+
+The same `key` always buckets the same way — a user in the 25% rollout stays in it across reloads and devices, and always sees the same experiment variant.
+
+## Targeting rules
+
+```ts
+new Flags({
+  "premium-banner": {
+    rollout: 0,                         // off for everyone by default…
+    rules: [
+      { when: { plan: "pro" }, value: true },                 // …except pro users
+      { when: { signupDays: { gte: 30 } }, rollout: 50 },     // …and 50% of 30-day-olds
+      { when: { email: { regex: "@lacspace\\.com$" } }, value: true }, // …and staff
+    ],
+  },
+});
+```
+
+Operators: `eq`, `ne`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `contains`, `regex` (a bare value means equality). Rules are evaluated top-to-bottom; the first match wins.
+
+## Bootstrap a client (no flicker)
+
+```ts
+// server: evaluate everything once, ship it with the page
+const initial = flags.all({ key: user.id, attributes });
+// → { "new-dashboard": true, "beta": false, "checkout-exp": "one-click", … }
+```
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `new Flags(config)` | build a flag set from a config object |
+| `.isEnabled(key, ctx)` | boolean flag → `boolean` |
+| `.variant(key, ctx)` | variant flag → variant key |
+| `.evaluate(key, ctx)` · `.all(ctx)` | generic / evaluate-all |
+| `.update(config)` · `.set(key, def)` | hot-reload config |
+| `isEnabled(key, def, ctx)` · `variant(key, def, ctx)` | functional (no store) |
+| `bucket(key)` · `percentage(flag, ctx)` | inspect the deterministic bucketing |
+
+Context is `{ key, attributes? }`. `key` drives bucketing; `attributes` drive targeting. Set a flag's `seed` to re-shuffle everyone. No rules → `rollout` defaults to 100%; with rules, unmatched users default to off unless you set an explicit `rollout`.
+
+## Licensing
+
+This package is **free** under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — MIT-equivalent freedoms. Use it in personal and commercial projects at no cost; just keep the notice.
+
+Not every Lacspace package is free. We also offer **Commercial** (paid), **Client-specific**, and **Private** (proprietary) packages under separate terms. See the full **[Lacspace Licence Centre](https://lacspace.com/licenses)**.
+
+---
+
+<div align="center">
+
+**Part of the Lacspace ecosystem — zero-dependency, isomorphic TypeScript packages.**
+
+[All packages ↗](https://lacspace.com/packages) · [npm org ↗](https://www.npmjs.com/org/lacspace) · [Licence Centre ↗](https://lacspace.com/licenses) · [GitHub ↗](https://github.com/lacspace/npm-packages)
+
+</div>
+
+<div align="center"><sub>Built with care by <a href="https://lacspace.com">Lacspace</a> · Lacspace Free Licence · <a href="https://github.com/lacspace/npm-packages">source</a></sub></div>

package/dist/index.cjs

@@ -0,0 +1,146 @@
+'use strict';
+
+// src/index.ts
+function fnv1a(str) {
+  let h = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+  }
+  return h >>> 0;
+}
+function bucket(key) {
+  return fnv1a(key) % 1e5 / 1e5;
+}
+function percentage(flag, ctx, seed = "") {
+  return Math.floor(bucket(`${flag}:${seed}:${ctx.key}`) * 100);
+}
+function matchOperator(actual, op) {
+  if ("eq" in op && actual !== op.eq) return false;
+  if ("ne" in op && actual === op.ne) return false;
+  if (op.in && !op.in.includes(actual)) return false;
+  if (op.nin && op.nin.includes(actual)) return false;
+  if (typeof op.gt === "number" && !(typeof actual === "number" && actual > op.gt)) return false;
+  if (typeof op.gte === "number" && !(typeof actual === "number" && actual >= op.gte)) return false;
+  if (typeof op.lt === "number" && !(typeof actual === "number" && actual < op.lt)) return false;
+  if (typeof op.lte === "number" && !(typeof actual === "number" && actual <= op.lte)) return false;
+  if (typeof op.contains === "string" && !(typeof actual === "string" && actual.includes(op.contains))) return false;
+  if (typeof op.regex === "string" && !(typeof actual === "string" && new RegExp(op.regex).test(actual))) return false;
+  return true;
+}
+function matchCondition(attrs, cond) {
+  for (const [field, expected] of Object.entries(cond)) {
+    const actual = attrs[field];
+    if (expected !== null && typeof expected === "object" && !Array.isArray(expected)) {
+      if (!matchOperator(actual, expected)) return false;
+    } else if (actual !== expected) {
+      return false;
+    }
+  }
+  return true;
+}
+function inRollout(flagKey, seed, ctx, rollout, salt = "") {
+  if (rollout >= 100) return true;
+  if (rollout <= 0) return false;
+  return bucket(`${flagKey}:${seed}:${salt}:${ctx.key}`) * 100 < rollout;
+}
+function pickVariant(flagKey, seed, ctx, variants) {
+  const total = variants.reduce((s, v) => s + (v.weight ?? 1), 0);
+  if (total <= 0) return variants[0]?.key ?? "";
+  let point = bucket(`${flagKey}:${seed}:variant:${ctx.key}`) * total;
+  for (const v of variants) {
+    point -= v.weight ?? 1;
+    if (point < 0) return v.key;
+  }
+  return variants[variants.length - 1].key;
+}
+function isEnabled(flagKey, def, ctx) {
+  const fallback = def.default ?? false;
+  if (def.enabled === false) return fallback;
+  const seed = def.seed ?? "";
+  for (const rule of def.rules ?? []) {
+    if (matchCondition(ctx.attributes ?? {}, rule.when)) {
+      if (typeof rule.value === "boolean") return rule.value;
+      if (typeof rule.rollout === "number") {
+        return inRollout(flagKey, seed, ctx, rule.rollout, ruleSalt(rule)) ? true : fallback;
+      }
+      return true;
+    }
+  }
+  const rollout = def.rollout ?? (def.rules && def.rules.length ? 0 : 100);
+  return inRollout(flagKey, seed, ctx, rollout) ? true : fallback;
+}
+function variant(flagKey, def, ctx) {
+  const fallback = def.default ?? def.variants[0]?.key ?? "";
+  if (def.enabled === false) return fallback;
+  const seed = def.seed ?? "";
+  for (const rule of def.rules ?? []) {
+    if (matchCondition(ctx.attributes ?? {}, rule.when)) {
+      if (typeof rule.value === "string") return rule.value;
+      break;
+    }
+  }
+  return pickVariant(flagKey, seed, ctx, def.variants);
+}
+function ruleSalt(rule) {
+  return JSON.stringify(rule.when);
+}
+var isVariantFlag = (d) => d.type === "variant";
+var Flags = class {
+  constructor(defs = {}) {
+    this.defs = { ...defs };
+  }
+  /** Replace / merge flag definitions at runtime (hot config reload). */
+  update(defs) {
+    this.defs = { ...this.defs, ...defs };
+    return this;
+  }
+  /** Set (or remove, with `undefined`) a single flag. */
+  set(key, def) {
+    if (def === void 0) delete this.defs[key];
+    else this.defs[key] = def;
+    return this;
+  }
+  has(key) {
+    return key in this.defs;
+  }
+  /** Boolean evaluation. Unknown flag → false. */
+  isEnabled(key, ctx) {
+    const def = this.defs[key];
+    if (!def || isVariantFlag(def)) return false;
+    return isEnabled(key, def, ctx);
+  }
+  /** Variant evaluation. Unknown flag → "". */
+  variant(key, ctx) {
+    const def = this.defs[key];
+    if (!def || !isVariantFlag(def)) return "";
+    return variant(key, def, ctx);
+  }
+  /** Generic evaluation → boolean for boolean flags, variant key for variant flags. */
+  evaluate(key, ctx) {
+    const def = this.defs[key];
+    if (!def) return false;
+    return isVariantFlag(def) ? variant(key, def, ctx) : isEnabled(key, def, ctx);
+  }
+  /**
+   * Evaluate every flag for a context — ideal for bootstrapping a client so the
+   * browser never flickers or needs a round-trip.
+   */
+  all(ctx) {
+    const out = {};
+    for (const key of Object.keys(this.defs)) out[key] = this.evaluate(key, ctx);
+    return out;
+  }
+  /** The current raw config. */
+  toJSON() {
+    return { ...this.defs };
+  }
+};
+
+exports.Flags = Flags;
+exports.bucket = bucket;
+exports.isEnabled = isEnabled;
+exports.percentage = percentage;
+exports.variant = variant;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @lacspace/flags\n *\n * Feature flags & A/B experiments with **no SaaS and no infrastructure**.\n * You own the config (a plain object — from JSON, env, a DB row, anywhere);\n * this evaluates it. The whole space is hosted vendors (LaunchDarkly, Optimizely,\n * Unleash) — this is the tiny, self-hosted primitive for the rest of us.\n *\n * - Deterministic bucketing — the same user ALWAYS gets the same result\n *   (stable percentage rollouts & A/B assignment, no flicker, works offline)\n * - Targeting rules on user attributes (eq / in / gt / contains / regex …)\n * - Boolean flags AND weighted multivariate experiments\n * - Synchronous, zero-dependency, isomorphic — evaluate flags right in render\n */\n\nexport type AttrValue = string | number | boolean | null | undefined;\nexport type Attributes = Record<string, AttrValue>;\n\nexport interface Context {\n  /** Stable identifier the bucketing is keyed on (user id, account id, device id). */\n  key: string;\n  /** Attributes used by targeting rules. */\n  attributes?: Attributes;\n}\n\n/* ------------------------------ conditions ------------------------------ */\n\nexport interface Operator {\n  eq?: AttrValue;\n  ne?: AttrValue;\n  in?: AttrValue[];\n  nin?: AttrValue[];\n  gt?: number;\n  gte?: number;\n  lt?: number;\n  lte?: number;\n  contains?: string;\n  regex?: string;\n}\n\n/** A set of attribute conditions — ALL must match. */\nexport type Condition = Record<string, AttrValue | Operator>;\n\nexport interface Rule {\n  /** Attribute conditions that must all match for this rule to apply. */\n  when: Condition;\n  /** Force this value (boolean flag) or variant key (variant flag). */\n  value?: boolean | string;\n  /** Or: percentage rollout within the matched segment (0–100). */\n  rollout?: number;\n}\n\nexport interface Variant {\n  key: string;\n  /** Relative weight (default 1 → equal split). */\n  weight?: number;\n}\n\nexport interface BooleanFlag {\n  type?: \"boolean\";\n  /** Master switch. Default true. */\n  enabled?: boolean;\n  /** Percentage rollout 0–100 when no rule matches. Default 100. */\n  rollout?: number;\n  rules?: Rule[];\n  /** Value when disabled or outside the rollout. Default false. */\n  default?: boolean;\n  /** Salt for bucketing (change it to re-shuffle everyone). */\n  seed?: string;\n}\n\nexport interface VariantFlag {\n  type: \"variant\";\n  enabled?: boolean;\n  variants: Variant[];\n  rules?: Rule[];\n  /** Fallback variant key when disabled. Default: first variant. */\n  default?: string;\n  seed?: string;\n}\n\nexport type FlagDef = BooleanFlag | VariantFlag;\n\n/* ------------------------------ hashing ------------------------------ */\n\n/** FNV-1a 32-bit — fast, deterministic, well-distributed for bucketing. */\nfunction fnv1a(str: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < str.length; i++) {\n    h ^= str.charCodeAt(i);\n    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;\n  }\n  return h >>> 0;\n}\n\n/** Stable bucket in [0, 1) for a key. */\nexport function bucket(key: string): number {\n  return (fnv1a(key) % 100000) / 100000;\n}\n\n/** Stable 0–100 percentage for a (flag, context) pair — useful for debugging rollouts. */\nexport function percentage(flag: string, ctx: Context, seed = \"\"): number {\n  return Math.floor(bucket(`${flag}:${seed}:${ctx.key}`) * 100);\n}\n\n/* ------------------------------ matching ------------------------------ */\n\nfunction matchOperator(actual: AttrValue, op: Operator): boolean {\n  if (\"eq\" in op && actual !== op.eq) return false;\n  if (\"ne\" in op && actual === op.ne) return false;\n  if (op.in && !op.in.includes(actual)) return false;\n  if (op.nin && op.nin.includes(actual)) return false;\n  if (typeof op.gt === \"number\" && !(typeof actual === \"number\" && actual > op.gt)) return false;\n  if (typeof op.gte === \"number\" && !(typeof actual === \"number\" && actual >= op.gte)) return false;\n  if (typeof op.lt === \"number\" && !(typeof actual === \"number\" && actual < op.lt)) return false;\n  if (typeof op.lte === \"number\" && !(typeof actual === \"number\" && actual <= op.lte)) return false;\n  if (typeof op.contains === \"string\" && !(typeof actual === \"string\" && actual.includes(op.contains))) return false;\n  if (typeof op.regex === \"string\" && !(typeof actual === \"string\" && new RegExp(op.regex).test(actual))) return false;\n  return true;\n}\n\nfunction matchCondition(attrs: Attributes, cond: Condition): boolean {\n  for (const [field, expected] of Object.entries(cond)) {\n    const actual = attrs[field];\n    if (expected !== null && typeof expected === \"object\" && !Array.isArray(expected)) {\n      if (!matchOperator(actual, expected)) return false;\n    } else if (actual !== expected) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/* ------------------------------ evaluation ------------------------------ */\n\nfunction inRollout(flagKey: string, seed: string, ctx: Context, rollout: number, salt = \"\"): boolean {\n  if (rollout >= 100) return true;\n  if (rollout <= 0) return false;\n  return bucket(`${flagKey}:${seed}:${salt}:${ctx.key}`) * 100 < rollout;\n}\n\nfunction pickVariant(flagKey: string, seed: string, ctx: Context, variants: Variant[]): string {\n  const total = variants.reduce((s, v) => s + (v.weight ?? 1), 0);\n  if (total <= 0) return variants[0]?.key ?? \"\";\n  let point = bucket(`${flagKey}:${seed}:variant:${ctx.key}`) * total;\n  for (const v of variants) {\n    point -= v.weight ?? 1;\n    if (point < 0) return v.key;\n  }\n  return variants[variants.length - 1]!.key;\n}\n\n/** Evaluate a boolean flag for a context. */\nexport function isEnabled(flagKey: string, def: BooleanFlag, ctx: Context): boolean {\n  const fallback = def.default ?? false;\n  if (def.enabled === false) return fallback;\n  const seed = def.seed ?? \"\";\n\n  for (const rule of def.rules ?? []) {\n    if (matchCondition(ctx.attributes ?? {}, rule.when)) {\n      if (typeof rule.value === \"boolean\") return rule.value;\n      if (typeof rule.rollout === \"number\") {\n        return inRollout(flagKey, seed, ctx, rule.rollout, ruleSalt(rule)) ? true : fallback;\n      }\n      return true;\n    }\n  }\n  // Fallthrough rollout: default 100% when there are no rules, but 0% when rules\n  // exist (rules define who gets it; set an explicit `rollout` to also include a\n  // slice of everyone else).\n  const rollout = def.rollout ?? (def.rules && def.rules.length ? 0 : 100);\n  return inRollout(flagKey, seed, ctx, rollout) ? true : fallback;\n}\n\n/** Evaluate a variant/experiment flag for a context — returns the variant key. */\nexport function variant(flagKey: string, def: VariantFlag, ctx: Context): string {\n  const fallback = def.default ?? def.variants[0]?.key ?? \"\";\n  if (def.enabled === false) return fallback;\n  const seed = def.seed ?? \"\";\n\n  for (const rule of def.rules ?? []) {\n    if (matchCondition(ctx.attributes ?? {}, rule.when)) {\n      if (typeof rule.value === \"string\") return rule.value;\n      break; // matched a rule with no explicit variant → fall through to weighted split\n    }\n  }\n  return pickVariant(flagKey, seed, ctx, def.variants);\n}\n\nfunction ruleSalt(rule: Rule): string {\n  return JSON.stringify(rule.when);\n}\n\nconst isVariantFlag = (d: FlagDef): d is VariantFlag => d.type === \"variant\";\n\n/* ------------------------------ the store ------------------------------ */\n\n/**\n * A flag set built from a plain config object. Evaluate synchronously anywhere.\n *\n * @example\n * const flags = new Flags({\n *   \"new-dashboard\": { rollout: 25 },                       // 25% of users\n *   \"beta\": { rules: [{ when: { plan: \"pro\" }, value: true }] },\n *   \"checkout-exp\": { type: \"variant\", variants: [\n *     { key: \"control\", weight: 1 }, { key: \"one-click\", weight: 1 },\n *   ]},\n * });\n * flags.isEnabled(\"new-dashboard\", { key: user.id });        // stable per user\n * flags.variant(\"checkout-exp\", { key: user.id });           // \"control\" | \"one-click\"\n */\nexport class Flags {\n  private defs: Record<string, FlagDef>;\n\n  constructor(defs: Record<string, FlagDef> = {}) {\n    this.defs = { ...defs };\n  }\n\n  /** Replace / merge flag definitions at runtime (hot config reload). */\n  update(defs: Record<string, FlagDef>): this {\n    this.defs = { ...this.defs, ...defs };\n    return this;\n  }\n\n  /** Set (or remove, with `undefined`) a single flag. */\n  set(key: string, def: FlagDef | undefined): this {\n    if (def === undefined) delete this.defs[key];\n    else this.defs[key] = def;\n    return this;\n  }\n\n  has(key: string): boolean {\n    return key in this.defs;\n  }\n\n  /** Boolean evaluation. Unknown flag → false. */\n  isEnabled(key: string, ctx: Context): boolean {\n    const def = this.defs[key];\n    if (!def || isVariantFlag(def)) return false;\n    return isEnabled(key, def, ctx);\n  }\n\n  /** Variant evaluation. Unknown flag → \"\". */\n  variant(key: string, ctx: Context): string {\n    const def = this.defs[key];\n    if (!def || !isVariantFlag(def)) return \"\";\n    return variant(key, def, ctx);\n  }\n\n  /** Generic evaluation → boolean for boolean flags, variant key for variant flags. */\n  evaluate(key: string, ctx: Context): boolean | string {\n    const def = this.defs[key];\n    if (!def) return false;\n    return isVariantFlag(def) ? variant(key, def, ctx) : isEnabled(key, def, ctx);\n  }\n\n  /**\n   * Evaluate every flag for a context — ideal for bootstrapping a client so the\n   * browser never flickers or needs a round-trip.\n   */\n  all(ctx: Context): Record<string, boolean | string> {\n    const out: Record<string, boolean | string> = {};\n    for (const key of Object.keys(this.defs)) out[key] = this.evaluate(key, ctx);\n    return out;\n  }\n\n  /** The current raw config. */\n  toJSON(): Record<string, FlagDef> {\n    return { ...this.defs };\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,117 @@
+/**
+ * @lacspace/flags
+ *
+ * Feature flags & A/B experiments with **no SaaS and no infrastructure**.
+ * You own the config (a plain object — from JSON, env, a DB row, anywhere);
+ * this evaluates it. The whole space is hosted vendors (LaunchDarkly, Optimizely,
+ * Unleash) — this is the tiny, self-hosted primitive for the rest of us.
+ *
+ * - Deterministic bucketing — the same user ALWAYS gets the same result
+ *   (stable percentage rollouts & A/B assignment, no flicker, works offline)
+ * - Targeting rules on user attributes (eq / in / gt / contains / regex …)
+ * - Boolean flags AND weighted multivariate experiments
+ * - Synchronous, zero-dependency, isomorphic — evaluate flags right in render
+ */
+type AttrValue = string | number | boolean | null | undefined;
+type Attributes = Record<string, AttrValue>;
+interface Context {
+    /** Stable identifier the bucketing is keyed on (user id, account id, device id). */
+    key: string;
+    /** Attributes used by targeting rules. */
+    attributes?: Attributes;
+}
+interface Operator {
+    eq?: AttrValue;
+    ne?: AttrValue;
+    in?: AttrValue[];
+    nin?: AttrValue[];
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    contains?: string;
+    regex?: string;
+}
+/** A set of attribute conditions — ALL must match. */
+type Condition = Record<string, AttrValue | Operator>;
+interface Rule {
+    /** Attribute conditions that must all match for this rule to apply. */
+    when: Condition;
+    /** Force this value (boolean flag) or variant key (variant flag). */
+    value?: boolean | string;
+    /** Or: percentage rollout within the matched segment (0–100). */
+    rollout?: number;
+}
+interface Variant {
+    key: string;
+    /** Relative weight (default 1 → equal split). */
+    weight?: number;
+}
+interface BooleanFlag {
+    type?: "boolean";
+    /** Master switch. Default true. */
+    enabled?: boolean;
+    /** Percentage rollout 0–100 when no rule matches. Default 100. */
+    rollout?: number;
+    rules?: Rule[];
+    /** Value when disabled or outside the rollout. Default false. */
+    default?: boolean;
+    /** Salt for bucketing (change it to re-shuffle everyone). */
+    seed?: string;
+}
+interface VariantFlag {
+    type: "variant";
+    enabled?: boolean;
+    variants: Variant[];
+    rules?: Rule[];
+    /** Fallback variant key when disabled. Default: first variant. */
+    default?: string;
+    seed?: string;
+}
+type FlagDef = BooleanFlag | VariantFlag;
+/** Stable bucket in [0, 1) for a key. */
+declare function bucket(key: string): number;
+/** Stable 0–100 percentage for a (flag, context) pair — useful for debugging rollouts. */
+declare function percentage(flag: string, ctx: Context, seed?: string): number;
+/** Evaluate a boolean flag for a context. */
+declare function isEnabled(flagKey: string, def: BooleanFlag, ctx: Context): boolean;
+/** Evaluate a variant/experiment flag for a context — returns the variant key. */
+declare function variant(flagKey: string, def: VariantFlag, ctx: Context): string;
+/**
+ * A flag set built from a plain config object. Evaluate synchronously anywhere.
+ *
+ * @example
+ * const flags = new Flags({
+ *   "new-dashboard": { rollout: 25 },                       // 25% of users
+ *   "beta": { rules: [{ when: { plan: "pro" }, value: true }] },
+ *   "checkout-exp": { type: "variant", variants: [
+ *     { key: "control", weight: 1 }, { key: "one-click", weight: 1 },
+ *   ]},
+ * });
+ * flags.isEnabled("new-dashboard", { key: user.id });        // stable per user
+ * flags.variant("checkout-exp", { key: user.id });           // "control" | "one-click"
+ */
+declare class Flags {
+    private defs;
+    constructor(defs?: Record<string, FlagDef>);
+    /** Replace / merge flag definitions at runtime (hot config reload). */
+    update(defs: Record<string, FlagDef>): this;
+    /** Set (or remove, with `undefined`) a single flag. */
+    set(key: string, def: FlagDef | undefined): this;
+    has(key: string): boolean;
+    /** Boolean evaluation. Unknown flag → false. */
+    isEnabled(key: string, ctx: Context): boolean;
+    /** Variant evaluation. Unknown flag → "". */
+    variant(key: string, ctx: Context): string;
+    /** Generic evaluation → boolean for boolean flags, variant key for variant flags. */
+    evaluate(key: string, ctx: Context): boolean | string;
+    /**
+     * Evaluate every flag for a context — ideal for bootstrapping a client so the
+     * browser never flickers or needs a round-trip.
+     */
+    all(ctx: Context): Record<string, boolean | string>;
+    /** The current raw config. */
+    toJSON(): Record<string, FlagDef>;
+}
+
+export { type AttrValue, type Attributes, type BooleanFlag, type Condition, type Context, type FlagDef, Flags, type Operator, type Rule, type Variant, type VariantFlag, bucket, isEnabled, percentage, variant };

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @lacspace/flags
+ *
+ * Feature flags & A/B experiments with **no SaaS and no infrastructure**.
+ * You own the config (a plain object — from JSON, env, a DB row, anywhere);
+ * this evaluates it. The whole space is hosted vendors (LaunchDarkly, Optimizely,
+ * Unleash) — this is the tiny, self-hosted primitive for the rest of us.
+ *
+ * - Deterministic bucketing — the same user ALWAYS gets the same result
+ *   (stable percentage rollouts & A/B assignment, no flicker, works offline)
+ * - Targeting rules on user attributes (eq / in / gt / contains / regex …)
+ * - Boolean flags AND weighted multivariate experiments
+ * - Synchronous, zero-dependency, isomorphic — evaluate flags right in render
+ */
+type AttrValue = string | number | boolean | null | undefined;
+type Attributes = Record<string, AttrValue>;
+interface Context {
+    /** Stable identifier the bucketing is keyed on (user id, account id, device id). */
+    key: string;
+    /** Attributes used by targeting rules. */
+    attributes?: Attributes;
+}
+interface Operator {
+    eq?: AttrValue;
+    ne?: AttrValue;
+    in?: AttrValue[];
+    nin?: AttrValue[];
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    contains?: string;
+    regex?: string;
+}
+/** A set of attribute conditions — ALL must match. */
+type Condition = Record<string, AttrValue | Operator>;
+interface Rule {
+    /** Attribute conditions that must all match for this rule to apply. */
+    when: Condition;
+    /** Force this value (boolean flag) or variant key (variant flag). */
+    value?: boolean | string;
+    /** Or: percentage rollout within the matched segment (0–100). */
+    rollout?: number;
+}
+interface Variant {
+    key: string;
+    /** Relative weight (default 1 → equal split). */
+    weight?: number;
+}
+interface BooleanFlag {
+    type?: "boolean";
+    /** Master switch. Default true. */
+    enabled?: boolean;
+    /** Percentage rollout 0–100 when no rule matches. Default 100. */
+    rollout?: number;
+    rules?: Rule[];
+    /** Value when disabled or outside the rollout. Default false. */
+    default?: boolean;
+    /** Salt for bucketing (change it to re-shuffle everyone). */
+    seed?: string;
+}
+interface VariantFlag {
+    type: "variant";
+    enabled?: boolean;
+    variants: Variant[];
+    rules?: Rule[];
+    /** Fallback variant key when disabled. Default: first variant. */
+    default?: string;
+    seed?: string;
+}
+type FlagDef = BooleanFlag | VariantFlag;
+/** Stable bucket in [0, 1) for a key. */
+declare function bucket(key: string): number;
+/** Stable 0–100 percentage for a (flag, context) pair — useful for debugging rollouts. */
+declare function percentage(flag: string, ctx: Context, seed?: string): number;
+/** Evaluate a boolean flag for a context. */
+declare function isEnabled(flagKey: string, def: BooleanFlag, ctx: Context): boolean;
+/** Evaluate a variant/experiment flag for a context — returns the variant key. */
+declare function variant(flagKey: string, def: VariantFlag, ctx: Context): string;
+/**
+ * A flag set built from a plain config object. Evaluate synchronously anywhere.
+ *
+ * @example
+ * const flags = new Flags({
+ *   "new-dashboard": { rollout: 25 },                       // 25% of users
+ *   "beta": { rules: [{ when: { plan: "pro" }, value: true }] },
+ *   "checkout-exp": { type: "variant", variants: [
+ *     { key: "control", weight: 1 }, { key: "one-click", weight: 1 },
+ *   ]},
+ * });
+ * flags.isEnabled("new-dashboard", { key: user.id });        // stable per user
+ * flags.variant("checkout-exp", { key: user.id });           // "control" | "one-click"
+ */
+declare class Flags {
+    private defs;
+    constructor(defs?: Record<string, FlagDef>);
+    /** Replace / merge flag definitions at runtime (hot config reload). */
+    update(defs: Record<string, FlagDef>): this;
+    /** Set (or remove, with `undefined`) a single flag. */
+    set(key: string, def: FlagDef | undefined): this;
+    has(key: string): boolean;
+    /** Boolean evaluation. Unknown flag → false. */
+    isEnabled(key: string, ctx: Context): boolean;
+    /** Variant evaluation. Unknown flag → "". */
+    variant(key: string, ctx: Context): string;
+    /** Generic evaluation → boolean for boolean flags, variant key for variant flags. */
+    evaluate(key: string, ctx: Context): boolean | string;
+    /**
+     * Evaluate every flag for a context — ideal for bootstrapping a client so the
+     * browser never flickers or needs a round-trip.
+     */
+    all(ctx: Context): Record<string, boolean | string>;
+    /** The current raw config. */
+    toJSON(): Record<string, FlagDef>;
+}
+
+export { type AttrValue, type Attributes, type BooleanFlag, type Condition, type Context, type FlagDef, Flags, type Operator, type Rule, type Variant, type VariantFlag, bucket, isEnabled, percentage, variant };

package/dist/index.js

@@ -0,0 +1,140 @@
+// src/index.ts
+function fnv1a(str) {
+  let h = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+  }
+  return h >>> 0;
+}
+function bucket(key) {
+  return fnv1a(key) % 1e5 / 1e5;
+}
+function percentage(flag, ctx, seed = "") {
+  return Math.floor(bucket(`${flag}:${seed}:${ctx.key}`) * 100);
+}
+function matchOperator(actual, op) {
+  if ("eq" in op && actual !== op.eq) return false;
+  if ("ne" in op && actual === op.ne) return false;
+  if (op.in && !op.in.includes(actual)) return false;
+  if (op.nin && op.nin.includes(actual)) return false;
+  if (typeof op.gt === "number" && !(typeof actual === "number" && actual > op.gt)) return false;
+  if (typeof op.gte === "number" && !(typeof actual === "number" && actual >= op.gte)) return false;
+  if (typeof op.lt === "number" && !(typeof actual === "number" && actual < op.lt)) return false;
+  if (typeof op.lte === "number" && !(typeof actual === "number" && actual <= op.lte)) return false;
+  if (typeof op.contains === "string" && !(typeof actual === "string" && actual.includes(op.contains))) return false;
+  if (typeof op.regex === "string" && !(typeof actual === "string" && new RegExp(op.regex).test(actual))) return false;
+  return true;
+}
+function matchCondition(attrs, cond) {
+  for (const [field, expected] of Object.entries(cond)) {
+    const actual = attrs[field];
+    if (expected !== null && typeof expected === "object" && !Array.isArray(expected)) {
+      if (!matchOperator(actual, expected)) return false;
+    } else if (actual !== expected) {
+      return false;
+    }
+  }
+  return true;
+}
+function inRollout(flagKey, seed, ctx, rollout, salt = "") {
+  if (rollout >= 100) return true;
+  if (rollout <= 0) return false;
+  return bucket(`${flagKey}:${seed}:${salt}:${ctx.key}`) * 100 < rollout;
+}
+function pickVariant(flagKey, seed, ctx, variants) {
+  const total = variants.reduce((s, v) => s + (v.weight ?? 1), 0);
+  if (total <= 0) return variants[0]?.key ?? "";
+  let point = bucket(`${flagKey}:${seed}:variant:${ctx.key}`) * total;
+  for (const v of variants) {
+    point -= v.weight ?? 1;
+    if (point < 0) return v.key;
+  }
+  return variants[variants.length - 1].key;
+}
+function isEnabled(flagKey, def, ctx) {
+  const fallback = def.default ?? false;
+  if (def.enabled === false) return fallback;
+  const seed = def.seed ?? "";
+  for (const rule of def.rules ?? []) {
+    if (matchCondition(ctx.attributes ?? {}, rule.when)) {
+      if (typeof rule.value === "boolean") return rule.value;
+      if (typeof rule.rollout === "number") {
+        return inRollout(flagKey, seed, ctx, rule.rollout, ruleSalt(rule)) ? true : fallback;
+      }
+      return true;
+    }
+  }
+  const rollout = def.rollout ?? (def.rules && def.rules.length ? 0 : 100);
+  return inRollout(flagKey, seed, ctx, rollout) ? true : fallback;
+}
+function variant(flagKey, def, ctx) {
+  const fallback = def.default ?? def.variants[0]?.key ?? "";
+  if (def.enabled === false) return fallback;
+  const seed = def.seed ?? "";
+  for (const rule of def.rules ?? []) {
+    if (matchCondition(ctx.attributes ?? {}, rule.when)) {
+      if (typeof rule.value === "string") return rule.value;
+      break;
+    }
+  }
+  return pickVariant(flagKey, seed, ctx, def.variants);
+}
+function ruleSalt(rule) {
+  return JSON.stringify(rule.when);
+}
+var isVariantFlag = (d) => d.type === "variant";
+var Flags = class {
+  constructor(defs = {}) {
+    this.defs = { ...defs };
+  }
+  /** Replace / merge flag definitions at runtime (hot config reload). */
+  update(defs) {
+    this.defs = { ...this.defs, ...defs };
+    return this;
+  }
+  /** Set (or remove, with `undefined`) a single flag. */
+  set(key, def) {
+    if (def === void 0) delete this.defs[key];
+    else this.defs[key] = def;
+    return this;
+  }
+  has(key) {
+    return key in this.defs;
+  }
+  /** Boolean evaluation. Unknown flag → false. */
+  isEnabled(key, ctx) {
+    const def = this.defs[key];
+    if (!def || isVariantFlag(def)) return false;
+    return isEnabled(key, def, ctx);
+  }
+  /** Variant evaluation. Unknown flag → "". */
+  variant(key, ctx) {
+    const def = this.defs[key];
+    if (!def || !isVariantFlag(def)) return "";
+    return variant(key, def, ctx);
+  }
+  /** Generic evaluation → boolean for boolean flags, variant key for variant flags. */
+  evaluate(key, ctx) {
+    const def = this.defs[key];
+    if (!def) return false;
+    return isVariantFlag(def) ? variant(key, def, ctx) : isEnabled(key, def, ctx);
+  }
+  /**
+   * Evaluate every flag for a context — ideal for bootstrapping a client so the
+   * browser never flickers or needs a round-trip.
+   */
+  all(ctx) {
+    const out = {};
+    for (const key of Object.keys(this.defs)) out[key] = this.evaluate(key, ctx);
+    return out;
+  }
+  /** The current raw config. */
+  toJSON() {
+    return { ...this.defs };
+  }
+};
+
+export { Flags, bucket, isEnabled, percentage, variant };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @lacspace/flags\n *\n * Feature flags & A/B experiments with **no SaaS and no infrastructure**.\n * You own the config (a plain object — from JSON, env, a DB row, anywhere);\n * this evaluates it. The whole space is hosted vendors (LaunchDarkly, Optimizely,\n * Unleash) — this is the tiny, self-hosted primitive for the rest of us.\n *\n * - Deterministic bucketing — the same user ALWAYS gets the same result\n *   (stable percentage rollouts & A/B assignment, no flicker, works offline)\n * - Targeting rules on user attributes (eq / in / gt / contains / regex …)\n * - Boolean flags AND weighted multivariate experiments\n * - Synchronous, zero-dependency, isomorphic — evaluate flags right in render\n */\n\nexport type AttrValue = string | number | boolean | null | undefined;\nexport type Attributes = Record<string, AttrValue>;\n\nexport interface Context {\n  /** Stable identifier the bucketing is keyed on (user id, account id, device id). */\n  key: string;\n  /** Attributes used by targeting rules. */\n  attributes?: Attributes;\n}\n\n/* ------------------------------ conditions ------------------------------ */\n\nexport interface Operator {\n  eq?: AttrValue;\n  ne?: AttrValue;\n  in?: AttrValue[];\n  nin?: AttrValue[];\n  gt?: number;\n  gte?: number;\n  lt?: number;\n  lte?: number;\n  contains?: string;\n  regex?: string;\n}\n\n/** A set of attribute conditions — ALL must match. */\nexport type Condition = Record<string, AttrValue | Operator>;\n\nexport interface Rule {\n  /** Attribute conditions that must all match for this rule to apply. */\n  when: Condition;\n  /** Force this value (boolean flag) or variant key (variant flag). */\n  value?: boolean | string;\n  /** Or: percentage rollout within the matched segment (0–100). */\n  rollout?: number;\n}\n\nexport interface Variant {\n  key: string;\n  /** Relative weight (default 1 → equal split). */\n  weight?: number;\n}\n\nexport interface BooleanFlag {\n  type?: \"boolean\";\n  /** Master switch. Default true. */\n  enabled?: boolean;\n  /** Percentage rollout 0–100 when no rule matches. Default 100. */\n  rollout?: number;\n  rules?: Rule[];\n  /** Value when disabled or outside the rollout. Default false. */\n  default?: boolean;\n  /** Salt for bucketing (change it to re-shuffle everyone). */\n  seed?: string;\n}\n\nexport interface VariantFlag {\n  type: \"variant\";\n  enabled?: boolean;\n  variants: Variant[];\n  rules?: Rule[];\n  /** Fallback variant key when disabled. Default: first variant. */\n  default?: string;\n  seed?: string;\n}\n\nexport type FlagDef = BooleanFlag | VariantFlag;\n\n/* ------------------------------ hashing ------------------------------ */\n\n/** FNV-1a 32-bit — fast, deterministic, well-distributed for bucketing. */\nfunction fnv1a(str: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < str.length; i++) {\n    h ^= str.charCodeAt(i);\n    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;\n  }\n  return h >>> 0;\n}\n\n/** Stable bucket in [0, 1) for a key. */\nexport function bucket(key: string): number {\n  return (fnv1a(key) % 100000) / 100000;\n}\n\n/** Stable 0–100 percentage for a (flag, context) pair — useful for debugging rollouts. */\nexport function percentage(flag: string, ctx: Context, seed = \"\"): number {\n  return Math.floor(bucket(`${flag}:${seed}:${ctx.key}`) * 100);\n}\n\n/* ------------------------------ matching ------------------------------ */\n\nfunction matchOperator(actual: AttrValue, op: Operator): boolean {\n  if (\"eq\" in op && actual !== op.eq) return false;\n  if (\"ne\" in op && actual === op.ne) return false;\n  if (op.in && !op.in.includes(actual)) return false;\n  if (op.nin && op.nin.includes(actual)) return false;\n  if (typeof op.gt === \"number\" && !(typeof actual === \"number\" && actual > op.gt)) return false;\n  if (typeof op.gte === \"number\" && !(typeof actual === \"number\" && actual >= op.gte)) return false;\n  if (typeof op.lt === \"number\" && !(typeof actual === \"number\" && actual < op.lt)) return false;\n  if (typeof op.lte === \"number\" && !(typeof actual === \"number\" && actual <= op.lte)) return false;\n  if (typeof op.contains === \"string\" && !(typeof actual === \"string\" && actual.includes(op.contains))) return false;\n  if (typeof op.regex === \"string\" && !(typeof actual === \"string\" && new RegExp(op.regex).test(actual))) return false;\n  return true;\n}\n\nfunction matchCondition(attrs: Attributes, cond: Condition): boolean {\n  for (const [field, expected] of Object.entries(cond)) {\n    const actual = attrs[field];\n    if (expected !== null && typeof expected === \"object\" && !Array.isArray(expected)) {\n      if (!matchOperator(actual, expected)) return false;\n    } else if (actual !== expected) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/* ------------------------------ evaluation ------------------------------ */\n\nfunction inRollout(flagKey: string, seed: string, ctx: Context, rollout: number, salt = \"\"): boolean {\n  if (rollout >= 100) return true;\n  if (rollout <= 0) return false;\n  return bucket(`${flagKey}:${seed}:${salt}:${ctx.key}`) * 100 < rollout;\n}\n\nfunction pickVariant(flagKey: string, seed: string, ctx: Context, variants: Variant[]): string {\n  const total = variants.reduce((s, v) => s + (v.weight ?? 1), 0);\n  if (total <= 0) return variants[0]?.key ?? \"\";\n  let point = bucket(`${flagKey}:${seed}:variant:${ctx.key}`) * total;\n  for (const v of variants) {\n    point -= v.weight ?? 1;\n    if (point < 0) return v.key;\n  }\n  return variants[variants.length - 1]!.key;\n}\n\n/** Evaluate a boolean flag for a context. */\nexport function isEnabled(flagKey: string, def: BooleanFlag, ctx: Context): boolean {\n  const fallback = def.default ?? false;\n  if (def.enabled === false) return fallback;\n  const seed = def.seed ?? \"\";\n\n  for (const rule of def.rules ?? []) {\n    if (matchCondition(ctx.attributes ?? {}, rule.when)) {\n      if (typeof rule.value === \"boolean\") return rule.value;\n      if (typeof rule.rollout === \"number\") {\n        return inRollout(flagKey, seed, ctx, rule.rollout, ruleSalt(rule)) ? true : fallback;\n      }\n      return true;\n    }\n  }\n  // Fallthrough rollout: default 100% when there are no rules, but 0% when rules\n  // exist (rules define who gets it; set an explicit `rollout` to also include a\n  // slice of everyone else).\n  const rollout = def.rollout ?? (def.rules && def.rules.length ? 0 : 100);\n  return inRollout(flagKey, seed, ctx, rollout) ? true : fallback;\n}\n\n/** Evaluate a variant/experiment flag for a context — returns the variant key. */\nexport function variant(flagKey: string, def: VariantFlag, ctx: Context): string {\n  const fallback = def.default ?? def.variants[0]?.key ?? \"\";\n  if (def.enabled === false) return fallback;\n  const seed = def.seed ?? \"\";\n\n  for (const rule of def.rules ?? []) {\n    if (matchCondition(ctx.attributes ?? {}, rule.when)) {\n      if (typeof rule.value === \"string\") return rule.value;\n      break; // matched a rule with no explicit variant → fall through to weighted split\n    }\n  }\n  return pickVariant(flagKey, seed, ctx, def.variants);\n}\n\nfunction ruleSalt(rule: Rule): string {\n  return JSON.stringify(rule.when);\n}\n\nconst isVariantFlag = (d: FlagDef): d is VariantFlag => d.type === \"variant\";\n\n/* ------------------------------ the store ------------------------------ */\n\n/**\n * A flag set built from a plain config object. Evaluate synchronously anywhere.\n *\n * @example\n * const flags = new Flags({\n *   \"new-dashboard\": { rollout: 25 },                       // 25% of users\n *   \"beta\": { rules: [{ when: { plan: \"pro\" }, value: true }] },\n *   \"checkout-exp\": { type: \"variant\", variants: [\n *     { key: \"control\", weight: 1 }, { key: \"one-click\", weight: 1 },\n *   ]},\n * });\n * flags.isEnabled(\"new-dashboard\", { key: user.id });        // stable per user\n * flags.variant(\"checkout-exp\", { key: user.id });           // \"control\" | \"one-click\"\n */\nexport class Flags {\n  private defs: Record<string, FlagDef>;\n\n  constructor(defs: Record<string, FlagDef> = {}) {\n    this.defs = { ...defs };\n  }\n\n  /** Replace / merge flag definitions at runtime (hot config reload). */\n  update(defs: Record<string, FlagDef>): this {\n    this.defs = { ...this.defs, ...defs };\n    return this;\n  }\n\n  /** Set (or remove, with `undefined`) a single flag. */\n  set(key: string, def: FlagDef | undefined): this {\n    if (def === undefined) delete this.defs[key];\n    else this.defs[key] = def;\n    return this;\n  }\n\n  has(key: string): boolean {\n    return key in this.defs;\n  }\n\n  /** Boolean evaluation. Unknown flag → false. */\n  isEnabled(key: string, ctx: Context): boolean {\n    const def = this.defs[key];\n    if (!def || isVariantFlag(def)) return false;\n    return isEnabled(key, def, ctx);\n  }\n\n  /** Variant evaluation. Unknown flag → \"\". */\n  variant(key: string, ctx: Context): string {\n    const def = this.defs[key];\n    if (!def || !isVariantFlag(def)) return \"\";\n    return variant(key, def, ctx);\n  }\n\n  /** Generic evaluation → boolean for boolean flags, variant key for variant flags. */\n  evaluate(key: string, ctx: Context): boolean | string {\n    const def = this.defs[key];\n    if (!def) return false;\n    return isVariantFlag(def) ? variant(key, def, ctx) : isEnabled(key, def, ctx);\n  }\n\n  /**\n   * Evaluate every flag for a context — ideal for bootstrapping a client so the\n   * browser never flickers or needs a round-trip.\n   */\n  all(ctx: Context): Record<string, boolean | string> {\n    const out: Record<string, boolean | string> = {};\n    for (const key of Object.keys(this.defs)) out[key] = this.evaluate(key, ctx);\n    return out;\n  }\n\n  /** The current raw config. */\n  toJSON(): Record<string, FlagDef> {\n    return { ...this.defs };\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@lacspace/flags",
+  "version": "1.0.0",
+  "description": "Feature flags & A/B experiments with no SaaS and no infrastructure — deterministic bucketing (same user always gets the same result), targeting rules, percentage rollouts and weighted variants. Synchronous, zero-dependency, isomorphic.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "feature-flags",
+    "feature-toggle",
+    "feature-flag",
+    "ab-testing",
+    "a-b-testing",
+    "experiments",
+    "rollout",
+    "percentage-rollout",
+    "targeting",
+    "launchdarkly-alternative",
+    "unleash-alternative",
+    "self-hosted",
+    "deterministic",
+    "isomorphic",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://lacspace.com/packages",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "flags"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}