arkenv 0.6.0 → 0.7.1

package/README.md

@@ -1,24 +1,67 @@
 <p align="center">
-  <sup><b>We are now featured on <a href="https://arktype.io/docs/ecosystem#arkenv">arktype.io</a>!</b></sup>
-  <br />
   <a href="https://arkenv.js.org">
     <img alt="arkenv - Typesafe Environment Variables" src="https://og.tailgraph.com/og?titleFontFamily=JetBrains+Mono&textFontFamily=Inter&title=ArkEnv&titleTailwind=text-[%23e9eef9]%20font-bold%20relative%20decoration-%5Brgb(180,215,255)%5D%20decoration-wavy%20decoration-[5px]%20underline%20underline-offset-[16px]%20text-5xl%20mb-8&text=Typesafe%20environment%20variables%20powered%20by%20ArkType&textTailwind=text-[%238b9dc1]%20text-3xl&bgTailwind=bg-gradient-to-b%20from-[%23061a3a]%20to-black" width="645px">
   </a>
   <br />
   <a href="https://github.com/yamcodes/arkenv/actions/workflows/tests.yml?query=branch%3Amain"><img alt="Tests Status" src="https://github.com/yamcodes/arkenv/actions/workflows/tests.yml/badge.svg?event=push&branch=main"></a>
-  <a href="https://discord.com/channels/957797212103016458/1415373591394127894"><img alt="Chat on Discord" src="https://img.shields.io/discord/957797212103016458?label=Chat&color=5865f4&logo=discord&labelColor=121214"></a>
+  <img alt="npm bundle size" src="https://img.shields.io/bundlephobia/minzip/arkenv">
   <a href="https://www.typescriptlang.org/"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white"></a>
   <a href="https://arktype.io/"><img alt="Powered By ArkType" src="https://custom-icon-badges.demolab.com/badge/ArkType-0d1526?logo=arktype2&logoColor=e9eef9"></a>
   <a href="https://nodejs.org/en"><img alt="Node.js" src="https://img.shields.io/badge/Node.js-339933?style=flat&logo=node.js&logoColor=white"></a>
   <a href="https://bun.com/"><img alt="Bun" src="https://img.shields.io/badge/Bun-14151a?logo=bun&logoColor=fbf0df"></a>
   <a href="https://vite.dev/"><img alt="Vite" src="https://custom-icon-badges.demolab.com/badge/Vite-2e2742?logo=vite2&logoColor=dfdfd6"></a>
-  <a href="https://github.com/yamcodes/arkenv"><img alt="GitHub Repo stars" src="https://custom-icon-badges.demolab.com/github/stars/yamcodes/arkenv?logo=star&logoColor=373737&label=Star%20us!"></a>
+  <a href="https://discord.com/channels/957797212103016458/1415373591394127894"><img alt="Chat on Discord" src="https://img.shields.io/discord/957797212103016458?label=Chat&color=5865f4&logo=discord&labelColor=121214"></a>
 </p>
+<h3 align="center">Proud member of the <a href="https://arktype.io/docs/ecosystem#arkenv">ArkType ecosystem</a></h3>
 
-## Requirements
+<br/>
+<br/>
+<br/>
 
