feat: add watchers

Author: tilyupo

README.md

@@ -36,29 +36,40 @@ const client = createReplaneClient({
   baseUrl: "https://api.my-replane-host.com",
 });
 
-const featureFlag = await client.getConfig<boolean>({
+// One-off fetch
+const featureFlag = await client.getConfigValue<boolean>({
   name: "new-onboarding",
   fallback: false,
 });
 
-// or a more complex example
-
+// Typed example
 interface PasswordRequirements {
   minLength: number;
   requireSymbol: boolean;
 }
 
-const passwordRequirements = await client.getConfig<PasswordRequirements>({
+const passwordRequirements = await client.getConfigValue<PasswordRequirements>({
   name: "password-requirements",
   fallback: { minLength: 8, requireSymbol: false },
 });
+
+// Watching a config
+const billingEnabled = await client.watchConfigValue<boolean>({
+  name: "billing-enabled",
+  fallback: false,
+});
+
+// Later, read the latest value
+if (billingEnabled.get()) {
+  console.log("Billing enabled!");
+}
 ```
 
 ## API
 
 ### `createReplaneClient(options)`
 
-Returns an object: `{ getConfig }`.
+Returns an object: `{ getConfigValue, watchConfigValue }`.
 
 #### Options
 
@@ -68,21 +79,27 @@ Returns an object: `{ getConfig }`.
 - `timeoutMs` (number) – abort the request after N ms. Default: 1000.
 - `logger` (`{ info(...), error(...) }`) – optional logger (defaults to `console`).
 
-### `client.getConfig({ name, fallback, ...overrides })`
+### `client.getConfigValue({ name, fallback, ...overrides })`
 
 Parameters:
 
 - `name` (string) – config name to fetch.
 - `fallback` (any) – value returned when request fails or response is invalid.
 - Overrides: `baseUrl`, `apiKey`, `fetchFn`, `timeoutMs`, `logger` – same semantics as in `createReplaneClient`.
 
-Returns: the config value.
+Returns: the config value (or the provided fallback on failure).
 
 Failures (non-2xx, network error, or invalid JSON) do not throw; the function logs via `logger.error(...)` and returns your `fallback`.
 
+### `client.watchConfigValue({ name, fallback, ...overrides })`
+
+Creates a lightweight watcher that refreshes the config value in the background. Useful for long‑lived processes wanting near‑real‑time updates without manually refetching.
+
+Returns a promise resolving to `{ get(): T }` where `get()` returns the current value. Until the first successful fetch it returns the provided fallback. Errors during refresh reuse the last known value.
+
 ### Errors
 
-This SDK doesn't throw on request/response errors during `getConfig`. Instead, it logs (using the provided or default logger) and returns the provided `fallback`.
+This SDK doesn't throw on request/response errors during `getConfigValue` or background refreshes in `watchConfigValue`. Instead, it logs (using the provided or default logger) and returns the provided `fallback` (or previous value for watchers).
 
 ## Environment notes
 
@@ -98,7 +115,7 @@ interface LayoutConfig {
   variant: "a" | "b";
   ttl: number;
 }
-const layout = await client.getConfig<LayoutConfig>({
+const layout = await client.getConfigValue<LayoutConfig>({
   name: "layout",
   fallback: { variant: "a", ttl: 0 },
 });
@@ -107,7 +124,7 @@ const layout = await client.getConfig<LayoutConfig>({
 Timeout override:
 
 ```ts
-await client.getConfig({
+await client.getConfigValue({
   name: "slow-config",
   fallback: null,
   timeoutMs: 1500,

src/index.ts

@@ -59,9 +59,17 @@ export interface GetConfigRequest<T> extends Partial<ReplaneClientOptions> {
   fallback: T;
 }
 
+export interface ConfigValueWatcher<T> {
+  /** Current config value (or fallback if not found). */
+  get(): T;
+}
+
 export interface ReplaneClient {
   /** Fetch a config value by name. */
-  getConfig<T = unknown>(req: GetConfigRequest<T>): Promise<T | undefined>;
+  getConfigValue<T = unknown>(req: GetConfigRequest<T>): Promise<T | undefined>;
+  watchConfigValue<T = unknown>(
+    req: GetConfigRequest<T>
+  ): Promise<ConfigValueWatcher<T>>;
 }
 
 /**
@@ -75,21 +83,46 @@ export function createReplaneClient(
 ): ReplaneClient {
   if (!sdkOptions.apiKey) throw new Error("API key is required");
 
+  async function getConfigValue<T = unknown>(
+    req: GetConfigRequest<T>
+  ): Promise<T> {
+    if (!req.name) throw new Error("config name is required");
+    const finalOptions = combineOptions(sdkOptions, req);
+    try {
+      return await _getConfig<T>({
+        configName: req.name,
+        fallback: req.fallback,
+        options: finalOptions,
+      });
+    } catch (err: unknown) {
+      finalOptions.logger.error("ReplaneClient.getConfig error", err);
+      return req.fallback;
+    }
+  }
+
+  async function watchConfigValue<T = unknown>(
+    originalReq: GetConfigRequest<T>
+  ): Promise<ConfigValueWatcher<T>> {
+    const req = { ...originalReq };
+    let currentValue: T = await getConfigValue<T>(req);
+
+    setInterval(async () => {
+      currentValue = await getConfigValue<T>({
+        ...req,
+        fallback: currentValue,
+      });
+    }, 60_000);
+
+    return {
+      get() {
+        return currentValue;
+      },
+    };
+  }
+
   return {
-    async getConfig<T = unknown>(req: GetConfigRequest<T>): Promise<T> {
-      if (!req.name) throw new Error("config name is required");
-      const finalOptions = combineOptions(sdkOptions, req);
-      try {
-        return await _getConfig<T>({
-          configName: req.name,
-          fallback: req.fallback,
-          options: finalOptions,
-        });
-      } catch (err: unknown) {
-        finalOptions.logger.error("ReplaneClient.getConfig error", err);
-        return req.fallback;
-      }
-    },
+    getConfigValue,
+    watchConfigValue,
   };
 }