parseOrThrow.ts

/**
 * Copyright 2025 Erik Pukinskis
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the “Software”), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

import type {
  z,
  ZodDiscriminatedUnion,
  ZodIssue,
  ZodObject,
  ZodRawShape,
  ZodUnion,
} from "zod"
import { ZodError } from "zod"

/**
 * Parse an object using a Zod schema, and if parsing fails throw a nice error
 * message. Unlike the default Zod error messages, it:
 *
 *  - Indicates something about what the app was doing when parsing failed
 *  - Only reports a single validation error, even if there are many
 *  - Tries to be as specific as possible while also being concise.
 */
export function parseOrThrow<
  SchemaType extends
    | ZodObject<ZodRawShape>
    | ZodUnion<[ZodObject<ZodRawShape>, ...ZodObject<ZodRawShape>[]]>
    | ZodDiscriminatedUnion<
        string,
        [ZodObject<ZodRawShape>, ...ZodObject<ZodRawShape>[]]
      >
>(schema: SchemaType, data: unknown, message: string): z.infer<SchemaType> {
  try {
    return schema.parse(data)
  } catch (error) {
    console.error(`Data: ${JSON.stringify(data, null, 4)}`)
    if (error instanceof ZodError) {
      const [issue] = error.issues
      if (message.endsWith(".")) {
        message = message.slice(0, -1)
      }

      if (issue.code === "invalid_union") {
        const [
          {
            issues: [unionIssue],
          },
        ] = issue.unionErrors

        throw new Error(`${message}. ${describeIssue(unionIssue) ?? ""}`)
      } else {
        throw new Error(`${message}. ${describeIssue(issue) ?? ""}`)
      }
    }
    throw error
  }
}

function describeIssue(issue?: ZodIssue) {
  if (!issue) return undefined
  if (issue.code === "invalid_union") return undefined
  if (issue.path.length < 1) return undefined

  const location = issue.path.join(".")
  let received = ""

  switch (issue.code) {
    case "invalid_enum_value":
    case "invalid_literal":
      received = ` received ${JSON.stringify(issue.received)}`
  }

  return `Zod validation failed at .${location}: ${issue.message}${received}`
}