@g14o/env-core 0.1.2 → 0.2.0

package/README.md

@@ -88,6 +88,9 @@ export const env = createEnv({
 When your framework only inlines env vars you reference explicitly, use `runtimeEnvStrict`:
 
 ```ts
+import { createEnv } from "@g14o/env-core";
+import * as z from "zod";
+
 export const env = createEnv({
   server: { DATABASE_URL: z.url() },
   clientPrefix: "NEXT_PUBLIC_",
@@ -99,6 +102,52 @@ export const env = createEnv({
 });
 ```
 
+### Overriding default error handler
+
+```ts
+import { createEnv } from "@g14o/env-core";
+
+export const env = createEnv({
+  // ...
+  // Called when schema validation fails.
+  onValidationError: (issues) => {
+    console.error("Invalid environment variables:", issues);
+    throw new Error("Invalid environment variables");
+  },
+  // Called when a server variable is accessed on the client.
+  onInvalidAccess: (variable) => {
+    console.error("Invalid access to server variable:", variable);
+    throw new Error("Invalid access to server variable");
+  },
+});
+```
+
+### Tell when we're in a server context
+
+```ts
+import { createEnv } from "@g14o/env-core";
+
+export const env = createEnv({
+  // ...
+  // Tell when we're in a server context
+  isServer: typeof window === "undefined", // or straight up `true` or `false`
+});
+```
+
+### Skip validation
+
+`skipValidation` bypasses both schema validation and the client-access proxy. Only use it when exposing the picked keys acceptable for the current runtime.
+
+```ts
+import { createEnv } from "@g14o/env-core";
+
+export const env = createEnv({
+  // ...
+  // Tell the library to skip validation and return picked runtime values only
+  skipValidation: true,
+});
+```
+
 ## Options
 
 | Option | Description |
@@ -110,7 +159,9 @@ export const env = createEnv({
 | `runtimeEnvStrict` | Explicit per-key mapping; mutually exclusive with `runtimeEnv` |
 | `emptyStringAsUndefined` | Treat `""` as `undefined` before validation |
 | `isServer` | Override server detection (default: `typeof window === "undefined"`) |
-| `onInvalidAccess` | Hook before throwing when a server key is read on the client |
+| `onValidationError` | Hook when schema validation fails; may throw custom error, otherwise default `InvalidEnvironmentVariablesError` is thrown |
+| `onInvalidAccess` | Hook when a server key is accessed on the client; may throw custom error, otherwise default server-access error is thrown |
+| `skipValidation` | Bypasses both schema validation and the client-access proxy. Only use it when exposing the picked keys acceptable for the current runtime (default: `false`) |
 
 ## Security
 

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 //#region src/client-guard.d.ts
-type OnInvalidAccessHandler = (variable: string) => void;
+/** Called when a server key is read on the client. May throw a custom error; otherwise the default is thrown. */
+type OnInvalidAccessHandler = (variable: string) => never;
 //#endregion
 //#region src/standard-schema.d.ts
 /** @see https://standardschema.dev */
@@ -33,6 +34,10 @@ declare namespace StandardSchemaV1 {
   }
 }
 //#endregion
+//#region src/validate.d.ts
+/** Called when schema validation fails. May throw a custom error; otherwise the default is thrown. */
+type OnValidationErrorHandler = (issues: readonly StandardSchemaV1.Issue[]) => never;
+//#endregion
 //#region src/types.d.ts
 /**
 * Record mapping environment variable names to
@@ -159,8 +164,9 @@ type CreateEnvOptions<TServer extends SchemaShape | undefined = undefined, TClie
   client?: TClient; /** Prefix every `client` key must use (enforced at compile time and runtime). */
   clientPrefix?: TPrefix; /** Treat `""` as `undefined` before validation. Default `false`. */
   emptyStringAsUndefined?: boolean; /** Override server detection. Default: no `window` on `globalThis`. */
-  isServer?: boolean; /** Called before throwing when a non-client key is read on the client. */
-  onInvalidAccess?: OnInvalidAccessHandler; /** @internal Skip schema validation and return picked runtime values only. */
+  isServer?: boolean; /** Called when a non-client key is read on the client. May throw a custom error; otherwise the default is thrown. */
+  onInvalidAccess?: OnInvalidAccessHandler; /** Called when schema validation fails. May throw a custom error; otherwise the default is thrown. */
+  onValidationError?: OnValidationErrorHandler; /** @internal Skip schema validation and return picked runtime values only. */
   skipValidation?: boolean;
 } & RuntimeEnvSource<TServer, TClient>;
 /**
@@ -195,7 +201,8 @@ type CreateEnvOutput<TServer extends SchemaShape | undefined, TClient extends Sc
 * @param options.runtimeEnvStrict - Explicit per-key mapping; mutually exclusive with `runtimeEnv`.
 * @param options.emptyStringAsUndefined - Treat `""` as `undefined` before validation. Default `false`.
 * @param options.isServer - Override server detection. Default: no `window` on `globalThis`.
-* @param options.onInvalidAccess - Called before throwing when a non-client key is read on the client.
+* @param options.onInvalidAccess - Called when a non-client key is read on the client. May throw a custom error; otherwise the default is thrown.
+* @param options.onValidationError - Called when schema validation fails. May throw a custom error; otherwise the default is thrown.
 * @param options.skipValidation - Skip schema validation and return picked runtime values only. Default `false`.
 * @returns Readonly, frozen env object typed from inferred schema outputs; client reads are guarded by `Proxy`.
 *
@@ -227,4 +234,4 @@ declare class InvalidEnvironmentVariablesError extends Error {
   constructor(issues: readonly string[], scope: string);
 }
 //#endregion
-export { type AssertValidClientPrefix, type CreateEnvOptions, type CreateEnvOutput, type InferSchemaOutput, type InferShapeOutput, type InvalidClientKeys, InvalidEnvironmentVariablesError, type OnInvalidAccessHandler, type PrefixedClientShape, type RuntimeEnvInput, type RuntimeEnvValue, type SchemaShape, type Simplify, type StandardSchemaV1, type StrictRuntimeEnv, createEnv };
+export { type AssertValidClientPrefix, type CreateEnvOptions, type CreateEnvOutput, type InferSchemaOutput, type InferShapeOutput, type InvalidClientKeys, InvalidEnvironmentVariablesError, type OnInvalidAccessHandler, type OnValidationErrorHandler, type PrefixedClientShape, type RuntimeEnvInput, type RuntimeEnvValue, type SchemaShape, type Simplify, type StandardSchemaV1, type StrictRuntimeEnv, createEnv };

package/dist/index.mjs

@@ -1,2 +1,2 @@
 var e=class extends Error{issues;constructor(e,t){super(`Invalid environment variables (${t}):\n${e.map(e=>`  - ${e}`).join(`
-`)}`),this.name=`InvalidEnvironmentVariablesError`,this.issues=e}};function t(e){return`${e.path&&e.path.length>0?`${e.path.map(e=>n(e)).join(`.`)}: `:``}${e.message}`}function n(e){return typeof e==`object`&&e&&`key`in e?String(e.key):String(e)}function r(e){return Error(`Attempted to access server environment variable(s) on the client: ${e}`)}const i=new Set([`__esModule`,`$$typeof`]);function a(e,t){let{isServer:n,clientKeys:a,onInvalidAccess:o}=t;return new Proxy(e,{get(e,t,s){if(typeof t!=`string`)return Reflect.get(e,t,s);if(!(n||i.has(t)||a.has(t)))throw o?.(t),r(t);return Reflect.get(e,t,s)}})}function o(e,t,n){let r={};for(let i of e){let e=Object.hasOwn(t,i)?t[i]:void 0;n&&e===``&&(e=void 0),r[i]=e}return r}function s(e,t){let n=[];for(let r of e)Object.hasOwn(t,r)||n.push(r);if(n.length>0)throw Error(`runtimeEnvStrict is missing required keys: ${n.join(`, `)}`)}function c(e,t){if(e!==void 0){for(let n of t)if(!n.startsWith(e))throw Error(`Environment variable "${n}" must start with "${e}" to be exposed on the client`)}}function l(e,t){for(let n of e)if(t.includes(n))throw Error(`Environment variable "${n}" cannot be defined in both server and client`)}function u(t,n,r){let i=Object.keys(t);if(i.length===0)return{};let a={},o=[],s=[];for(let e of i){let r=t[e];if(!r)continue;let i=r[`~standard`].validate(n[e]);if(i instanceof Promise){s.push({key:e,promise:i});continue}d(e,i,a,o)}if(s.length>0)throw Error(`Async Standard Schema validation is not supported in createEnv (${r}). Use synchronous validators.`);if(o.length>0)throw new e(o,r);return a}function d(e,n,r,i){if(n.issues){for(let r of n.issues)i.push(`${e}: ${t(r)}`);return}r[e]=n.value}function f(e){return e===void 0?globalThis.window===void 0:e}function p(e){if(`runtimeEnvStrict`in e&&e.runtimeEnvStrict!==void 0)return e.runtimeEnvStrict;if(`runtimeEnv`in e&&e.runtimeEnv!==void 0)return e.runtimeEnv;throw Error(`createEnv requires either runtimeEnv or runtimeEnvStrict`)}function m(e,t){return{server:e??{},client:t??{}}}function h(e){let{server:t,client:n}=m(e.server,e.client),r=Object.keys(t),i=Object.keys(n),a=[...r,...i];l(r,i),c(e.clientPrefix,i);let o=p(e);return`runtimeEnvStrict`in e&&e.runtimeEnvStrict!==void 0&&s(a,o),{server:t,client:n,clientPrefix:e.clientPrefix,emptyStringAsUndefined:e.emptyStringAsUndefined??!1,isServer:f(e.isServer),onInvalidAccess:e.onInvalidAccess,skipValidation:e.skipValidation??!1,runtime:o}}function g(e){let t=h(e),n=Object.keys(t.server),r=Object.keys(t.client),i=[...n,...r],s=new Set(r),c=o(i,t.runtime,t.emptyStringAsUndefined);if(t.skipValidation)return Object.freeze({...c});let l=o(r,t.runtime,t.emptyStringAsUndefined),d=u(t.client,l,`client`),f={};if(t.isServer&&n.length>0){let e=o(n,t.runtime,t.emptyStringAsUndefined);f=u(t.server,e,`server`)}return a(Object.freeze(t.isServer?{...f,...d}:{...d}),{isServer:t.isServer,clientKeys:s,onInvalidAccess:t.onInvalidAccess})}export{e as InvalidEnvironmentVariablesError,g as createEnv};
+`)}`),this.name=`InvalidEnvironmentVariablesError`,this.issues=e}};function t(e){return`${e.path&&e.path.length>0?`${e.path.map(e=>n(e)).join(`.`)}: `:``}${e.message}`}function n(e){return typeof e==`object`&&e&&`key`in e?String(e.key):String(e)}function r(e){return Error(`Attempted to access server environment variable(s) on the client: ${e}`)}const i=new Set([`__esModule`,`$$typeof`]);function a(e,t){let{isServer:n,clientKeys:a,onInvalidAccess:o}=t,s=e=>{throw o&&o(e),r(e)};return new Proxy(e,{get(e,t,r){return typeof t==`string`?n||i.has(t)||a.has(t)?Reflect.get(e,t,r):s(t):Reflect.get(e,t,r)}})}function o(e,t,n){let r={};for(let i of e){let e=Object.hasOwn(t,i)?t[i]:void 0;n&&e===``&&(e=void 0),r[i]=e}return r}function s(e,t){let n=[];for(let r of e)Object.hasOwn(t,r)||n.push(r);if(n.length>0)throw Error(`runtimeEnvStrict is missing required keys: ${n.join(`, `)}`)}function c(e,t){if(e!==void 0){for(let n of t)if(!n.startsWith(e))throw Error(`Environment variable "${n}" must start with "${e}" to be exposed on the client`)}}function l(e,t){for(let n of e)if(t.includes(n))throw Error(`Environment variable "${n}" cannot be defined in both server and client`)}function u(e,t){return{message:t.message,path:[{key:e},...t.path??[]]}}function d(t,n,r,i){let a=Object.keys(t);if(a.length===0)return{};let o={},s=[],c=[],l=[];for(let e of a){let r=t[e];if(!r)continue;let i=r[`~standard`].validate(n[e]);if(i instanceof Promise){l.push({key:e,promise:i});continue}f(e,i,o,s,c)}if(l.length>0)throw Error(`Async Standard Schema validation is not supported in createEnv (${r}). Use synchronous validators.`);return c.length>0?(t=>{throw i&&i(t),console.error(`❌ Invalid environment variables:`,t),new e(s,r)})(c):o}function f(e,n,r,i,a){if(n.issues){for(let r of n.issues){let n=u(e,r);a.push(n),i.push(`${e}: ${t(r)}`)}return}r[e]=n.value}function p(e){return e===void 0?globalThis.window===void 0:e}function m(e){if(`runtimeEnvStrict`in e&&e.runtimeEnvStrict!==void 0)return e.runtimeEnvStrict;if(`runtimeEnv`in e&&e.runtimeEnv!==void 0)return e.runtimeEnv;throw Error(`createEnv requires either runtimeEnv or runtimeEnvStrict`)}function h(e,t){return{server:e??{},client:t??{}}}function g(e){let{server:t,client:n}=h(e.server,e.client),r=Object.keys(t),i=Object.keys(n),a=[...r,...i];l(r,i),c(e.clientPrefix,i);let o=m(e);return`runtimeEnvStrict`in e&&e.runtimeEnvStrict!==void 0&&s(a,o),{server:t,client:n,clientPrefix:e.clientPrefix,emptyStringAsUndefined:e.emptyStringAsUndefined??!1,isServer:p(e.isServer),onInvalidAccess:e.onInvalidAccess,onValidationError:e.onValidationError,skipValidation:e.skipValidation??!1,runtime:o}}function _(e){let t=g(e),n=Object.keys(t.server),r=Object.keys(t.client),i=[...n,...r],s=new Set(r),c=o(i,t.runtime,t.emptyStringAsUndefined);if(t.skipValidation)return Object.freeze({...c});let l=o(r,t.runtime,t.emptyStringAsUndefined),u=d(t.client,l,`client`,t.onValidationError),f={};if(t.isServer&&n.length>0){let e=o(n,t.runtime,t.emptyStringAsUndefined);f=d(t.server,e,`server`,t.onValidationError)}return a(Object.freeze(t.isServer?{...f,...u}:{...u}),{isServer:t.isServer,clientKeys:s,onInvalidAccess:t.onInvalidAccess})}export{e as InvalidEnvironmentVariablesError,_ as createEnv};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g14o/env-core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Framework-agnostic, typesafe environment variables via Standard Schema (Zod, Valibot, ArkType).",
   "type": "module",
   "sideEffects": false,