@jondotsoy/configs 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+export declare class ConfigError extends Error {
+}

package/dist/sources/env.d.ts

@@ -0,0 +1,36 @@
+import { Source } from "./source";
+/** Maps an env var key to a path into the config tree, e.g. `mapKey("FOO_TAR")`. */
+export type EnvKeyMapper = (key: string) => string[];
+export interface EnvSourceOptions {
+    /** The env vars to read. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Only keys starting with `prefix` are included; the prefix is stripped before `mapKey` runs. */
+    prefix?: string;
+    /** Only keys ending with `suffix` are included; the suffix is stripped before `mapKey` runs. */
+    suffix?: string;
+    /** Maps each key to a path. Defaults to the identity mapping: `"FOO_TAR" => ["FOO_TAR"]`. */
+    mapKey?: EnvKeyMapper;
+}
+/** Built-in `mapKey` strategies for `EnvSourceOptions.mapKey`, each a factory returning an `EnvKeyMapper`. */
+export declare const mapKey: {
+    /**
+     * Splits an env key into a lowercase nested path on `separator` (default `"_"`):
+     * `"FOO_TAR" => ["foo", "tar"]`. Pass a different `separator` (e.g. `"__"`) to keep a single
+     * underscore inside a segment from splitting it, e.g. `"API_KEY_V2"` with `separator: "__"`.
+     */
+    snakeCase(options?: {
+        separator?: string;
+    }): EnvKeyMapper;
+    /** Passes each key through unchanged, as a single-segment path: `"FOO_TAR" => ["FOO_TAR"]`. Equivalent to the default when `mapKey` is omitted — spells it out explicitly. */
+    identity(): EnvKeyMapper;
+    /** Maps an env key to a single camelCase segment: `"FOO_TAR" => ["fooTar"]`. */
+    camelCase(): EnvKeyMapper;
+    /**
+     * Maps specific env keys to explicit paths via a `table` lookup, e.g.
+     * `mapKey.lookup({ PORT: ["server", "port"] })` maps `"PORT" => ["server", "port"]`. A key not
+     * found in `table` falls back to `fallback` (default: the identity mapping, `key => [key]`).
+     */
+    lookup(table: Record<string, string[]>, fallback?: EnvKeyMapper): EnvKeyMapper;
+};
+/** A `Source` that snapshots `env` into a config tree, one field per key (as mapped by `mapKey`). */
+export declare function envSource(options?: EnvSourceOptions): Source<Record<string, unknown>>;

package/dist/sources/env.js

