br(v28): Making zod plugin an optional peer dependency.

cjs-test/zod-plugin.spec.ts

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 
-require("express-zod-api"); // side effect here via Zod Plugin
+require("@express-zod-api/zod-plugin"); // side effect here
 const z = require("zod"); // ensure CJS version of Zod is used
 
 describe("Zod plugin in CJS environment", () => {

compat-test/dts.spec.ts

@@ -2,14 +2,6 @@ import { describe, test, expect } from "vitest";
 import { readFile } from "node:fs/promises";
 
 describe("DTS", () => {
-  test("Framework must import Zod plugin", async () => {
-    const fwDts = await readFile(
-      "./node_modules/express-zod-api/dist/index.d.ts",
-      "utf-8",
-    );
-    expect(fwDts).toMatch(`import "@express-zod-api/zod-plugin";`);
-  });
-
   test("Zod plugin must import augmentation", async () => {
     const pluginDts = await readFile(
       "./node_modules/express-zod-api/node_modules/@express-zod-api/zod-plugin/dist/index.d.ts",

example/config.ts

@@ -1,3 +1,4 @@
+import "@express-zod-api/zod-plugin"; // adds .example() method
 import { BuiltinLogger, createConfig } from "express-zod-api";
 import ui from "swagger-ui-express";
 import createHttpError from "http-errors";

example/generate-client.ts

@@ -1,7 +1,7 @@
+import { config } from "./config.ts";
 import { writeFile } from "node:fs/promises";
 import { Integration } from "express-zod-api";
 import { routing } from "./routing.ts";
-import { config } from "./config.ts";
 import typescript from "typescript";
 
 await writeFile(

example/generate-documentation.ts

@@ -1,6 +1,6 @@
+import { config } from "./config.ts";
 import { writeFile } from "node:fs/promises";
 import { Documentation } from "express-zod-api";
-import { config } from "./config.ts";
 import { routing } from "./routing.ts";
 import manifest from "./package.json" with { type: "json" };
 

example/package.json

@@ -12,6 +12,7 @@
     "test": "vitest run index.spec.ts"
   },
   "devDependencies": {
+    "@express-zod-api/zod-plugin": "workspace:*",
     "@types/http-errors": "catalog:dev",
     "@types/swagger-ui-express": "^4.1.8",
     "express-zod-api": "workspace:*",

express-zod-api/package.json

@@ -24,7 +24,6 @@
     "prepack": "cp ../*.md ../LICENSE ./"
   },
   "type": "module",
-  "sideEffects": true,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "dist/index.js",
@@ -42,13 +41,13 @@
     "node": "^22.19.0 || ^24.0.0"
   },
   "dependencies": {
-    "@express-zod-api/zod-plugin": "workspace:^",
     "ansis": "^4.2.0",
     "node-mocks-http": "^1.17.2",
     "openapi3-ts": "^4.5.0",
     "ramda": "catalog:prod"
   },
   "peerDependencies": {
+    "@express-zod-api/zod-plugin": "workspace:^",
     "@types/compression": "^1.7.5",
     "@types/express": "^5.0.0",
     "@types/express-fileupload": "^1.5.0",
@@ -61,6 +60,9 @@
     "zod": "catalog:peer"
   },
   "peerDependenciesMeta": {
+    "@express-zod-api/zod-plugin": {
+      "optional": true
+    },
     "@types/compression": {
       "optional": true
     },
@@ -84,6 +86,7 @@
     }
   },
   "devDependencies": {
+    "@express-zod-api/zod-plugin": "workspace:^",
     "@types/compression": "catalog:dev",
     "@types/cors": "^2.8.19",
     "@types/depd": "^1.1.37",

express-zod-api/src/brand.ts

@@ -0,0 +1,15 @@
+import type { brandProperty as brandProp } from "../../zod-plugin/src/brand.ts";
+import { globalRegistry, type z } from "zod";
+
+export const brandProperty = "x-brand" satisfies typeof brandProp;
+
+export const getBrand = (subject: z.core.$ZodType) => {
+  const { [brandProperty]: brand } = globalRegistry.get(subject) || {};
+  if (
+    typeof brand === "symbol" ||
+    typeof brand === "string" ||
+    typeof brand === "number"
+  )
+    return brand;
+  return undefined;
+};

express-zod-api/src/buffer-schema.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { brandProperty } from "./brand";
 
 export const ezBufferBrand = Symbol("Buffer");
 
@@ -7,4 +8,4 @@ export const buffer = () =>
     .custom<Buffer>((subject) => Buffer.isBuffer(subject), {
       error: "Expected Buffer",
     })
-    .brand(ezBufferBrand as symbol);
+    .meta({ [brandProperty]: ezBufferBrand });

express-zod-api/src/date-in-schema.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { brandProperty } from "./brand";
 
 export const ezDateInBrand = Symbol("DateIn");
 
@@ -20,6 +21,5 @@ export const dateIn = ({ examples, ...rest }: DateInParams = {}) => {
     .meta({ examples })
     .transform((str) => new Date(str))
     .pipe(z.date())
-    .brand(ezDateInBrand as symbol)
-    .meta(rest);
+    .meta({ ...rest, [brandProperty]: ezDateInBrand });
 };

express-zod-api/src/date-out-schema.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { brandProperty } from "./brand";
 
 export const ezDateOutBrand = Symbol("DateOut");
 
@@ -13,5 +14,4 @@ export const dateOut = (meta: DateOutParams = {}) =>
   z
     .date()
     .transform((date) => date.toISOString())
-    .brand(ezDateOutBrand as symbol)
-    .meta(meta);
+    .meta({ ...meta, [brandProperty]: ezDateOutBrand });

express-zod-api/src/deep-checks.ts

@@ -6,7 +6,7 @@ import { ezDateOutBrand } from "./date-out-schema";
 import { DeepCheckError } from "./errors";
 import { ezFormBrand } from "./form-schema";
 import type { IOSchema } from "./io-schema";
-import { getBrand } from "@express-zod-api/zod-plugin";
+import { getBrand } from "./brand";
 import type { FirstPartyKind } from "./schema-walker";
 import { ezUploadBrand } from "./upload-schema";
 import { ezRawBrand } from "./raw-schema";

express-zod-api/src/documentation-helpers.ts

@@ -38,7 +38,7 @@ import { DocumentationError } from "./errors";
 import type { IOSchema } from "./io-schema";
 import { flattenIO } from "./json-schema-helpers";
 import type { Alternatives } from "./logical-container";
-import { getBrand } from "@express-zod-api/zod-plugin";
+import { getBrand } from "./brand";
 import type { ClientMethod } from "./method";
 import type { ProprietaryBrand } from "./proprietary-schemas";
 import { ezRawBrand } from "./raw-schema";

express-zod-api/src/endpoint.ts

@@ -21,7 +21,7 @@ import type { IOSchema } from "./io-schema";
 import { lastResortHandler } from "./last-resort";
 import type { ActualLogger } from "./logger-helpers";
 import type { LogicalContainer } from "./logical-container";
-import { getBrand } from "@express-zod-api/zod-plugin";
+import { getBrand } from "./brand";
 import type { ClientMethod, CORSMethod, Method, SomeMethod } from "./method";
 import { AbstractMiddleware, ExpressMiddleware } from "./middleware";
 import type { ContentType } from "./content-type";
@@ -92,9 +92,11 @@ export class Endpoint<
 > extends AbstractEndpoint {
   readonly #def: ConstructorParameters<typeof Endpoint<IN, OUT, CTX>>[0];
 
-  /** considered expensive operation, only required for generators */
+  /** considered an expensive operation, only required for generators */
   #ensureOutputExamples = R.once(() => {
-    if (globalRegistry.get(this.#def.outputSchema)?.examples?.length) return; // examples on output schema, or pull up:
+    const { examples: existing } =
+      globalRegistry.get(this.#def.outputSchema) || {};
+    if (Array.isArray(existing) && existing.length) return; // examples on output schema, or pull up:
     if (!isSchema<z.core.$ZodObject>(this.#def.outputSchema, "object")) return;
     const examples = pullResponseExamples(this.#def.outputSchema);
     if (!examples.length) return;

express-zod-api/src/form-schema.ts

@@ -1,9 +1,10 @@
 import { z } from "zod";
+import { brandProperty } from "./brand";
 
 export const ezFormBrand = Symbol("Form");
 
 /** @desc Accepts an object shape or a custom object schema */
 export const form = <S extends z.core.$ZodShape>(base: S | z.ZodObject<S>) =>
-  (base instanceof z.ZodObject ? base : z.object(base)).brand(
-    ezFormBrand as symbol,
-  );
+  (base instanceof z.ZodObject ? base : z.object(base)).meta({
+    [brandProperty]: ezFormBrand,
+  });

express-zod-api/src/index.ts

@@ -1,4 +1,3 @@
-import "@express-zod-api/zod-plugin"; // side effects here
 export { createConfig } from "./config-type";
 export {
   EndpointsFactory,

express-zod-api/src/raw-schema.ts

@@ -1,20 +1,21 @@
 import { z } from "zod";
 import { buffer } from "./buffer-schema";
+import { brandProperty } from "./brand";
 
 export const ezRawBrand = Symbol("Raw");
 
 const base = z.object({ raw: buffer() });
-type Base = ReturnType<typeof base.brand<symbol>>;
+type Base = typeof base;
 
 const extended = <S extends z.core.$ZodShape>(extra: S) =>
-  base.extend(extra).brand(ezRawBrand as symbol);
+  base.extend(extra).meta({ [brandProperty]: ezRawBrand });
 
 export function raw(): Base;
 export function raw<S extends z.core.$ZodShape>(
   extra: S,
 ): ReturnType<typeof extended<S>>;
 export function raw(extra?: z.core.$ZodShape) {
-  return extra ? extended(extra) : base.brand(ezRawBrand as symbol);
+  return extra ? extended(extra) : base.meta({ [brandProperty]: ezRawBrand });
 }
 
 export type RawSchema = Base;

express-zod-api/src/result-handler.ts

@@ -111,7 +111,7 @@ export const defaultResultHandler = new ResultHandler({
       data: output,
     });
     const { examples } = globalRegistry.get(output) || {}; // pulling down:
-    if (examples?.length) {
+    if (Array.isArray(examples) && examples.length) {
       globalRegistry.add(responseSchema, {
         examples: examples.map((data) => ({
           status: "success" as const,
@@ -160,11 +160,11 @@ export const arrayResultHandler = new ResultHandler({
       output.shape.items instanceof z.ZodArray
         ? output.shape.items
         : z.array(z.any());
-    if (globalRegistry.get(responseSchema)?.examples?.length)
-      return responseSchema; // has examples on the items, or pull down:
-    const examples = globalRegistry
-      .get(output)
-      ?.examples?.filter(
+    const { examples: existing } = globalRegistry.get(responseSchema) || {};
+    if (Array.isArray(existing) && existing.length) return responseSchema; // has examples on the items, or pull down:
+    const { examples: pulled } = globalRegistry.get(output) || {};
+    const examples = (Array.isArray(pulled) ? pulled : [])
+      .filter(
         (example): example is { items: unknown[] } =>
           isObject(example) &&
           "items" in example &&

express-zod-api/src/result-helpers.ts

@@ -91,11 +91,12 @@ export const getPublicErrorMessage = (error: HttpError): string =>
 export const pullResponseExamples = <T extends z.core.$ZodObject>(subject: T) =>
   Object.entries(subject._zod.def.shape).reduce<FlatObject[]>(
     (acc, [key, schema]) => {
-      const { examples = [] } = globalRegistry.get(schema) || {};
-      return combinations(acc, examples.map(R.objOf(key)), ([left, right]) => ({
-        ...left,
-        ...right,
-      }));
+      const { examples } = globalRegistry.get(schema) || {};
+      return combinations(
+        acc,
+        (Array.isArray(examples) ? examples : []).map(R.objOf(key)),
+        ([left, right]) => ({ ...left, ...right }),
+      );
     },
     [],
   );

express-zod-api/src/schema-walker.ts

@@ -1,5 +1,5 @@
 import type { EmptyObject, FlatObject } from "./common-helpers";
-import { getBrand } from "@express-zod-api/zod-plugin";
+import { getBrand } from "./brand";
 import type { z } from "zod";
 
 export type FirstPartyKind = z.core.$ZodTypeDef["type"];

express-zod-api/src/upload-schema.ts

@@ -1,5 +1,6 @@
 import type { UploadedFile } from "express-fileupload";
 import { z } from "zod";
+import { brandProperty } from "./brand";
 
 export const ezUploadBrand = Symbol("Upload");
 
@@ -33,4 +34,4 @@ export const upload = () =>
         }),
       },
     )
-    .brand(ezUploadBrand as symbol);
+    .meta({ [brandProperty]: ezUploadBrand });

express-zod-api/tests/__snapshots__/zts.spec.ts.snap

@@ -252,14 +252,7 @@ exports[`zod-to-ts > z.object() > specially handles coercive schema in response
 }"
 `;
 
-exports[`zod-to-ts > z.object() > supports string literal properties 1`] = `
-"{
-    "5": number;
-    "string-literal": string;
-}"
-`;
-
-exports[`zod-to-ts > z.object() > supports zod.deprecated() 1`] = `
+exports[`zod-to-ts > z.object() > supports deprecated metadata 1`] = `
 "{
     /** @deprecated */
     one: string;
@@ -268,6 +261,13 @@ exports[`zod-to-ts > z.object() > supports zod.deprecated() 1`] = `
 }"
 `;
 
+exports[`zod-to-ts > z.object() > supports string literal properties 1`] = `
+"{
+    "5": number;
+    "string-literal": string;
+}"
+`;
+
 exports[`zod-to-ts > z.object() > supports zod.describe() 1`] = `
 "{
     /** The name of the item */

express-zod-api/tests/brand.spec.ts

@@ -0,0 +1,13 @@
+import { globalRegistry, z } from "zod";
+import { brandProperty, getBrand } from "../src/brand";
+
+describe("getBrand", () => {
+  test.each([{ [brandProperty]: "test" }, {}, undefined])(
+    "should take it from metadata in globalRegistry %#",
+    (metadata) => {
+      const subject = z.string();
+      if (metadata) globalRegistry.add(subject, metadata);
+      expect(getBrand(subject)).toBe(metadata?.[brandProperty]);
+    },
+  );
+});

express-zod-api/tests/buffer-schema.spec.ts

@@ -1,13 +1,13 @@
 import { readFile } from "node:fs/promises";
-import { z, $brand } from "zod";
+import { z } from "zod";
 import { ez } from "../src";
 
 describe("ez.buffer()", () => {
   describe("creation", () => {
     test("should create a Buffer", () => {
       const schema = ez.buffer();
       expect(schema).toBeInstanceOf(z.ZodCustom);
-      expectTypeOf(schema._zod.output).toEqualTypeOf<Buffer & $brand<symbol>>();
+      expectTypeOf(schema._zod.output).toEqualTypeOf<Buffer>();
     });
   });
 

express-zod-api/tests/date-in-schema.spec.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ezDateInBrand } from "../src/date-in-schema";
 import { ez } from "../src";
-import { getBrand } from "@express-zod-api/zod-plugin";
+import { getBrand } from "../src/brand";
 
 describe("ez.dateIn()", () => {
   describe("creation", () => {

express-zod-api/tests/date-out-schema.spec.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ezDateOutBrand } from "../src/date-out-schema";
 import { ez } from "../src";
-import { getBrand } from "@express-zod-api/zod-plugin";
+import { getBrand } from "../src/brand";
 
 describe("ez.dateOut()", () => {
   describe("creation", () => {

express-zod-api/tests/deep-checks.spec.ts

@@ -2,7 +2,7 @@ import type { UploadedFile } from "express-fileupload";
 import { z } from "zod";
 import { ez } from "../src";
 import { findNestedSchema, hasCycle } from "../src/deep-checks";
-import { getBrand } from "@express-zod-api/zod-plugin";
+import { getBrand } from "../src/brand";
 import { ezUploadBrand } from "../src/upload-schema";
 
 describe("Checks", () => {
@@ -22,7 +22,7 @@ describe("Checks", () => {
       z.object({ test: z.boolean() }).and(z.object({ test2: ez.upload() })),
       z.optional(ez.upload()),
       ez.upload().nullable(),
-      ez.upload().default({} as UploadedFile & z.core.$brand<symbol>),
+      ez.upload().default({} as UploadedFile),
       z.record(z.string(), ez.upload()),
       ez.upload().refine(() => true),
       z.array(ez.upload()),

express-zod-api/tests/documentation.spec.ts

@@ -1,3 +1,4 @@
+import "@express-zod-api/zod-plugin";
 import camelize from "camelize-ts";
 import snakify from "snakify-ts";
 import {