feat(utils): provide validateAsync alternative to synchronous validate

Author: matejchalk

packages/models/src/index.ts

@@ -74,6 +74,7 @@ export { exists } from './lib/implementation/utils.js';
 export {
   SchemaValidationError,
   validate,
+  validateAsync,
 } from './lib/implementation/validate.js';
 export {
   issueSchema,

packages/models/src/lib/implementation/validate.ts

@@ -6,6 +6,15 @@ type SchemaValidationContext = {
   filePath?: string;
 };
 
+/**
+ * Autocompletes valid Zod Schema input for convience, but will accept any other data as well
+ */
+type ZodInputLooseAutocomplete<T extends ZodType> =
+  | z.input<T>
+  | {}
+  | null
+  | undefined;
+
 export class SchemaValidationError extends Error {
   constructor(
     error: ZodError,
@@ -29,7 +38,7 @@ export class SchemaValidationError extends Error {
 
 export function validate<T extends ZodType>(
   schema: T,
-  data: z.input<T> | {} | null | undefined, // loose autocomplete
+  data: ZodInputLooseAutocomplete<T>,
   context: SchemaValidationContext = {},
 ): z.output<T> {
   const result = schema.safeParse(data);
@@ -38,3 +47,15 @@ export function validate<T extends ZodType>(
   }
   throw new SchemaValidationError(result.error, schema, context);
 }
+
+export async function validateAsync<T extends ZodType>(
+  schema: T,
+  data: ZodInputLooseAutocomplete<T>,
+  context: SchemaValidationContext = {},
+): Promise<z.output<T>> {
+  const result = await schema.safeParseAsync(data);
+  if (result.success) {
+    return result.data;
+  }
+  throw new SchemaValidationError(result.error, schema, context);
+}

packages/models/src/lib/implementation/validate.unit.test.ts

@@ -1,7 +1,10 @@
 import ansis from 'ansis';
+import { vol } from 'memfs';
+import { readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
-import z, { ZodError } from 'zod';
-import { SchemaValidationError, validate } from './validate.js';
+import { ZodError, z } from 'zod';
+import { MEMFS_VOLUME } from '@code-pushup/test-utils';
+import { SchemaValidationError, validate, validateAsync } from './validate.js';
 
 describe('validate', () => {
   it('should return parsed data if valid', () => {
@@ -37,6 +40,76 @@ describe('validate', () => {
 ✖ Invalid ISO date
   → at dateOfBirth`);
   });
+
+  it('should throw if async schema provided (handled by validateAsync)', () => {
+    const projectNameSchema = z
+      .string()
+      .optional()
+      .transform(
+        async name =>
+          name || JSON.parse(await readFile('package.json', 'utf8')).name,
+      )
+      .meta({ title: 'ProjectName' });
+
+    expect(() => validate(projectNameSchema, undefined)).toThrow(
+      'Encountered Promise during synchronous parse. Use .parseAsync() instead.',
+    );
+  });
+});
+
+describe('validateAsync', () => {
+  it('should parse schema with async transform', async () => {
+    vol.fromJSON({ 'package.json': '{ "name": "core" }' }, MEMFS_VOLUME);
+    const projectNameSchema = z
+      .string()
+      .optional()
+      .transform(
+        async name =>
+          name || JSON.parse(await readFile('package.json', 'utf8')).name,
+      )
+      .meta({ title: 'ProjectName' });
+
+    await expect(validateAsync(projectNameSchema, undefined)).resolves.toBe(
+      'core',
+    );
+  });
+
+  it('should parse schema with async refinement', async () => {
+    vol.fromJSON({ 'package.json': '{}' }, MEMFS_VOLUME);
+    const filePathSchema = z
+      .string()
+      .refine(
+        file =>
+          stat(file)
+            .then(stats => stats.isFile())
+            .catch(() => false),
+        { error: 'File does not exist' },
+      )
+      .transform(file => path.resolve(process.cwd(), file))
+      .meta({ title: 'FilePath' });
+
+    await expect(validateAsync(filePathSchema, 'package.json')).resolves.toBe(
+      path.join(process.cwd(), 'package.json'),
+    );
+  });
+
+  it('should reject with formatted error if async schema is invalid', async () => {
+    vol.fromJSON({}, MEMFS_VOLUME);
+    const filePathSchema = z
+      .string()
+      .refine(
+        file =>
+          stat(file)
+            .then(stats => stats.isFile())
+            .catch(() => false),
+        { error: 'File does not exist' },
+      )
+      .meta({ title: 'FilePath' });
+
+    await expect(validateAsync(filePathSchema, 'package.json')).rejects.toThrow(
+      `Invalid ${ansis.bold('FilePath')}\n✖ File does not exist`,
+    );
+  });
 });
 
 describe('SchemaValidationError', () => {