@arkenv/core 1.0.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yam Borodetsky <https://yam.codes/>
+
+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,104 @@
+<p align="center">
+  <a href="https://github.com/yamcodes/arkenv/blob/main/apps/www/public/assets/icon.svg"><img alt="ArkEnv Logo" src="https://arkenv.js.org/assets/icon.svg" width="160px" align="center"/></a>
+  <h1 align="center">ArkEnv</h1>
+  <div align="center">
+    <p align="center">
+      Environment variable validation from editor to runtime<br/> for <a href="https://nextjs.org/">Next.js</a>, <a href="https://nuxt.com/">Nuxt</a>, <a href="https://nodejs.org/">Node.js</a>, <a href="https://vite.dev/">Vite</a>, and <a href="https://bun.com/">Bun</a>
+    </p>
+    <a href="https://github.com/yamcodes/arkenv/actions/workflows/test.yml?query=branch%3Amain"><img alt="Test Status" src="https://github.com/yamcodes/arkenv/actions/workflows/tests-badge.yml/badge.svg?branch=main"></a>
+    <a href="https://bundlephobia.com/package/arkenv"><img alt="npm bundle size" src="https://img.shields.io/bundlephobia/minzip/arkenv"></a>
+    <a href="https://arktype.io/docs/ecosystem#arkenv"><img alt="ArkType Ecosystem" src="https://custom-icon-badges.demolab.com/badge/ArkType%20Ecosystem-0d1526?logo=arktype2&logoColor=e9eef9"></a>
+    <a href="https://pullfrog.com"><img alt="Pullfrog" src="https://custom-icon-badges.demolab.com/badge/Powered%20by%20Pullfrog-2f4032?logo=pullfrog-white"></a>
+  </div>
+</p>
+
+<div align="center">
+  <a href="https://arkenv.js.org/docs/arkenv">Docs</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://arkenv.js.org/docs/arkenv/faq">FAQ</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://stackblitz.com/github/yamcodes/arkenv/tree/main/examples/stackblitz?file=index.ts">Try on StackBlitz</a>
+  <br />
+</div>
+
+<br />
+<br />
+
+<p align="center">
+  <img alt="ArkEnv Demo" src="https://arkenv.js.org/assets/demo.gif" />
+</p>
+
+<br />
+
+
+
+<details open>
+<summary>npm</summary>
+
+```sh
+npx arkenv@latest init
+```
+
+</details>
+
+<details>
+<summary>pnpm</summary>
+
+```sh
+pnx arkenv@latest init
+```
+
+</details>
+
+<details>
+<summary>Yarn</summary>
+
+```sh
+yarn dlx arkenv@latest init
+```
+
+</details>
+
+<details>
+<summary>Bun</summary>
+
+```sh
+bunx arkenv@latest init
+```
+
+</details>
+
+<br />
+
+### [Read the docs →](https://arkenv.js.org/docs/ArkEnv/quickstart)
+
+<br />
+
+## Supporting ArkEnv
+
+If you love ArkEnv, you can support the project by **starring it on GitHub**!
+
+You are also welcome to [contribute to the project](https://github.com/yamcodes/arkenv/blob/main/docs/CONTRIBUTING.md) and join the wonderful people who have contributed:
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://yam.codes"><img src="https://avatars.githubusercontent.com/u/2014360?v=4?s=100" width="100px;" alt="Yam C Borodetsky"/><br /><sub><b>Yam C Borodetsky</b></sub></a><br /><a href="https://github.com/yamcodes/arkenv/commits?author=yamcodes" title="Code">💻</a> <a href="#question-yamcodes" title="Answering Questions">💬</a> <a href="#ideas-yamcodes" title="Ideas, Planning, & Feedback">🤔</a> <a href="#design-yamcodes" title="Design">🎨</a> <a href="https://github.com/yamcodes/arkenv/commits?author=yamcodes" title="Documentation">📖</a> <a href="https://github.com/yamcodes/arkenv/issues?q=author%3Ayamcodes" title="Bug reports">🐛</a> <a href="#example-yamcodes" title="Examples">💡</a> <a href="#infra-yamcodes" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/yamcodes/arkenv/commits?author=yamcodes" title="Tests">⚠️</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/aruaycodes"><img src="https://avatars.githubusercontent.com/u/57131628?v=4?s=100" width="100px;" alt="Aruay Berdikulova"/><br /><sub><b>Aruay Berdikulova</b></sub></a><br /><a href="https://github.com/yamcodes/arkenv/commits?author=aruaycodes" title="Code">💻</a> <a href="#ideas-aruaycodes" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://arktype.io"><img src="https://avatars.githubusercontent.com/u/10645823?v=4?s=100" width="100px;" alt="David Blass"/><br /><sub><b>David Blass</b></sub></a><br /><a href="#ideas-ssalbdivad" title="Ideas, Planning, & Feedback">🤔</a> <a href="#mentoring-ssalbdivad" title="Mentoring">🧑‍🏫</a> <a href="#question-ssalbdivad" title="Answering Questions">💬</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/danciudev"><img src="https://avatars.githubusercontent.com/u/44430251?v=4?s=100" width="100px;" alt="Andrei Danciu"/><br /><sub><b>Andrei Danciu</b></sub></a><br /><a href="https://github.com/yamcodes/arkenv/commits?author=danciudev" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://joakim.beng.se"><img src="https://avatars.githubusercontent.com/u/1427383?v=4?s=100" width="100px;" alt="Joakim Carlstein"/><br /><sub><b>Joakim Carlstein</b></sub></a><br /><a href="https://github.com/yamcodes/arkenv/commits?author=joakimbeng" title="Code">💻</a> <a href="https://github.com/yamcodes/arkenv/commits?author=joakimbeng" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://fresh-accordion-06a.notion.site/Jiayi-Du-1817075e92978076b95cf9d90fb5eceb"><img src="https://avatars.githubusercontent.com/u/166608075?v=4?s=100" width="100px;" alt="RoomWithOutRoof"/><br /><sub><b>RoomWithOutRoof</b></sub></a><br /><a href="https://github.com/yamcodes/arkenv/commits?author=Jah-yee" title="Documentation">📖</a></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+We [acknowledge](https://github.com/yamcodes/arkenv/blob/main/docs/ACKNOWLEDGEMENTS.md) the various projects and people that inspired ArkEnv.

package/dist/index.cjs

@@ -0,0 +1,403 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+let arktype = require("arktype");
+
+//#region ../internal/scope/dist/index.js
+const n$1 = (0, arktype.type)(`0 <= number.integer <= 65535`), r$1 = (0, arktype.type)(`string.ip | 'localhost'`), i$1 = (0, arktype.scope)({
+	string: arktype.type.module({
+		...arktype.type.keywords.string,
+		host: r$1
+	}),
+	number: arktype.type.module({
+		...arktype.type.keywords.number,
+		port: n$1
+	})
+});
+
+//#endregion
+//#region ../internal/utils/dist/index.js
+const e = (e) => {
+	if (typeof e == `number` || typeof e != `string` || !e.trim()) return e;
+	if (e.trim() === `NaN`) return NaN;
+	let t = Number(e);
+	return Number.isNaN(t) ? e : t;
+}, t = (e) => e === `true` ? !0 : e === `false` ? !1 : e, n = (e) => {
+	if (typeof e != `string`) return e;
+	let t = e.trim();
+	if (t[0] !== `{` && t[0] !== `[`) return e;
+	try {
+		return JSON.parse(t);
+	} catch {
+		return e;
+	}
+}, r = (e) => {
+	if (e instanceof Date || typeof e != `string` || !e.trim()) return e;
+	let t = new Date(e);
+	return Number.isNaN(t.getTime()) ? e : t;
+}, i = (e) => {
+	let t = {};
+	for (let n in e) {
+		let r = e[n];
+		r !== `` && (t[n] = r);
+	}
+	return t;
+}, a = `*`, o = (e, t = []) => {
+	let n = [];
+	if (!e || typeof e != `object` || Array.isArray(e)) return n;
+	let r = e;
+	if (`const` in r) {
+		let e = typeof r.const;
+		(e === `number` || e === `boolean`) && n.push({
+			path: [...t],
+			type: `primitive`
+		});
+	}
+	`enum` in r && Array.isArray(r.enum) && r.enum.some((e) => typeof e == `number` || typeof e == `boolean`) && n.push({
+		path: [...t],
+		type: `primitive`
+	});
+	let i = r.type;
+	if (i === `number` || i === `integer` || i === `boolean`) n.push({
+		path: [...t],
+		type: `primitive`
+	});
+	else if (i === `string` && `format` in r && (r.format === `date-time` || r.format === `date`)) n.push({
+		path: [...t],
+		type: `date`
+	});
+	else if (i === `object`) {
+		if (r.properties && Object.keys(r.properties).length > 0) {
+			n.push({
+				path: [...t],
+				type: `object`
+			});
+			for (let e in r.properties) n.push(...o(r.properties[e], [...t, e]));
+		}
+	} else i === `array` && (n.push({
+		path: [...t],
+		type: `array`
+	}), r.items && (Array.isArray(r.items) ? r.items.forEach((e, r) => {
+		n.push(...o(e, [...t, String(r)]));
+	}) : n.push(...o(r.items, [...t, `*`]))));
+	for (let e of [
+		`anyOf`,
+		`allOf`,
+		`oneOf`
+	]) if (r[e] && Array.isArray(r[e])) for (let i of r[e]) n.push(...o(i, t));
+	let a = /* @__PURE__ */ new Set();
+	return n.filter((e) => {
+		let t = e.path.join(`/`) + `:` + e.type;
+		return a.has(t) ? !1 : a.add(t);
+	});
+}, s = (i, a, o = {}) => {
+	let { arrayFormat: s = `comma` } = o, c = (e) => {
+		if (s === `json`) try {
+			return JSON.parse(e);
+		} catch {
+			return e;
+		}
+		return e.trim() ? e.split(`,`).map((e) => e.trim()) : [];
+	}, l = (i, a) => {
+		if (a === `array` && typeof i == `string`) return c(i);
+		if (a === `object` && typeof i == `string`) return n(i);
+		if (a === `date` && typeof i == `string`) return r(i);
+		if (a === `primitive`) {
+			if (Array.isArray(i)) return i.map((n) => {
+				if (typeof n != `string`) return n;
+				let r = e(n);
+				return typeof r == `number` ? r : t(n);
+			});
+			if (typeof i != `string`) return i;
+			let n = e(i);
+			return typeof n == `number` ? n : t(i);
+		}
+		return i;
+	};
+	if (typeof i != `object` || !i) {
+		let e = a.find((e) => e.path.length === 0);
+		return e ? l(i, e.type) : i;
+	}
+	let u = [...a].sort((e, t) => e.path.length - t.path.length), d = (e, t, n) => {
+		if (t.length === 0) return n(e);
+		let [r, ...i] = t;
+		if (r === `*`) {
+			if (Array.isArray(e)) {
+				let t = !1, r = e.map((e) => {
+					let r = d(e, i, n);
+					return r !== e && (t = !0), r;
+				});
+				return t ? r : e;
+			}
+			return e;
+		}
+		if (!e || typeof e != `object`) return e;
+		if (Array.isArray(e)) {
+			let t = Number(r);
+			if (!Number.isNaN(t) && t >= 0 && t < e.length) {
+				let r = d(e[t], i, n);
+				if (r !== e[t]) {
+					let n = [...e];
+					return n[t] = r, n;
+				}
+			}
+			return e;
+		}
+		if (Object.hasOwn(e, r)) {
+			let t = d(e[r], i, n);
+			if (t !== e[r]) return {
+				...e,
+				[r]: t
+			};
+		}
+		return e;
+	}, f = i;
+	for (let e of u) e.path.length > 0 && (f = d(f, e.path, (t) => l(t, e.type)));
+	return f;
+};
+function c(e, t, n, r) {
+	let a = t ? i(e) : e, c = { ...a }, l = [];
+	if (r) {
+		let e = r();
+		l.push(...e.missingKeys || []), e.hasSchema && (c = s(c, o(e.schema), { arrayFormat: n }));
+	}
+	return {
+		processedEnv: a,
+		coercedEnv: c,
+		missingKeys: l
+	};
+}
+const l = (e, t = 2, { dontDetectNewlines: n = !1 } = {}) => n ? `${` `.repeat(t)}${e}` : e.split(`
+`).map((e) => `${` `.repeat(t)}${e}`).join(`
+`), u = {
+	red: `\x1B[31m`,
+	yellow: `\x1B[33m`,
+	cyan: `\x1B[36m`,
+	reset: `\x1B[0m`
+}, d = () => typeof process < `u` && process.versions != null && process.versions.node != null, f = () => !!(!d() || process.env.NO_COLOR !== void 0 || process.env.CI !== void 0 || process.stdout && !process.stdout.isTTY), p = (e, t) => d() && !f() ? `${u[e]}${t}${u.reset}` : t;
+function m(e) {
+	return e.map((e) => `${p(`yellow`, e.path)} ${e.message.trimStart()}`).join(`
+`);
+}
+var h = class extends Error {
+	constructor(e, t = `Errors found while validating environment variables`) {
+		let n = m(e);
+		super(`${p(`red`, t)}\n${l(n)}\n`), this.name = `ArkEnvError`, this.issues = e;
+	}
+};
+Object.defineProperty(h, `name`, { value: `ArkEnvError` });
+const y = /secret|(_|^)key(_|$)|token|(_|^)password(_|$)|(_|^)pass(_|$)|(_|^)auth(_|$)|jwt|cert|credential|database_url|db_url/i;
+function b(e) {
+	if (e !== void 0) return e;
+	if (typeof process > `u`) return !1;
+	let t = process.env.ARKENV_DEBUG_SECRETS;
+	return t === `true` || t === `1`;
+}
+function x(e) {
+	return y.test(e) && !/public/i.test(e);
+}
+function E(e) {
+	try {
+		return {
+			success: !0,
+			data: e()
+		};
+	} catch (e) {
+		if (e instanceof h) return {
+			success: !1,
+			issues: e.issues
+		};
+		throw e;
+	}
+}
+function D(e, t, n, r, i, a) {
+	let o = {
+		path: e,
+		message: t,
+		code: n,
+		meta: r ?? {}
+	};
+	return i && (o.expected = i), a !== void 0 && (o.received = a), o;
+}
+function P(e) {
+	if (!e || typeof e != `object` && typeof e != `function`) return [];
+	if (e.json && typeof e.json == `object` && e.json.domain === `object`) {
+		let t = [];
+		if (Array.isArray(e.json.required)) for (let n of e.json.required) n && typeof n == `object` && `key` in n && t.push(n.key);
+		if (Array.isArray(e.json.optional)) for (let n of e.json.optional) n && typeof n == `object` && `key` in n && t.push(n.key);
+		return t;
+	}
+	let t = e[`~standard`], n = typeof t?.jsonSchema?.input == `function` && t.jsonSchema.input || typeof e.jsonSchema?.input == `function` && e.jsonSchema.input;
+	if (n) try {
+		let e = n({ target: `draft-07` });
+		if (e && typeof e == `object` && e.properties) return Object.keys(e.properties);
+	} catch {}
+	if (typeof e.toJSONSchema == `function`) try {
+		let t = e.toJSONSchema();
+		if (t && typeof t == `object` && t.properties) return Object.keys(t.properties);
+	} catch {}
+	if (typeof e.toStandardJSONSchema?.v1 == `function`) try {
+		let t = e.toStandardJSONSchema.v1();
+		if (t && typeof t == `object` && t.properties) return Object.keys(t.properties);
+	} catch {}
+	return Object.keys(e);
+}
+
+//#endregion
+//#region src/arktype/index.ts
+const ARKTYPE_CODE_MAP = {
+	required: "MISSING_VARIABLE",
+	pattern: "PATTERN_MISMATCH",
+	min: "VALUE_TOO_SMALL",
+	minLength: "VALUE_TOO_SMALL",
+	max: "VALUE_TOO_LARGE",
+	maxLength: "VALUE_TOO_LARGE",
+	divisor: "INVALID_TYPE",
+	intersection: "INVALID_TYPE",
+	union: "INVALID_TYPE",
+	unit: "INVALID_TYPE",
+	proto: "INVALID_TYPE",
+	domain: "INVALID_TYPE",
+	exactLength: "INVALID_FORMAT",
+	before: "INVALID_FORMAT",
+	after: "INVALID_FORMAT",
+	predicate: "CUSTOM"
+};
+/**
+* Map an ArkType error code to an ArkEnv issue code.
+*
+* @param engineCode The ArkType engine error code
+* @returns The corresponding ArkEnv issue code
+*/
+function mapArkTypeCode(engineCode) {
+	return engineCode in ARKTYPE_CODE_MAP ? ARKTYPE_CODE_MAP[engineCode] : "INVALID_FORMAT";
+}
+/**
+* Extract numeric bounds from an ArkType error object.
+*
+* @param error The ArkType error object
+* @returns An object containing optional min and max bounds
+*/
+function getArkTypeMeta(error) {
+	const min = error.min ?? error.rule;
+	const max = error.max;
+	return {
+		...typeof min === "number" ? { min } : {},
+		...typeof max === "number" ? { max } : {}
+	};
+}
+/**
+* Redact and colorize the value inside a "(was ...)" message fragment.
+*
+* @param message The validation error message
+* @param path The environment variable key path
+* @param debugSecrets Whether to display sensitive values in debug mode
+* @returns The modified error message with styled or redacted value
+*/
+function redactMessageWasValue(message, path, debugSecrets) {
+	const valueMatch = message.match(/\(was (.*)\)/);
+	if (!valueMatch?.[1]) return message;
+	const value = valueMatch[1];
+	const displayedValue = !b(debugSecrets) && x(path) ? "[REDACTED]" : value;
+	if (displayedValue.includes("\x1B[")) return message;
+	return message.replace(`(was ${value})`, `(was ${p("cyan", displayedValue)})`);
+}
+/**
+* Convert ArkType's `ArkErrors` (keyed by path) into a flat `EnvIssue[]`
+* suitable for `ArkEnvError`.
+*
+* @param errors The ArkType errors object to convert
+* @param config Optional ArkEnvConfig to read debugSecrets options
+* @returns An array of flattened validation issues
+*
+* @internal
+*/
+function arkErrorsToIssues(errors, config) {
+	return Object.entries(errors.byPath).map(([path, error]) => {
+		let message = error.message;
+		let trimmed = message.trimStart();
+		if (trimmed.length > 0 && ":.-".includes(trimmed[0])) trimmed = trimmed.slice(1).trimStart();
+		if (trimmed.toLowerCase().startsWith(path.toLowerCase())) {
+			let rest = trimmed.slice(path.length).trimStart();
+			if (rest.length > 0 && ":.-".includes(rest[0])) rest = rest.slice(1);
+			message = rest.trimStart();
+		}
+		message = redactMessageWasValue(message, path, config?.debugSecrets);
+		const code = mapArkTypeCode(error.code);
+		const meta = { ...getArkTypeMeta(error) };
+		return D(path, message, code, meta, error.expected, error.code === "required" ? void 0 : error.data);
+	});
+}
+/**
+* Parse and validate environment variables using ArkEnv's schema rules.
+*
+* This applies:
+* - schema validation
+* - optional coercion (strings → numbers, booleans, arrays)
+* - undeclared key handling
+*
+* On success, returns the validated environment object.
+* On failure, throws an {@link ArkEnvError}.
+*
+* This is a low-level utility used internally by ArkEnv.
+* Most users should prefer the default `arkenv()` export.
+*
+* @param def The ArkType schema definition to validate against
+* @param config The configuration object for parsing and coercion
+* @returns The parsed and validated environment variables
+* @throws {@link ArkEnvError} if validation fails
+*
+* @internal
+*/
+function parse(def, config) {
+	const { env = process.env, coerce: shouldCoerce = true, onUndeclaredKey = "delete", arrayFormat = "comma", emptyAsUndefined = false } = config;
+	const schemaWithKeys = (typeof def === "function" && "assert" in def ? def : i$1.type.raw(def)).onUndeclaredKey(onUndeclaredKey);
+	const { coercedEnv } = c(env, emptyAsUndefined, arrayFormat, shouldCoerce ? () => {
+		return {
+			schema: schemaWithKeys.in.toJsonSchema({ fallback: (ctx) => ctx.base }),
+			hasSchema: true
+		};
+	} : void 0);
+	const validatedEnv = schemaWithKeys(coercedEnv);
+	if (validatedEnv instanceof arktype.ArkErrors) throw new h(arkErrorsToIssues(validatedEnv, config));
+	return validatedEnv;
+}
+
+//#endregion
+//#region src/arkenv.ts
+function arkenv(def, config = {}) {
+	if (config.safe) return E(() => parse(def, config));
+	return parse(def, config);
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* Like ArkType's `type`, but with ArkEnv's extra keywords, such as:
+*
+* - `string.host` – a hostname (e.g. `"localhost"`, `"127.0.0.1"`)
+* - `number.port` – a port number (e.g. `8080`)
+*
+* See ArkType's docs for the full API:
+* https://arktype.io/docs/type-api
+*/
+const type = i$1.type;
+/**
+* ArkEnv's main export, an alias for {@link arkenv}
+*
+* {@link https://arkenv.js.org | ArkEnv} is a typesafe environment variables validator from editor to runtime.
+*/
+var src_default = arkenv;
+
+//#endregion
+exports.ArkEnvError = h;
+exports.arkenv = arkenv;
+exports.default = src_default;
+exports.formatIssues = m;
+exports.getSchemaKeys = P;
+exports.type = type;
+
+// CJS Interop Shim
+if (module.exports && module.exports.default) {
+    Object.assign(module.exports.default, module.exports);
+    module.exports = module.exports.default;
+}
+