arkenv 0.2.0

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,7 @@
+# ArkEnv
+
+Hello, developers! Welcome to the ArkEnv package codebase. This directory contains the core implementation of the ArkEnv library, which provides typesafe environment variable parsing and validation for Node.js.
+
+For more information, please refer to the main [README](../../README.md) in the monorepo root.
+
+Happy coding!

package/dist/index.cjs

@@ -0,0 +1,119 @@
+"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)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  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, {
+  default: () => index_default,
+  defineEnv: () => defineEnv,
+  host: () => host,
+  port: () => port
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/define-env.ts
+var define_env_exports = {};
+__export(define_env_exports, {
+  defineEnv: () => defineEnv
+});
+var import_arktype = require("arktype");
+
+// src/errors.ts
+var import_chalk = __toESM(require("chalk"), 1);
+
+// src/utils.ts
+var indent = (str, amt = 2, { dontDetectNewlines = false } = {}) => {
+  const detectNewlines = !dontDetectNewlines;
+  if (detectNewlines) {
+    return str.split("\n").map((line) => `${" ".repeat(amt)}${line}`).join("\n");
+  }
+  return `${" ".repeat(amt)}${str}`;
+};
+
+// src/errors.ts
+var formatErrors = (errors) => Object.entries(errors.byPath).map(([path, error]) => {
+  const messageWithoutPath = error.message.startsWith(path) ? error.message.slice(path.length) : error.message;
+  const valueMatch = messageWithoutPath.match(/\(was "([^"]+)"\)/);
+  const formattedMessage = valueMatch ? messageWithoutPath.replace(
+    `(was "${valueMatch[1]}")`,
+    `(was ${import_chalk.default.cyan(`"${valueMatch[1]}"`)})`
+  ) : messageWithoutPath;
+  return `${import_chalk.default.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)}
+${indent(formatErrors(errors))}
+`);
+    this.name = "ArkEnvError";
+  }
+};
+
+// src/define-env.ts
+var defineEnv = (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/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);
+  const isInteger = Number.isInteger(asNumber);
+  const isBetween = 0 <= asNumber && asNumber <= 65535;
+  if (!isInteger || !isBetween) {
+    ctx.mustBe("an integer between 0 and 65535");
+  }
+  return asNumber;
+});
+var host = (0, import_arktype2.type)("string.ip | 'localhost'");
+
+// src/index.ts
+var index_default = { ...define_env_exports, ...types_exports };
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineEnv,
+  host,
+  port
+});

package/dist/index.d.cts

@@ -0,0 +1,34 @@
+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';
+
+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
+ */
+declare const defineEnv: <const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: UserEnvironment) => distill.Out<type.infer<T>>;
+
+/**
+ * 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"`
+ */
+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, {}>;
+    defineEnv: <const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: {
+        [x: string]: string | undefined;
+    }) => arktype.distill.Out<arktype.type.infer<T>>;
+};
+
+export { type EnvSchema, _default as default, defineEnv, host, port };

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+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';
+
+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
+ */
+declare const defineEnv: <const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: UserEnvironment) => distill.Out<type.infer<T>>;
+
+/**
+ * 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"`
+ */
+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, {}>;
+    defineEnv: <const T extends Record<string, string | undefined>>(def: EnvSchema<T>, env?: {
+        [x: string]: string | undefined;
+    }) => arktype.distill.Out<arktype.type.infer<T>>;
+};
+
+export { type EnvSchema, _default as default, defineEnv, host, port };

package/dist/index.js

@@ -0,0 +1,86 @@
+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, {
+  defineEnv: () => defineEnv
+});
+import { type } from "arktype";
+
+// src/errors.ts
+import chalk from "chalk";
+
+// src/utils.ts
+var indent = (str, amt = 2, { dontDetectNewlines = false } = {}) => {
+  const detectNewlines = !dontDetectNewlines;
+  if (detectNewlines) {
+    return str.split("\n").map((line) => `${" ".repeat(amt)}${line}`).join("\n");
+  }
+  return `${" ".repeat(amt)}${str}`;
+};
+
+// src/errors.ts
+var formatErrors = (errors) => Object.entries(errors.byPath).map(([path, error]) => {
+  const messageWithoutPath = error.message.startsWith(path) ? error.message.slice(path.length) : error.message;
+  const valueMatch = messageWithoutPath.match(/\(was "([^"]+)"\)/);
+  const formattedMessage = valueMatch ? messageWithoutPath.replace(
+    `(was "${valueMatch[1]}")`,
+    `(was ${chalk.cyan(`"${valueMatch[1]}"`)})`
+  ) : messageWithoutPath;
+  return `${chalk.yellow(path)}${formattedMessage}`;
+}).join("\n");
+var ArkEnvError = class extends Error {
+  constructor(errors, message = "Errors found while validating environment variables") {
+    super(`${chalk.red(message)}
+${indent(formatErrors(errors))}
+`);
+    this.name = "ArkEnvError";
+  }
+};
+
+// src/define-env.ts
+var defineEnv = (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/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);
+  const isInteger = Number.isInteger(asNumber);
+  const isBetween = 0 <= asNumber && asNumber <= 65535;
+  if (!isInteger || !isBetween) {
+    ctx.mustBe("an integer between 0 and 65535");
+  }
+  return asNumber;
+});
+var host = type2("string.ip | 'localhost'");
+
+// src/index.ts
+var index_default = { ...define_env_exports, ...types_exports };
+export {
+  index_default as default,
+  defineEnv,
+  host,
+  port
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "arkenv",
+  "type": "module",
+  "version": "0.2.0",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "description": "Typesafe environment variables parsing and validation with ArkType",
+  "exports": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.js",
+    "require": "./dist/index.cjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "pnpm",
+    "arktype",
+    "environment",
+    "variables",
+    "typesafe",
+    "validation"
+  ],
+  "license": "MIT",
+  "homepage": "https://yam.codes/arkenv",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yamcodes/arkenv.git"
+  },
+  "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",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "arktype": "^2.0.2"
+  },
+  "dependencies": {
+    "chalk": "^5.6.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsup",
+    "test:once": "pnpm test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist node_modules",
+    "test": "pnpm -w test --project arkenv"
+  }
+}