feat(guard) reintroduce check as guard

discussion: unlike check, guard is only visible when Output extend Input

Author: oberbeck

deno/lib/__tests__/guard.test-d.ts

@@ -0,0 +1,29 @@
+import { describe, expectTypeOf, test } from "vitest";
+import { z } from "../index.ts";
+
+describe("guard", () => {
+  test("work as a type guard when Output extends Input", () => {
+    expectTypeOf<true>().toEqualTypeOf<true>();
+  });
+  test("work as a type guard when Output *does* extend Input", () => {
+    const inputExtendsOutputSchema = z.object({
+      a: z.string(),
+      b: z.enum(["x", "y"]).transform((arg) => arg as string),
+    });
+    const val = null as unknown;
+    if (inputExtendsOutputSchema.guard(val)) {
+      expectTypeOf(val).toEqualTypeOf<{ a: string; b: string }>();
+    } else {
+      expectTypeOf(val).toEqualTypeOf<unknown>();
+    }
+  });
+
+  test("to be unavailable when Output *does not* extend Input", () => {
+    const inputDiffersFromOutputSchema = z
+      .string()
+      .transform((arg) => parseFloat(arg));
+    const val = null as unknown;
+    // @ts-expect-error - compile error as Input does not extend Output
+    inputDiffersFromOutputSchema.guard(val);
+  });
+});

deno/lib/types.ts

@@ -517,6 +517,13 @@ export abstract class ZodType<
   isNullable(): boolean {
     return this.safeParse(null).success;
   }
+
+  guard<T extends Output>(
+    this: ZodType<T, any, T>,
+    data: unknown
+  ): data is Output {
+    return this.safeParse(data).success;
+  }
 }
 
 /////////////////////////////////////////

src/__tests__/guard.test-d.ts

@@ -0,0 +1,29 @@
+import { describe, expectTypeOf, test } from "vitest";
+import { z } from "../index";
+
+describe("guard", () => {
+  test("work as a type guard when Output extends Input", () => {
+    expectTypeOf<true>().toEqualTypeOf<true>();
+  });
+  test("work as a type guard when Output *does* extend Input", () => {
+    const inputExtendsOutputSchema = z.object({
+      a: z.string(),
+      b: z.enum(["x", "y"]).transform((arg) => arg as string),
+    });
+    const val = null as unknown;
+    if (inputExtendsOutputSchema.guard(val)) {
+      expectTypeOf(val).toEqualTypeOf<{ a: string; b: string }>();
+    } else {
+      expectTypeOf(val).toEqualTypeOf<unknown>();
+    }
+  });
+
+  test("to be unavailable when Output *does not* extend Input", () => {
+    const inputDiffersFromOutputSchema = z
+      .string()
+      .transform((arg) => parseFloat(arg));
+    const val = null as unknown;
+    // @ts-expect-error - compile error as Input does not extend Output
+    inputDiffersFromOutputSchema.guard(val);
+  });
+});

src/types.ts

@@ -517,6 +517,13 @@ export abstract class ZodType<
   isNullable(): boolean {
     return this.safeParse(null).success;
   }
+
+  guard<T extends Output>(
+    this: ZodType<T, any, T>,
+    data: unknown
+  ): data is Output {
+    return this.safeParse(data).success;
+  }
 }
 
 /////////////////////////////////////////