typed-settings 0.1.1 → 0.2.1

package/dist/index.d.cts

@@ -1,7 +1,34 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { S as SettingsOptions, F as Flat } from './types-CClP1lxq.cjs';
-export { A as ArrayStrategy, a as SecretProvider, b as SourceInput, U as UnknownKeys } from './types-CClP1lxq.cjs';
-export { C as ConfigError } from './errors-itGaU4Q8.cjs';
+import { S as SettingsOptions, F as Flat } from './types-CcsYDAdO.cjs';
+export { A as ArrayStrategy, a as SecretProvider, b as SourceInput, U as UnknownKeys } from './types-CcsYDAdO.cjs';
+export { C as ConfigError, i as isSecretKey } from './errors-JkkOM0u-.cjs';
+
+/** Validation outcome with root-attributed, path-normalized issues. */
+interface NormalizedResult {
+    ok: boolean;
+    value?: unknown;
+    issues?: {
+        path: string;
+        message: string;
+    }[];
+}
+/**
+ * Runs a Standard Schema `validate()` and normalizes the outcome. Sync results
+ * return `{ value }` or `{ issues, async: false }`; a thenable (checked by shape,
+ * not `instanceof`) returns `{ promise }` for the async path. Throwing validators
+ * become root issues instead of leaking.
+ */
+declare function validateStandard<S extends StandardSchemaV1>(schema: S, input: unknown): {
+    value: unknown;
+} | {
+    issues: {
+        path: string;
+        message: string;
+    }[];
+    async: false;
+} | {
+    promise: Promise<NormalizedResult>;
+};
 
 /**
  * Typed config in one call.
@@ -10,12 +37,17 @@ export { C as ConfigError } from './errors-itGaU4Q8.cjs';
  * secrets-dir maps, and vault secrets, then merge, expand `$VAR` references,
  * coerce, validate against a Standard Schema, and return the result frozen.
  * Anything invalid throws `ConfigError` at boot with the key and source attached.
+ *
+ * @module
  */
 
 /**
  * Runs `fn` with `process.env` patched by `map` (`undefined` deletes a key),
  * then restores the exact previous environment — synchronously for sync `fn`,
  * held until settle for async `fn`. Restores on throw too.
+ *
+ * NOTE: not safe for overlapping concurrent use — two in-flight `withOverrides`
+ * calls interleave on the shared global. Serialize them, or pass `env:` instead.
  */
 declare function withOverrides<T>(map: Flat, fn: () => T): T;
 /**
@@ -31,16 +63,20 @@ declare function pickPublic<T extends object>(cfg: T, keys: (keyof T)[]): Partia
 declare function viteSettings<S extends StandardSchemaV1>(opts: SettingsOptions<S>, metaEnv: Flat): StandardSchemaV1.InferOutput<S>;
 /**
  * Loads, merges, expands, coerces, and validates config synchronously, returning
- * the inferred output type, frozen. Throws `ConfigError` on invalid input (issues
- * carry `path` + winning-source `from`, secrets redacted) and `USE_ASYNC` when a
- * provider or the schema itself is async — then use `settingsAsync()`.
+ * the inferred output type, frozen. Each issue names the failing `path` and the
+ * source that won it, with secrets redacted.
+ *
+ * @throws ConfigError on merge, parse, expansion, or validation failure.
+ * @throws ConfigError with `code: 'USE_ASYNC'` if a provider or the schema is
+ * async — switch to `settingsAsync()`.
  */
 declare function settings<S extends StandardSchemaV1>(opts: SettingsOptions<S>): StandardSchemaV1.InferOutput<S>;
 /**
- * Async twin of `settings()`: awaits async providers (whole collection races
- * `timeoutMs`) and async schemas, with the same merge/expand/coerce/validate/
- * freeze pipeline and the same `ConfigError` contract.
+ * Async twin of `settings()`: awaits async providers (the whole collection
+ * shares one `timeoutMs` deadline) and async schemas (which race a separate
+ * `timeoutMs` budget), with the same merge/expand/coerce/validate/freeze
+ * pipeline and the same `ConfigError` contract.
  */
 declare function settingsAsync<S extends StandardSchemaV1>(opts: SettingsOptions<S>): Promise<StandardSchemaV1.InferOutput<S>>;
 
-export { Flat, SettingsOptions, pickPublic, settings, settingsAsync, viteSettings, withOverrides };
+export { Flat, SettingsOptions, pickPublic, settings, settingsAsync, validateStandard, viteSettings, withOverrides };

package/dist/index.d.ts

