feat: decouple env schema validation from internal helper

A.P.A. Slaa · A.P.A. Slaa · commit 2c29d59796dd · 2026-03-28T19:54:03.000+01:00
diff --git a/README.md b/README.md
@@ -129,6 +129,31 @@ const runtimeConfig = env.config.map({
 
 `env.config.safeMap()` returns `{ success, data | errors }` instead of throwing.
 
+### Plug in another schema library
+
+The package ships with a built-in dependency-free validator, but the root export also exposes `adaptSchema()` so you can wrap another runtime schema library later without coupling your app to an internal helper module.
+
+```ts
+import { adaptSchema, env, validation } from "@sourceregistry/node-env";
+
+const externalSchema = {
+  safeParse(value: unknown) {
+    return typeof value === "string"
+      ? { success: true as const, data: value }
+      : { success: false as const, issues: [{ message: "Expected string" }] };
+  },
+};
+
+const ExternalString = adaptSchema<typeof externalSchema, string>(externalSchema, {
+  safeParse(schema, value) {
+    return schema.safeParse(value);
+  },
+});
+
+validation.parse(ExternalString, "ok");
+env.config.field("APP_NAME", ExternalString);
+```
+
 ### CSV env values
 
 Use `env.schema.csv()` for comma-separated env variables:
diff --git a/src/index.ts b/src/index.ts
@@ -1,5 +1,6 @@
 import {readFileSync, existsSync} from "fs";
 import {
+    adaptSchema,
     fail,
     InferValidator,
     InferSchemaShape,
@@ -14,8 +15,11 @@ import {
     ValidationFailure,
     ValidationResult,
     ValidationSuccess,
+    ValidationAdapter,
+    ValidationAdapterResult,
+    ValidationIssueInput,
     Validator
-} from "./schema.helper";
+} from "./validation";
 
 type DotEnvEntries = Record<string, string>;
 const ENV_KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
@@ -701,17 +705,25 @@ export const env = Object.freeze({
  * Re-export of the generic validation primitives and supporting public types.
  */
 export {
+    adaptSchema,
     envConfig,
     envValidation,
+    fail,
+    isFailure,
+    ok,
+    runValidation,
     SchemaValidationError,
     validation,
 };
 export type {
     InferValidator,
     InferSchemaShape,
     SchemaShape,
+    ValidationAdapter,
+    ValidationAdapterResult,
     ValidationFailure,
     ValidationIssue,
+    ValidationIssueInput,
     ValidationPath,
     ValidationResult,
     ValidationSuccess,
diff --git a/src/validation.ts b/src/validation.ts
@@ -37,21 +37,56 @@ export type ValidationPath = Array<string | number>;
  * Runtime validator function.
  */
 export type Validator<T> = (value: unknown, path?: ValidationPath) => ValidationResult<T>;
+
 /**
  * Infers the validated type from a validator.
  */
 export type InferValidator<V> = V extends Validator<infer T> ? T : never;
+
 /**
  * Generic object schema shape.
  */
 export type SchemaShape = Record<string, Validator<any>>;
+
 /**
  * Infers the validated output from an object schema shape.
  */
 export type InferSchemaShape<S extends SchemaShape> = {
     [K in keyof S]: InferValidator<S[K]>;
 };
 
+/**
+ * Issue input shape accepted by adapter helpers.
+ */
+export type ValidationIssueInput = {
+    path?: string | ValidationPath;
+    message: string;
+    code?: string;
+};
+
+/**
+ * Result shape accepted by adapter helpers.
+ */
+export type ValidationAdapterResult<T> =
+    | ValidationResult<T>
+    | {
+        success: true;
+        data: T;
+    }
+    | {
+        success: false;
+        errors?: ValidationIssueInput[];
+        issues?: ValidationIssueInput[];
+        error?: unknown;
+    };
+
+/**
+ * Adapter used to bridge external schema libraries into the local validator contract.
+ */
+export type ValidationAdapter<TSchema, TOutput = unknown> = {
+    safeParse(schema: TSchema, value: unknown): ValidationAdapterResult<TOutput>;
+};
+
 /**
  * Error thrown by `validation.parse()` when validation fails.
  */
@@ -65,7 +100,7 @@ export class SchemaValidationError extends Error {
     }
 }
 
-const toPathString = (path: ValidationPath) => {
+export const toPathString = (path: ValidationPath) => {
     if (path.length === 0) return "$";
     return path.reduce<string>((acc, part) => {
         if (typeof part === "number") return `${acc}[${part}]`;
@@ -74,6 +109,19 @@ const toPathString = (path: ValidationPath) => {
     }, "$");
 };
 
+const normalizePath = (path: string | ValidationPath | undefined, fallback: ValidationPath): string => {
+    if (typeof path === "string") {
+        return path.startsWith("$") ? path : toPathString([...fallback, path]);
+    }
+    return toPathString(path ?? fallback);
+};
+
+const normalizeIssue = (issue: ValidationIssueInput, fallback: ValidationPath): ValidationIssue => ({
+    path: normalizePath(issue.path, fallback),
+    message: issue.message,
+    code: issue.code,
+});
+
 /**
  * Creates a successful validation result.
  */
@@ -104,6 +152,47 @@ export const isFailure = <T>(result: ValidationResult<T>): result is ValidationF
 const isPlainObject = (value: unknown): value is Record<string, unknown> =>
     typeof value === "object" && value !== null && !Array.isArray(value);
 
+/**
+ * Normalizes adapter output into the local validation result format.
+ */
+export const normalizeAdapterResult = <T>(
+    result: ValidationAdapterResult<T>,
+    path: ValidationPath = []
+): ValidationResult<T> => {
+    if (result.success) {
+        return ok(result.data);
+    }
+
+    if ("errors" in result && Array.isArray(result.errors) && result.errors.length > 0) {
+        return {
+            success: false,
+            errors: result.errors.map((issue) => normalizeIssue(issue, path)),
+        };
+    }
+
+    if ("issues" in result && Array.isArray(result.issues) && result.issues.length > 0) {
+        return {
+            success: false,
+            errors: result.issues.map((issue) => normalizeIssue(issue, path)),
+        };
+    }
+
+    const error = "error" in result ? result.error : undefined;
+    const message = error instanceof Error
+        ? error.message
+        : "Schema validation failed";
+    return fail(message, path, "invalid_schema");
+};
+
+/**
+ * Wraps an external schema and adapter into a local validator function.
+ */
+export const adaptSchema = <TSchema, T>(
+    schema: TSchema,
+    adapter: ValidationAdapter<TSchema, T>
+): Validator<T> =>
+    (value, path = []) => normalizeAdapterResult<T>(adapter.safeParse(schema, value), path);
+
 /**
  * Runs a validator against a value.
  */
diff --git a/tests/schema.test.ts b/tests/schema.test.ts
@@ -1,14 +1,16 @@
 import {describe, expect, it} from "vitest";
 import {
+    adaptSchema,
     fail,
     isFailure,
     ok,
     runValidation,
     SchemaValidationError,
+    ValidationAdapterResult,
     validation
-} from "../src/schema.helper";
+} from "../src";
 
-describe("schema helper", () => {
+describe("validation", () => {
     it("exposes ok, fail, isFailure, and runValidation helpers", () => {
         const success = ok("value");
         const failure = fail("Broken", ["ROOT", 0], "bad");
@@ -196,4 +198,30 @@ describe("schema helper", () => {
 
         expect(() => validation.parse(validation.number(), "nope")).toThrow(SchemaValidationError);
     });
+
+    it("adapts external safeParse-style schemas without adding a dependency", () => {
+        const schema = {
+            safeParse(value: unknown) {
+                if (typeof value === "string" && value.length > 0) {
+                    return {success: true as const, data: value.toUpperCase()};
+                }
+                return {
+                    success: false as const,
+                    issues: [{path: [], message: "Expected non-empty string", code: "custom"}],
+                };
+            },
+        };
+
+        const validator = adaptSchema<typeof schema, string>(schema, {
+            safeParse(target, value): ValidationAdapterResult<string> {
+                return target.safeParse(value);
+            },
+        });
+
+        expect(validation.parse(validator, "test")).toBe("TEST");
+        expect(validation.safeParse(validator, "")).toEqual(expect.objectContaining({
+            success: false,
+            errors: [expect.objectContaining({path: "$", code: "custom"})],
+        }));
+    });
 });
