@express-zod-api/zod-plugin 1.0.0-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anna Bocharova
+
+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.

package/README.md

@@ -0,0 +1,33 @@
+# Zod Plugin from Express Zod API
+
+## Overview
+
+This module extends Zod functionality when it's imported:
+
+- Adds `.example()` method to all Zod schemas:
+  - shorthand for `.meta({ examples: [...] })`;
+- Adds `.deprecated()` method to all Zod schemas:
+  - shorthand for `.meta({ deprecated: true })`;
+- Adds `.label()` method to `ZodDefault`:
+  - shorthand for `.meta({ default: ... })`;
+- Adds `.remap()` method to `ZodObject` for renaming object properties:
+  - Supports a mapping objects or an object transforming function as an argument;
+  - Relies on `R.renameKeys()` from the `ramda` library;
+- Alters the `.brand()` method on all Zod schemas by making the assigned brand available in runtime:
+  - The provided `getBrand()` method can retrieve the brand from the schema.
+
+## Requirements
+
+- Zod `^4.0.0`
+
+## Usage
+
+```ts
+import { z } from "zod";
+import { getBrand } from "@express-zod-api/zod-plugin";
+
+const schema = z.string().example("test").example("another").brand("custom");
+
+getBrand(schema); // "custom"
+schema.meta(); // { examples: ["test", "another"] }
+```

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+
+/**
+ * @fileoverview Mapping utils for Zod Runtime Plugin (remap)
+ * @link https://stackoverflow.com/questions/55454125/typescript-remapping-object-properties-in-typesafe
+ * @todo try to reuse R.Remap from Ramda (requires to move its types to prod dependencies)
+ */
+type TuplesFromObject<T> = {
+    [P in keyof T]: [P, T[P]];
+}[keyof T];
+type GetKeyByValue<T, V> = TuplesFromObject<T> extends infer TT ? TT extends [infer P, V] ? P : never : never;
+type Remap<T, U extends {
+    [P in keyof T]?: V;
+}, V extends string> = {
+    [P in NonNullable<U[keyof U]>]: T[GetKeyByValue<U, P>];
+};
+type Intact<T, U> = {
+    [K in Exclude<keyof T, keyof U>]: T[K];
+};
+
+declare module "zod/v4/core" {
+    interface GlobalMeta {
+        default?: unknown;
+        examples?: unknown[];
+    }
+}
+declare module "zod" {
+    interface ZodType<out Output = unknown, out Input = unknown, out Internals extends z.core.$ZodTypeInternals<Output, Input> = z.core.$ZodTypeInternals<Output, Input>> extends z.core.$ZodType<Output, Input, Internals> {
+        /** @desc Alias for .meta({examples}), but argument is typed to ensure the correct placement for transformations */
+        example(example: z.output<this>): this;
+        deprecated(): this;
+    }
+    interface ZodDefault<T extends z.core.SomeType = z.core.$ZodType> extends z._ZodType<z.core.$ZodDefaultInternals<T>>, z.core.$ZodDefault<T> {
+        /** @desc Change the default value in the generated Documentation to a label, alias for .meta({ default }) */
+        label(label: string): this;
+    }
+    interface ZodObject<out Shape extends z.core.$ZodShape = z.core.$ZodLooseShape, out Config extends z.core.$ZodObjectConfig = z.core.$strip> extends z._ZodType<z.core.$ZodObjectInternals<Shape, Config>>, z.core.$ZodObject<Shape, Config> {
+        remap<V extends string, U extends {
+            [P in keyof Shape]?: V;
+        }>(mapping: U): z.ZodPipe<z.ZodPipe<this, z.ZodTransform>, // internal type simplified
+        z.ZodObject<Remap<Shape, U, V> & Intact<Shape, U>, Config>>;
+        remap<U extends z.core.$ZodShape>(mapper: (subject: Shape) => U): z.ZodPipe<z.ZodPipe<this, z.ZodTransform>, z.ZodObject<U>>;
+    }
+}
+
+declare const getBrand: (subject: z.core.$ZodType) => string | number | symbol | undefined;
+
+export { getBrand };

package/dist/index.js

@@ -0,0 +1 @@
+import*as o from"ramda";import{globalRegistry as p,z as n}from"zod";var r="@express-zod-api/zod-plugin";var c=n.core.$constructor("$EZBrandCheck",(e,t)=>{n.core.$ZodCheck.init(e,t),e._zod.onattach.push(s=>s._zod.bag.brand=t.brand),e._zod.check=()=>{}}),u=function(e){let t=p.get(this)?.examples?.slice()||[];return t.push(e),this.meta({examples:t})},l=function(){return this.meta({deprecated:!0})},f=function(e){return this.meta({default:e})},h=function(e){return this.check(new c({brand:e,check:"$EZBrandCheck"}))},m=function(e){let t=typeof e=="function"?e:o.renameKeys(o.reject(o.isNil,e)),s=t(o.map(o.invoker(0,"clone"),this._zod.def.shape)),i=(this._zod.def.catchall instanceof n.ZodUnknown?n.looseObject:n.object)(s);return this.transform(t).pipe(i)},a=Symbol.for(r);if(!(a in globalThis)){globalThis[a]=!0;for(let e of Object.keys(n)){if(!e.startsWith("Zod")||/(Success|Error|Function)$/.test(e))continue;let t=n[e];typeof t=="function"&&Object.defineProperties(t.prototype,{example:{value:u,writable:!1},deprecated:{value:l,writable:!1},brand:{set(){},get(){return h.bind(this)}}})}Object.defineProperty(n.ZodDefault.prototype,"label",{value:f,writable:!1}),Object.defineProperty(n.ZodObject.prototype,"remap",{value:m,writable:!1})}var z=e=>{let{brand:t}=e._zod.bag||{};if(typeof t=="symbol"||typeof t=="string"||typeof t=="number")return t};export{z as getBrand};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@express-zod-api/zod-plugin",
+  "version": "1.0.0-beta.3",
+  "license": "MIT",
+  "description": "Zod plugin for express-zod-api",
+  "sideEffects": true,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RobinTail/express-zod-api.git"
+  },
+  "author": {
+    "name": "Anna Bocharova",
+    "url": "https://robintail.cz",
+    "email": "me@robintail.cz"
+  },
+  "bugs": "https://github.com/RobinTail/express-zod-api/issues",
+  "funding": "https://github.com/sponsors/RobinTail",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "*.md"
+  ],
+  "dependencies": {
+    "ramda": "^0.31.3"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/ramda": "^0.31.0",
+    "camelize-ts": "^3.0.0",
+    "typescript": "^5.8.3",
+    "zod": "^4.0.0"
+  },
+  "scripts": {
+    "pretest": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsup",
+    "postbuild": "attw --pack --profile esm-only"
+  }
+}