@@ -1,7 +1,34 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { S as SettingsOptions, F as Flat } from './types-CClP1lxq.js';
-export { A as ArrayStrategy, a as SecretProvider, b as SourceInput, U as UnknownKeys } from './types-CClP1lxq.js';
-export { C as ConfigError } from './errors-itGaU4Q8.js';
+import { S as SettingsOptions, F as Flat } from './types-CcsYDAdO.js';
+export { A as ArrayStrategy, a as SecretProvider, b as SourceInput, U as UnknownKeys } from './types-CcsYDAdO.js';
+export { C as ConfigError, i as isSecretKey } from './errors-JkkOM0u-.js';
+
+/** Validation outcome with root-attributed, path-normalized issues. */
+interface NormalizedResult {
+    ok: boolean;
+    value?: unknown;
+    issues?: {
+        path: string;
+        message: string;
+    }[];
+}
+/**
+ * Runs a Standard Schema `validate()` and normalizes the outcome. Sync results
+ * return `{ value }` or `{ issues, async: false }`; a thenable (checked by shape,
+ * not `instanceof`) returns `{ promise }` for the async path. Throwing validators
+ * become root issues instead of leaking.
+ */
+declare function validateStandard<S extends StandardSchemaV1>(schema: S, input: unknown): {
+    value: unknown;
+} | {
+    issues: {
+        path: string;
+        message: string;
+    }[];
+    async: false;
+} | {
+    promise: Promise<NormalizedResult>;
+};
 
 /**
  * Typed config in one call.
@@ -10,12 +37,17 @@ export { C as ConfigError } from './errors-itGaU4Q8.js';
  * secrets-dir maps, and vault secrets, then merge, expand `$VAR` references,
  * coerce, validate against a Standard Schema, and return the result frozen.
  * Anything invalid throws `ConfigError` at boot with the key and source attached.
+ *
+ * @module
  */
 
 /**
  * Runs `fn` with `process.env` patched by `map` (`undefined` deletes a key),
  * then restores the exact previous environment — synchronously for sync `fn`,
  * held until settle for async `fn`. Restores on throw too.
+ *
+ * NOTE: not safe for overlapping concurrent use — two in-flight `withOverrides`
+ * calls interleave on the shared global. Serialize them, or pass `env:` instead.
  */
 declare function withOverrides<T>(map: Flat, fn: () => T): T;
 /**
@@ -31,16 +63,20 @@ declare function pickPublic<T extends object>(cfg: T, keys: (keyof T)[]): Partia
 declare function viteSettings<S extends StandardSchemaV1>(opts: SettingsOptions<S>, metaEnv: Flat): StandardSchemaV1.InferOutput<S>;
 /**
  * Loads, merges, expands, coerces, and validates config synchronously, returning
- * the inferred output type, frozen. Throws `ConfigError` on invalid input (issues
- * carry `path` + winning-source `from`, secrets redacted) and `USE_ASYNC` when a
- * provider or the schema itself is async — then use `settingsAsync()`.
+ * the inferred output type, frozen. Each issue names the failing `path` and the
+ * source that won it, with secrets redacted.
+ *
+ * @throws ConfigError on merge, parse, expansion, or validation failure.
+ * @throws ConfigError with `code: 'USE_ASYNC'` if a provider or the schema is
+ * async — switch to `settingsAsync()`.
  */
 declare function settings<S extends StandardSchemaV1>(opts: SettingsOptions<S>): StandardSchemaV1.InferOutput<S>;
 /**
- * Async twin of `settings()`: awaits async providers (whole collection races
- * `timeoutMs`) and async schemas, with the same merge/expand/coerce/validate/
- * freeze pipeline and the same `ConfigError` contract.
+ * Async twin of `settings()`: awaits async providers (the whole collection
+ * shares one `timeoutMs` deadline) and async schemas (which race a separate
+ * `timeoutMs` budget), with the same merge/expand/coerce/validate/freeze
+ * pipeline and the same `ConfigError` contract.
  */
 declare function settingsAsync<S extends StandardSchemaV1>(opts: SettingsOptions<S>): Promise<StandardSchemaV1.InferOutput<S>>;
 
-export { Flat, SettingsOptions, pickPublic, settings, settingsAsync, viteSettings, withOverrides };
+export { Flat, SettingsOptions, pickPublic, settings, settingsAsync, validateStandard, viteSettings, withOverrides };

package/dist/index.js

@@ -1,6 +1 @@
-export { pickPublic, settings, settingsAsync, viteSettings, withOverrides } from './chunk-RCO6K3WQ.js';
-import './chunk-33M5GIKQ.js';
-import './chunk-OVFMKC2O.js';
-import './chunk-UFUHHR2J.js';
-export { ConfigError } from './chunk-EE6LXNJV.js';
-import './chunk-F6DX3HXZ.js';
+export{d as pickPublic,f as settings,g as settingsAsync,b as validateStandard,e as viteSettings,c as withOverrides}from'./chunk-4EAMKDNK.js';export{d as ConfigError,a as isSecretKey}from'./chunk-NQDE3WLR.js';