@g14o/env-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gideon Ofori Addo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @g14o/env-core
+
+Framework-agnostic, typesafe environment variables validated with any [Standard Schema](https://standardschema.dev) library (Zod, Valibot, ArkType, and others).
+
+**Zero runtime dependencies** — install only the validator you use.
+
+## Install
+
+```bash
+pnpm add @g14o/env-core zod
+```
+
+### Peer dependencies
+
+`zod`, `valibot`, and `arktype` are **optional** peers — install the validator you use. Ranges follow [Standard Schema v1](https://standardschema.dev) support on each major line (`arktype` ^2.0.0, `valibot` ^1.0.0, `zod` ^4.0.0). `typescript` (>=5) is optional but recommended for typed env definitions.
+
+## Usage
+
+```ts
+import { createEnv } from "@g14o/env-core";
+import * as z from "zod";
+
+export const env = createEnv({
+  clientPrefix: "NEXT_PUBLIC_",
+  server: {
+    DATABASE_URL: z.url(),
+    OPEN_AI_API_KEY: z.string().min(1),
+  },
+  client: {
+    NEXT_PUBLIC_API_URL: z.url(),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+});
+```
+
+On the **server**, all variables are validated and readable. On the **client**, only `client` keys are validated; accessing a `server` key throws with the exact variable name.
+
+Import the same `env` object in server and client code — no separate client export is required.
+
+### How client protection works
+
+`createEnv` returns a [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) around the validated environment object (on both server and client):
+
+- **Server**: the proxy is transparent — all validated server and client keys are readable.
+- **Client**: only `client` schemas are validated at import time (missing server vars in `process.env` do not throw).
+- **Client access**: any property that is not a declared `client` key throws with the exact name, e.g. `DATABASE_URL` or typos like `NOT_DECLARED`.
+- **Interop**: `__esModule` and `$$typeof` are ignored so bundlers and React do not trigger false positives.
+
+### Valibot
+
+```ts
+import { createEnv } from "@g14o/env-core";
+import * as v from "valibot";
+
+export const env = createEnv({
+  clientPrefix: "PUBLIC_",
+  server: {
+    DATABASE_URL: v.pipe(v.string(), v.url()),
+  },
+  client: {
+    PUBLIC_API_URL: v.pipe(v.string(), v.url()),
+  },
+  runtimeEnv: process.env,
+});
+```
+
+### ArkType
+
+```ts
+import { createEnv } from "@g14o/env-core";
+import { type } from "arktype";
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: type("string.url"),
+  },
+  clientPrefix: "PUBLIC_",
+  client: {
+    PUBLIC_API_URL: type("string.url"),
+  },
+  runtimeEnv: process.env,
+});
+```
+
+### Strict runtime mapping (bundler-friendly)
+
+When your framework only inlines env vars you reference explicitly, use `runtimeEnvStrict`:
+
+```ts
+export const env = createEnv({
+  server: { DATABASE_URL: z.url() },
+  clientPrefix: "NEXT_PUBLIC_",
+  client: { NEXT_PUBLIC_API_URL: z.url() },
+  runtimeEnvStrict: {
+    DATABASE_URL: process.env.DATABASE_URL,
+    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
+  },
+});
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `server` | Server-only variables (validated on server; throw on client access) |
+| `client` | Client-safe variables (validated on server and client) |
+| `clientPrefix` | Optional prefix required on all `client` keys (type + runtime) |
+| `runtimeEnv` | Record to read values from (e.g. `process.env`) |
+| `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 |
+
+## Security
+
+Server **values** are never validated or exposed on the client. Importing a single `env.ts` that defines `server` schemas still ships those **names** to the client bundle. For sensitive names, split into `env/server.ts` and `env/client.ts`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+//#region src/client-guard.d.ts
+type OnInvalidAccessHandler = (variable: string) => void;
+//#endregion
+//#region src/standard-schema.d.ts
+/** @see https://standardschema.dev */
+type StandardSchemaV1<Input = unknown, Output = Input> = {
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+};
+declare namespace StandardSchemaV1 {
+  interface Props<Input = unknown, Output = Input> {
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    };
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    readonly vendor: string;
+    readonly version: 1;
+  }
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  interface SuccessResult<Output> {
+    readonly issues?: undefined;
+    readonly value: Output;
+  }
+  interface FailureResult {
+    readonly issues: readonly Issue[];
+  }
+  interface Issue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | PathSegment)[] | undefined;
+  }
+  interface PathSegment {
+    readonly key: PropertyKey;
+  }
+}
+//#endregion
+//#region src/types.d.ts
+type SchemaShape = Record<string, StandardSchemaV1>;
+type RuntimeEnvValue = string | number | boolean | undefined | null;
+type RuntimeEnvInput = Record<string, RuntimeEnvValue>;
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+type InferSchemaOutput<TSchema extends StandardSchemaV1> = TSchema extends StandardSchemaV1<unknown, infer TOutput> ? TOutput : never;
+type InferShapeOutput<TShape extends SchemaShape> = Simplify<{ [K in keyof TShape]: InferSchemaOutput<TShape[K]> }>;
+type ClientKeyWithPrefix<TPrefix extends string, TKey extends PropertyKey> = TKey extends `${TPrefix}${string}` ? TKey : never;
+type PrefixedClientShape<TPrefix extends string, TClient extends SchemaShape> = Simplify<{ [K in keyof TClient as ClientKeyWithPrefix<TPrefix, K>]: TClient[K] }>;
+type InvalidClientKeys<TPrefix extends string, TClient extends SchemaShape> = Exclude<keyof TClient, `${TPrefix}${string}`>;
+type AssertValidClientPrefix<TPrefix extends string | undefined, TClient extends SchemaShape | undefined> = TPrefix extends string ? TClient extends SchemaShape ? InvalidClientKeys<TPrefix, TClient> extends never ? unknown : `Client environment variable(s) must start with "${TPrefix}": ${InvalidClientKeys<TPrefix, TClient> & string}` : unknown : unknown;
+type ResolveClientShape<TPrefix extends string | undefined, TClient extends SchemaShape | undefined> = TClient extends SchemaShape ? TPrefix extends string ? PrefixedClientShape<TPrefix, TClient> : TClient : Record<string, never>;
+type ShapeKeys<TShape extends SchemaShape | undefined> = TShape extends SchemaShape ? keyof TShape : never;
+type StrictRuntimeEnv<TServer extends SchemaShape | undefined, TClient extends SchemaShape | undefined> = Simplify<{ [K in ShapeKeys<TServer> | ShapeKeys<TClient>]: RuntimeEnvValue }>;
+type MutuallyExclusive<A extends Record<string, unknown>, B extends Record<string, unknown>> = (A & { [K in keyof B]?: never }) | (B & { [K in keyof A]?: never });
+type RuntimeEnvSource<TServer extends SchemaShape | undefined, TClient extends SchemaShape | undefined> = MutuallyExclusive<{
+  runtimeEnv: RuntimeEnvInput;
+}, {
+  runtimeEnvStrict: StrictRuntimeEnv<TServer, TClient>;
+}>;
+type MergeEnvShapes<TServer extends SchemaShape | undefined, TClient extends SchemaShape | undefined> = (TServer extends SchemaShape ? TServer : Record<string, never>) & (TClient extends SchemaShape ? TClient : Record<string, never>);
+type CreateEnvOptions<TServer extends SchemaShape | undefined = undefined, TClient extends SchemaShape | undefined = undefined, TPrefix extends string | undefined = undefined> = {
+  server?: TServer;
+  client?: TClient;
+  clientPrefix?: TPrefix;
+  emptyStringAsUndefined?: boolean;
+  isServer?: boolean;
+  onInvalidAccess?: OnInvalidAccessHandler; /** @internal */
+  skipValidation?: boolean;
+} & RuntimeEnvSource<TServer, TClient>;
+type CreateEnvOutput<TServer extends SchemaShape | undefined, TClient extends SchemaShape | undefined> = Readonly<InferShapeOutput<MergeEnvShapes<TServer, TClient>>>;
+//#endregion
+//#region src/create-env.d.ts
+/**
+* Validates environment variables with Standard Schema shapes and returns a typed, frozen env object.
+*
+* On the server (`isServer` true by default when `globalThis.window` is undefined), all declared
+* `server` and `client` keys are picked from `runtimeEnv` or `runtimeEnvStrict`, validated, and
+* exposed. On the client, only `client` keys are validated; `server` keys are omitted from the
+* validated object and throw if accessed (via a `Proxy` guard unless `onInvalidAccess` handles it).
+*
+* When `skipValidation` is true, values are picked without schema validation (internal/testing use).
+*
+* @template TServer - Server-only schema shape.
+* @template TClient - Client-safe schema shape.
+* @template TPrefix - Required `client` key prefix when `clientPrefix` is set.
+* @param options - Server/client schemas, runtime source, and validation behavior.
+* @param options.server - Server-only variables; validated only when `isServer` is true.
+* @param options.client - Variables safe on the client; always validated unless `skipValidation`.
+* @param options.clientPrefix - Prefix every `client` key must use (enforced at compile time and runtime).
+* @param options.runtimeEnv - Loose record to read values from (e.g. `process.env`).
+* @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.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`.
+*
+* @example
+* ```ts
+* import { createEnv } from "@g14o/env-core";
+* import * as z from "zod";
+*
+* export const env = createEnv({
+*   clientPrefix: "PUBLIC_",
+*   server: {
+*     DATABASE_URL: z.url(),
+*     OPEN_AI_API_KEY: z.string().min(8),
+*   },
+*   client: {
+*     PUBLIC_API_URL: z.url(),
+*     PUBLIC_APP_NAME: z.string().min(1),
+*   },
+*   runtimeEnvStrict: runtimeEnvStrict(),
+*   emptyStringAsUndefined: true,
+* });
+* ```
+*/
+declare function createEnv<TServer extends SchemaShape | undefined = undefined, const TClient extends SchemaShape | undefined = undefined, const TPrefix extends string | undefined = undefined>(options: CreateEnvOptions<TServer, TClient, TPrefix> & AssertValidClientPrefix<TPrefix, TClient>): CreateEnvOutput<TServer, ResolveClientShape<TPrefix, TClient>>;
+//#endregion
+//#region src/errors.d.ts
+declare class InvalidEnvironmentVariablesError extends Error {
+  readonly issues: readonly string[];
+  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 };

package/dist/index.js

@@ -0,0 +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};

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@g14o/env-core",
+  "version": "0.1.0",
+  "description": "Framework-agnostic, typesafe environment variables via Standard Schema (Zod, Valibot, ArkType).",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wuzgood98/g14o.git",
+    "directory": "packages/env-core"
+  },
+  "bugs": "https://github.com/wuzgood98/g14o/issues",
+  "homepage": "https://github.com/wuzgood98/g14o/tree/main/packages/env-core#readme",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "arktype": "^2.0.0",
+    "typescript": ">=5.0.0",
+    "valibot": "^1.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    },
+    "arktype": {
+      "optional": true
+    },
+    "valibot": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "arktype": "^2.0.0",
+    "rimraf": "^6.0.1",
+    "tsdown": "^0.22.1",
+    "typescript": "^5",
+    "valibot": "^1.0.0",
+    "vitest": "^3.2.4",
+    "zod": "^4.0.0",
+    "@workspace/typescript-config": "0.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "environment",
+    "env",
+    "validation",
+    "zod",
+    "valibot",
+    "arktype",
+    "standard-schema",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test-types/tsconfig.json",
+    "test": "vitest run"
+  }
+}