@jondotsoy/configs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Delgado <hi@jon.soy> (https://jon.soy)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation 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 following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -0,0 +1,296 @@
+# @jondotsoy/configs
+
+A tool for all your configurations.
+
+- **Reactive configs** — every field is a live `Store`; subscribe to it and get notified whenever an upstream source changes.
+- **Lightweight** — no dependencies, just a thin layer over plain objects and stores.
+- **Typed with TS check** — schemas are statically checked, so `cfg.port.get()` is inferred as `number | null` (or `number` when a `default` is set), not `any`.
+
+```ts
+import { configs, envSource, mapKey } from "@jondotsoy/configs";
+
+// SERVER_PORT=3000 SERVER_HOST=localhost → { server: { port: "3000", host: "localhost" } }
+const source = envSource({ mapKey: mapKey.snakeCase() });
+
+const serverConfigs = await configs.create(
+  {
+    server: configs.create({
+      port: { type: "number", summary: "HTTP port", default: 3000 },
+      host: { type: "string", summary: "bind host", default: "localhost" },
+    }),
+    tls: configs.create({
+      key: { type: "string", summary: "TLS key path" },
+      cert: { type: "string", summary: "TLS cert path" },
+    }),
+  },
+  { sources: [source] },
+);
+
+// React to changes
+serverConfigs.server.port.subscribe((port) => {
+  console.log(`listening on port ${port}`);
+});
+
+console.log(serverConfigs.server.port.get());
+// 3000
+```
+
+## Table of contents
+
+- [Install](#install)
+- [Guide](#guide)
+  - [`Source` — building a custom source](#source--building-a-custom-source)
+  - [`envSource` — environment variables](#envsource--environment-variables)
+  - [`fetchSource` — a JSON endpoint over HTTP](#fetchsource--a-json-endpoint-over-http)
+  - [`sseSource` — live updates over Server-Sent Events](#ssesource--live-updates-over-server-sent-events)
+  - [`fileSource` — a local `.json` or `.env` file](#filesource--a-local-json-or-env-file)
+  - [`literalSource` — a static value](#literalsource--a-static-value)
+  - [Reacting to changes — restarting a periodic task](#reacting-to-changes--restarting-a-periodic-task)
+  - [Closing a config tree](#closing-a-config-tree)
+
+## Install
+
+```sh
+npm install @jondotsoy/configs
+```
+
+## Guide
+
+### `Source` — building a custom source
+
+The building block behind `envSource`, `fetchSource`, `sseSource`, `fileSource`, and
+`literalSource`. It takes an
+object with `start(control)` and an optional `close()`, mirroring `ReadableStream`'s
+`UnderlyingSource`: `start` runs once and pushes snapshots via `control.set(value)`, while `close`
+— called from within `start` via `control.close()`, or from the outside via the `Source`'s own
+`close()` — is where you release whatever `start` set up, like a timer or an in-flight request.
+
+```ts
+import { Source } from "@jondotsoy/configs";
+
+function pollingSource(url: string, intervalMs: number): Source<{ port: number }> {
+  let timer: ReturnType<typeof setInterval>;
+
+  return new Source({
+    async start(control) {
+      const poll = async () => control.set((await (await fetch(url)).json()) as { port: number });
+      await poll();
+      timer = setInterval(poll, intervalMs);
+    },
+    close() {
+      clearInterval(timer);
+    },
+  });
+}
+```
+
+An optional `reduce(incoming, previous)` runs every `control.set(incoming)` call through it (along
+with the last published value, `null` before the first `set()`) instead of publishing `incoming`
+as-is — so a source whose `start()` only ever produces a partial patch (like `sseSource`, which
+hands `control.set` one SSE message at a time) can publish the merged result without keeping its
+own accumulator variable around:
+
+```ts
+const source = new Source<{ port?: number; host?: string }>({
+  start(control) {
+    control.set({ port: 3000 });   // -> reduce({ port: 3000 }, null)
+    control.set({ host: "x" });    // -> reduce({ host: "x" }, { port: 3000 })
+  },
+  reduce: (patch, previous) => ({ ...(previous ?? {}), ...patch }),
+});
+// published: { port: 3000, host: "x" }
+```
+
+### `envSource` — environment variables
+
+Reads `process.env` (or any object you pass as `env`) into the config tree. `mapKey` decides how
+each key maps to a path; the default is the identity mapping, `"FOO_TAR" => ["FOO_TAR"]`.
+
+Built-in strategies live under the `mapKey` namespace, each a factory returning an `EnvKeyMapper`:
+
+- **`mapKey.snakeCase(options?)`** — splits a `SCREAMING_SNAKE_CASE` 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:
+  `mapKey.snakeCase({ separator: "__" })` maps `"API_KEY_V2__ENABLED"` to
+  `["api_key_v2", "enabled"]` instead of splitting on every `_`.
+- **`mapKey.identity()`** — passes each key through unchanged, as a single-segment path:
+  `"FOO_TAR" => ["FOO_TAR"]`. Same as omitting `mapKey`, spelled out explicitly.
+- **`mapKey.camelCase()`** — maps a key to a single camelCase segment instead of nesting it:
+  `"FOO_TAR" => ["fooTar"]`.
+- **`mapKey.lookup(table, fallback?)`** — maps specific keys to explicit paths via a
+  `Record<string, string[]>` lookup table; a key not in `table` falls back to `fallback` (default:
+  the identity mapping). Handy when most keys follow no consistent naming, or when a few need an
+  exception to whatever strategy the rest use.
+
+```ts
+import { envSource, mapKey } from "@jondotsoy/configs";
+
+// SERVER_PORT=3000 SERVER_HOST=localhost → { server: { port: "3000", host: "localhost" } }
+const source = envSource({ mapKey: mapKey.snakeCase() });
+
+// PORT=3000 HOST=localhost → { server: { port: "3000" }, HOST: "localhost" }
+const source2 = envSource({ mapKey: mapKey.lookup({ PORT: ["server", "port"] }) });
+```
+
+You can also pass your own `EnvKeyMapper` instead of a built-in strategy — it's just a
+`(key: string) => string[]` function:
+
+```ts
+const source = envSource({
+  mapKey: (key) => (key === "PORT" ? ["server", "port"] : [key]),
+});
+```
+
+### `fetchSource` — a JSON endpoint over HTTP
+
+Fetches a JSON snapshot from `url` (with `method` and `headers`, if needed). Only JSON is
+supported — a non-JSON `Content-Type` still gets a fallback parse attempt. `attempts` retries the
+download on a network error or a non-`ok` response (default `1`, no retry). If the download never
+succeeds, or the body isn't valid JSON, it logs a `console.error` and leaves the store empty
+instead of throwing.
+
+```ts
+import { fetchSource } from "@jondotsoy/configs";
+
+const source = fetchSource<{ port: number }>({
+  url: "https://config-service.internal/app",
+  method: "GET",
+  headers: { authorization: `Bearer ${process.env.CONFIG_TOKEN}` },
+  attempts: 3,
+});
+```
+
+### `sseSource` — live updates over Server-Sent Events
+
+Connects to an SSE endpoint (`url`, `method`, `headers`). Every message tries to parse as JSON and,
+if it's a plain object, is applied as a **patch** on top of what was already received — fields add
+up and overwrite, the tree is never replaced wholesale:
+
+```ts
+import { sseSource } from "@jondotsoy/configs";
+
+const source = sseSource<{ port?: number; host?: string }>({
+  url: "https://config-service.internal/app/events",
+});
+
+// message: {"port":3000}       => Store<{ port: 3000 }>
+// message: {"host":"10.0.0.1"} => Store<{ port: 3000, host: "10.0.0.1" }>
+```
+
+A message that isn't valid JSON, or doesn't parse to a plain object, is logged via
+`console.error` and skipped — it never resets what was already received.
+
+Opening the source waits for the first message (so the `Store` you get back already has data,
+not `null`), then keeps the connection alive in the background, applying further messages as
+patches until the resource closes the stream.
+
+### `fileSource` — a local `.json` or `.env` file
+
+Reads a config tree from `path`, parsed by its extension: `.json` or `.env` (matched by extension,
+or by the bare `.env` filename itself — a `.env` file always parses to a flat string map, one
+entry per `KEY=VALUE` line, blank lines and `#`-comments skipped). `watch` defaults to `true`: the
+file is re-read and the store updated live on every change; `watch: false` reads it once. A
+missing file, an unrecognized extension, or a parse failure (including on a later watched change)
+is logged via `console.error` and leaves the store empty instead of throwing — a parse error on a
+later change keeps the last good value instead.
+
+```ts
+import { fileSource } from "@jondotsoy/configs";
+
+const source = fileSource<{ port: number; host: string }>("./config.json");
+// config.json: { "port": 3000, "host": "localhost" }
+```
+
+### `literalSource` — a static value
+
+Publishes a plain, already-in-hand value as a snapshot immediately, then closes. No I/O, no
+options — just wraps `value` in a `Source` so it can sit in a `sources` array alongside the rest.
+Handy as a static fallback tree (put it last so real sources win), a hardcoded default for a
+single environment, or a stand-in source in a test.
+
+```ts
+import { configs, envSource, literalSource, mapKey } from "@jondotsoy/configs";
+
+const cfg = await configs.create(
+  {
+    port: { type: "number", required: true },
+    host: { type: "string", required: true },
+  },
+  {
+    sources: [
+      envSource({ mapKey: mapKey.snakeCase() }),
+      literalSource({ port: 3000, host: "localhost" }), // fallback if env vars are unset
+    ],
+  },
+);
+```
+
+### Reacting to changes — restarting a periodic task
+
+Because every field is a live `Store`, `.subscribe()` is the hook point for keeping something
+else in sync with the config — for example, restarting a `setInterval` job whenever its period
+changes. This only really happens at runtime with a live source like `sseSource`; an
+`envSource` resolves once and never changes:
+
+```ts
+import { configs, sseSource } from "@jondotsoy/configs";
+
+async function cleanupTempFiles() {
+  // ...
+}
+
+const cfg = await configs.create(
+  {
+    service: configs.create({
+      cleanupIntervalMs: { type: "number", summary: "cleanup interval", default: 60_000 },
+    }),
+  },
+  { sources: [sseSource({ url: "https://config-service.internal/app/events" })] },
+);
+
+let timer: ReturnType<typeof setInterval> | undefined;
+
+const unsubscribe = cfg.service.cleanupIntervalMs.subscribe((intervalMs) => {
+  clearInterval(timer);
+  timer = setInterval(cleanupTempFiles, intervalMs);
+  return () => clearInterval(timer); // runs when `unsubscribe()` is called, not on the next change
+});
+```
+
+`subscribe` fires immediately with the current value (starting the first timer) and again on every
+subsequent change — `clearInterval(timer)` cancels the previous one before `setInterval` starts the
+new one, so there's never more than one timer running for this field. The callback's returned
+cleanup only fires once, when `unsubscribe()` itself is called, so it's the right place to stop the
+last timer for good — it's not a substitute for the `clearInterval` at the top of the callback.
+
+### Closing a config tree
+
+`configs.create(...)` results (and their nested groups) expose `close()`, which closes every
+source backing them — for `sseSource`, this aborts the live connection instead of leaving
+it open in the background:
+
+```ts
+import { configs, sseSource } from "@jondotsoy/configs";
+
+const source = sseSource({ url: "https://config-service.internal/app/events" });
+const serverConfigs = await configs.create({ port: { type: "number" } }, { sources: [source] });
+
+await serverConfigs.close();
+```
+
+It also implements `Symbol.asyncDispose`, so `await using` closes it automatically at the end of
+the scope — including when the scope throws:
+
+```ts
+import { configs, sseSource } from "@jondotsoy/configs";
+
+async function run() {
+  await using serverConfigs = await configs.create(
+    { port: { type: "number" } },
+    { sources: [sseSource({ url: "https://config-service.internal/app/events" })] },
+  );
+
+  console.log(serverConfigs.port.get());
+  // closed automatically here, no explicit serverConfigs.close() needed
+}
+```

package/dist/config.types.d.ts

@@ -0,0 +1,177 @@
+import { Source } from "./sources/source";
+import { Store, type Subscriber, type Unsubscribe } from "./utils/store";
+export type FieldType = "string" | "number" | "boolean";
+interface BaseFieldSchema {
+    summary?: string;
+    required?: boolean;
+    /** Freezes the field at its first resolved value: later source updates no longer reach `.get()`. */
+    readonly?: boolean;
+}
+export type FieldSchema = (BaseFieldSchema & {
+    type: "string";
+    pattern?: RegExp;
+    default?: string;
+}) | (BaseFieldSchema & {
+    type: "number";
+    default?: number;
+}) | (BaseFieldSchema & {
+    type: "boolean";
+    default?: boolean;
+});
+export interface CreateOptions {
+    sources?: Source<any>[];
+    /**
+     * Static, lowest-priority fallback tree — checked after every source, before a field's own `default`.
+     * @deprecated No longer read by `configs.create()`.
+     */
+    defaultValues?: unknown;
+}
+/**
+ * Discriminates a nested group from a leaf field inside a `SchemaShape`. Deliberately not generic
+ * (unlike `SchemaGroup<S>` below): a generic member here — even `SchemaGroup<any>` — becomes the
+ * contextual type TypeScript propagates into a nested `configs.create(...)` call written inline as
+ * a shape property, and `any` there widens every literal `type: "string"` inside it to `string`,
+ * breaking every field's inferred type. This plain marker carries no such poison.
+ */
+interface SchemaGroupNode {
+    readonly shape: SchemaShape;
+}
+export type SchemaNode = FieldSchema | SchemaGroupNode;
+export type SchemaShape = Record<string, SchemaNode>;
+type PrimitiveOfField<F extends FieldSchema> = F extends {
+    type: "number";
+} ? number : F extends {
+    type: "string";
+} ? string : F extends {
+    type: "boolean";
+} ? boolean : never;
+/**
+ * A field only ever resolves to `null` when no source has it and it has no `default` — data comes
+ * from async sources that may simply have nothing, so `required` documents intent but can't be enforced
+ * at runtime and doesn't affect this type.
+ */
+type HasDefault<F extends FieldSchema> = F extends {
+    default: any;
+} ? true : false;
+type InferFieldValue<F extends FieldSchema> = HasDefault<F> extends true ? PrimitiveOfField<F> : PrimitiveOfField<F> | null;
+type InferField<F extends SchemaNode> = F extends ConfigNode<infer S> ? InferShape<S> : F extends FieldSchema ? InferFieldValue<F> : never;
+export type InferShape<S extends SchemaShape> = {
+    [K in keyof S]: InferField<S[K]>;
+};
+/** A read-only view of a `Store<T>`: exposes `get`/`subscribe`/`listen` but never `set`. */
+export interface ReadOnlyStore<T> {
+    get(): T;
+    /** Calls `subscriber` immediately with the current value, then on every subsequent update. */
+    subscribe(subscriber: Subscriber<T>): Unsubscribe;
+    /** Calls `subscriber` only on subsequent updates, not with the current value. */
+    listen(subscriber: Subscriber<T>): Unsubscribe;
+}
+type InferReadOnlyAccessor<F extends SchemaNode> = F extends ConfigNode<infer S> ? SchemaGroup<S> : F extends FieldSchema ? ReadOnlyStore<InferFieldValue<F>> : never;
+/** Shape of the live proxy returned by `configs.create()`: a leaf field is a read-only `ReadOnlyStore<T>`, a nested group is a `SchemaGroup`. */
+export type InferReadOnlyAccessors<S extends SchemaShape> = {
+    [K in keyof S]: InferReadOnlyAccessor<S[K]>;
+};
+/** A leaf config field, live as a `Store<T>`: read-only — `set()` always throws. */
+declare class ConfigField<T> extends Store<T> {
+    set(): void;
+    /** Pushes a recomputed value when an upstream source changes, bypassing the public read-only `set()`. */
+    _update(value: T): void;
+}
+/**
+ * The engine behind a `ConfigNode`/`ConfigNodeResolved`: resolves fields from `rootStores` (in
+ * priority order), caches field/child-group instances, and recomputes them live as `rootStores`
+ * change. A nested group embedded in a parent (via `configs.create(shape)` with no `options`)
+ * shares its parent's `rootStores`; one created with its own `sources` (root form) resolves
+ * independently, tracked via `ownsResolution`.
+ */
+declare class ConfigNodeState<S extends SchemaShape> {
+    readonly shape: S;
+    private readonly basePath;
+    private readonly ownSources;
+    readonly ownsResolution: boolean;
+    /** The sources this node's (or an ancestor's) `close()` actually closes. */
+    private readonly closableSources;
+    private rootStores;
+    private readonly fields;
+    private readonly children;
+    private snapshotStore;
+    readonly readyPromise: Promise<void>;
+    constructor(shape: S, rootStores: Store<any>[], basePath: string[], ownSources: Source<any>[], ownsResolution: boolean, 
+    /** The sources this node's (or an ancestor's) `close()` actually closes. */
+    closableSources: Source<any>[]);
+    private wireLiveUpdates;
+    private resolveField;
+    private refreshFields;
+    private refreshSnapshot;
+    fieldFor(key: string): ConfigField<any>;
+    childNode(key: string): object;
+    get(): InferShape<S>;
+    set(key: string): never;
+    private ensureSnapshotStore;
+    subscribe(subscriber: Subscriber<InferShape<S>>): Unsubscribe;
+    listen(subscriber: Subscriber<InferShape<S>>): Unsubscribe;
+    close(): Promise<void>;
+}
+/**
+ * Shared, non-thenable base behind both `ConfigNode` and `ConfigNodeResolved`: a resolved node
+ * must not itself be thenable (awaiting a thenable whose `then()` resolves to itself is a
+ * chaining cycle, both at runtime per the Promise spec and in TypeScript's `Awaited<T>`, which
+ * rejects the type outright with a "referenced directly or indirectly in the fulfillment
+ * callback of its own `then` method" error) — so `then()` lives only on `ConfigNode`, added by a
+ * sibling subclass rather than inherited.
+ */
+declare class ConfigNodeCore<S extends SchemaShape> {
+    readonly _state: ConfigNodeState<S>;
+    constructor(_state: ConfigNodeState<S>);
+    get shape(): S;
+    /** Snapshot of every field's current value, recursing into nested groups. */
+    get(): InferShape<S>;
+    /** Always throws: config values are read-only. */
+    set<K extends keyof S & string>(key: K, _value: InferShape<S>[K]): void;
+    /** Calls `subscriber` immediately with the current snapshot (per `get()`), then again on every subsequent change to it. */
+    subscribe(subscriber: Subscriber<InferShape<S>>): Unsubscribe;
+    /** Calls `subscriber` only on a subsequent change to the snapshot, not with the current one. */
+    listen(subscriber: Subscriber<InferShape<S>>): Unsubscribe;
+    /** Closes every source backing this config tree, including nested groups' own. A no-op for a nested-form group of its own. */
+    close(): Promise<void>;
+    /** Enables `await using s = await configs.create(...)`: disposal closes the config tree. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** A `ConfigNode` once every source behind it has published its first snapshot. Synchronous only — no longer thenable. */
+export declare class ConfigNodeResolved<S extends SchemaShape> extends ConfigNodeCore<S> {
+}
+/**
+ * `configs.create()`'s return value: synchronous and read-only, but also a `PromiseLike` —
+ * awaiting it resolves once every source has published its first snapshot, yielding a
+ * `ConfigNodeResolved`. A nested group (`configs.create(shape)` with no `options`) never needs
+ * awaiting: it shares its parent's already-resolved values unless given sources of its own.
+ */
+export declare class ConfigNode<S extends SchemaShape> extends ConfigNodeCore<S> implements PromiseLike<ConfigNodeResolved<S> & InferReadOnlyAccessors<S>> {
+    /**
+     * `ConfigNodeResolved` is a sibling class, not a subclass (see the note on `ConfigNodeCore`),
+     * so it fails a plain `instanceof ConfigNode` check. Custom `Symbol.hasInstance` widens that
+     * check to "any `ConfigNodeCore`" instead, which both classes satisfy — without giving
+     * `ConfigNodeResolved` a real `then()` and reintroducing the chaining cycle.
+     */
+    static [Symbol.hasInstance](instance: unknown): boolean;
+    then<TResult1 = ConfigNodeResolved<S> & InferReadOnlyAccessors<S>, TResult2 = never>(onfulfilled?: ((value: ConfigNodeResolved<S> & InferReadOnlyAccessors<S>) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
+}
+/**
+ * A nested config group embedded in a parent shape: either shares the parent's resolved values,
+ * or — when created with its own `sources` — resolves independently of it.
+ */
+export type SchemaGroup<S extends SchemaShape = SchemaShape> = ConfigNode<S> & InferReadOnlyAccessors<S>;
+/**
+ * Nested-group form (no `options`): synchronous, no sources of its own — inherits the
+ * parent's resolved values when embedded, unless `options` gives it its own.
+ *
+ * Root form (`options` given): opens every source. Returns synchronously as a `ConfigNode`
+ * and is awaitable — for each field, the first source (in array order) whose snapshot has
+ * that field wins; a field missing everywhere falls back to the field's own `default`, else `null`.
+ */
+export declare function createConfigNode<S extends SchemaShape>(shape: S, options?: CreateOptions): ConfigNode<S> & InferReadOnlyAccessors<S>;
+/** The type of the `configs` namespace object. */
+export interface configs {
+    create<S extends SchemaShape>(shape: S, options?: CreateOptions): ConfigNode<S> & InferReadOnlyAccessors<S>;
+}
+export {};

package/dist/configs.d.ts

@@ -0,0 +1,21 @@
+import type { configs as ConfigsApi } from "./config.types";
+export type { CreateOptions, FieldSchema, FieldType, InferReadOnlyAccessors, InferShape, ReadOnlyStore, SchemaGroup, SchemaNode, SchemaShape, } from "./config.types";
+export type { SourceControl, UnderlyingSource } from "./types";
+export type { DataType, DataTypeName } from "./utils/data-types";
+export type { EnvSourceOptions, EnvKeyMapper } from "./sources/env";
+export type { FetchSourceOptions } from "./sources/fetch";
+export type { SseSourceOptions } from "./sources/sse";
+export type { FileSourceOptions } from "./sources/file";
+export { ConfigNode, ConfigNodeResolved } from "./config.types";
+export { Source } from "./sources/source";
+export { envSource, mapKey } from "./sources/env";
+export { fetchSource } from "./sources/fetch";
+export { sseSource } from "./sources/sse";
+export { fileSource } from "./sources/file";
+export { literalSource } from "./sources/literal";
+export { Store } from "./utils/store";
+export { DataTypes } from "./utils/data-types";
+export { DotEnv } from "./utils/dotenv";
+export { ConfigError } from "./errors";
+export declare const configs: ConfigsApi;
+export default configs;