@guidelytech/flags 0.7.0 → 0.8.0

package/dist/cli.js

@@ -5,7 +5,7 @@ import {
   decryptPayloadString,
   isEncryptedPayload,
   isFlagsPayload
-} from "./chunk-ZTY7K7P2.js";
+} from "./chunk-2RZKAT37.js";
 import "./chunk-OY4QS3WL.js";
 
 // src/cli-main.ts

package/dist/index.cjs

@@ -34,6 +34,11 @@ __export(index_exports, {
   InMemoryStickyBucketStore: () => InMemoryStickyBucketStore,
   LocalStorageStickyBucketStore: () => LocalStorageStickyBucketStore,
   NUMBER_OPERATORS: () => NUMBER_OPERATORS,
+  OVERRIDES_ENV: () => OVERRIDES_ENV,
+  OVERRIDES_FILE_ENV: () => OVERRIDES_FILE_ENV,
+  OVERRIDES_GLOBAL: () => OVERRIDES_GLOBAL,
+  OVERRIDE_BEHAVIOUR_ENV: () => OVERRIDE_BEHAVIOUR_ENV,
+  OVERRIDE_BEHAVIOUR_GLOBAL: () => OVERRIDE_BEHAVIOUR_GLOBAL,
   PRESENCE_OPERATORS: () => PRESENCE_OPERATORS,
   SEMVER_OPERATORS: () => SEMVER_OPERATORS,
   TEXT_OPERATORS: () => TEXT_OPERATORS,
@@ -56,8 +61,10 @@ __export(index_exports, {
   jsonEquals: () => jsonEquals,
   lookupAttribute: () => lookupAttribute,
   numberOf: () => numberOf,
+  parseOverrides: () => parseOverrides,
   parseSemver: () => parseSemver,
   parseUrlOverrides: () => parseUrlOverrides,
+  readDevOverrides: () => readDevOverrides,
   sha256Hex: () => sha256Hex,
   stableStringify: () => stableStringify,
   textOf: () => textOf
@@ -893,14 +900,25 @@ function compact(attrs) {
   return out;
 }
 function parseUrlOverrides(search, param = "guidely_flags") {
-  const out = {};
   let raw = null;
   try {
     raw = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search).get(param);
   } catch {
-    return out;
+    return {};
+  }
+  return raw && parseOverrides(raw) || {};
+}
+function parseOverrides(text) {
+  const raw = text.trim();
+  if (raw.startsWith("{")) {
+    try {
+      const obj = JSON.parse(raw);
+      return obj && typeof obj === "object" && !Array.isArray(obj) ? obj : null;
+    } catch {
+      return null;
+    }
   }
-  if (!raw) return out;
+  const out = {};
   const items = [];
   let depth = 0;
   let quoted = false;
@@ -913,7 +931,7 @@ function parseUrlOverrides(search, param = "guidely_flags") {
     } else if (c === '"') quoted = true;
     else if (c === "[" || c === "{") depth++;
     else if (c === "]" || c === "}") depth = Math.max(0, depth - 1);
-    else if (c === "," && depth === 0) {
+    else if ((c === "," || c === "\n") && depth === 0) {
       items.push(raw.slice(start, i));
       start = i + 1;
     }
@@ -923,12 +941,12 @@ function parseUrlOverrides(search, param = "guidely_flags") {
     const sep = item.indexOf(":");
     if (sep <= 0) continue;
     const key = item.slice(0, sep).trim();
-    const text = item.slice(sep + 1).trim();
+    const text2 = item.slice(sep + 1).trim();
     if (!key) continue;
     try {
-      out[key] = JSON.parse(text);
+      out[key] = JSON.parse(text2);
     } catch {
-      out[key] = text;
+      out[key] = text2;
     }
   }
   return out;
@@ -947,6 +965,74 @@ function timer(fn, ms) {
   return t;
 }
 
+// src/dev-overrides.ts
+var OVERRIDES_ENV = "GUIDELY_FLAG_OVERRIDES";
+var OVERRIDES_FILE_ENV = "GUIDELY_FLAG_OVERRIDES_FILE";
+var OVERRIDE_BEHAVIOUR_ENV = "GUIDELY_FLAG_OVERRIDE_BEHAVIOUR";
+var OVERRIDES_GLOBAL = "__GUIDELY_FLAG_OVERRIDES__";
+var OVERRIDE_BEHAVIOUR_GLOBAL = "__GUIDELY_FLAG_OVERRIDE_BEHAVIOUR__";
+var BEHAVIOURS = ["localOnly", "localOverRemote", "remoteOverLocal"];
+var runtime = () => globalThis;
+function env(name) {
+  const g = runtime();
+  try {
+    const v = g.process?.env?.[name];
+    if (v !== void 0) return v;
+  } catch {
+  }
+  try {
+    return g.Deno?.env?.get(name);
+  } catch {
+    return void 0;
+  }
+}
+function readFile(path) {
+  const g = runtime();
+  const fs = g.process?.getBuiltinModule?.("node:fs");
+  if (fs) return fs.readFileSync(path, "utf8");
+  if (g.Deno?.readTextFileSync) return g.Deno.readTextFileSync(path);
+  throw new Error("this runtime cannot read files");
+}
+function behaviourOf(raw, source, out) {
+  if (typeof raw !== "string" || !raw.trim()) return;
+  const b = raw.trim();
+  if (BEHAVIOURS.includes(b)) {
+    out.behaviour = b;
+    out.sources.push(source);
+  } else out.errors.push(`${source} must be localOnly, localOverRemote or remoteOverLocal (got "${raw}"); ignoring it.`);
+}
+function merge(text, source, out) {
+  if (text === void 0 || !text.trim()) return;
+  const values = parseOverrides(text);
+  if (!values) return void out.errors.push(`${source} is not a JSON object or a key:value list; ignoring it.`);
+  if (!Object.keys(values).length) return;
+  Object.assign(out.values, values);
+  out.sources.push(source);
+}
+function readDevOverrides() {
+  const out = { values: {}, sources: [], errors: [] };
+  const file = env(OVERRIDES_FILE_ENV);
+  if (file?.trim()) {
+    try {
+      merge(readFile(file.trim()), `${OVERRIDES_FILE_ENV} (${file.trim()})`, out);
+    } catch (err) {
+      out.errors.push(`Could not read ${OVERRIDES_FILE_ENV} (${file.trim()}): ${err instanceof Error ? err.message : String(err)}; ignoring it.`);
+    }
+  }
+  merge(env(OVERRIDES_ENV), OVERRIDES_ENV, out);
+  const g = runtime()[OVERRIDES_GLOBAL];
+  if (g && typeof g === "object" && !Array.isArray(g)) {
+    if (Object.keys(g).length) {
+      Object.assign(out.values, g);
+      out.sources.push(OVERRIDES_GLOBAL);
+    }
+  } else if (typeof g === "string") merge(g, OVERRIDES_GLOBAL, out);
+  else if (g !== void 0 && g !== null) out.errors.push(`${OVERRIDES_GLOBAL} must be an object or overrides text; ignoring it.`);
+  behaviourOf(env(OVERRIDE_BEHAVIOUR_ENV), OVERRIDE_BEHAVIOUR_ENV, out);
+  behaviourOf(runtime()[OVERRIDE_BEHAVIOUR_GLOBAL], OVERRIDE_BEHAVIOUR_GLOBAL, out);
+  return out;
+}
+
 // src/evaluator.ts
 function typeMatches(value, fallback) {
   if (value === null || value === void 0) return false;
@@ -1037,7 +1123,7 @@ function createSseParser(onEvent) {
 
 // src/client.ts
 var FLAGS_SDK_NAME = "@guidelytech/flags";
-var FLAGS_SDK_VERSION = "0.7.0";
+var FLAGS_SDK_VERSION = "0.8.0";
 var DEFAULT_FLAGS_API_URL = "https://guidelytech.com";
 var SECRET_PREFIX = "gly_sk_";
 var MAX_RESULT_CACHE = 20;
@@ -1084,6 +1170,7 @@ var FlagsClient = class {
     __publicField(this, "context");
     __publicField(this, "attributes");
     __publicField(this, "overrides");
+    __publicField(this, "devOverrides");
     __publicField(this, "urlOverrides");
     __publicField(this, "offline");
     __publicField(this, "destroyed", false);
@@ -1125,12 +1212,13 @@ var FlagsClient = class {
     this.log = o.logger === null ? {} : o.logger ?? { warn: (...a) => console.warn("[Guidely flags]", ...a), error: (...a) => console.error("[Guidely flags]", ...a) };
     if (this.secret && !o.environment) throw new Error("[Guidely flags] `environment` (development | staging | production) is required with a gly_sk_ key.");
     if (this.secret && isBrowser()) this.log.warn?.("A gly_sk_ secret key is being used in a browser. Secret keys belong on servers; use the environment's public pk_ key here.");
+    const dev = o.devOverrides === false ? null : readDevOverrides();
     this.cfg = {
       mode: o.pollingMode ?? "auto",
       pollMs: Math.max(1, o.pollIntervalSeconds ?? 60) * 1e3,
       ttlMs: Math.max(0, o.cacheTtlSeconds ?? 60) * 1e3,
       debounceMs: Math.max(0, o.remoteEvalDebounceMs ?? 50),
-      behaviour: o.overrideBehaviour ?? "localOverRemote",
+      behaviour: dev?.behaviour ?? o.overrideBehaviour ?? "localOverRemote",
       trackExposures: o.trackExposures ?? !o.trackingCallback,
       reportUsage: o.reportUsage ?? true
     };
@@ -1139,10 +1227,16 @@ var FlagsClient = class {
     this.context = compact(o.contextAttributes ?? {});
     this.attributes = compact(o.attributes ?? {});
     this.overrides = { ...o.overrides ?? {} };
+    this.devOverrides = dev?.values ?? {};
     this.urlOverrides = o.enableUrlOverrides && isBrowser() ? parseUrlOverrides(location.search) : {};
     this.storage = o.storage === false || o.storage === null ? null : o.storage ?? defaultStorage();
     this.storageKey = `guidely:flags:${key}${o.environment && this.secret ? `:${o.environment}` : ""}`;
     this.readyPromise = new Promise((r) => this.resolveReady = r);
+    if (dev) {
+      dev.errors.forEach((e) => this.reportError(new Error(e)));
+      const n = Object.keys(dev.values).length;
+      if (dev.sources.length) this.log.warn?.(`Dev overrides from ${dev.sources.join(", ")}: ${n} flag${n === 1 ? "" : "s"}, behaviour ${this.cfg.behaviour}.`);
+    }
     this.getters = makeEvaluator(
       (k) => this.resolve(k, this.getAttributes(), true),
       () => this.all(this.getAttributes()),
@@ -1224,7 +1318,7 @@ var FlagsClient = class {
   getAttributes() {
     return { ...this.context, ...this.attributes };
   }
-  /** Replaces the overrides (`null` clears them). URL overrides stay. */
+  /** Replaces the overrides (`null` clears them). Dev and URL overrides stay. */
   setOverrides(overrides) {
     this.overrides = { ...overrides ?? {} };
     this.notify();
@@ -1301,6 +1395,7 @@ var FlagsClient = class {
   // ---------------------------------------------------------------------------
   overrideFor(key) {
     if (Object.prototype.hasOwnProperty.call(this.urlOverrides, key)) return this.urlOverrides[key];
+    if (Object.prototype.hasOwnProperty.call(this.devOverrides, key)) return this.devOverrides[key];
     if (Object.prototype.hasOwnProperty.call(this.overrides, key)) return this.overrides[key];
     return void 0;
   }
@@ -1312,7 +1407,6 @@ var FlagsClient = class {
       const forced = Object.prototype.hasOwnProperty.call(this.urlOverrides, key);
       const override = ov === void 0 ? null : { key, value: ov, reason: "OVERRIDE", inExperiment: false };
       if (override && (forced || this.cfg.behaviour !== "remoteOverLocal")) res = override;
-      else if (this.cfg.behaviour === "localOnly") res = notFound(key);
       else {
         res = this.evaluateRemoteOrLocal(key, attrs);
         if (override && res.reason === "FLAG_NOT_FOUND") res = override;
@@ -1333,11 +1427,9 @@ var FlagsClient = class {
     return evaluateFlag(this.payload, key, attrs, { now: this.now(), stickyBuckets: this.o.stickyBucketService });
   }
   all(attrs) {
-    const keys = /* @__PURE__ */ new Set([...Object.keys(this.overrides), ...Object.keys(this.urlOverrides)]);
-    if (this.cfg.behaviour !== "localOnly") {
-      if (this.remote) for (const k of Object.keys(this.results?.flags ?? {})) keys.add(k);
-      else for (const k of Object.keys(this.payload?.flags ?? {})) keys.add(k);
-    }
+    const keys = /* @__PURE__ */ new Set([...Object.keys(this.overrides), ...Object.keys(this.devOverrides), ...Object.keys(this.urlOverrides)]);
+    if (this.remote) for (const k of Object.keys(this.results?.flags ?? {})) keys.add(k);
+    else for (const k of Object.keys(this.payload?.flags ?? {})) keys.add(k);
     const out = {};
     for (const k of keys) {
       const v = this.resolve(k, attrs, false).value;
@@ -1584,7 +1676,7 @@ var FlagsClient = class {
   async start() {
     const boot = this.o.payload;
     if (isEncryptedPayload(boot)) await this.applyRaw(boot, null);
-    if (!this.payload && !this.results && !this.remote) await this.loadStored();
+    if (!this.payload && !this.results && !this.remote && this.cfg.behaviour !== "localOnly") await this.loadStored();
     if (this.destroyed) return;
     const bootstrapped = !!(boot || this.o.remoteResults) && !!(this.payload || this.results);
     if (this.cfg.behaviour === "localOnly" || this.offline || this.cfg.mode === "manual") return this.settle();
@@ -1730,6 +1822,11 @@ var FlagsClient = class {
   }
   takeBatch() {
     if (!this.usage.size && !this.exposures.length) return null;
+    if (this.cfg.behaviour === "localOnly") {
+      this.usage.clear();
+      this.exposures = [];
+      return null;
+    }
     const batch = { sdk: this.o.sdk ?? { name: FLAGS_SDK_NAME, version: FLAGS_SDK_VERSION } };
     if (this.usage.size) batch.usage = Array.from(this.usage.values());
     if (this.exposures.length) batch.exposures = this.exposures;
@@ -1853,6 +1950,11 @@ var LocalStorageStickyBucketStore = class {
   InMemoryStickyBucketStore,
   LocalStorageStickyBucketStore,
   NUMBER_OPERATORS,
+  OVERRIDES_ENV,
+  OVERRIDES_FILE_ENV,
+  OVERRIDES_GLOBAL,
+  OVERRIDE_BEHAVIOUR_ENV,
+  OVERRIDE_BEHAVIOUR_GLOBAL,
   PRESENCE_OPERATORS,
   SEMVER_OPERATORS,
   TEXT_OPERATORS,
@@ -1875,8 +1977,10 @@ var LocalStorageStickyBucketStore = class {
   jsonEquals,
   lookupAttribute,
   numberOf,
+  parseOverrides,
   parseSemver,
   parseUrlOverrides,
+  readDevOverrides,
   sha256Hex,
   stableStringify,
   textOf