@@ -0,0 +1,190 @@
+// src/utils/store.ts
+class Store {
+  value;
+  subscribers = new Set;
+  cleanups = new Map;
+  mountListeners = new Set;
+  unmountListeners = new Set;
+  constructor(initial) {
+    this.value = initial;
+  }
+  get() {
+    return this.value;
+  }
+  set(next) {
+    this.value = next;
+    for (const subscriber of this.subscribers) {
+      this.runSubscriber(subscriber, this.value);
+    }
+  }
+  subscribe(subscriber) {
+    this.addSubscriber(subscriber);
+    this.runSubscriber(subscriber, this.value);
+    return () => this.removeSubscriber(subscriber);
+  }
+  listen(subscriber) {
+    this.addSubscriber(subscriber);
+    return () => this.removeSubscriber(subscriber);
+  }
+  runSubscriber(subscriber, value) {
+    const cleanup = subscriber(value);
+    if (typeof cleanup === "function")
+      this.cleanups.set(subscriber, cleanup);
+  }
+  onMount(listener) {
+    this.mountListeners.add(listener);
+    return () => {
+      this.mountListeners.delete(listener);
+    };
+  }
+  onUnmount(listener) {
+    this.unmountListeners.add(listener);
+    return () => {
+      this.unmountListeners.delete(listener);
+    };
+  }
+  addSubscriber(subscriber) {
+    const wasEmpty = this.subscribers.size === 0;
+    if (wasEmpty) {
+      for (const listener of this.mountListeners)
+        listener();
+    }
+    this.subscribers.add(subscriber);
+  }
+  removeSubscriber(subscriber) {
+    if (!this.subscribers.delete(subscriber))
+      return;
+    const cleanup = this.cleanups.get(subscriber);
+    this.cleanups.delete(subscriber);
+    cleanup?.();
+    if (this.subscribers.size === 0) {
+      for (const listener of this.unmountListeners)
+        listener();
+    }
+  }
+  static onMount(store, callback) {
+    let cleanup;
+    const unsubMount = store.onMount(() => {
+      cleanup = callback();
+    });
+    const unsubUnmount = store.onUnmount(() => {
+      cleanup?.();
+      cleanup = undefined;
+    });
+    return () => {
+      cleanup?.();
+      cleanup = undefined;
+      unsubMount();
+      unsubUnmount();
+    };
+  }
+}
+function create(initial) {
+  return new Store(initial);
+}
+function computed(source, selector) {
+  const result = new Store(selector(source.get()));
+  Store.onMount(result, () => {
+    return source.subscribe((value) => {
+      result.set(selector(value));
+    });
+  });
+  return result;
+}
+var store = { create, computed, onMount: Store.onMount };
+
+// src/sources/source.ts
+class Source {
+  underlying;
+  store = new Store(null);
+  closed = false;
+  closePromise;
+  startPromise;
+  constructor(underlying) {
+    this.underlying = underlying;
+    const control = {
+      set: (value) => {
+        if (this.closed)
+          return;
+        const next = this.underlying.reduce ? this.underlying.reduce(value, this.store.get()) : value;
+        this.store.set(next);
+      },
+      close: () => {
+        this.close();
+      }
+    };
+    this.startPromise = Promise.resolve().then(() => underlying.start(control)).then(() => {
+      return;
+    });
+    this.startPromise.catch(() => {});
+  }
+  async open() {
+    await this.startPromise;
+    return this.store;
+  }
+  close() {
+    if (!this.closePromise) {
+      this.closed = true;
+      this.closePromise = Promise.resolve(this.underlying.close?.()).then(() => {
+        return;
+      }, () => {
+        return;
+      });
+    }
+    return this.closePromise;
+  }
+}
+
+// src/sources/env.ts
+var mapKey = {
+  snakeCase(options = {}) {
+    const separator = options.separator ?? "_";
+    return (key) => key.toLowerCase().split(separator);
+  },
+  identity() {
+    return (key) => [key];
+  },
+  camelCase() {
+    return (key) => [key.toLowerCase().replace(/_([a-z0-9])/g, (_, char) => char.toUpperCase())];
+  },
+  lookup(table, fallback = (key) => [key]) {
+    return (key) => table[key] ?? fallback(key);
+  }
+};
+function setPath(target, path, value) {
+  let node = target;
+  for (const segment of path.slice(0, -1)) {
+    const next = node[segment];
+    if (typeof next !== "object" || next === null) {
+      node[segment] = {};
+    }
+    node = node[segment];
+  }
+  node[path[path.length - 1]] = value;
+}
+function envSource(options = {}) {
+  const env = options.env ?? process.env;
+  const { prefix, suffix } = options;
+  const mapKey2 = options.mapKey ?? ((key) => [key]);
+  return new Source({
+    start(control) {
+      const tree = {};
+      for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+          continue;
+        if (prefix !== undefined && !key.startsWith(prefix))
+          continue;
+        if (suffix !== undefined && !key.endsWith(suffix))
+          continue;
+        const trimmedKey = key.slice(prefix !== undefined ? prefix.length : 0, suffix !== undefined ? key.length - suffix.length : key.length);
+        setPath(tree, mapKey2(trimmedKey), value);
+      }
+      control.set(tree);
+      control.close();
+    }
+  });
+}
+export {
+  mapKey,
+  envSource
+};

package/dist/sources/fetch.d.ts

@@ -0,0 +1,15 @@
+import { Source } from "./source";
+export interface FetchSourceOptions {
+    url: string | URL;
+    method?: string;
+    headers?: Bun.HeadersInit;
+    /** Attempts to download the data before giving up. Defaults to 1 (no retry). */
+    attempts?: number;
+}
+/**
+ * A `Source` that fetches a JSON snapshot from `url`. Only JSON is supported: the response is
+ * parsed as JSON regardless of what `Content-Type` reports (a non-JSON content type is a fallback
+ * attempt, not a hard failure). If the download never succeeds, or the body isn't valid JSON, this
+ * logs a `console.error` and leaves the store empty (`null`) instead of throwing.
+ */
+export declare function fetchSource<T = unknown>(options: FetchSourceOptions): Source<T>;

package/dist/sources/fetch.js

