[Suggestion] Instruct users to return `z.NEVER` in `.superRefine()` when providing a type predicate

As the validation result solely depends on whether ctx.addIssue() is called,

https://github.com/colinhacks/zod/blob/ad4385439d7c0d7a584052dee5aa578fde5a6efd/README.md?plain=1#L1891

and the return value is only used to satisfy the type predicate and is always thrown away,

https://github.com/colinhacks/zod/blob/c9e4ed4095d77f5b43a5ba11d8f76b56ea48e5c6/src/types.ts#L3821-L3822

to prevent users from accidentally forgetting to call ctx.addIssue() while returning a boolean value as described in the example,

https://github.com/colinhacks/zod/blob/ad4385439d7c0d7a584052dee5aa578fde5a6efd/README.md?plain=1#L1931-L1945

instructing users to return z.NEVER instead of a boolean at the end (indicating the value is never used) just like the early return case when providing a type predicate may be a good idea.

  .superRefine((arg, ctx): arg is { first: string; second: number } => {
    if (!arg) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom, // customize your issue
        message: "object should exist",
      });
    }

    return z.NEVER;  // this should satisfy the typing
  })

[zetaraku]

Hi, @maxArturo.

I knew that the return type is necessary for the inferred refined type so I didn’t recommend users to declare their refinement function as refinement: (arg: Output, ctx: RefinementCtx) => z.NEVER but still like refinement: (arg: Output, ctx: RefinementCtx) => arg is something.

I only encourage users to return a z.NEVER in the refinement function. (See the last snippet above)

By the way, refinement: (arg: Output, ctx: RefinementCtx) => z.NEVER actually doesn’t work because z.NEVER is a value of never type, not a type itself.

[zetaraku]

I made the PR above to update the docs. Please take a look at it and let me know if anything needs to be adjusted 😃 I wonder if the test cases should be updated to return z.NEVER too. 🤔