arkenv 0.3.0 → 0.5.0

package/README.md

@@ -1,7 +1,106 @@
-# `arkenv`
-
-Hello, developers! Welcome to the `arkenv` package codebase. This directory contains the core implementation of ArkEnv, providing typesafe environment variable parsing and validation for Node.js.
-
-For more information, please refer to the [README](../../README.md) in the monorepo root.
-
-Happy coding!
+<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://www.npmjs.com/package/arkenv?activeTab=versions"><img alt="Total Downloads" src="https://img.shields.io/npm/dt/arkenv?logo=npm&color=blue&label=downloads"></a>
+  <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>
+</p>
+
+## Requirements
+
+- 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))
+
+## Installation
+
+<details open>
+<summary>npm</summary>
+
+```sh
+npm install arkenv arktype
+```
+</details>
+
+<details>
+<summary>pnpm</summary>
+
+```sh
+pnpm add arkenv arktype
+```
+</details>
+
+<details>
+<summary>Yarn</summary>
+
+```sh
+yarn add arkenv arktype
+```
+</details>
+
+<details>
+<summary>Bun</summary>
+
+```sh
+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.
+
+> [!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)
+
+## 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
+
+For detailed documentation and examples, please visit our [documentation site](https://arkenv.js.org/docs).
+
+## 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
+
+## Supporting ArkEnv
+
+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 🙏

package/dist/index.cjs

@@ -31,18 +31,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   createEnv: () => createEnv,
-  default: () => index_default,
-  host: () => host,
-  port: () => port
+  default: () => createEnv
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/define-env.ts
-var define_env_exports = {};
-__export(define_env_exports, {
-  createEnv: () => createEnv
-});
-var import_arktype = require("arktype");
+// src/create-env.ts
+var import_arktype3 = require("arktype");
 
 // src/errors.ts
 var import_chalk = __toESM(require("chalk"), 1);
@@ -75,31 +69,13 @@ ${indent(formatErrors(errors))}
   }
 };
 
-// src/define-env.ts
-var createEnv = (def, env = process.env) => {
-  const schema = (0, import_arktype.type)(def);
-  const requiredEnvKeys = Object.keys(
-    def
-  );
-  const filteredEnvVars = Object.fromEntries(
-    Object.entries(env).filter(([key]) => requiredEnvKeys.includes(key))
-  );
-  const validatedEnv = schema(filteredEnvVars);
-  if (validatedEnv instanceof import_arktype.type.errors) {
-    throw new ArkEnvError(validatedEnv);
-  }
-  return validatedEnv;
-};
+// src/scope.ts
+var import_arktype2 = require("arktype");
 
 // src/types.ts
-var types_exports = {};
-__export(types_exports, {
-  host: () => host,
-  port: () => port
-});
-var import_arktype2 = require("arktype");
-var port = (0, import_arktype2.type)("string", "=>", (data, ctx) => {
-  const asNumber = Number.parseInt(data);
+var import_arktype = require("arktype");
+var port = (0, import_arktype.type)("string", "=>", (data, ctx) => {
+  const asNumber = Number.parseInt(data, 10);
   const isInteger = Number.isInteger(asNumber);
   const isBetween = 0 <= asNumber && asNumber <= 65535;
   if (!isInteger || !isBetween) {
@@ -107,13 +83,30 @@ var port = (0, import_arktype2.type)("string", "=>", (data, ctx) => {
   }
   return asNumber;
 });
-var host = (0, import_arktype2.type)("string.ip | 'localhost'");
+var host = (0, import_arktype.type)("string.ip | 'localhost'");
 
-// src/index.ts
-var index_default = { ...define_env_exports, ...types_exports };
+// src/scope.ts
+var $ = (0, import_arktype2.scope)({
+  string: import_arktype2.type.module({
+    ...import_arktype2.type.keywords.string,
+    host
+  }),
+  number: import_arktype2.type.module({
+    ...import_arktype2.type.keywords.number,
+    port
+  })
+});
+
+// src/create-env.ts
+function createEnv(def, env = process.env) {
+  const schema = $.type.raw(def);
+  const validatedEnv = schema(env);
+  if (validatedEnv instanceof import_arktype3.type.errors) {
+    throw new ArkEnvError(validatedEnv);
+  }
+  return validatedEnv;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createEnv,
-  host,
-  port
+  createEnv
 });

package/dist/index.d.cts

@@ -1,34 +1,93 @@
 import * as arktype from 'arktype';
 import { type, distill } from 'arktype';
-import * as arktype_internal_methods_string_ts from 'arktype/internal/methods/string.ts';
-import * as arktype_internal_methods_morph_ts from 'arktype/internal/methods/morph.ts';
 import * as arktype_internal_attributes_ts from 'arktype/internal/attributes.ts';
+import * as arktype_internal_keywords_string_ts from 'arktype/internal/keywords/string.ts';
 
-type UserEnvironment = Record<string, string | undefined>;
-type EnvSchema<T extends Record<string, string | undefined> = Record<string, string | undefined>> = type.validate<T>;
 /**
- * Define an environment variable schema and validate it against a given environment (defaults to `process.env`)
- * @param def - The environment variable schema
- * @param env - The environment variables to validate, defaults to `process.env`
- * @returns The validated environment variable schema
+ * The root scope for the ArkEnv library, containing extensions to the ArkType scopes with ArkEnv-specific types like `string.host` and `number.port`.
  */
-declare const createEnv: <const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: UserEnvironment) => distill.Out<type.infer<T>>;
+declare const $: arktype.Scope<{
+    string: arktype.Submodule<{
+        root: string;
+        " arkInferred": string;
+        trim: arktype.Submodule<arktype_internal_keywords_string_ts.trim.$ & {
+            " arkInferred": (In: string) => arktype_internal_attributes_ts.To<string>;
+        }>;
+        normalize: arktype.Submodule<arktype_internal_keywords_string_ts.normalize.$ & {
+            " arkInferred": (In: string) => arktype_internal_attributes_ts.To<string>;
+        }>;
+        alpha: string;
+        alphanumeric: string;
+        hex: string;
+        base64: arktype.Submodule<{
+            root: string;
+            url: string;
+        } & {
+            " arkInferred": string;
+        }>;
+        capitalize: arktype.Submodule<arktype_internal_keywords_string_ts.capitalize.$ & {
+            " arkInferred": (In: string) => arktype_internal_attributes_ts.To<string>;
+        }>;
+        creditCard: string;
+        date: arktype.Submodule<arktype_internal_keywords_string_ts.stringDate.$ & {
+            " arkInferred": string;
+        }>;
+        digits: string;
+        email: string;
+        integer: arktype.Submodule<arktype_internal_keywords_string_ts.stringInteger.$ & {
+            " arkInferred": string;
+        }>;
+        ip: arktype.Submodule<arktype_internal_keywords_string_ts.ip.$ & {
+            " arkInferred": string;
+        }>;
+        json: arktype.Submodule<arktype_internal_keywords_string_ts.stringJson.$ & {
+            " arkInferred": string;
+        }>;
+        lower: arktype.Submodule<arktype_internal_keywords_string_ts.lower.$ & {
+            " arkInferred": (In: string) => arktype_internal_attributes_ts.To<string>;
+        }>;
+        numeric: arktype.Submodule<arktype_internal_keywords_string_ts.stringNumeric.$ & {
+            " arkInferred": string;
+        }>;
+        regex: string;
+        semver: string;
+        upper: arktype.Submodule<{
+            root: (In: string) => arktype_internal_attributes_ts.To<string>;
+            preformatted: string;
+        } & {
+            " arkInferred": (In: string) => arktype_internal_attributes_ts.To<string>;
+        }>;
+        url: arktype.Submodule<arktype_internal_keywords_string_ts.url.$ & {
+            " arkInferred": string;
+        }>;
+        uuid: arktype.Submodule<arktype_internal_keywords_string_ts.uuid.$ & {
+            " arkInferred": string;
+        }>;
+        host: string;
+    }>;
+    number: arktype.Submodule<{
+        NaN: number;
+        Infinity: number;
+        root: number;
+        " arkInferred": number;
+        integer: number;
+        epoch: number;
+        safe: number;
+        NegativeInfinity: number;
+        port: (In: string) => arktype.Out<number>;
+    }>;
+}>;
 
+type RuntimeEnvironment = Record<string, string | undefined>;
+type EnvSchema<def, $ = {}> = type.validate<def, $>;
 /**
- * A `string` that can be parsed into a number between 0 and 65535
- */
-declare const port: arktype_internal_methods_morph_ts.MorphType<(In: string) => arktype_internal_attributes_ts.Out<number>, {}>;
-/**
- * An IP address or `"localhost"`
+ * 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}
  */
-declare const host: arktype_internal_methods_string_ts.StringType<string, {}>;
-
-declare const _default: {
-    port: arktype_internal_methods_morph_ts.MorphType<(In: string) => arktype_internal_attributes_ts.Out<number>, {}>;
-    host: arktype_internal_methods_string_ts.StringType<string, {}>;
-    createEnv: <const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: {
-        [x: string]: string | undefined;
-    }) => arktype.distill.Out<arktype.type.infer<T>>;
-};
+declare function createEnv<const T extends Record<string, string | undefined>>(def: EnvSchema<T, (typeof $)["t"]>, env?: RuntimeEnvironment): distill.Out<type.infer<T, (typeof $)["t"]>>;
+declare function createEnv<const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: RuntimeEnvironment): distill.Out<type.infer<T>>;
 
-export { type EnvSchema, createEnv, _default as default, host, port };
+export { type EnvSchema, createEnv, createEnv as default };

package/dist/index.d.ts

@@ -1,34 +1,93 @@
 import * as arktype from 'arktype';
 import { type, distill } from 'arktype';
-import * as arktype_internal_methods_string_ts from 'arktype/internal/methods/string.ts';
-import * as arktype_internal_methods_morph_ts from 'arktype/internal/methods/morph.ts';
 import * as arktype_internal_attributes_ts from 'arktype/internal/attributes.ts';
+import * as arktype_internal_keywords_string_ts from 'arktype/internal/keywords/string.ts';
 
-type UserEnvironment = Record<string, string | undefined>;
-type EnvSchema<T extends Record<string, string | undefined> = Record<string, string | undefined>> = type.validate<T>;
 /**
- * Define an environment variable schema and validate it against a given environment (defaults to `process.env`)
- * @param def - The environment variable schema
- * @param env - The environment variables to validate, defaults to `process.env`
- * @returns The validated environment variable schema
+ * The root scope for the ArkEnv library, containing extensions to the ArkType scopes with ArkEnv-specific types like `string.host` and `number.port`.
  */
-declare const createEnv: <const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: UserEnvironment) => distill.Out<type.infer<T>>;
+declare const $: arktype.Scope<{
+    string: arktype.Submodule<{
+        root: string;
+        " arkInferred": string;
+        trim: arktype.Submodule<arktype_internal_keywords_string_ts.trim.$ & {
+            " arkInferred": (In: string) => arktype_internal_attributes_ts.To<string>;
+        }>;
+        normalize: arktype.Submodule<arktype_internal_keywords_string_ts.normalize.$ & {
+            " arkInferred": (In: string) => arktype_internal_attributes_ts.To<string>;
+        }>;
+        alpha: string;
+        alphanumeric: string;
+        hex: string;
+        base64: arktype.Submodule<{
+            root: string;
+            url: string;
+        } & {
+            " arkInferred": string;
+        }>;
+        capitalize: arktype.Submodule<arktype_internal_keywords_string_ts.capitalize.$ & {
+            " arkInferred": (In: string) => arktype_internal_attributes_ts.To<string>;
+        }>;
+        creditCard: string;
+        date: arktype.Submodule<arktype_internal_keywords_string_ts.stringDate.$ & {
+            " arkInferred": string;
+        }>;
+        digits: string;
+        email: string;
+        integer: arktype.Submodule<arktype_internal_keywords_string_ts.stringInteger.$ & {
+            " arkInferred": string;
+        }>;
+        ip: arktype.Submodule<arktype_internal_keywords_string_ts.ip.$ & {
+            " arkInferred": string;
+        }>;
+        json: arktype.Submodule<arktype_internal_keywords_string_ts.stringJson.$ & {
+            " arkInferred": string;
+        }>;
+        lower: arktype.Submodule<arktype_internal_keywords_string_ts.lower.$ & {
+            " arkInferred": (In: string) => arktype_internal_attributes_ts.To<string>;
+        }>;
+        numeric: arktype.Submodule<arktype_internal_keywords_string_ts.stringNumeric.$ & {
+            " arkInferred": string;
+        }>;
+        regex: string;
+        semver: string;
+        upper: arktype.Submodule<{
+            root: (In: string) => arktype_internal_attributes_ts.To<string>;
+            preformatted: string;
+        } & {
+            " arkInferred": (In: string) => arktype_internal_attributes_ts.To<string>;
+        }>;
+        url: arktype.Submodule<arktype_internal_keywords_string_ts.url.$ & {
+            " arkInferred": string;
+        }>;
+        uuid: arktype.Submodule<arktype_internal_keywords_string_ts.uuid.$ & {
+            " arkInferred": string;
+        }>;
+        host: string;
+    }>;
+    number: arktype.Submodule<{
+        NaN: number;
+        Infinity: number;
+        root: number;
+        " arkInferred": number;
+        integer: number;
+        epoch: number;
+        safe: number;
+        NegativeInfinity: number;
+        port: (In: string) => arktype.Out<number>;
+    }>;
+}>;
 
+type RuntimeEnvironment = Record<string, string | undefined>;
+type EnvSchema<def, $ = {}> = type.validate<def, $>;
 /**
- * A `string` that can be parsed into a number between 0 and 65535
- */
-declare const port: arktype_internal_methods_morph_ts.MorphType<(In: string) => arktype_internal_attributes_ts.Out<number>, {}>;
-/**
- * An IP address or `"localhost"`
+ * 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}
  */
-declare const host: arktype_internal_methods_string_ts.StringType<string, {}>;
-
-declare const _default: {
-    port: arktype_internal_methods_morph_ts.MorphType<(In: string) => arktype_internal_attributes_ts.Out<number>, {}>;
-    host: arktype_internal_methods_string_ts.StringType<string, {}>;
-    createEnv: <const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: {
-        [x: string]: string | undefined;
-    }) => arktype.distill.Out<arktype.type.infer<T>>;
-};
+declare function createEnv<const T extends Record<string, string | undefined>>(def: EnvSchema<T, (typeof $)["t"]>, env?: RuntimeEnvironment): distill.Out<type.infer<T, (typeof $)["t"]>>;
+declare function createEnv<const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: RuntimeEnvironment): distill.Out<type.infer<T>>;
 
-export { type EnvSchema, createEnv, _default as default, host, port };
+export { type EnvSchema, createEnv, createEnv as default };

package/dist/index.js

@@ -1,15 +1,5 @@
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-// src/define-env.ts
-var define_env_exports = {};
-__export(define_env_exports, {
-  createEnv: () => createEnv
-});
-import { type } from "arktype";
+// src/create-env.ts
+import { type as type3 } from "arktype";
 
 // src/errors.ts
 import chalk from "chalk";
@@ -42,31 +32,13 @@ ${indent(formatErrors(errors))}
   }
 };
 
-// src/define-env.ts
-var createEnv = (def, env = process.env) => {
-  const schema = type(def);
-  const requiredEnvKeys = Object.keys(
-    def
-  );
-  const filteredEnvVars = Object.fromEntries(
-    Object.entries(env).filter(([key]) => requiredEnvKeys.includes(key))
-  );
-  const validatedEnv = schema(filteredEnvVars);
-  if (validatedEnv instanceof type.errors) {
-    throw new ArkEnvError(validatedEnv);
-  }
-  return validatedEnv;
-};
+// src/scope.ts
+import { scope, type as type2 } from "arktype";
 
 // src/types.ts
-var types_exports = {};
-__export(types_exports, {
-  host: () => host,
-  port: () => port
-});
-import { type as type2 } from "arktype";
-var port = type2("string", "=>", (data, ctx) => {
-  const asNumber = Number.parseInt(data);
+import { type } from "arktype";
+var port = type("string", "=>", (data, ctx) => {
+  const asNumber = Number.parseInt(data, 10);
   const isInteger = Number.isInteger(asNumber);
   const isBetween = 0 <= asNumber && asNumber <= 65535;
   if (!isInteger || !isBetween) {
@@ -74,13 +46,30 @@ var port = type2("string", "=>", (data, ctx) => {
   }
   return asNumber;
 });
-var host = type2("string.ip | 'localhost'");
+var host = type("string.ip | 'localhost'");
+
+// src/scope.ts
+var $ = scope({
+  string: type2.module({
+    ...type2.keywords.string,
+    host
+  }),
+  number: type2.module({
+    ...type2.keywords.number,
+    port
+  })
+});
 
-// src/index.ts
-var index_default = { ...define_env_exports, ...types_exports };
+// src/create-env.ts
+function createEnv(def, env = process.env) {
+  const schema = $.type.raw(def);
+  const validatedEnv = schema(env);
+  if (validatedEnv instanceof type3.errors) {
+    throw new ArkEnvError(validatedEnv);
+  }
+  return validatedEnv;
+}
 export {
   createEnv,
-  index_default as default,
-  host,
-  port
+  createEnv as default
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "arkenv",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,22 +31,23 @@
   "bugs": "https://github.com/yamcodes/arkenv/labels/arkenv",
   "author": "Yam Borodetsky <yam@yam.codes>",
   "devDependencies": {
-    "@ark/schema": "^0.46.0",
-    "@types/node": "22.14.0",
+    "@ark/schema": "^0.49.0",
+    "@types/node": "24.3.1",
     "tsup": "^8.5.0",
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "arktype": "^2.0.2"
+    "arktype": "^2.1.22"
   },
   "dependencies": {
-    "chalk": "^5.6.0"
+    "chalk": "^5.6.2"
   },
   "scripts": {
     "build": "rimraf dist && tsup",
     "test:once": "pnpm test",
     "typecheck": "tsc --noEmit",
     "clean": "rimraf dist node_modules",
-    "test": "pnpm -w test --project arkenv"
+    "test": "pnpm -w test --project arkenv",
+    "fix": "pnpm -w run fix"
   }
 }