@tmrp/env 0.1.1 → 0.1.3

package/README.md

@@ -3,11 +3,11 @@
 Type-safe environment variable parsing for TypeScript projects, powered by
 [Zod](https://zod.dev/).
 
-`@tmrp/env` reads environment variables from the current runtime or an
-explicit env-like object, validates them with Zod schemas, and returns a
-strongly typed object for application code. It supports Node.js, Deno, Bun,
-Cloudflare Workers, Vercel Edge, Netlify, browser-injected config, and
-`import.meta.env`-based toolchains.
+`@tmrp/env` reads environment variables from the current runtime or an explicit
+env-like object, validates them with Zod schemas, and returns a strongly typed
+object for application code. It supports Node.js, Deno, Bun, Cloudflare Workers,
+Vercel Edge, Netlify, browser-injected config, and `import.meta.env`-based
+toolchains.
 
 ## Features
 
@@ -278,6 +278,36 @@ const env = createImportMetaEnv(
 );
 ```
 
+### Client-exposed Variables (`clientPrefix`)
+
+When building applications that run code on both the server and client-side
+(e.g. Next.js, Vite, Nuxt), the bundler statically injects environment variables
+that are prefixed with a specific keyword (like `NEXT_PUBLIC_` or `VITE_`).
+
+On the client-side, trying to validate server-only environment variables will
+normally throw errors because those variables are not exposed. To prevent this,
+you can pass the `clientPrefix` option:
+
+```ts
+import { createEnv } from "@tmrp/env";
+import z from "zod";
+
+const env = createEnv(
+  {
+    DATABASE_URL: z.string(), // Server-only
+    NEXT_PUBLIC_API_URL: z.url(), // Client-exposed
+  },
+  {
+    clientPrefix: "NEXT_PUBLIC_",
+  }
+);
+```
+
+When running in a client environment (determined automatically by checking if
+`"window" in globalThis` is false, or overridden by passing `isServer: false`),
+only keys that start with the `clientPrefix` will be read and validated. All
+other keys will bypass validation and return `undefined` on the client.
+
 ## Defining Schemas
 
 Pass an object whose keys are environment variable names and whose values are
@@ -366,8 +396,9 @@ env.PORT; // raw string value, or undefined when unavailable
 env.SECRET_KEY; // raw string value, or undefined when unavailable
 ```
 
-This option is intended for non-runtime code paths. Do not use it for application
-startup if the returned values will be used as validated configuration.
+This option is intended for non-runtime code paths. Do not use it for
+application startup if the returned values will be used as validated
+configuration.
 
 ## Error Behavior
 
@@ -408,6 +439,8 @@ Reads variables from the detected Bun, Node, or Deno runtime and validates them.
 
 ```ts
 type Options = {
+  clientPrefix?: string;
+  isServer?: boolean;
   skipValidation?: boolean;
 };
 

package/dist/effects/create-env-effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-env-effect.d.ts","sourceRoot":"","sources":["../../src/effects/create-env-effect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAK7D,wBAAgB,eAAe,CAAC,KAAK,CAAC,QAAQ,SAAS,OAAO,EAC5D,OAAO,EAAE,QAAQ,EACjB,aAAa,EAAE,wBAAwB,EACvC,oBAAoB,EAAE,CACpB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,wBAAwB,KAC7B,OAAO,EACZ,OAAO,CAAC,EAAE,OAAO,GAiBH,GAAG,CAAC,QAAQ,CAAC,CAC5B"}
+{"version":3,"file":"create-env-effect.d.ts","sourceRoot":"","sources":["../../src/effects/create-env-effect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAK7D,wBAAgB,eAAe,CAAC,KAAK,CAAC,QAAQ,SAAS,OAAO,EAC5D,OAAO,EAAE,QAAQ,EACjB,aAAa,EAAE,wBAAwB,EACvC,oBAAoB,EAAE,CACpB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,wBAAwB,KAC7B,OAAO,EACZ,OAAO,CAAC,EAAE,OAAO,GA4BH,GAAG,CAAC,QAAQ,CAAC,CAC5B"}

package/dist/effects/create-env-effect.js

@@ -2,7 +2,16 @@ import { Effect } from "effect";
 import { envParseValueEffect } from "./env-parse-value-effect.js";
 import { envReadValueEffect } from "./env-read-value-effect.js";
 export function createEnvEffect(envKeys, runtimeSchema, runtimeEnvReadEffect, options) {
-    const env = Effect.runSync(Effect.forEach(Object.entries(envKeys), ([key, schema]) => envReadValueEffect(key, (env) => runtimeEnvReadEffect(env, runtimeSchema), options).pipe(Effect.flatMap((value) => envParseValueEffect(key, schema, value, options)), Effect.map((value) => [key, value]))).pipe(Effect.map((entries) => Object.fromEntries(entries))));
+    const isServer = options?.isServer ?? !("window" in globalThis);
+    const clientPrefix = options?.clientPrefix;
+    const env = Effect.runSync(Effect.forEach(Object.entries(envKeys), ([key, schema]) => {
+        if (!isServer &&
+            clientPrefix !== undefined &&
+            !key.startsWith(clientPrefix)) {
+            return Effect.succeed([key, undefined]);
+        }
+        return envReadValueEffect(key, (env) => runtimeEnvReadEffect(env, runtimeSchema), options).pipe(Effect.flatMap((value) => envParseValueEffect(key, schema, value, options)), Effect.map((value) => [key, value]));
+    }).pipe(Effect.map((entries) => Object.fromEntries(entries))));
     return env;
 }
 //# sourceMappingURL=create-env-effect.js.map

package/dist/effects/create-env-effect.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-env-effect.js","sourceRoot":"","sources":["../../src/effects/create-env-effect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,MAAM,UAAU,eAAe,CAC7B,OAAiB,EACjB,aAAuC,EACvC,oBAGY,EACZ,OAAiB;IAEjB,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CACxB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,CACxD,kBAAkB,CAChB,GAAG,EACH,CAAC,GAAG,EAAE,EAAE,CAAC,oBAAoB,CAAC,GAAG,EAAE,aAAa,CAAC,EACjD,OAAO,CACR,CAAC,IAAI,CACJ,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CACvB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CACjD,EACD,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAU,CAAC,CAC7C,CACF,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAC7D,CAAC;IAEF,OAAO,GAAoB,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"create-env-effect.js","sourceRoot":"","sources":["../../src/effects/create-env-effect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,MAAM,UAAU,eAAe,CAC7B,OAAiB,EACjB,aAAuC,EACvC,oBAGY,EACZ,OAAiB;IAEjB,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,CAAC,CAAC,QAAQ,IAAI,UAAU,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;IAE3C,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CACxB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE;QACxD,IACE,CAAC,QAAQ;YACT,YAAY,KAAK,SAAS;YAC1B,CAAC,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,EAC7B,CAAC;YACD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,SAAS,CAAU,CAAC,CAAC;QACnD,CAAC;QAED,OAAO,kBAAkB,CACvB,GAAG,EACH,CAAC,GAAG,EAAE,EAAE,CAAC,oBAAoB,CAAC,GAAG,EAAE,aAAa,CAAC,EACjD,OAAO,CACR,CAAC,IAAI,CACJ,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CACvB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CACjD,EACD,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAU,CAAC,CAC7C,CAAC;IACJ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAC9D,CAAC;IAEF,OAAO,GAAoB,CAAC;AAC9B,CAAC"}

package/dist/lib/types.d.ts

@@ -5,6 +5,8 @@ export type Env<TEnvKeys extends EnvKeys> = {
 export type EnvKeys = Record<string, ZodType>;
 export type EnvRecord = object;
 export type Options = {
+    clientPrefix?: string;
+    isServer?: boolean;
     skipValidation?: boolean;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEtC,MAAM,MAAM,GAAG,CAAC,QAAQ,SAAS,OAAO,IAAI;KACzC,CAAC,IAAI,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,MAAM,MAAM,OAAO,GAAG;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEtC,MAAM,MAAM,GAAG,CAAC,QAAQ,SAAS,OAAO,IAAI;KACzC,CAAC,IAAI,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,MAAM,MAAM,OAAO,GAAG;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC"}

package/dist/runtime/record/create-record-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-record-env.d.ts","sourceRoot":"","sources":["../../../src/runtime/record/create-record-env.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAM3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,QAAQ,SAAS,OAAO,EAC5D,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE,OAAO,GAiBH,GAAG,CAAC,QAAQ,CAAC,CAC5B"}
+{"version":3,"file":"create-record-env.d.ts","sourceRoot":"","sources":["../../../src/runtime/record/create-record-env.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAM3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,QAAQ,SAAS,OAAO,EAC5D,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE,OAAO,GA4BH,GAAG,CAAC,QAAQ,CAAC,CAC5B"}

package/dist/runtime/record/create-record-env.js

@@ -33,7 +33,16 @@ import { readRecordEnv } from "./lib/read-record-env.js";
  *   `options.skipValidation` is enabled.
  */
 export function createRecordEnv(envKeys, record, options) {
-    const env = Effect.runSync(Effect.forEach(Object.entries(envKeys), ([key, schema]) => envReadValueEffect(key, (env) => readRecordEnv(env, record), options).pipe(Effect.flatMap((value) => envParseValueEffect(key, schema, value, options)), Effect.map((value) => [key, value]))).pipe(Effect.map((entries) => Object.fromEntries(entries))));
+    const isServer = options?.isServer ?? !("window" in globalThis);
+    const clientPrefix = options?.clientPrefix;
+    const env = Effect.runSync(Effect.forEach(Object.entries(envKeys), ([key, schema]) => {
+        if (!isServer &&
+            clientPrefix !== undefined &&
+            !key.startsWith(clientPrefix)) {
+            return Effect.succeed([key, undefined]);
+        }
+        return envReadValueEffect(key, (env) => readRecordEnv(env, record), options).pipe(Effect.flatMap((value) => envParseValueEffect(key, schema, value, options)), Effect.map((value) => [key, value]));
+    }).pipe(Effect.map((entries) => Object.fromEntries(entries))));
     return env;
 }
 //# sourceMappingURL=create-record-env.js.map

package/dist/runtime/record/create-record-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-record-env.js","sourceRoot":"","sources":["../../../src/runtime/record/create-record-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAiB,EACjB,MAAiB,EACjB,OAAiB;IAEjB,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CACxB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,CACxD,kBAAkB,CAChB,GAAG,EACH,CAAC,GAAG,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,EACnC,OAAO,CACR,CAAC,IAAI,CACJ,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CACvB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CACjD,EACD,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAU,CAAC,CAC7C,CACF,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAC7D,CAAC;IAEF,OAAO,GAAoB,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"create-record-env.js","sourceRoot":"","sources":["../../../src/runtime/record/create-record-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAiB,EACjB,MAAiB,EACjB,OAAiB;IAEjB,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,CAAC,CAAC,QAAQ,IAAI,UAAU,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;IAE3C,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CACxB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE;QACxD,IACE,CAAC,QAAQ;YACT,YAAY,KAAK,SAAS;YAC1B,CAAC,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,EAC7B,CAAC;YACD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,SAAS,CAAU,CAAC,CAAC;QACnD,CAAC;QAED,OAAO,kBAAkB,CACvB,GAAG,EACH,CAAC,GAAG,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,EACnC,OAAO,CACR,CAAC,IAAI,CACJ,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CACvB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CACjD,EACD,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAU,CAAC,CAC7C,CAAC;IACJ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAC9D,CAAC;IAEF,OAAO,GAAoB,CAAC;AAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmrp/env",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Type-safe environment variable parsing, powered by Zod.",
   "keywords": [
     "env",