-- TypeScript >= 5.1 and [anything else required by ArkType](https://arktype.io/docs/intro/setup#installation)
-- We support Node.js ([example](examples/basic/README.md)), Bun ([example](examples/with-bun/README.md)), and Vite ([example](examples/with-vite-react-ts/README.md))
+### [Read the docs →](https://arkenv.js.org/docs)
+
+<br/>
+<br/>
+
+## Introduction
+
+
+ArkEnv is an environment variable parser powered by [ArkType](https://arktype.io/), TypeScript's 1:1 validator. ArkEnv lets you use familiar TypeScript-like syntax to create a ready to use, typesafe environment variable object:
+
+
+```ts twoslash
+import arkenv from 'arkenv';
+
+const env = arkenv({
+  HOST: "string.host", // valid IP address or localhost
+  PORT: "number.port", // valid port number (0-65535)
+  NODE_ENV: "'development' | 'production' | 'test'",
+});
+
+
+// Automatically validate and parse process.env
+// TypeScript knows the ✨exact✨ types!
+console.log(env.HOST);     // (property) HOST: string
+console.log(env.PORT);     // (property) PORT: number
+console.log(env.NODE_ENV); // (property) NODE_ENV: "development" | "production" | "test"
+```
+
+With ArkEnv, your environment variables are **guaranteed to match your schema**. If any variable is incorrect or missing, the app won't start and a clear error will be thrown:
+
+```
+ArkEnvError: Errors found while validating environment variables
+  HOST must be a string or "localhost" (was missing)
+  PORT must be an integer between 0 and 65535 (was "hello")
+```
+
+## Features
+
+- Zero external dependencies
+- Works in Node.js, Bun, and Vite
+- Tiny: <1kB gzipped
+- Build-time and runtime validation
+- Single import, zero config for most projects
+- Powered by ArkType, TypeScript's 1:1 validator
 
 ## Installation
 
@@ -54,53 +97,27 @@ bun add arkenv arktype
 ```
 </details>
 
-## Quickstart
-
-```ts
-import arkenv from 'arkenv';
-
-const env = arkenv({
-  HOST: "string.host", // valid IP address or localhost
-  PORT: "number.port", // valid port number (0-65535)
-  NODE_ENV: "'development' | 'production' | 'test'",
-});
+:rocket: **Let's get started!** Read the [2-minute setup guide](https://arkenv.js.org/docs/quickstart) or [start with an example](https://arkenv.js.org/docs/examples).
 
 
-// Automatically validate and parse process.env
-// TypeScript knows the ✨exact✨ types!
-console.log(env.HOST);     // (property) HOST: string
-console.log(env.PORT);     // (property) PORT: number
-console.log(env.NODE_ENV); // (property) NODE_ENV: "development" | "production" | "test"
-```
-
-You can find more examples in the [examples](https://github.com/yamcodes/arkenv/tree/main/examples) directory.
-
 > [!TIP]
-> **VS Code Users:** Get syntax highlighting and inline error summaries for the ArkType ecosystem with the [ArkType VS Code extension](https://marketplace.visualstudio.com/items?itemName=arktypeio.arkdark). For even better TypeScript highlighting, try [ArkThemes](https://marketplace.cursorapi.com/items/?itemName=arktypeio.arkthemes).
+> Improve your DX with syntax highlighting in [VS Code & Cursor](/docs/integrations/vscode) or [JetBrains IDEs](/docs/integrations/jetbrains).
+> 
 > ![ArkType syntax highlighting in VS Code](https://raw.githubusercontent.com/yamcodes/arkenv/main/assets/dx.png)
 
-## Features
-
-- 🔒 **Typesafe**: Full TypeScript support with inferred types
-- 🚀 **Runtime validation**: Catch missing or invalid environment variables early
-- 💪 **Powered by ArkType**: Leverage ArkType's powerful type system
-- 🪶 **Lightweight**: Only a single dependency ([see size](https://bundlephobia.com/package/arkenv))
-- ⚡ **Fast**: Optimized for performance with minimal overhead
-
-## Documentation
+## Requirements
 
-For detailed documentation and examples, please visit our [documentation site](https://arkenv.js.org/docs).
+- TypeScript >= 5.1 and [anything else required by ArkType](https://arktype.io/docs/intro/setup#installation)
+-  [Node.js 22 LTS](https://github.com/yamcodes/arkenv/tree/main/examples/basic), [Bun 1.2](https://github.com/yamcodes/arkenv/tree/main/examples/with-bun), and [Vite 7](https://github.com/yamcodes/arkenv/tree/main/examples/with-vite-react-ts) are tested. Older versions may work but aren't officially supported
 
 ## Plugins
 
-- [@arkenv/vite-plugin](https://github.com/yamcodes/arkenv/tree/main/packages/vite-plugin): [Vite](https://vite.dev/) plugin to validate environment variables at build time
+- [@arkenv/vite-plugin](https://github.com/yamcodes/arkenv/tree/main/packages/vite-plugin)
 
 ## Supporting ArkEnv
 
-If you love ArkEnv, you can support the project by starring it on GitHub!
+If you love ArkEnv, you can support the project by **starring it on GitHub**!
 
 You are also welcome to directly [contribute to the project's development](https://github.com/yamcodes/arkenv/blob/main/CONTRIBUTING.md).
 
-## Thanks / Inspiration
-
-Find projects and people who helped or inspired the creation of ArkEnv in [THANKS.md](https://github.com/yamcodes/arkenv/blob/main/THANKS.md). Thank you 🙏
+## [Thanks / Inspiration](https://github.com/yamcodes/arkenv/blob/main/THANKS.md)

package/dist/index.cjs

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,21 +15,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ArkEnvError: () => ArkEnvError,
   createEnv: () => createEnv,
-  default: () => createEnv,
+  default: () => index_default,
   type: () => type4
 });
 module.exports = __toCommonJS(index_exports);
@@ -40,7 +31,7 @@ module.exports = __toCommonJS(index_exports);
 var import_arktype3 = require("arktype");
 
 // src/errors.ts
-var import_chalk = __toESM(require("chalk"), 1);
+var import_node_util = require("util");
 
 // src/utils.ts
 var indent = (str, amt = 2, { dontDetectNewlines = false } = {}) => {
@@ -57,13 +48,13 @@ var formatErrors = (errors) => Object.entries(errors.byPath).map(([path, error])
   const valueMatch = messageWithoutPath.match(/\(was "([^"]+)"\)/);
   const formattedMessage = valueMatch ? messageWithoutPath.replace(
     `(was "${valueMatch[1]}")`,
-    `(was ${import_chalk.default.cyan(`"${valueMatch[1]}"`)})`
+    `(was ${(0, import_node_util.styleText)("cyan", `"${valueMatch[1]}"`)})`
   ) : messageWithoutPath;
-  return `${import_chalk.default.yellow(path)}${formattedMessage}`;
+  return `${(0, import_node_util.styleText)("yellow", path)}${formattedMessage}`;
 }).join("\n");
 var ArkEnvError = class extends Error {
   constructor(errors, message = "Errors found while validating environment variables") {
-    super(`${import_chalk.default.red(message)}
+    super(`${(0, import_node_util.styleText)("red", message)}
 ${indent(formatErrors(errors))}
 `);
     this.name = "ArkEnvError";
@@ -110,8 +101,13 @@ function createEnv(def, env = process.env) {
 
 // src/type.ts
 var type4 = $.type;
+
+// src/index.ts
+var arkenv = createEnv;
+var index_default = arkenv;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ArkEnvError,
   createEnv,
   type
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as arktype from 'arktype';
-import { type as type$1, distill } from 'arktype';
+import { type as type$1, distill, ArkErrors } from 'arktype';
 import * as arktype_internal_attributes_ts from 'arktype/internal/attributes.ts';
 import * as arktype_internal_keywords_string_ts from 'arktype/internal/keywords/string.ts';
 import * as arktype_internal_type_ts from 'arktype/internal/type.ts';
@@ -80,16 +80,15 @@ declare const $: arktype.Scope<{
 }>;
 
 type RuntimeEnvironment = Record<string, string | undefined>;
-type EnvSchema<def, $ = {}> = type$1.validate<def, $>;
+type EnvSchema<def> = type$1.validate<def, (typeof $)["t"]>;
 /**
  * Create an environment variables object from a schema and an environment
  * @param def - The environment variable schema
  * @param env - The environment variables to validate, defaults to `process.env`
  * @returns The validated environment variable schema
- * @throws An error if the environment variables are invalid. See {@link ArkEnvError}
+ * @throws An {@link ArkEnvError | error} if the environment variables are invalid.
  */
-declare function createEnv<const T extends Record<string, string | undefined>>(def: EnvSchema<T, (typeof $)["t"]>, env?: RuntimeEnvironment): distill.Out<type$1.infer<T, (typeof $)["t"]>>;
-declare function createEnv<const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: RuntimeEnvironment): distill.Out<type$1.infer<T>>;
+declare function createEnv<const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: RuntimeEnvironment): distill.Out<type$1.infer<T, (typeof $)["t"]>>;
 
 declare const type: arktype_internal_type_ts.TypeParser<{
     string: arktype.Submodule<{
@@ -163,4 +162,15 @@ declare const type: arktype_internal_type_ts.TypeParser<{
     }>;
 }>;
 
-export { type EnvSchema, createEnv, createEnv as default, type };
+declare class ArkEnvError extends Error {
+    constructor(errors: ArkErrors, message?: string);
+}
+
+/**
+ * `arkenv`'s main export, an alias for {@link createEnv}
+ *
+ * {@link https://arkenv.js.org | ArkEnv} is a typesafe environment variables parser powered by {@link https://arktype.io | ArkType}, TypeScript's 1:1 validator.
+ */
+declare const arkenv: typeof createEnv;
+
+export { ArkEnvError, type EnvSchema, createEnv, arkenv as default, type };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as arktype from 'arktype';
-import { type as type$1, distill } from 'arktype';
+import { type as type$1, distill, ArkErrors } from 'arktype';
 import * as arktype_internal_attributes_ts from 'arktype/internal/attributes.ts';
 import * as arktype_internal_keywords_string_ts from 'arktype/internal/keywords/string.ts';
 import * as arktype_internal_type_ts from 'arktype/internal/type.ts';
@@ -80,16 +80,15 @@ declare const $: arktype.Scope<{
 }>;
 
 type RuntimeEnvironment = Record<string, string | undefined>;
-type EnvSchema<def, $ = {}> = type$1.validate<def, $>;
+type EnvSchema<def> = type$1.validate<def, (typeof $)["t"]>;
 /**
  * Create an environment variables object from a schema and an environment
  * @param def - The environment variable schema
  * @param env - The environment variables to validate, defaults to `process.env`
  * @returns The validated environment variable schema
- * @throws An error if the environment variables are invalid. See {@link ArkEnvError}
+ * @throws An {@link ArkEnvError | error} if the environment variables are invalid.
  */
-declare function createEnv<const T extends Record<string, string | undefined>>(def: EnvSchema<T, (typeof $)["t"]>, env?: RuntimeEnvironment): distill.Out<type$1.infer<T, (typeof $)["t"]>>;
-declare function createEnv<const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: RuntimeEnvironment): distill.Out<type$1.infer<T>>;
+declare function createEnv<const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: RuntimeEnvironment): distill.Out<type$1.infer<T, (typeof $)["t"]>>;
 
 declare const type: arktype_internal_type_ts.TypeParser<{
     string: arktype.Submodule<{
@@ -163,4 +162,15 @@ declare const type: arktype_internal_type_ts.TypeParser<{
     }>;
 }>;
 
-export { type EnvSchema, createEnv, createEnv as default, type };
+declare class ArkEnvError extends Error {
+    constructor(errors: ArkErrors, message?: string);
+}
+
+/**
+ * `arkenv`'s main export, an alias for {@link createEnv}
+ *
+ * {@link https://arkenv.js.org | ArkEnv} is a typesafe environment variables parser powered by {@link https://arktype.io | ArkType}, TypeScript's 1:1 validator.
+ */
+declare const arkenv: typeof createEnv;
+
+export { ArkEnvError, type EnvSchema, createEnv, arkenv as default, type };

package/dist/index.js

@@ -2,7 +2,7 @@
 import { type as type3 } from "arktype";
 
 // src/errors.ts
-import chalk from "chalk";
+import { styleText } from "util";
 
 // src/utils.ts
 var indent = (str, amt = 2, { dontDetectNewlines = false } = {}) => {
@@ -19,13 +19,13 @@ var formatErrors = (errors) => Object.entries(errors.byPath).map(([path, error])
   const valueMatch = messageWithoutPath.match(/\(was "([^"]+)"\)/);
   const formattedMessage = valueMatch ? messageWithoutPath.replace(
     `(was "${valueMatch[1]}")`,
-    `(was ${chalk.cyan(`"${valueMatch[1]}"`)})`
+    `(was ${styleText("cyan", `"${valueMatch[1]}"`)})`
   ) : messageWithoutPath;
-  return `${chalk.yellow(path)}${formattedMessage}`;
+  return `${styleText("yellow", path)}${formattedMessage}`;
 }).join("\n");
 var ArkEnvError = class extends Error {
   constructor(errors, message = "Errors found while validating environment variables") {
-    super(`${chalk.red(message)}
+    super(`${styleText("red", message)}
 ${indent(formatErrors(errors))}
 `);
     this.name = "ArkEnvError";
@@ -72,8 +72,13 @@ function createEnv(def, env = process.env) {
 
 // src/type.ts
 var type4 = $.type;
+
+// src/index.ts
+var arkenv = createEnv;
+var index_default = arkenv;
 export {
+  ArkEnvError,
   createEnv,
-  createEnv as default,
+  index_default as default,
   type4 as type
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "arkenv",
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -39,9 +39,6 @@
   "peerDependencies": {
     "arktype": "^2.1.22"
   },
-  "dependencies": {
-    "chalk": "^5.6.2"
-  },
   "scripts": {
     "build": "rimraf dist && tsup",
     "test:once": "pnpm test",