arkenv 0.7.0 → 0.7.2

package/README.md

@@ -1,24 +1,72 @@
 <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
+<p align="center">
+  <img alt="ArkEnv Demo" src="https://arkenv.js.org/assets/demo.gif" />
+</p>
 
-- 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))
+<br/>
+<br/>
+<br/>
+
+### [Read the docs →](https://arkenv.js.org/docs)
+
+<br/>
+<br/>
+
+## Introduction 
+
+> [!TIP]
+> 📖 **Reading this on GitHub?** Check out [this page in our docs](https://arkenv.js.org/docs) to hover over code blocks and get type hints!
+
+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'",
+});
+
+// Hover to see ✨exact✨ types
+const host = env.HOST;
+const port = env.PORT;
+const nodeEnv = env.NODE_ENV;
+```
+
+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
+- Validated, defaultable, typesafe environment variables
+- Powered by ArkType, TypeScript's 1:1 validator
+- Optimized from editor to runtime
 
 ## Installation
 
@@ -54,53 +102,24 @@ 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'",
-});
-
-
-// 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.
+: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).
 
 > [!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).
-> ![ArkType syntax highlighting in VS Code](https://raw.githubusercontent.com/yamcodes/arkenv/main/assets/dx.png)
+> Improve your DX with *syntax highlighting* in [VS Code & Cursor](https://arkenv.js.org/docs/integrations/vscode) or [JetBrains IDEs](https://arkenv.js.org/docs/integrations/jetbrains).
 
-## 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**: Zero dependencies, [tiny bundle 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

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ArkEnvError: () => ArkEnvError,
   createEnv: () => createEnv,
   default: () => index_default,
   type: () => type4
@@ -106,6 +107,7 @@ 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';
@@ -81,14 +81,18 @@ declare const $: arktype.Scope<{
 
 type RuntimeEnvironment = Record<string, string | undefined>;
 type EnvSchema<def> = type$1.validate<def, (typeof $)["t"]>;
+/**
+ * TODO: If possible, find a better type than "const T extends Record<string, unknown>",
+ * and be as close as possible to the type accepted by ArkType's `type`.
+ */
 /**
  * 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>, env?: RuntimeEnvironment): distill.Out<type$1.infer<T, (typeof $)["t"]>>;
+declare function createEnv<const T extends Record<string, unknown>>(def: EnvSchema<T>, env?: RuntimeEnvironment): distill.Out<type$1.infer<T, (typeof $)["t"]>>;
 
 declare const type: arktype_internal_type_ts.TypeParser<{
     string: arktype.Submodule<{
@@ -162,6 +166,15 @@ declare const type: arktype_internal_type_ts.TypeParser<{
     }>;
 }>;
 
+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 { type EnvSchema, createEnv, arkenv as default, type };
+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';
@@ -81,14 +81,18 @@ declare const $: arktype.Scope<{
 
 type RuntimeEnvironment = Record<string, string | undefined>;
 type EnvSchema<def> = type$1.validate<def, (typeof $)["t"]>;
+/**
+ * TODO: If possible, find a better type than "const T extends Record<string, unknown>",
+ * and be as close as possible to the type accepted by ArkType's `type`.
+ */
 /**
  * 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>, env?: RuntimeEnvironment): distill.Out<type$1.infer<T, (typeof $)["t"]>>;
+declare function createEnv<const T extends Record<string, unknown>>(def: EnvSchema<T>, env?: RuntimeEnvironment): distill.Out<type$1.infer<T, (typeof $)["t"]>>;
 
 declare const type: arktype_internal_type_ts.TypeParser<{
     string: arktype.Submodule<{
@@ -162,6 +166,15 @@ declare const type: arktype_internal_type_ts.TypeParser<{
     }>;
 }>;
 
+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 { type EnvSchema, createEnv, arkenv as default, type };
+export { ArkEnvError, type EnvSchema, createEnv, arkenv as default, type };

package/dist/index.js

@@ -77,6 +77,7 @@ var type4 = $.type;
 var arkenv = createEnv;
 var index_default = arkenv;
 export {
+  ArkEnvError,
   createEnv,
   index_default as default,
   type4 as type

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "arkenv",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -32,9 +32,9 @@
   "author": "Yam Borodetsky <yam@yam.codes>",
   "devDependencies": {
     "@ark/schema": "^0.49.0",
-    "@types/node": "24.3.1",
+    "@types/node": "24.6.2",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.3"
   },
   "peerDependencies": {
     "arktype": "^2.1.22"