Add JSDoc to all public exports + small bun-plugin, @repo/types refactor

.changeset/kind-garlics-move.md

@@ -0,0 +1,7 @@
+---
+"@arkenv/bun-plugin": minor
+---
+
+#### Refactoring + remove `processEnvSchema` export
+
+**Breaking change:** We've removed the `processEnvSchema` export from this library as it's an internal utility.

.changeset/mighty-kids-count.md

@@ -0,0 +1,7 @@
+---
+"@arkenv/bun-plugin": patch
+---
+
+#### Support for `.mts` and `.cts` extensions
+
+Updated the Bun plugin to correctly process and load `.mts` and `.cts` files. This ensures environment variables are properly injected when using these TypeScript file extensions.

.changeset/wacky-oranges-care.md

@@ -0,0 +1,7 @@
+---
+"@repo/types": minor
+---
+
+#### Renamed type: `CompiledEnvSchema` (was `EnvSchemaWithType`)
+
+**Breaking change:** The type `EnvSchemaWithType` has been renamed to `CompiledEnvSchema`.

packages/arkenv/src/arktype/index.ts

@@ -6,13 +6,44 @@ import type { ArkEnvConfig, EnvSchema } from "../create-env.ts";
 import { ArkEnvError } from "../errors.ts";
 import { coerce } from "./coercion/coerce.ts";
 
+/**
+ * Re-export of ArkType’s `distill` utilities.
+ *
+ * Exposed for internal use cases and type-level integrations.
+ * ArkEnv does not add behavior or guarantees beyond what ArkType provides.
+ *
+ * @internal
+ * @see https://github.com/arktypeio/arktype
+ */
 export type { distill };
 
 /**
- * Re-export the ArkType `type` function from the scoped root.
+ * 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
  */
 export const type = $.type;
 
+/**
+ * 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.
+ *
+ * @internal
+ */
 export function parse<const T extends SchemaShape>(
 	def: EnvSchema<T>,
 	config: ArkEnvConfig,

packages/arkenv/src/create-env.ts

@@ -1,7 +1,7 @@
 import type { $ } from "@repo/scope";
 import type {
+	CompiledEnvSchema,
 	Dict,
-	EnvSchemaWithType,
 	InferType,
 	SchemaShape,
 } from "@repo/types";
@@ -10,6 +10,20 @@ import { ArkEnvError } from "./errors.ts";
 import { parseStandard } from "./parse-standard.ts";
 import { loadArkTypeValidator } from "./utils/load-arktype.ts";
 
+/**
+ * Declarative environment schema definition accepted by ArkEnv.
+ *
+ * Represents a declarative schema object mapping environment
+ * variable names to schema definitions (e.g. ArkType DSL strings
+ * or Standard Schema validators).
+ *
+ * This type is used to validate that a schema object is compatible with
+ * ArkEnv’s validator scope before being compiled or parsed.
+ *
+ * Most users will provide schemas in this form.
+ *
+ * @template def - The schema shape object
+ */
 export type EnvSchema<def> = at.validate<def, $>;
 type RuntimeEnvironment = Dict<string>;
 
@@ -78,16 +92,16 @@ export function createEnv<const T extends SchemaShape>(
 	def: EnvSchema<T>,
 	config?: ArkEnvConfig,
 ): distill.Out<at.infer<T, $>>;
-export function createEnv<T extends EnvSchemaWithType>(
+export function createEnv<T extends CompiledEnvSchema>(
 	def: T,
 	config?: ArkEnvConfig,
 ): InferType<T>;
 export function createEnv<const T extends SchemaShape>(
-	def: EnvSchema<T> | EnvSchemaWithType,
+	def: EnvSchema<T> | CompiledEnvSchema,
 	config?: ArkEnvConfig,
 ): distill.Out<at.infer<T, $>> | InferType<typeof def>;
 export function createEnv<const T extends SchemaShape>(
-	def: EnvSchema<T> | EnvSchemaWithType,
+	def: EnvSchema<T> | CompiledEnvSchema,
 	config: ArkEnvConfig = {},
 ): distill.Out<at.infer<T, $>> | InferType<typeof def> {
 	const mode = config.validator ?? "arktype";

packages/arkenv/src/errors.ts

@@ -69,6 +69,28 @@ export const formatInternalErrors = (
 		)
 		.join("\n");
 
+/**
+ * Error thrown when environment variable validation fails.
+ *
+ * This error extends the native `Error` class and provides formatted error messages
+ * that clearly indicate which environment variables are invalid and why.
+ *
+ * @example
+ * ```ts
+ * import { createEnv, ArkEnvError } from 'arkenv';
+ *
+ * try {
+ *   const env = createEnv({
+ *     PORT: 'number.port',
+ *     HOST: 'string.host',
+ *   });
+ * } catch (error) {
+ *   if (error instanceof ArkEnvError) {
+ *     console.error('Environment validation failed:', error.message);
+ *   }
+ * }
+ * ```
+ */
 export class ArkEnvError extends Error {
 	constructor(
 		errors: ArkErrors | InternalValidationError[],

packages/arkenv/src/index.ts

@@ -5,7 +5,7 @@ export type { EnvSchema } from "./create-env.ts";
 export { ArkEnvError } from "./errors.ts";
 
 /**
- * `arkenv`'s main export, an alias for {@link createEnv}
+ * ArkEnv's main export, an alias for {@link createEnv}
  *
  * {@link https://arkenv.js.org | ArkEnv} is a typesafe environment variables validator from editor to runtime.
  */