@evinvest/settings 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# `@evinvest/settings`
+
+Typed, validated env settings with aggregate error reporting and a
+server/client split — **zero runtime dependencies**, one server-safe,
+browser-safe ESM entry. The TypeScript mirror of the `settings` Cargo feature
+of [`ev_lib`](../../rust/src/settings).
+
+> This package reads **environment variables only** — no config files, no hot
+> reload, and no decryption: secrets management stays at the shell/CI boundary
+> (sops + age). See the [GUIDE](./GUIDE.md) and the Rust
+> [GUIDE](../../rust/src/settings/GUIDE.md#secrets-the-sops-boundary) for the
+> full sops workflow.
+
+## Install
+
+```sh
+npm i @evinvest/settings
+```
+
+## Usage
+
+One `settings.ts` per app, evaluated at module scope so a bad environment fails
+the boot — and, imported from `next.config.*`, the build:
+
+```ts
+import { createSettings, list, port, presets, secret, str, url, withDefault } from '@evinvest/settings';
+
+export const settings = createSettings({
+  server: {
+    SESSION_REDIS_URL: url(),
+    PORT: withDefault(port(), '8080'),
+    BANKING_ISSUANCE_TOKEN: secret(str()),
+    MFE_ALLOWED_ORIGINS: withDefault(list(), ''),
+    ...presets.posthog(), // POSTHOG_KEY / POSTHOG_HOST, canonical names
+  },
+  clientPrefix: 'NEXT_PUBLIC_',
+  client: {
+    ...presets.posthogClient(), // NEXT_PUBLIC_POSTHOG_KEY / _HOST
+  },
+  // explicit destructure: bundlers inline NEXT_PUBLIC_* / import.meta.env.*
+  // only for static member expressions
+  runtimeEnv: {
+    SESSION_REDIS_URL: process.env.SESSION_REDIS_URL,
+    PORT: process.env.PORT,
+    BANKING_ISSUANCE_TOKEN: process.env.BANKING_ISSUANCE_TOKEN,
+    MFE_ALLOWED_ORIGINS: process.env.MFE_ALLOWED_ORIGINS,
+    POSTHOG_KEY: process.env.POSTHOG_KEY,
+    POSTHOG_HOST: process.env.POSTHOG_HOST,
+    NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,
+    NEXT_PUBLIC_POSTHOG_HOST: process.env.NEXT_PUBLIC_POSTHOG_HOST,
+  },
+});
+
+settings.PORT;                    // number — typed, validated
+settings.POSTHOG_KEY;             // string | undefined (optional)
+// on the client: settings.SESSION_REDIS_URL throws (server-only)
+```
+
+A missing/invalid environment throws one `SettingsError` listing **every**
+problem:
+
+```text
+invalid settings (2 problems)
+  - SESSION_REDIS_URL: missing
+  - PORT: invalid value "banana": expected a finite number
+```
+
+Validators: `str`, `num`, `int`, `port`, `bool`, `url`, `list`, `oneOf` —
+refined by `optional(v)`, `withDefault(v, 'literal')`, `secret(v)`.
+
+## Rust ↔ TS parity
+
+The Rust crate is the source of truth; this package preserves its *semantics*.
+The full mapping table lives in the Rust
+[README](../../rust/src/settings/README.md#rust--ts-parity); the load-bearing
+shared rules:
+
+- var names are written-out SCREAMING_SNAKE keys; required by default;
+  `optional(v)` ↔ `Option<T>`; `withDefault(v, lit)` ↔ `= "lit"` (the literal
+  parses by the same rules, only when unset).
+- the **empty string is unset**; `bool` accepts `true`/`false`/`1`/`0`
+  case-insensitively; `list` splits on `,`, trims items, drops empty items;
+  scalars are **not** trimmed; number grammar matches Rust `FromStr` (`int`:
+  plain decimal; `num`: decimal/point/exponent, no hex). Documented
+  divergences: JS numbers are doubles, so `num()` requires finite values
+  (Rust `f64` also accepts `inf`/`NaN`) and `int()` stops at the safe range
+  `±(2^53 - 1)` — use `str()` for 64-bit ids.
+- errors aggregate into one `SettingsError` (message shape shared with the
+  Rust `Display` impl); `secret(v)` redacts values in error output.
+- the contract is pinned by mirrored vectors:
+  [`test/contract.node.test.ts`](./test/contract.node.test.ts) ↔
+  `rust/src/settings/tests.rs` (`mod contract`). Change both sides or neither.
+
+TS-only (browser-bundler concerns, no Rust equivalent): the `server`/`client`
+split with `clientPrefix`, the explicit `runtimeEnv` destructure, and the
+`NEXT_PUBLIC_*` client presets.
+
+## Limitations
+
+- **Env-only, flat.** No config files, no `__` nesting — by design.
+- **`runtimeEnv` must destructure explicitly** for client vars: bundlers
+  (Next.js `NEXT_PUBLIC_*`, Vite `import.meta.env`) inline only static member
+  expressions at build time.
+- **`secret(v)` redacts what the library emits** (errors/issues). JS has no
+  `Debug` boundary — `console.log(settings.TOKEN)` still prints the value
+  (unlike Rust, where the generated `Debug` prints `***`).
+- **Worker runtimes:** the default server detection is "no `window` in
+  `globalThis`" — pass `isServer` explicitly in web workers.
+
+## Develop
+
+```sh
+npm run typecheck && npm test && npm run build
+```

package/dist/index.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Aggregate settings failure — every missing/invalid variable found in one
+ * pass, mirroring `SettingsError` of the Rust `settings` feature. The message
+ * format is kept in step with the Rust `Display` impl:
+ *
+ * ```text
+ * invalid settings (2 problems)
+ *   - DATABASE_URL: missing
+ *   - PORT: invalid value "abc": expected an integer
+ * ```
+ */
+/** What went wrong with one variable. */
+type SettingsIssueKind = 'missing' | 'invalid';
+/** One problem with one variable. */
+interface SettingsIssue {
+    /** The env var name as it was looked up. */
+    readonly key: string;
+    readonly kind: SettingsIssueKind;
+    /** For `invalid` issues: what went wrong while parsing. */
+    readonly detail?: string;
+    /** The offending raw value. Omitted for `secret(...)` settings. */
+    readonly value?: string;
+}
+/**
+ * Thrown by {@link createSettings} when any variable is missing or invalid.
+ * Carries every problem at once — fix the whole list in one edit instead of
+ * replaying the boot loop per variable.
+ */
+declare class SettingsError extends Error {
+    readonly issues: readonly SettingsIssue[];
+    constructor(issues: readonly SettingsIssue[]);
+}
+
+/**
+ * Validators — how a raw env string becomes a typed value, and the three
+ * wrappers that mirror the Rust field grammar: {@link optional} ↔ `Option<T>`,
+ * {@link withDefault} ↔ `= "literal"`, {@link secret} ↔ `#[secret]`.
+ *
+ * The shared Rust↔TS parsing contract lives here: `bool` accepts
+ * `true`/`false`/`1`/`0` case-insensitively, {@link list} is comma-separated
+ * with trimmed items and empty items dropped, and scalars are **not** trimmed —
+ * `" 8080"` is invalid for a number on both sides.
+ */
+/**
+ * Parses one env value into a typed setting. Build one with {@link str},
+ * {@link num}, {@link int}, {@link port}, {@link bool}, {@link url},
+ * {@link list}, or {@link oneOf}, then refine it with {@link optional},
+ * {@link withDefault}, and {@link secret}.
+ *
+ * The named validators are idiomatic TS and deliberately *not* a 1:1 copy of
+ * the Rust side, where types parse themselves through the `FromEnvValue` trait
+ * (`port: u16`, `bind: SocketAddr`); what both sides share is the semantics
+ * listed in the module docs.
+ */
+interface Validator<T> {
+    /** Human name used in error messages (e.g. `number`). */
+    readonly kind: string;
+    /** Unset is fine and yields `undefined` — the mirror of `Option<T>`. */
+    readonly optional: boolean;
+    /** Redact the raw value in error output — the mirror of `#[secret]`. */
+    readonly secret: boolean;
+    /** Used when the variable is unset; parsed by the same rules as an env value. */
+    readonly defaultLiteral: string | undefined;
+    /** Parse a raw (non-empty) env string; throws `Error(message)` when invalid. */
+    readonly parse: (raw: string) => T;
+}
+/** Any string, taken verbatim (no trimming). */
+declare function str(): Validator<string>;
+/** Contract: `true`/`1` and `false`/`0`, case-insensitive, no trimming. */
+declare function bool(): Validator<boolean>;
+/**
+ * A finite decimal number (point/exponent forms included). Not trimmed:
+ * `" 3"` is invalid, like Rust's `FromStr`. Divergence from the Rust mirror:
+ * Rust `f64` also accepts `inf`/`NaN` — this validator requires finite.
+ */
+declare function num(): Validator<number>;
+/**
+ * A plain decimal integer (no exponent/point/hex forms — Rust integer
+ * `FromStr` grammar), limited to the safe range `±(2^53 - 1)`: JS numbers are
+ * doubles, so bigger values would silently round (Rust 64-bit integers parse
+ * them exactly — use {@link str} for 64-bit ids).
+ */
+declare function int(): Validator<number>;
+/** A TCP/UDP port: an integer in `1..=65535`. */
+declare function port(): Validator<number>;
+/** An absolute URL (validated with `new URL`, returned as the original string). */
+declare function url(): Validator<string>;
+/**
+ * One of a fixed set of strings, narrowed to the literal union:
+ *
+ * ```ts
+ * const env = oneOf(['development', 'production']); // Validator<'development' | 'production'>
+ * ```
+ */
+declare function oneOf<const V extends string>(values: readonly V[]): Validator<V>;
+/**
+ * Contract: split on `,`, trim each item, drop empty items, parse the rest
+ * with `item` (default {@link str}). Item numbering in errors counts the kept
+ * items from 1 and never leaks the item value, so secret lists stay
+ * redactable. Wrap the *list* in {@link secret}/{@link optional}, not the item.
+ */
+declare function list(): Validator<readonly string[]>;
+declare function list<T>(item: Validator<T>): Validator<readonly T[]>;
+/**
+ * Unset (or empty) is fine and yields `undefined` — the mirror of a Rust
+ * `Option<T>` field. Cannot be combined with {@link withDefault}: a defaulted
+ * setting is always present ({@link createSettings} rejects the combination).
+ */
+declare function optional<T>(validator: Validator<T>): Validator<T | undefined>;
+/**
+ * Fall back to `literal` when the variable is unset. The literal goes through
+ * the exact same parsing rules as an env value — the mirror of the Rust
+ * `= "literal"` field default.
+ */
+declare function withDefault<T>(validator: Validator<T>, literal: string): Validator<T>;
+/**
+ * Redact the raw value in error output — the mirror of `#[secret]`. Note that
+ * unlike Rust (whose generated `Debug` prints `***`), JS has no debug-print
+ * boundary: `console.log(settings.TOKEN)` prints the real value. The redaction
+ * covers what the *library* emits: `SettingsError` messages and issues.
+ */
+declare function secret<T>(validator: Validator<T>): Validator<T>;
+
+/**
+ * {@link createSettings} — read a validated, typed settings object out of an
+ * explicitly injected environment record, with a server/client split for
+ * browser bundles.
+ */
+
+/** A settings declaration: env var name → {@link Validator}. */
+type SettingsSchema = Record<string, Validator<unknown>>;
+/** The typed settings object a schema produces. */
+type InferSettings<S extends SettingsSchema> = {
+    readonly [K in keyof S]: S[K] extends Validator<infer T> ? T : never;
+};
+interface CreateSettingsOptions<S extends SettingsSchema, C extends SettingsSchema> {
+    /** Server-only settings. Accessing one from client code throws. */
+    readonly server?: S;
+    /**
+     * Client-exposable settings. Every key must start with {@link clientPrefix}
+     * so nothing leaks into a browser bundle by accident.
+     */
+    readonly client?: C;
+    /** Required when `client` is non-empty — e.g. `NEXT_PUBLIC_`. */
+    readonly clientPrefix?: string;
+    /**
+     * The environment record, destructured **explicitly** — bundlers inline
+     * `process.env.NEXT_PUBLIC_*` / `import.meta.env.*` at build time only when
+     * each variable is a static member expression, so a bare `process.env` pass
+     * works on the server but leaves client values undefined in the browser:
+     *
+     * ```ts
+     * runtimeEnv: {
+     *   DATABASE_URL: process.env.DATABASE_URL,
+     *   NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,
+     * }
+     * ```
+     */
+    readonly runtimeEnv: Readonly<Record<string, string | undefined>>;
+    /** Contract: `VAR=` (empty string) behaves like unset. Default `true`. */
+    readonly emptyStringAsUnset?: boolean;
+    /**
+     * Where we are running. Default: `window` is absent from `globalThis`.
+     * Override for workers or exotic runtimes.
+     */
+    readonly isServer?: boolean;
+}
+/**
+ * Validate the injected environment against the schema and return the typed,
+ * read-only settings object. Mirrors the Rust `settings!` macro's
+ * `from_source`, plus the client/server split (a bundler concern with no Rust
+ * equivalent).
+ *
+ * - Every missing/invalid variable is reported at once in one
+ *   {@link SettingsError} — no fix-one-reboot-fix-next loops.
+ * - Validation runs eagerly, at the `createSettings` call. Call it at module
+ *   scope of a single `settings.ts` so a bad environment fails the boot (or,
+ *   in Next.js, the build — import your settings module from `next.config`).
+ * - On the client only the `client` schema is validated (server values never
+ *   reach the bundle); accessing a server key there throws.
+ *
+ * @example
+ * ```ts
+ * export const settings = createSettings({
+ *   server: {
+ *     DATABASE_URL: url(),
+ *     SIGNING_KEY: secret(str()),
+ *     PORT: withDefault(port(), '8080'),
+ *     ...presets.posthog(),
+ *   },
+ *   clientPrefix: 'NEXT_PUBLIC_',
+ *   client: { ...presets.posthogClient() },
+ *   runtimeEnv: {
+ *     DATABASE_URL: process.env.DATABASE_URL,
+ *     SIGNING_KEY: process.env.SIGNING_KEY,
+ *     PORT: process.env.PORT,
+ *     POSTHOG_KEY: process.env.POSTHOG_KEY,
+ *     POSTHOG_HOST: process.env.POSTHOG_HOST,
+ *     NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,
+ *     NEXT_PUBLIC_POSTHOG_HOST: process.env.NEXT_PUBLIC_POSTHOG_HOST,
+ *   },
+ * });
+ * ```
+ */
+declare function createSettings<S extends SettingsSchema = Record<never, never>, C extends SettingsSchema = Record<never, never>>(options: CreateSettingsOptions<S, C>): InferSettings<S> & InferSettings<C>;
+
+/**
+ * Org-canonical shared variable groups — one place that fixes the names, so
+ * `POSTHOG_KEY` vs `POSTHOG_API_KEY` vs `NEXT_PUBLIC_POSTHOG_KEY` drift stops
+ * at the source. Spread a preset into the `server` / `client` block of
+ * {@link createSettings}; the Rust mirror ships the same server-side groups as
+ * ready-made structs (`settings::presets`).
+ */
+
+declare const presets: {
+    /**
+     * PostHog capture credentials, canonical names: `POSTHOG_KEY` /
+     * `POSTHOG_HOST`. Both optional — capture is simply off without them. The
+     * project key (`phc_…`) is write-only and ships in frontend bundles anyway,
+     * so it is not `secret(...)`.
+     */
+    readonly posthog: () => {
+        POSTHOG_KEY: Validator<string | undefined>;
+        POSTHOG_HOST: Validator<string | undefined>;
+    };
+    /**
+     * Sentry reporting, canonical name: `SENTRY_DSN`. Optional — monitoring is
+     * off without it. A DSN authorises event *submission* only, so it is not
+     * `secret(...)`.
+     */
+    readonly sentry: () => {
+        SENTRY_DSN: Validator<string | undefined>;
+    };
+    /**
+     * The deployment environment, canonical name: `APP_ENV`. Defaults to
+     * `development`; kept a free string on purpose — constraining the values
+     * would break consumers that add a stage.
+     */
+    readonly appEnv: () => {
+        APP_ENV: Validator<string>;
+    };
+    /** The `client`-block variant of {@link presets.posthog} for Next.js bundles. */
+    readonly posthogClient: () => {
+        NEXT_PUBLIC_POSTHOG_KEY: Validator<string | undefined>;
+        NEXT_PUBLIC_POSTHOG_HOST: Validator<string | undefined>;
+    };
+    /** The `client`-block variant of {@link presets.sentry} + `APP_ENV` for Next.js bundles. */
+    readonly sentryClient: () => {
+        NEXT_PUBLIC_SENTRY_DSN: Validator<string | undefined>;
+        NEXT_PUBLIC_APP_ENV: Validator<string>;
+    };
+};
+
+export { type CreateSettingsOptions, type InferSettings, SettingsError, type SettingsIssue, type SettingsIssueKind, type SettingsSchema, type Validator, bool, createSettings, int, list, num, oneOf, optional, port, presets, secret, str, url, withDefault };

package/dist/index.js

@@ -0,0 +1,241 @@
+// src/error.ts
+var SettingsError = class extends Error {
+  issues;
+  constructor(issues) {
+    super(formatIssues(issues));
+    this.name = "SettingsError";
+    this.issues = issues;
+  }
+};
+function formatIssues(issues) {
+  const noun = issues.length === 1 ? "problem" : "problems";
+  const lines = issues.map((issue) => `  - ${formatIssue(issue)}`);
+  return [`invalid settings (${issues.length} ${noun})`, ...lines].join("\n");
+}
+function formatIssue(issue) {
+  if (issue.kind === "missing") return `${issue.key}: missing`;
+  const value = issue.value === void 0 ? "" : ` ${JSON.stringify(issue.value)}`;
+  return `${issue.key}: invalid value${value}: ${issue.detail ?? "failed to parse"}`;
+}
+
+// src/validators.ts
+function base(kind, parse) {
+  return { kind, optional: false, secret: false, defaultLiteral: void 0, parse };
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function str() {
+  return base("string", (raw) => raw);
+}
+function bool() {
+  return base("boolean", (raw) => {
+    const lower = raw.toLowerCase();
+    if (lower === "true" || lower === "1") return true;
+    if (lower === "false" || lower === "0") return false;
+    throw new Error("expected one of `true`, `false`, `1`, `0` (case-insensitive)");
+  });
+}
+var FLOAT_GRAMMAR = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+var INT_GRAMMAR = /^[+-]?\d+$/;
+function num() {
+  return base("number", (raw) => {
+    if (!FLOAT_GRAMMAR.test(raw)) throw new Error("expected a finite number");
+    const value = Number(raw);
+    if (!Number.isFinite(value)) throw new Error("expected a finite number");
+    return value;
+  });
+}
+function int() {
+  return base("integer", (raw) => {
+    if (!INT_GRAMMAR.test(raw)) throw new Error("expected an integer");
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value)) throw new Error("expected a safe integer (within \xB1(2^53 - 1))");
+    return value;
+  });
+}
+function port() {
+  const inner = int();
+  return base("port", (raw) => {
+    const value = inner.parse(raw);
+    if (value < 1 || value > 65535) throw new Error("expected a port (1-65535)");
+    return value;
+  });
+}
+function url() {
+  return base("url", (raw) => {
+    if (raw === "" || /\s/.test(raw)) throw new Error("expected an absolute URL");
+    try {
+      new URL(raw);
+    } catch {
+      throw new Error("expected an absolute URL");
+    }
+    return raw;
+  });
+}
+function oneOf(values) {
+  const expected = `expected one of ${values.map((value) => `\`${value}\``).join(", ")}`;
+  return base("choice", (raw) => {
+    if (values.includes(raw)) return raw;
+    throw new Error(expected);
+  });
+}
+function list(item) {
+  const inner = item ?? str();
+  return base(
+    "list",
+    (raw) => raw.split(",").map((piece) => piece.trim()).filter((piece) => piece !== "").map((piece, index) => {
+      try {
+        return inner.parse(piece);
+      } catch (error) {
+        throw new Error(`item ${index + 1}: ${messageOf(error)}`);
+      }
+    })
+  );
+}
+function optional(validator) {
+  return { ...validator, optional: true };
+}
+function withDefault(validator, literal) {
+  return { ...validator, defaultLiteral: literal };
+}
+function secret(validator) {
+  return { ...validator, secret: true };
+}
+
+// src/create-settings.ts
+function createSettings(options) {
+  const server = options.server ?? {};
+  const client = options.client ?? {};
+  const { clientPrefix } = options;
+  const emptyAsUnset = options.emptyStringAsUnset ?? true;
+  const isServer = options.isServer ?? !("window" in globalThis);
+  const serverKeys = Object.keys(server);
+  const clientKeys = Object.keys(client);
+  if (clientKeys.length > 0 && clientPrefix === void 0) {
+    throw new Error("@evinvest/settings: `clientPrefix` is required when `client` settings are declared");
+  }
+  for (const key of serverKeys) {
+    if (Object.hasOwn(client, key)) {
+      throw new Error(`@evinvest/settings: setting "${key}" is declared in both server and client`);
+    }
+  }
+  if (clientPrefix !== void 0) {
+    for (const key of clientKeys) {
+      if (!key.startsWith(clientPrefix)) {
+        throw new Error(`@evinvest/settings: client setting "${key}" must start with clientPrefix "${clientPrefix}"`);
+      }
+    }
+    for (const key of serverKeys) {
+      if (key.startsWith(clientPrefix)) {
+        throw new Error(
+          `@evinvest/settings: server setting "${key}" starts with clientPrefix "${clientPrefix}" \u2014 declare it under \`client\``
+        );
+      }
+    }
+  }
+  for (const [key, validator] of [...Object.entries(server), ...Object.entries(client)]) {
+    if (validator.optional && validator.defaultLiteral !== void 0) {
+      throw new Error(
+        `@evinvest/settings: setting "${key}" is both optional and defaulted \u2014 a defaulted setting is always present, drop one`
+      );
+    }
+  }
+  const active = isServer ? { ...server, ...client } : client;
+  const issues = [];
+  const values = {};
+  for (const [key, validator] of Object.entries(active)) {
+    let raw = options.runtimeEnv[key];
+    if (emptyAsUnset && raw === "") raw = void 0;
+    const fromDefault = raw === void 0 && validator.defaultLiteral !== void 0;
+    if (fromDefault) raw = validator.defaultLiteral;
+    if (raw === void 0) {
+      if (validator.optional) {
+        values[key] = void 0;
+        continue;
+      }
+      issues.push({ key, kind: "missing" });
+      continue;
+    }
+    try {
+      values[key] = validator.parse(raw);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      issues.push({
+        key,
+        kind: "invalid",
+        detail: fromDefault ? `invalid default: ${message}` : message,
+        ...validator.secret && !fromDefault ? {} : { value: raw }
+      });
+    }
+  }
+  if (issues.length > 0) throw new SettingsError(issues);
+  Object.freeze(values);
+  const serverOnly = new Set(serverKeys);
+  return new Proxy(values, {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      if (!isServer && serverOnly.has(prop)) {
+        throw new Error(`@evinvest/settings: attempted to access server-only setting "${prop}" on the client`);
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+
+// src/presets.ts
+var presets = {
+  /**
+   * PostHog capture credentials, canonical names: `POSTHOG_KEY` /
+   * `POSTHOG_HOST`. Both optional — capture is simply off without them. The
+   * project key (`phc_…`) is write-only and ships in frontend bundles anyway,
+   * so it is not `secret(...)`.
+   */
+  posthog: () => ({
+    POSTHOG_KEY: optional(str()),
+    POSTHOG_HOST: optional(str())
+  }),
+  /**
+   * Sentry reporting, canonical name: `SENTRY_DSN`. Optional — monitoring is
+   * off without it. A DSN authorises event *submission* only, so it is not
+   * `secret(...)`.
+   */
+  sentry: () => ({
+    SENTRY_DSN: optional(str())
+  }),
+  /**
+   * The deployment environment, canonical name: `APP_ENV`. Defaults to
+   * `development`; kept a free string on purpose — constraining the values
+   * would break consumers that add a stage.
+   */
+  appEnv: () => ({
+    APP_ENV: withDefault(str(), "development")
+  }),
+  /** The `client`-block variant of {@link presets.posthog} for Next.js bundles. */
+  posthogClient: () => ({
+    NEXT_PUBLIC_POSTHOG_KEY: optional(str()),
+    NEXT_PUBLIC_POSTHOG_HOST: optional(str())
+  }),
+  /** The `client`-block variant of {@link presets.sentry} + `APP_ENV` for Next.js bundles. */
+  sentryClient: () => ({
+    NEXT_PUBLIC_SENTRY_DSN: optional(str()),
+    NEXT_PUBLIC_APP_ENV: withDefault(str(), "development")
+  })
+};
+export {
+  SettingsError,
+  bool,
+  createSettings,
+  int,
+  list,
+  num,
+  oneOf,
+  optional,
+  port,
+  presets,
+  secret,
+  str,
+  url,
+  withDefault
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/error.ts","../src/validators.ts","../src/create-settings.ts","../src/presets.ts"],"sourcesContent":["/**\n * Aggregate settings failure — every missing/invalid variable found in one\n * pass, mirroring `SettingsError` of the Rust `settings` feature. The message\n * format is kept in step with the Rust `Display` impl:\n *\n * ```text\n * invalid settings (2 problems)\n *   - DATABASE_URL: missing\n *   - PORT: invalid value \"abc\": expected an integer\n * ```\n */\n\n/** What went wrong with one variable. */\nexport type SettingsIssueKind = 'missing' | 'invalid';\n\n/** One problem with one variable. */\nexport interface SettingsIssue {\n  /** The env var name as it was looked up. */\n  readonly key: string;\n  readonly kind: SettingsIssueKind;\n  /** For `invalid` issues: what went wrong while parsing. */\n  readonly detail?: string;\n  /** The offending raw value. Omitted for `secret(...)` settings. */\n  readonly value?: string;\n}\n\n/**\n * Thrown by {@link createSettings} when any variable is missing or invalid.\n * Carries every problem at once — fix the whole list in one edit instead of\n * replaying the boot loop per variable.\n */\nexport class SettingsError extends Error {\n  readonly issues: readonly SettingsIssue[];\n\n  constructor(issues: readonly SettingsIssue[]) {\n    super(formatIssues(issues));\n    this.name = 'SettingsError';\n    this.issues = issues;\n  }\n}\n\nfunction formatIssues(issues: readonly SettingsIssue[]): string {\n  const noun = issues.length === 1 ? 'problem' : 'problems';\n  const lines = issues.map((issue) => `  - ${formatIssue(issue)}`);\n  return [`invalid settings (${issues.length} ${noun})`, ...lines].join('\\n');\n}\n\nfunction formatIssue(issue: SettingsIssue): string {\n  if (issue.kind === 'missing') return `${issue.key}: missing`;\n  // JSON.stringify quotes/escapes like Rust's `{:?}` for printable values\n  // (control characters escape differently — cosmetic, not part of the contract).\n  const value = issue.value === undefined ? '' : ` ${JSON.stringify(issue.value)}`;\n  return `${issue.key}: invalid value${value}: ${issue.detail ?? 'failed to parse'}`;\n}\n","/**\n * Validators — how a raw env string becomes a typed value, and the three\n * wrappers that mirror the Rust field grammar: {@link optional} ↔ `Option<T>`,\n * {@link withDefault} ↔ `= \"literal\"`, {@link secret} ↔ `#[secret]`.\n *\n * The shared Rust↔TS parsing contract lives here: `bool` accepts\n * `true`/`false`/`1`/`0` case-insensitively, {@link list} is comma-separated\n * with trimmed items and empty items dropped, and scalars are **not** trimmed —\n * `\" 8080\"` is invalid for a number on both sides.\n */\n\n/**\n * Parses one env value into a typed setting. Build one with {@link str},\n * {@link num}, {@link int}, {@link port}, {@link bool}, {@link url},\n * {@link list}, or {@link oneOf}, then refine it with {@link optional},\n * {@link withDefault}, and {@link secret}.\n *\n * The named validators are idiomatic TS and deliberately *not* a 1:1 copy of\n * the Rust side, where types parse themselves through the `FromEnvValue` trait\n * (`port: u16`, `bind: SocketAddr`); what both sides share is the semantics\n * listed in the module docs.\n */\nexport interface Validator<T> {\n  /** Human name used in error messages (e.g. `number`). */\n  readonly kind: string;\n  /** Unset is fine and yields `undefined` — the mirror of `Option<T>`. */\n  readonly optional: boolean;\n  /** Redact the raw value in error output — the mirror of `#[secret]`. */\n  readonly secret: boolean;\n  /** Used when the variable is unset; parsed by the same rules as an env value. */\n  readonly defaultLiteral: string | undefined;\n  /** Parse a raw (non-empty) env string; throws `Error(message)` when invalid. */\n  readonly parse: (raw: string) => T;\n}\n\nfunction base<T>(kind: string, parse: (raw: string) => T): Validator<T> {\n  return { kind, optional: false, secret: false, defaultLiteral: undefined, parse };\n}\n\nfunction messageOf(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\n/** Any string, taken verbatim (no trimming). */\nexport function str(): Validator<string> {\n  return base('string', (raw) => raw);\n}\n\n/** Contract: `true`/`1` and `false`/`0`, case-insensitive, no trimming. */\nexport function bool(): Validator<boolean> {\n  return base('boolean', (raw) => {\n    const lower = raw.toLowerCase();\n    if (lower === 'true' || lower === '1') return true;\n    if (lower === 'false' || lower === '0') return false;\n    throw new Error('expected one of `true`, `false`, `1`, `0` (case-insensitive)');\n  });\n}\n\n// Rust `f64::from_str` grammar minus `inf`/`NaN`: sign, digits with an\n// optional point (`5.`/`.5` are valid), optional exponent. Rejects the extra\n// JS `Number()` literals (`0x10`, `0b101`, `0o17`) so both sides agree.\nconst FLOAT_GRAMMAR = /^[+-]?(\\d+\\.?\\d*|\\.\\d+)([eE][+-]?\\d+)?$/;\nconst INT_GRAMMAR = /^[+-]?\\d+$/;\n\n/**\n * A finite decimal number (point/exponent forms included). Not trimmed:\n * `\" 3\"` is invalid, like Rust's `FromStr`. Divergence from the Rust mirror:\n * Rust `f64` also accepts `inf`/`NaN` — this validator requires finite.\n */\nexport function num(): Validator<number> {\n  return base('number', (raw) => {\n    if (!FLOAT_GRAMMAR.test(raw)) throw new Error('expected a finite number');\n    const value = Number(raw);\n    if (!Number.isFinite(value)) throw new Error('expected a finite number');\n    return value;\n  });\n}\n\n/**\n * A plain decimal integer (no exponent/point/hex forms — Rust integer\n * `FromStr` grammar), limited to the safe range `±(2^53 - 1)`: JS numbers are\n * doubles, so bigger values would silently round (Rust 64-bit integers parse\n * them exactly — use {@link str} for 64-bit ids).\n */\nexport function int(): Validator<number> {\n  return base('integer', (raw) => {\n    if (!INT_GRAMMAR.test(raw)) throw new Error('expected an integer');\n    const value = Number(raw);\n    if (!Number.isSafeInteger(value)) throw new Error('expected a safe integer (within ±(2^53 - 1))');\n    return value;\n  });\n}\n\n/** A TCP/UDP port: an integer in `1..=65535`. */\nexport function port(): Validator<number> {\n  const inner = int();\n  return base('port', (raw) => {\n    const value = inner.parse(raw);\n    if (value < 1 || value > 65535) throw new Error('expected a port (1-65535)');\n    return value;\n  });\n}\n\n/** An absolute URL (validated with `new URL`, returned as the original string). */\nexport function url(): Validator<string> {\n  return base('url', (raw) => {\n    // `new URL` silently strips whitespace/tabs/newlines; a padded value would\n    // validate here and then break whatever consumes the raw string.\n    if (raw === '' || /\\s/.test(raw)) throw new Error('expected an absolute URL');\n    try {\n      new URL(raw);\n    } catch {\n      throw new Error('expected an absolute URL');\n    }\n    return raw;\n  });\n}\n\n/**\n * One of a fixed set of strings, narrowed to the literal union:\n *\n * ```ts\n * const env = oneOf(['development', 'production']); // Validator<'development' | 'production'>\n * ```\n */\nexport function oneOf<const V extends string>(values: readonly V[]): Validator<V> {\n  const expected = `expected one of ${values.map((value) => `\\`${value}\\``).join(', ')}`;\n  return base('choice', (raw) => {\n    if ((values as readonly string[]).includes(raw)) return raw as V;\n    throw new Error(expected);\n  });\n}\n\n/**\n * Contract: split on `,`, trim each item, drop empty items, parse the rest\n * with `item` (default {@link str}). Item numbering in errors counts the kept\n * items from 1 and never leaks the item value, so secret lists stay\n * redactable. Wrap the *list* in {@link secret}/{@link optional}, not the item.\n */\nexport function list(): Validator<readonly string[]>;\nexport function list<T>(item: Validator<T>): Validator<readonly T[]>;\nexport function list<T>(item?: Validator<T>): Validator<readonly (T | string)[]> {\n  const inner = item ?? str();\n  return base('list', (raw) =>\n    raw\n      .split(',')\n      .map((piece) => piece.trim())\n      .filter((piece) => piece !== '')\n      .map((piece, index) => {\n        try {\n          return inner.parse(piece);\n        } catch (error) {\n          throw new Error(`item ${index + 1}: ${messageOf(error)}`);\n        }\n      }),\n  );\n}\n\n/**\n * Unset (or empty) is fine and yields `undefined` — the mirror of a Rust\n * `Option<T>` field. Cannot be combined with {@link withDefault}: a defaulted\n * setting is always present ({@link createSettings} rejects the combination).\n */\nexport function optional<T>(validator: Validator<T>): Validator<T | undefined> {\n  return { ...validator, optional: true };\n}\n\n/**\n * Fall back to `literal` when the variable is unset. The literal goes through\n * the exact same parsing rules as an env value — the mirror of the Rust\n * `= \"literal\"` field default.\n */\nexport function withDefault<T>(validator: Validator<T>, literal: string): Validator<T> {\n  return { ...validator, defaultLiteral: literal };\n}\n\n/**\n * Redact the raw value in error output — the mirror of `#[secret]`. Note that\n * unlike Rust (whose generated `Debug` prints `***`), JS has no debug-print\n * boundary: `console.log(settings.TOKEN)` prints the real value. The redaction\n * covers what the *library* emits: `SettingsError` messages and issues.\n */\nexport function secret<T>(validator: Validator<T>): Validator<T> {\n  return { ...validator, secret: true };\n}\n","/**\n * {@link createSettings} — read a validated, typed settings object out of an\n * explicitly injected environment record, with a server/client split for\n * browser bundles.\n */\n\nimport { SettingsError, type SettingsIssue } from './error';\nimport type { Validator } from './validators';\n\n/** A settings declaration: env var name → {@link Validator}. */\nexport type SettingsSchema = Record<string, Validator<unknown>>;\n\n/** The typed settings object a schema produces. */\nexport type InferSettings<S extends SettingsSchema> = {\n  readonly [K in keyof S]: S[K] extends Validator<infer T> ? T : never;\n};\n\nexport interface CreateSettingsOptions<S extends SettingsSchema, C extends SettingsSchema> {\n  /** Server-only settings. Accessing one from client code throws. */\n  readonly server?: S;\n  /**\n   * Client-exposable settings. Every key must start with {@link clientPrefix}\n   * so nothing leaks into a browser bundle by accident.\n   */\n  readonly client?: C;\n  /** Required when `client` is non-empty — e.g. `NEXT_PUBLIC_`. */\n  readonly clientPrefix?: string;\n  /**\n   * The environment record, destructured **explicitly** — bundlers inline\n   * `process.env.NEXT_PUBLIC_*` / `import.meta.env.*` at build time only when\n   * each variable is a static member expression, so a bare `process.env` pass\n   * works on the server but leaves client values undefined in the browser:\n   *\n   * ```ts\n   * runtimeEnv: {\n   *   DATABASE_URL: process.env.DATABASE_URL,\n   *   NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,\n   * }\n   * ```\n   */\n  readonly runtimeEnv: Readonly<Record<string, string | undefined>>;\n  /** Contract: `VAR=` (empty string) behaves like unset. Default `true`. */\n  readonly emptyStringAsUnset?: boolean;\n  /**\n   * Where we are running. Default: `window` is absent from `globalThis`.\n   * Override for workers or exotic runtimes.\n   */\n  readonly isServer?: boolean;\n}\n\n/**\n * Validate the injected environment against the schema and return the typed,\n * read-only settings object. Mirrors the Rust `settings!` macro's\n * `from_source`, plus the client/server split (a bundler concern with no Rust\n * equivalent).\n *\n * - Every missing/invalid variable is reported at once in one\n *   {@link SettingsError} — no fix-one-reboot-fix-next loops.\n * - Validation runs eagerly, at the `createSettings` call. Call it at module\n *   scope of a single `settings.ts` so a bad environment fails the boot (or,\n *   in Next.js, the build — import your settings module from `next.config`).\n * - On the client only the `client` schema is validated (server values never\n *   reach the bundle); accessing a server key there throws.\n *\n * @example\n * ```ts\n * export const settings = createSettings({\n *   server: {\n *     DATABASE_URL: url(),\n *     SIGNING_KEY: secret(str()),\n *     PORT: withDefault(port(), '8080'),\n *     ...presets.posthog(),\n *   },\n *   clientPrefix: 'NEXT_PUBLIC_',\n *   client: { ...presets.posthogClient() },\n *   runtimeEnv: {\n *     DATABASE_URL: process.env.DATABASE_URL,\n *     SIGNING_KEY: process.env.SIGNING_KEY,\n *     PORT: process.env.PORT,\n *     POSTHOG_KEY: process.env.POSTHOG_KEY,\n *     POSTHOG_HOST: process.env.POSTHOG_HOST,\n *     NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,\n *     NEXT_PUBLIC_POSTHOG_HOST: process.env.NEXT_PUBLIC_POSTHOG_HOST,\n *   },\n * });\n * ```\n */\nexport function createSettings<\n  S extends SettingsSchema = Record<never, never>,\n  C extends SettingsSchema = Record<never, never>,\n>(options: CreateSettingsOptions<S, C>): InferSettings<S> & InferSettings<C> {\n  const server: SettingsSchema = options.server ?? {};\n  const client: SettingsSchema = options.client ?? {};\n  const { clientPrefix } = options;\n  const emptyAsUnset = options.emptyStringAsUnset ?? true;\n  const isServer = options.isServer ?? !('window' in globalThis);\n\n  const serverKeys = Object.keys(server);\n  const clientKeys = Object.keys(client);\n\n  // Declaration bugs (not environment problems) fail fast as plain errors.\n  if (clientKeys.length > 0 && clientPrefix === undefined) {\n    throw new Error('@evinvest/settings: `clientPrefix` is required when `client` settings are declared');\n  }\n  for (const key of serverKeys) {\n    // `in` would also match Object.prototype members (\"toString\", …).\n    if (Object.hasOwn(client, key)) {\n      throw new Error(`@evinvest/settings: setting \"${key}\" is declared in both server and client`);\n    }\n  }\n  if (clientPrefix !== undefined) {\n    for (const key of clientKeys) {\n      if (!key.startsWith(clientPrefix)) {\n        throw new Error(`@evinvest/settings: client setting \"${key}\" must start with clientPrefix \"${clientPrefix}\"`);\n      }\n    }\n    for (const key of serverKeys) {\n      if (key.startsWith(clientPrefix)) {\n        throw new Error(\n          `@evinvest/settings: server setting \"${key}\" starts with clientPrefix \"${clientPrefix}\" — declare it under \\`client\\``,\n        );\n      }\n    }\n  }\n  for (const [key, validator] of [...Object.entries(server), ...Object.entries(client)]) {\n    if (validator.optional && validator.defaultLiteral !== undefined) {\n      throw new Error(\n        `@evinvest/settings: setting \"${key}\" is both optional and defaulted — a defaulted setting is always present, drop one`,\n      );\n    }\n  }\n\n  // On the client, server values never reach the bundle: validate (and store)\n  // the client schema only.\n  const active = isServer ? { ...server, ...client } : client;\n  const issues: SettingsIssue[] = [];\n  const values: Record<string, unknown> = {};\n  for (const [key, validator] of Object.entries(active)) {\n    let raw = options.runtimeEnv[key];\n    if (emptyAsUnset && raw === '') raw = undefined;\n    // A default literal lives in source code, so it is never redacted.\n    const fromDefault = raw === undefined && validator.defaultLiteral !== undefined;\n    if (fromDefault) raw = validator.defaultLiteral;\n    if (raw === undefined) {\n      if (validator.optional) {\n        values[key] = undefined;\n        continue;\n      }\n      issues.push({ key, kind: 'missing' });\n      continue;\n    }\n    try {\n      values[key] = validator.parse(raw);\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n      issues.push({\n        key,\n        kind: 'invalid',\n        detail: fromDefault ? `invalid default: ${message}` : message,\n        ...(validator.secret && !fromDefault ? {} : { value: raw }),\n      });\n    }\n  }\n  if (issues.length > 0) throw new SettingsError(issues);\n\n  Object.freeze(values); // the documented read-only contract, enforced (ESM is strict mode: writes throw)\n  const serverOnly = new Set(serverKeys);\n  return new Proxy(values, {\n    get(target, prop, receiver) {\n      if (typeof prop !== 'string') return Reflect.get(target, prop, receiver);\n      if (!isServer && serverOnly.has(prop)) {\n        throw new Error(`@evinvest/settings: attempted to access server-only setting \"${prop}\" on the client`);\n      }\n      return Reflect.get(target, prop, receiver);\n    },\n  }) as InferSettings<S> & InferSettings<C>;\n}\n","/**\n * Org-canonical shared variable groups — one place that fixes the names, so\n * `POSTHOG_KEY` vs `POSTHOG_API_KEY` vs `NEXT_PUBLIC_POSTHOG_KEY` drift stops\n * at the source. Spread a preset into the `server` / `client` block of\n * {@link createSettings}; the Rust mirror ships the same server-side groups as\n * ready-made structs (`settings::presets`).\n */\n\nimport { optional, str, withDefault, type Validator } from './validators';\n\nexport const presets = {\n  /**\n   * PostHog capture credentials, canonical names: `POSTHOG_KEY` /\n   * `POSTHOG_HOST`. Both optional — capture is simply off without them. The\n   * project key (`phc_…`) is write-only and ships in frontend bundles anyway,\n   * so it is not `secret(...)`.\n   */\n  posthog: (): { POSTHOG_KEY: Validator<string | undefined>; POSTHOG_HOST: Validator<string | undefined> } => ({\n    POSTHOG_KEY: optional(str()),\n    POSTHOG_HOST: optional(str()),\n  }),\n\n  /**\n   * Sentry reporting, canonical name: `SENTRY_DSN`. Optional — monitoring is\n   * off without it. A DSN authorises event *submission* only, so it is not\n   * `secret(...)`.\n   */\n  sentry: (): { SENTRY_DSN: Validator<string | undefined> } => ({\n    SENTRY_DSN: optional(str()),\n  }),\n\n  /**\n   * The deployment environment, canonical name: `APP_ENV`. Defaults to\n   * `development`; kept a free string on purpose — constraining the values\n   * would break consumers that add a stage.\n   */\n  appEnv: (): { APP_ENV: Validator<string> } => ({\n    APP_ENV: withDefault(str(), 'development'),\n  }),\n\n  /** The `client`-block variant of {@link presets.posthog} for Next.js bundles. */\n  posthogClient: (): {\n    NEXT_PUBLIC_POSTHOG_KEY: Validator<string | undefined>;\n    NEXT_PUBLIC_POSTHOG_HOST: Validator<string | undefined>;\n  } => ({\n    NEXT_PUBLIC_POSTHOG_KEY: optional(str()),\n    NEXT_PUBLIC_POSTHOG_HOST: optional(str()),\n  }),\n\n  /** The `client`-block variant of {@link presets.sentry} + `APP_ENV` for Next.js bundles. */\n  sentryClient: (): {\n    NEXT_PUBLIC_SENTRY_DSN: Validator<string | undefined>;\n    NEXT_PUBLIC_APP_ENV: Validator<string>;\n  } => ({\n    NEXT_PUBLIC_SENTRY_DSN: optional(str()),\n    NEXT_PUBLIC_APP_ENV: withDefault(str(), 'development'),\n  }),\n} as const;\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@evinvest/settings",
+  "version": "0.1.0",
+  "description": "Typed, validated env settings with aggregate error reporting and a server/client split — zero runtime deps, mirroring the settings Cargo feature. Secrets stay in sops at the shell/CI boundary; this package only reads the already-injected environment.",
+  "license": "BlueOak-1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EV-invest/lib.git",
+    "directory": "ts/settings"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.core.json --noEmit",
+    "prepare": "tsup"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}