@@ -0,0 +1,182 @@
+// src/utils/store.ts
+class Store {
+  value;
+  subscribers = new Set;
+  cleanups = new Map;
+  mountListeners = new Set;
+  unmountListeners = new Set;
+  constructor(initial) {
+    this.value = initial;
+  }
+  get() {
+    return this.value;
+  }
+  set(next) {
+    this.value = next;
+    for (const subscriber of this.subscribers) {
+      this.runSubscriber(subscriber, this.value);
+    }
+  }
+  subscribe(subscriber) {
+    this.addSubscriber(subscriber);
+    this.runSubscriber(subscriber, this.value);
+    return () => this.removeSubscriber(subscriber);
+  }
+  listen(subscriber) {
+    this.addSubscriber(subscriber);
+    return () => this.removeSubscriber(subscriber);
+  }
+  runSubscriber(subscriber, value) {
+    const cleanup = subscriber(value);
+    if (typeof cleanup === "function")
+      this.cleanups.set(subscriber, cleanup);
+  }
+  onMount(listener) {
+    this.mountListeners.add(listener);
+    return () => {
+      this.mountListeners.delete(listener);
+    };
+  }
+  onUnmount(listener) {
+    this.unmountListeners.add(listener);
+    return () => {
+      this.unmountListeners.delete(listener);
+    };
+  }
+  addSubscriber(subscriber) {
+    const wasEmpty = this.subscribers.size === 0;
+    if (wasEmpty) {
+      for (const listener of this.mountListeners)
+        listener();
+    }
+    this.subscribers.add(subscriber);
+  }
+  removeSubscriber(subscriber) {
+    if (!this.subscribers.delete(subscriber))
+      return;
+    const cleanup = this.cleanups.get(subscriber);
+    this.cleanups.delete(subscriber);
+    cleanup?.();
+    if (this.subscribers.size === 0) {
+      for (const listener of this.unmountListeners)
+        listener();
+    }
+  }
+  static onMount(store, callback) {
+    let cleanup;
+    const unsubMount = store.onMount(() => {
+      cleanup = callback();
+    });
+    const unsubUnmount = store.onUnmount(() => {
+      cleanup?.();
+      cleanup = undefined;
+    });
+    return () => {
+      cleanup?.();
+      cleanup = undefined;
+      unsubMount();
+      unsubUnmount();
+    };
+  }
+}
+function create(initial) {
+  return new Store(initial);
+}
+function computed(source, selector) {
+  const result = new Store(selector(source.get()));
+  Store.onMount(result, () => {
+    return source.subscribe((value) => {
+      result.set(selector(value));
+    });
+  });
+  return result;
+}
+var store = { create, computed, onMount: Store.onMount };
+
+// src/sources/source.ts
+class Source {
+  underlying;
+  store = new Store(null);
+  closed = false;
+  closePromise;
+  startPromise;
+  constructor(underlying) {
+    this.underlying = underlying;
+    const control = {
+      set: (value) => {
+        if (this.closed)
+          return;
+        const next = this.underlying.reduce ? this.underlying.reduce(value, this.store.get()) : value;
+        this.store.set(next);
+      },
+      close: () => {
+        this.close();
+      }
+    };
+    this.startPromise = Promise.resolve().then(() => underlying.start(control)).then(() => {
+      return;
+    });
+    this.startPromise.catch(() => {});
+  }
+  async open() {
+    await this.startPromise;
+    return this.store;
+  }
+  close() {
+    if (!this.closePromise) {
+      this.closed = true;
+      this.closePromise = Promise.resolve(this.underlying.close?.()).then(() => {
+        return;
+      }, () => {
+        return;
+      });
+    }
+    return this.closePromise;
+  }
+}
+
+// src/sources/fetch.ts
+async function download(url, init) {
+  const response = await fetch(url, init);
+  if (!response.ok) {
+    throw new Error(`fetchSource: received ${response.status} ${response.statusText} from "${url}"`);
+  }
+  return response;
+}
+function fetchSource(options) {
+  const { url, method = "GET", headers, attempts = 1 } = options;
+  return new Source({
+    async start(control) {
+      let response;
+      let lastError;
+      for (let attempt = 0;attempt < Math.max(1, attempts); attempt++) {
+        try {
+          response = await download(url, { method, headers });
+          break;
+        } catch (error) {
+          lastError = error;
+        }
+      }
+      if (!response) {
+        console.error(`fetchSource: failed to fetch "${url}" after ${attempts} attempt(s)`, lastError);
+        control.close();
+        return;
+      }
+      const contentType = response.headers.get("content-type") ?? "";
+      const text = await response.text();
+      let data;
+      try {
+        data = JSON.parse(text);
+      } catch (error) {
+        console.error(`fetchSource: response body from "${url}" is not valid JSON (content-type: "${contentType}")`, error);
+        control.close();
+        return;
+      }
+      control.set(data);
+      control.close();
+    }
+  });
+}
+export {
+  fetchSource
+};

package/dist/sources/file.d.ts

@@ -0,0 +1,28 @@
+import { Source } from "./source";
+export interface FileSourceOptions {
+    /** Republishes the config tree whenever the file changes on disk. Defaults to `true`. */
+    watch?: boolean;
+    /**
+     * Selects a subtree of the parsed file to use as the config tree, e.g. `["containers", "settings"]`
+     * to use `{ containers: { settings: {...} } }`'s inner object and ignore the rest of the file.
+     * Defaults to `[]`: the whole parsed file is used, unchanged.
+     */
+    treePath?: string[];
+}
+/**
+ * A `Source` that reads a config tree from a local file — `.json` or `.env` (matched by
+ * `path`'s extension, or by the bare `.env` filename itself). `path` may be a plain string or a
+ * `file:` `URL` (e.g. `import.meta.resolve(...)` or `new URL("./config.json", import.meta.url)`).
+ * Like `fetchSource` and `sseSource`, a read or parse failure is logged via `console.error` and
+ * leaves the store empty (`null`) instead of throwing.
+ *
+ * `treePath` selects a subtree of the parsed file to use, instead of the whole thing. A missing
+ * or non-object segment along the way is logged via `console.error`, same as a parse failure —
+ * but unlike one, it still publishes a snapshot: an empty object (`{}`), not `null` / the last
+ * good value, since the file itself was read and parsed fine.
+ *
+ * With `watch` (the default), the file is re-read on every change and the store updated live; a
+ * parse error on one of those later reads is logged but keeps the last good value, same as
+ * `sseSource` does for a bad SSE message. `watch: false` reads the file once and closes.
+ */
+export declare function fileSource<T = unknown>(path: string | URL, options?: FileSourceOptions): Source<T>;