@arki/env 0.0.8 → 0.0.11

package/README.md

@@ -74,6 +74,56 @@ const env = defineEnv({
   package for plugin authoring, lifecycle, diagnostics, and the
   [adapter authoring guide](https://github.com/arkijs/arki/blob/main/packages/dot/docs/adapter-authoring.md).
 
+<!-- bench:start -->
+## Benchmarks
+
+Defining and validating a 15-variable server environment with `defineEnv()`, against `@t3-oss/env-core` (which it wraps), envalid, and a plain zod object parse.
+
+Node v22.13.1 on Apple M2 Max, 2026-10-13. Median time per operation, lower is better.
+
+### Define + validate 15 variables + read one value
+
+Each call builds a fresh environment from scratch, validates every variable, then reads `PORT`.
+
+| Library | Time / op | vs fastest |
+| --- | ---: | ---: |
+| @arki/env defineEnv() | 25.03 µs | fastest |
+| @t3-oss/env-core createEnv() (used directly) | 306.02 µs | 12.22× |
+| envalid cleanEnv() | 59.23 µs | 2.37× |
+| zod z.object().parse(process.env) | 177.92 µs | 7.11× |
+
+### Define only (no read)
+
+Declare the environment and never read it. `defineEnv()` defers all work to the first read; the others validate immediately.
+
+| Library | Time / op | vs fastest |
+| --- | ---: | ---: |
+| @arki/env defineEnv() (lazy, no validation yet) | 126.8 ns | fastest |
+| @t3-oss/env-core createEnv() (validates now) | 519.07 µs | 4094.95× |
+| envalid cleanEnv() (validates now) | 115.66 µs | 912.46× |
+| zod z.object().parse(process.env) (validates now) | 431.26 µs | 3402.26× |
+
+### Read one value from an already-validated environment
+
+The hot path: `env.PORT` after the environment exists.
+
+| Library | Time / op | vs fastest |
+| --- | ---: | ---: |
+| @arki/env (lazy object over createEnv) | 229.1 ns | 28.25× |
+| @t3-oss/env-core createEnv() | 50.3 ns | 6.20× |
+| envalid cleanEnv() | 83.8 ns | 10.34× |
+| zod parsed plain object | 8.1 ns | fastest |
+
+Read the rows with the contracts in mind:
+
+- `defineEnv()` is lazy: it builds and validates the environment on the first property read, so "define + first read" is the fair row for it. The "define only" group shows what declaring an env costs before anything reads it.
+- Validation is forced on (`skipValidation: false`) for `defineEnv()` and `createEnv`, because `defineEnv()` skips validation outside development by default.
+- `defineEnv()` and `createEnv` share the same zod schemas, so the gap between them is the wrapper alone: building `runtimeEnv` from `process.env`, a labelled error handler, and the lazy object. envalid uses its own validators, and the plain zod parse does no env-specific work (no empty-string handling, no frozen result).
+- `createEnv`, envalid and the zod parse are given the whole `process.env`, as their docs show, so their cost grows with how many variables the process has. `defineEnv()` reads only the keys it declares. The gap therefore depends on the size of the environment it runs in.
+
+Reproduce with `bun run bench` in the package directory; regenerate this section with `bun run bench --write-readme`.
+<!-- bench:end -->
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/contracts/common.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 export declare const commonContracts: {
-    string: (defaultValue?: string) => z.ZodString | z.ZodDefault<z.ZodString>;
+    string: (defaultValue?: string) => z.ZodDefault<z.ZodString> | z.ZodString;
     number: (defaultValue?: number) => z.ZodCoercedNumber<unknown> | z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     port: (defaultValue?: number) => z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     nodeEnv: () => z.ZodDefault<z.ZodEnum<{
@@ -11,14 +11,14 @@ export declare const commonContracts: {
     boolean: (defaultValue?: boolean) => z.ZodPipe<z.ZodDefault<z.ZodEnum<{
         0: "0";
         1: "1";
-        true: "true";
         false: "false";
-    }>>, z.ZodTransform<boolean, "0" | "1" | "true" | "false">>;
-    logLevel: (defaultValue?: "debug" | "info" | "warn" | "error") => z.ZodDefault<z.ZodEnum<{
+        true: "true";
+    }>>, z.ZodTransform<boolean, "0" | "1" | "false" | "true">>;
+    logLevel: (defaultValue?: 'debug' | 'info' | 'warn' | 'error') => z.ZodDefault<z.ZodEnum<{
         debug: "debug";
+        error: "error";
         info: "info";
         warn: "warn";
-        error: "error";
     }>>;
 };
 //# sourceMappingURL=common.d.ts.map

package/dist/contracts/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/contracts/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,eAAe;4BACF,MAAM;4BAKN,MAAM;;;;;;;;;;;;;8BAoBL,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO;;;;;;CAE7D,CAAC"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/contracts/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,eAAe;IAC1B,MAAM,kBAAkB,MAAM;IAK9B,MAAM,kBAAkB,MAAM;IAK9B,IAAI;IAOJ,OAAO;;;;;IAEP,OAAO;;;;;;IAMP,QAAQ,kBAAiB,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO;;;;;;CAE7D,CAAC"}

package/dist/contracts/common.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/contracts/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,MAAM,EAAE,CAAC,YAAqB,EAAE,EAAE;QAChC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,OAAO,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9D,CAAC;IAED,MAAM,EAAE,CAAC,YAAqB,EAAE,EAAE;QAChC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACjC,OAAO,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9D,CAAC;IAED,IAAI,EAAE,CAAC,YAAY,GAAG,IAAI,EAAE,EAAE,CAC5B,CAAC;SACE,MAAM,CAAC,MAAM,EAAE;SACf,GAAG,CAAC,CAAC,EAAE,yBAAyB,CAAC;SACjC,GAAG,CAAC,MAAM,EAAE,4BAA4B,CAAC;SACzC,OAAO,CAAC,YAAY,CAAC;IAE1B,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;IAEnF,OAAO,EAAE,CAAC,YAAY,GAAG,KAAK,EAAE,EAAE,CAChC,CAAC;SACE,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;SACjC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;SACxC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC;IAEpD,QAAQ,EAAE,CAAC,eAAoD,MAAM,EAAE,EAAE,CACvE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;CACnE,CAAC"}
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/contracts/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,MAAM,EAAE,CAAC,YAAqB,EAAE,EAAE;QAChC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,OAAO,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9D,CAAC;IAED,MAAM,EAAE,CAAC,YAAqB,EAAE,EAAE;QAChC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACjC,OAAO,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9D,CAAC;IAED,IAAI,EAAE,CAAC,YAAY,GAAG,IAAI,EAAE,EAAE,CAC5B,CAAC;SACE,MAAM,CAAC,MAAM,EAAE;SACf,GAAG,CAAC,CAAC,EAAE,yBAAyB,CAAC;SACjC,GAAG,CAAC,MAAM,EAAE,4BAA4B,CAAC;SACzC,OAAO,CAAC,YAAY,CAAC;IAE1B,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;IAEnF,OAAO,EAAE,CAAC,YAAY,GAAG,KAAK,EAAE,EAAE,CAChC,CAAC;SACE,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;SACjC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;SACxC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC;IAEpD,QAAQ,EAAE,CAAC,YAAY,GAAwC,MAAM,EAAE,EAAE,CACvE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;CACnE,CAAC"}

package/dist/contracts/index.d.ts

@@ -1,11 +1,5 @@
 export declare const contracts: {
-    json: <T extends import("zod").ZodType>(schema: T) => import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<Awaited<import("zod").infer<T>>, string>>;
-    csvArray: <T extends import("zod").ZodType>(itemSchema: T) => import("zod").ZodPreprocess<import("zod").ZodArray<T>, unknown>;
-    csvSet: <T extends import("zod").ZodType>(itemSchema: T) => import("zod").ZodPreprocess<import("zod").ZodArray<T>, unknown>;
-    url: (defaultValue?: string) => import("zod").ZodURL | import("zod").ZodDefault<import("zod").ZodURL>;
-    databaseUrl: () => import("zod").ZodURL;
-    redisUrl: () => import("zod").ZodURL;
-    string: (defaultValue?: string) => import("zod").ZodString | import("zod").ZodDefault<import("zod").ZodString>;
+    string: (defaultValue?: string) => import("zod").ZodDefault<import("zod").ZodString> | import("zod").ZodString;
     number: (defaultValue?: number) => import("zod").ZodCoercedNumber<unknown> | import("zod").ZodDefault<import("zod").ZodCoercedNumber<unknown>>;
     port: (defaultValue?: number) => import("zod").ZodDefault<import("zod").ZodCoercedNumber<unknown>>;
     nodeEnv: () => import("zod").ZodDefault<import("zod").ZodEnum<{
@@ -16,15 +10,21 @@ export declare const contracts: {
     boolean: (defaultValue?: boolean) => import("zod").ZodPipe<import("zod").ZodDefault<import("zod").ZodEnum<{
         0: "0";
         1: "1";
-        true: "true";
         false: "false";
-    }>>, import("zod").ZodTransform<boolean, "0" | "1" | "true" | "false">>;
-    logLevel: (defaultValue?: "debug" | "info" | "warn" | "error") => import("zod").ZodDefault<import("zod").ZodEnum<{
+        true: "true";
+    }>>, import("zod").ZodTransform<boolean, "0" | "1" | "false" | "true">>;
+    logLevel: (defaultValue?: 'debug' | 'info' | 'warn' | 'error') => import("zod").ZodDefault<import("zod").ZodEnum<{
         debug: "debug";
+        error: "error";
         info: "info";
         warn: "warn";
-        error: "error";
     }>>;
+    json: <T extends import("zod").ZodType>(schema: T) => import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<Awaited<import("zod").infer<T>>, string>>;
+    csvArray: <T extends import("zod").ZodType>(itemSchema: T) => import("zod").ZodPreprocess<import("zod").ZodArray<T>, unknown>;
+    csvSet: <T extends import("zod").ZodType>(itemSchema: T) => import("zod").ZodPreprocess<import("zod").ZodArray<T>, unknown>;
+    url: (defaultValue?: string) => import("zod").ZodDefault<import("zod").ZodURL> | import("zod").ZodURL;
+    databaseUrl: () => import("zod").ZodURL;
+    redisUrl: () => import("zod").ZodURL;
 };
 export { commonContracts } from './common.js';
 export { urlContracts } from './urls.js';

package/dist/contracts/parsing.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 export declare const parseContracts: {
-    json: <T extends z.ZodType>(schema: T) => z.ZodPipe<z.ZodString, z.ZodTransform<Awaited<z.core.output<T>>, string>>;
+    json: <T extends z.ZodType>(schema: T) => z.ZodPipe<z.ZodString, z.ZodTransform<Awaited<z.infer<T>>, string>>;
     csvArray: <T extends z.ZodType>(itemSchema: T) => z.ZodPreprocess<z.ZodArray<T>, unknown>;
     csvSet: <T extends z.ZodType>(itemSchema: T) => z.ZodPreprocess<z.ZodArray<T>, unknown>;
 };

package/dist/contracts/parsing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parsing.d.ts","sourceRoot":"","sources":["../../src/contracts/parsing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc;WAClB,CAAC,SAAS,CAAC,CAAC,OAAO,UAAU,CAAC;eAM1B,CAAC,SAAS,CAAC,CAAC,OAAO,cAAc,CAAC;aASpC,CAAC,SAAS,CAAC,CAAC,OAAO,cAAc,CAAC;CAQ5C,CAAC"}
+{"version":3,"file":"parsing.d.ts","sourceRoot":"","sources":["../../src/contracts/parsing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc;IACzB,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,UAAU,CAAC;IAMrC,QAAQ,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,cAAc,CAAC;IAM7C,MAAM,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,cAAc,CAAC;CAK5C,CAAC"}

package/dist/contracts/parsing.js

@@ -1,18 +1,18 @@
 import { z } from 'zod';
 export const parseContracts = {
-    json: (schema) => z.string().transform((str) => {
+    json: (schema) => z.string().transform(str => {
         const parsed = JSON.parse(str);
         return schema.parse(parsed);
     }),
-    csvArray: (itemSchema) => z.preprocess((val) => {
+    csvArray: (itemSchema) => z.preprocess(val => {
         if (typeof val !== 'string')
             return val;
-        return val.split(',').map((s) => s.trim());
+        return val.split(',').map(s => s.trim());
     }, z.array(itemSchema)),
-    csvSet: (itemSchema) => z.preprocess((val) => {
+    csvSet: (itemSchema) => z.preprocess(val => {
         if (typeof val !== 'string')
             return val;
-        return [...new Set(val.split(',').map((s) => s.trim()))];
+        return [...new Set(val.split(',').map(s => s.trim()))];
     }, z.array(itemSchema)),
 };
 //# sourceMappingURL=parsing.js.map

package/dist/contracts/parsing.js.map

@@ -1 +1 @@
-{"version":3,"file":"parsing.js","sourceRoot":"","sources":["../../src/contracts/parsing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,CAAsB,MAAS,EAAE,EAAE,CACvC,CAAC,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE;QAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAe,CAAC;IAC5C,CAAC,CAAC;IAEJ,QAAQ,EAAE,CAAsB,UAAa,EAAE,EAAE,CAC/C,CAAC,CAAC,UAAU,CACV,CAAC,GAAG,EAAE,EAAE;QACN,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC;QACxC,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC,EACD,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CACpB;IAEH,MAAM,EAAE,CAAsB,UAAa,EAAE,EAAE,CAC7C,CAAC,CAAC,UAAU,CACV,CAAC,GAAG,EAAE,EAAE;QACN,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC;QACxC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC,EACD,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CACpB;CACJ,CAAC"}
+{"version":3,"file":"parsing.js","sourceRoot":"","sources":["../../src/contracts/parsing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,CAAsB,MAAS,EAAE,EAAE,CACvC,CAAC,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;QACzB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC,CAAC;IAEJ,QAAQ,EAAE,CAAsB,UAAa,EAAE,EAAE,CAC/C,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;QACjB,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC;QACxC,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAEzB,MAAM,EAAE,CAAsB,UAAa,EAAE,EAAE,CAC7C,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;QACjB,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC;QACxC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACzD,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;CAC1B,CAAC"}

package/dist/contracts/urls.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 export declare const urlContracts: {
-    url: (defaultValue?: string) => z.ZodURL | z.ZodDefault<z.ZodURL>;
+    url: (defaultValue?: string) => z.ZodDefault<z.ZodURL> | z.ZodURL;
     databaseUrl: () => z.ZodURL;
     redisUrl: () => z.ZodURL;
 };

package/dist/contracts/urls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../src/contracts/urls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,YAAY;yBACF,MAAM;;;CAoB5B,CAAC"}
+{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../src/contracts/urls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,YAAY;IACvB,GAAG,kBAAkB,MAAM;IAK3B,WAAW;IAQX,QAAQ;CAOT,CAAC"}

package/dist/core/define-env.d.ts

@@ -1,6 +1,6 @@
-import { createEnv } from '@t3-oss/env-core';
 import type { CreateEnv, DefaultCombinedSchema } from '@t3-oss/env-core';
 import type { ZodType } from 'zod';
+import { createEnv } from '@t3-oss/env-core';
 /** The issue shape t3-oss hands to `onValidationError`, derived so it stays in sync with the lib. */
 type ValidationIssues = Parameters<NonNullable<Parameters<typeof createEnv>[0]['onValidationError']>>[0];
 /**
@@ -13,7 +13,7 @@ type ValidationIssues = Parameters<NonNullable<Parameters<typeof createEnv>[0]['
  * client keys (and only client keys) carry the prefix. Widening it to `string` would make every
  * server key collapse to a type-level `ErrorMessage`, so the prefix must stay a literal.
  */
-export declare function defineEnv<TServer extends Record<string, ZodType>, TClient extends Record<string, ZodType> = NonNullable<unknown>, TShared extends Record<string, ZodType> = NonNullable<unknown>, const TPrefix extends string = '', const TExtends extends Array<Record<string, unknown>> = []>(config: {
+export declare function defineEnv<TServer extends Record<string, ZodType>, TClient extends Record<string, ZodType> = NonNullable<unknown>, TShared extends Record<string, ZodType> = NonNullable<unknown>, const TPrefix extends string = '', const TExtends extends Record<string, unknown>[] = []>(config: {
     /**
      * Label shown in validation-error logs, e.g. `'@acme/backend'`. Without it a misconfigured
      * deploy logs a bare "Invalid environment variables" with no hint which env failed — exactly the

package/dist/core/define-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-env.d.ts","sourceRoot":"","sources":["../../src/core/define-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAEzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,qGAAqG;AACrG,KAAK,gBAAgB,GAAG,UAAU,CAChC,WAAW,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAClE,CAAC,CAAC,CAAC,CAAC;AAkBL;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,EAC9D,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,EAC9D,KAAK,CAAC,OAAO,SAAS,MAAM,GAAG,EAAE,EACjC,KAAK,CAAC,QAAQ,SAAS,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,EAAE,EAC1D,MAAM,EAAE;IACR;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IACnE,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB;;;;WAIG;QACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;QACjC,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,KAAK,CAAC;KACzD,CAAC;CACH,GAAG,SAAS,CAAC,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,CAkExE"}
+{"version":3,"file":"define-env.d.ts","sourceRoot":"","sources":["../../src/core/define-env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,qGAAqG;AACrG,KAAK,gBAAgB,GAAG,UAAU,CAAC,WAAW,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAkBzG;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,EAC9D,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,EAC9D,KAAK,CAAC,OAAO,SAAS,MAAM,GAAG,EAAE,EACjC,KAAK,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,EACrD,MAAM,EAAE;IACR;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IACnE,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB;;;;WAIG;QACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;QACjC,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,KAAK,CAAC;KACzD,CAAC;CACH,GAAG,SAAS,CAAC,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,CAsExE"}

package/dist/core/define-env.js

@@ -1,5 +1,4 @@
 import { createEnv } from '@t3-oss/env-core';
-import { lazyObject } from '@arki/ts';
 /**
  * Fold validation issues into a human-legible, log-pipeline-safe string. The t3-oss default handler
  * logs `issues` as a raw object, which platforms like Coolify collapse to `[Object]` — so the var
@@ -80,8 +79,102 @@ export function defineEnv(config) {
             emptyStringAsUndefined: config.options?.emptyStringAsUndefined ?? true,
             onValidationError,
         };
-        return createEnv(options);
+        const env = createEnv(options);
+        // Skipped validation returns `runtimeEnv` itself: private only when `defineEnv` built it.
+        // Otherwise `createEnv` returns a fresh Proxy whose reads return its stored values on the server.
+        const isPrivate = skipValidation ? config.runtimeEnv === undefined : isServer();
+        return { env, isPrivate };
     };
-    return lazyObject(build);
+    return lazyEnv(build);
+}
+/**
+ * Reads an env takes through the lazy view before it copies the values for fast reads. A copy costs
+ * about as much as this many reads save (ski-rental), so an env that is read only a few times, such
+ * as one built for a single check, never pays for it, and a hot env pays it once.
+ */
+const READS_BEFORE_COPY = 64;
+/**
+ * A lazy view over the env `build()` returns: nothing runs until the first operation, then every
+ * operation forwards to the built env.
+ *
+ * Reads are the hot path. `createEnv` returns a Proxy, so a second Proxy over it pays two traps per
+ * read. Where it is safe, once the env has been read `READS_BEFORE_COPY` times, its values are copied
+ * into the Proxy's own target and the `get` trap is removed, so later reads are plain property reads
+ * on that copy. It is safe when the built object is private to this env and reads on it return its
+ * stored values:
+ * - on the server, `createEnv`'s Proxy returns stored values (its client guard is off), and its
+ *   object is a fresh copy nobody else holds;
+ * - with validation skipped, `createEnv` returns the `runtimeEnv` it was given: only the one
+ *   `defineEnv` built itself is private. A caller's own `runtimeEnv` stays a live view.
+ * Writes and deletes through this object update both the built env and the copy.
+ */
+function lazyEnv(build) {
+    let built;
+    let canCopy = false;
+    let copied = false;
+    let reads = 0;
+    const target = {};
+    const resolve = () => {
+        if (built !== undefined)
+            return built;
+        const result = build();
+        built = result.env;
+        canCopy = result.isPrivate;
+        return built;
+    };
+    const copy = (instance) => {
+        for (const key of Reflect.ownKeys(instance)) {
+            setValue(target, key, readValue(instance, key));
+        }
+        copied = true;
+        Reflect.deleteProperty(handler, 'get');
+    };
+    const handler = {
+        get: (_target, property) => {
+            const instance = resolve();
+            if (canCopy && ++reads >= READS_BEFORE_COPY) {
+                copy(instance);
+                return target[property];
+            }
+            return readValue(instance, property);
+        },
+        set: (_target, property, value) => {
+            const instance = resolve();
+            const ok = Reflect.set(instance, property, value);
+            if (ok && copied)
+                setValue(target, property, readValue(instance, property));
+            return ok;
+        },
+        deleteProperty: (_target, property) => {
+            const ok = Reflect.deleteProperty(resolve(), property);
+            if (ok && copied)
+                Reflect.deleteProperty(target, property);
+            return ok;
+        },
+        getPrototypeOf: () => Reflect.getPrototypeOf(resolve()),
+        has: (_target, property) => Reflect.has(resolve(), property),
+        ownKeys: () => Reflect.ownKeys(resolve()),
+        getOwnPropertyDescriptor: (_target, property) => Object.getOwnPropertyDescriptor(resolve(), property),
+    };
+    return new Proxy(target, handler);
+}
+/** Same test `createEnv` uses to decide whether its client-side access guard applies. */
+function isServer() {
+    const { window } = globalThis;
+    return window === undefined || 'Deno' in window;
+}
+/** A read as the old lazy view returned it: functions come back bound to the built env. */
+function readValue(instance, property) {
+    const value = Reflect.get(instance, property, instance);
+    return typeof value === 'function' ? value.bind(instance) : value;
+}
+/** An own data property. `__proto__` is defined, not assigned, so it never replaces the prototype. */
+function setValue(target, key, value) {
+    if (key === '__proto__') {
+        Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+    }
+    else {
+        target[key] = value;
+    }
 }
 //# sourceMappingURL=define-env.js.map

package/dist/core/define-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-env.js","sourceRoot":"","sources":["../../src/core/define-env.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define-env.js","sourceRoot":"","sources":["../../src/core/define-env.ts"],"names":[],"mappings":"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"}

package/dist/dot.d.ts

@@ -33,8 +33,8 @@
  * this adapter without `@arki/dot` installed will fail at module load —
  * that is intentional: the adapter only makes sense in a DOT app.
  */
-import { type EmptyShape, type Plugin } from '@arki/dot/plugin';
 import type { ZodType } from 'zod';
+import type { EmptyShape, Plugin } from '@arki/dot/plugin';
 /**
  * Options for the env DOT adapter.
  *

package/dist/dot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAU,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACnE,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACjE,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;KAAE,CAAC;CAClG,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAC9B,MAAM,CAAC,UAAU,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAuB1C"}
+{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAK3D;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACnE,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACjE,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;KAAE,CAAC;CAClG,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAC9B,MAAM,CAAC,UAAU,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAoB1C"}

package/dist/dot.js

@@ -51,9 +51,7 @@ export function env(options) {
         boot() {
             const validated = defineEnv({
                 server: options.schema,
-                options: options.skipValidation !== undefined
-                    ? { skipValidation: options.skipValidation }
-                    : undefined,
+                options: options.skipValidation === undefined ? undefined : { skipValidation: options.skipValidation },
             });
             // `defineEnv` returns a Proxy from `@t3-oss/env-core`; we narrow it
             // to the schema-derived shape so downstream typing flows through.

package/dist/dot.js.map

@@ -1 +1 @@
-{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,MAAM,EAAgC,MAAM,kBAAkB,CAAC;AAGxE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAwBjD;;;;;GAKG;AACH,MAAM,UAAU,GAAG,CACjB,OAA+B;IAE/B,OAAO,MAAM,CAAC;QACZ,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,OAAO;QAChB,SAAS,CAAC,GAAG;YACX,GAAG,CAAC,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,IAAI;YACF,MAAM,SAAS,GAAG,SAAS,CAAC;gBAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,OAAO,EACL,OAAO,CAAC,cAAc,KAAK,SAAS;oBAClC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE;oBAC5C,CAAC,CAAC,SAAS;aAChB,CAAC,CAAC;YACH,oEAAoE;YACpE,kEAAkE;YAClE,8DAA8D;YAC9D,0DAA0D;YAC1D,MAAM,SAAS,GAAG,SAAmD,CAAC;YACtE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;QAC5B,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAKH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAwBjD;;;;;GAKG;AACH,MAAM,UAAU,GAAG,CACjB,OAA+B;IAE/B,OAAO,MAAM,CAAC;QACZ,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,OAAO;QAChB,SAAS,CAAC,GAAG;YACX,GAAG,CAAC,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,IAAI;YACF,MAAM,SAAS,GAAG,SAAS,CAAC;gBAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,OAAO,EAAE,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE;aACvG,CAAC,CAAC;YACH,oEAAoE;YACpE,kEAAkE;YAClE,8DAA8D;YAC9D,0DAA0D;YAC1D,MAAM,SAAS,GAAG,SAAmD,CAAC;YACtE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;QAC5B,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arki/env",
-  "version": "0.0.8",
+  "version": "0.0.11",
   "description": "Type-safe environment variable parsing for ARKI — defineEnv() built on @t3-oss/env-core with Zod contracts for common variable shapes.",
   "license": "MIT",
   "repository": {
@@ -63,7 +63,7 @@
     "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@arki/dot": "^0.4.1"
+    "@arki/dot": "^0.6.1"
   },
   "peerDependenciesMeta": {
     "@arki/dot": {

package/src/contracts/parsing.ts

@@ -2,26 +2,20 @@ import { z } from 'zod';
 
 export const parseContracts = {
   json: <T extends z.ZodType>(schema: T) =>
-    z.string().transform((str) => {
+    z.string().transform(str => {
       const parsed = JSON.parse(str);
-      return schema.parse(parsed) as z.infer<T>;
+      return schema.parse(parsed);
     }),
 
   csvArray: <T extends z.ZodType>(itemSchema: T) =>
-    z.preprocess(
-      (val) => {
-        if (typeof val !== 'string') return val;
-        return val.split(',').map((s) => s.trim());
-      },
-      z.array(itemSchema)
-    ),
+    z.preprocess(val => {
+      if (typeof val !== 'string') return val;
+      return val.split(',').map(s => s.trim());
+    }, z.array(itemSchema)),
 
   csvSet: <T extends z.ZodType>(itemSchema: T) =>
-    z.preprocess(
-      (val) => {
-        if (typeof val !== 'string') return val;
-        return [...new Set(val.split(',').map((s) => s.trim()))];
-      },
-      z.array(itemSchema)
-    ),
+    z.preprocess(val => {
+      if (typeof val !== 'string') return val;
+      return [...new Set(val.split(',').map(s => s.trim()))];
+    }, z.array(itemSchema)),
 };

package/src/core/define-env.ts

@@ -1,12 +1,9 @@
-import { createEnv } from '@t3-oss/env-core';
 import type { CreateEnv, DefaultCombinedSchema } from '@t3-oss/env-core';
-import { lazyObject } from '@arki/ts';
 import type { ZodType } from 'zod';
+import { createEnv } from '@t3-oss/env-core';
 
 /** The issue shape t3-oss hands to `onValidationError`, derived so it stays in sync with the lib. */
-type ValidationIssues = Parameters<
-  NonNullable<Parameters<typeof createEnv>[0]['onValidationError']>
->[0];
+type ValidationIssues = Parameters<NonNullable<Parameters<typeof createEnv>[0]['onValidationError']>>[0];
 
 /**
  * Fold validation issues into a human-legible, log-pipeline-safe string. The t3-oss default handler
@@ -39,7 +36,7 @@ export function defineEnv<
   TClient extends Record<string, ZodType> = NonNullable<unknown>,
   TShared extends Record<string, ZodType> = NonNullable<unknown>,
   const TPrefix extends string = '',
-  const TExtends extends Array<Record<string, unknown>> = [],
+  const TExtends extends Record<string, unknown>[] = [],
 >(config: {
   /**
    * Label shown in validation-error logs, e.g. `'@acme/backend'`. Without it a misconfigured
@@ -86,7 +83,7 @@ export function defineEnv<
   // zero environment, and validation fires exactly when a value is actually
   // consumed (boot, a request, a job). This is the same import/observe split
   // drizzle tables have: define everywhere, observe only at use.
-  const build = (): Result => {
+  const build = (): Built<Result> => {
     const skipValidation =
       config.options?.skipValidation ?? (!!process.env.CI || process.env.NODE_ENV !== 'development');
 
@@ -138,8 +135,110 @@ export function defineEnv<
       onValidationError,
     } satisfies Record<string, unknown>;
 
-    return createEnv(options as Parameters<typeof createEnv>[0]) as Result;
+    const env = createEnv(options as Parameters<typeof createEnv>[0]) as Result;
+    // Skipped validation returns `runtimeEnv` itself: private only when `defineEnv` built it.
+    // Otherwise `createEnv` returns a fresh Proxy whose reads return its stored values on the server.
+    const isPrivate = skipValidation ? config.runtimeEnv === undefined : isServer();
+    return { env, isPrivate };
+  };
+
+  return lazyEnv(build);
+}
+
+/** The built env, and whether its reads may be copied (it is private and returns stored values). */
+type Built<T> = { env: T; isPrivate: boolean };
+
+/**
+ * Reads an env takes through the lazy view before it copies the values for fast reads. A copy costs
+ * about as much as this many reads save (ski-rental), so an env that is read only a few times, such
+ * as one built for a single check, never pays for it, and a hot env pays it once.
+ */
+const READS_BEFORE_COPY = 64;
+
+/**
+ * A lazy view over the env `build()` returns: nothing runs until the first operation, then every
+ * operation forwards to the built env.
+ *
+ * Reads are the hot path. `createEnv` returns a Proxy, so a second Proxy over it pays two traps per
+ * read. Where it is safe, once the env has been read `READS_BEFORE_COPY` times, its values are copied
+ * into the Proxy's own target and the `get` trap is removed, so later reads are plain property reads
+ * on that copy. It is safe when the built object is private to this env and reads on it return its
+ * stored values:
+ * - on the server, `createEnv`'s Proxy returns stored values (its client guard is off), and its
+ *   object is a fresh copy nobody else holds;
+ * - with validation skipped, `createEnv` returns the `runtimeEnv` it was given: only the one
+ *   `defineEnv` built itself is private. A caller's own `runtimeEnv` stays a live view.
+ * Writes and deletes through this object update both the built env and the copy.
+ */
+function lazyEnv<T extends object>(build: () => Built<T>): T {
+  let built: T | undefined;
+  let canCopy = false;
+  let copied = false;
+  let reads = 0;
+  const target: Record<PropertyKey, unknown> = {};
+
+  const resolve = (): T => {
+    if (built !== undefined) return built;
+    const result = build();
+    built = result.env;
+    canCopy = result.isPrivate;
+    return built;
+  };
+
+  const copy = (instance: T): void => {
+    for (const key of Reflect.ownKeys(instance)) {
+      setValue(target, key, readValue(instance, key));
+    }
+    copied = true;
+    Reflect.deleteProperty(handler, 'get');
+  };
+
+  const handler: ProxyHandler<Record<PropertyKey, unknown>> = {
+    get: (_target, property) => {
+      const instance = resolve();
+      if (canCopy && ++reads >= READS_BEFORE_COPY) {
+        copy(instance);
+        return target[property];
+      }
+      return readValue(instance, property);
+    },
+    set: (_target, property, value) => {
+      const instance = resolve();
+      const ok = Reflect.set(instance, property, value);
+      if (ok && copied) setValue(target, property, readValue(instance, property));
+      return ok;
+    },
+    deleteProperty: (_target, property) => {
+      const ok = Reflect.deleteProperty(resolve(), property);
+      if (ok && copied) Reflect.deleteProperty(target, property);
+      return ok;
+    },
+    getPrototypeOf: () => Reflect.getPrototypeOf(resolve()),
+    has: (_target, property) => Reflect.has(resolve(), property),
+    ownKeys: () => Reflect.ownKeys(resolve()),
+    getOwnPropertyDescriptor: (_target, property) => Object.getOwnPropertyDescriptor(resolve(), property),
   };
 
-  return lazyObject(build);
+  return new Proxy(target, handler) as T;
+}
+
+/** Same test `createEnv` uses to decide whether its client-side access guard applies. */
+function isServer(): boolean {
+  const { window } = globalThis as { window?: object };
+  return window === undefined || 'Deno' in window;
+}
+
+/** A read as the old lazy view returned it: functions come back bound to the built env. */
+function readValue(instance: object, property: PropertyKey): unknown {
+  const value: unknown = Reflect.get(instance, property, instance);
+  return typeof value === 'function' ? (value as (...args: unknown[]) => unknown).bind(instance) : value;
+}
+
+/** An own data property. `__proto__` is defined, not assigned, so it never replaces the prototype. */
+function setValue(target: Record<PropertyKey, unknown>, key: PropertyKey, value: unknown): void {
+  if (key === '__proto__') {
+    Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+  } else {
+    target[key] = value;
+  }
 }

package/src/dot.ts

@@ -34,9 +34,11 @@
  * that is intentional: the adapter only makes sense in a DOT app.
  */
 
-import { plugin, type EmptyShape, type Plugin } from '@arki/dot/plugin';
 import type { ZodType } from 'zod';
 
+import type { EmptyShape, Plugin } from '@arki/dot/plugin';
+import { plugin } from '@arki/dot/plugin';
+
 import { defineEnv } from './core/define-env.js';
 
 /**
@@ -79,10 +81,7 @@ export function env<TSchema extends Record<string, ZodType>>(
     boot() {
       const validated = defineEnv({
         server: options.schema,
-        options:
-          options.skipValidation !== undefined
-            ? { skipValidation: options.skipValidation }
-            : undefined,
+        options: options.skipValidation === undefined ? undefined : { skipValidation: options.skipValidation },
       });
       // `defineEnv` returns a Proxy from `@t3-oss/env-core`; we narrow it
       // to the schema-derived shape so downstream typing flows through.