@parziva-1/zod-mongoose 5.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2023 Zodyac (bebrasmell) and contributors
+Copyright (c) 2026 Jaime Linares / spybee-sas (fork additions)
+
+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,320 @@
+# @parziva-1/zod-mongoose
+
+![CI](https://github.com/parziva-1/zod-mongoose/actions/workflows/ci.yml/badge.svg)
+![NPM Version](https://img.shields.io/npm/v/%40parziva-1%2Fzod-mongoose)
+![License](https://img.shields.io/npm/l/%40parziva-1%2Fzod-mongoose)
+![Test coverage](./badges/coverage.svg)
+
+Convert [Zod](https://www.npmjs.com/package/zod) object schemas into
+[Mongoose](https://www.npmjs.com/package/mongoose) schemas, keeping a single
+source of truth for both runtime validation and your database layer.
+
+## Why this fork exists
+
+This is a fork of the excellent
+[`@zodyac/zod-mongoose`](https://www.npmjs.com/package/@zodyac/zod-mongoose)
+(upstream: [git-zodyac/mongoose](https://github.com/git-zodyac/mongoose)),
+created to add **Zod v4 support**. As of this writing, upstream is still on
+Zod v3 internals and has not published a v4-compatible release. This fork
+ports the schema introspection layer to Zod v4's runtime shape
+(`schema._zod.def`) while keeping the public API unchanged, so it's a drop-in
+replacement once your own Zod schemas are upgraded to v4.
+
+All credit for the original design and implementation goes to the upstream
+`zodyac` project and its contributors (see [LICENSE](./LICENSE)).
+
+## Installation
+
+```bash
+npm install @parziva-1/zod-mongoose
+pnpm add @parziva-1/zod-mongoose
+yarn add @parziva-1/zod-mongoose
+bun add @parziva-1/zod-mongoose
+```
+
+Peer dependencies: `zod@^4.0.0` and `mongoose@^8.20.2 || ^9.0.0`.
+
+## Migrating from `@zodyac/zod-mongoose`
+
+- **Package name**: import from `@parziva-1/zod-mongoose` instead of
+  `@zodyac/zod-mongoose`.
+- **Zod version**: you must be on `zod@^4.0.0`. Zod v3 is not supported at
+  all - stay on the upstream package (or this fork's `4.x` line, if you need
+  an intermediate step) until your schemas are migrated.
+- **Module format**: this package is **ESM-only** starting with v5 (no CJS
+  build). If you `require()` it from CommonJS, use a dynamic
+  `await import("@parziva-1/zod-mongoose")` instead.
+- **Public API is unchanged**: `zodSchema`, `zodSchemaRaw`, `extendZod`,
+  `zId`, `zUUID`, `.unique()`, `.sparse()`, `.ref()`, `.refPath()` all keep
+  their existing signatures.
+
+See [CHANGELOG.md](./CHANGELOG.md) for the full list of changes.
+
+## Quick start
+
+First, extend Zod with `extendZod`, then create your Zod schema:
+
+```typescript
+import { z } from "zod";
+import { extendZod, zId, zUUID } from "@parziva-1/zod-mongoose";
+
+extendZod(z);
+
+const zUser = z.object({
+  name: z.string().min(3).max(255),
+  age: z.number().min(18).max(100),
+  active: z.boolean().default(false),
+  access: z.enum(["admin", "user"]).default("user"),
+  companyId: zId("Company"),
+  wearable: zUUID(),
+  address: z.object({
+    street: z.string(),
+    city: z.string(),
+    state: z.enum(["CA", "NY", "TX"]),
+  }),
+  tags: z.array(z.string()),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+```
+
+Then convert it to a Mongoose schema and connect a model:
+
+```typescript
+import { zodSchema } from "@parziva-1/zod-mongoose";
+import { model } from "mongoose";
+
+const schema = zodSchema(zUser);
+const userModel = model("User", schema);
+```
+
+That's it - now use your Mongoose model as usual:
+
+```typescript
+userModel.find({ name: "John" });
+```
+
+> [!NOTE]
+> `extendZod` should be called once for the whole application.
+
+## Features
+
+See [SUPPORTED.md](./SUPPORTED.md) for the full, authoritative type/feature
+support matrix. Summary:
+
+- Basic types (string, number, boolean, date)
+- Nested objects, subdocuments, and arrays
+- Tuples (`z.tuple()`, including `.rest()`), stored as a length/type-validated
+  array
+- Enums and native (TypeScript) enums
+- Literals (`z.literal()`), including Zod v4's multi-value form
+- Discriminated unions (`z.discriminatedUnion()`)
+- Intersections (`z.intersection()`) of two object shapes, merged into one
+  flat sub-schema
+- Recursive / self-referencing schemas (`z.lazy()`)
+- Fallback values (`z.catch()`)
+- Default values (static and factory-function forms)
+- Maps and records (records become `Map`)
+- ObjectId and UUID, with `ref` / `refPath` support
+- `ZodAny` and `ZodUnknown` as `SchemaTypes.Mixed`
+- Validation via `.refine()` for String, Number, Date - including a
+  refinement applied both before *and* after a single `.transform()`
+- `.unique()` / `.sparse()` for String, Number, Date, ObjectId, and UUID
+- `.transform()` / `z.preprocess()`
+
+Known limitations: plain unions (`z.union()`) pick the first inner type
+(Mongoose has no native union type), and intersections only support merging
+two object-shape schemas - see [SUPPORTED.md](./SUPPORTED.md) for the full
+matrix and the design notes behind each non-obvious mapping (tuples,
+literals, discriminated unions, `z.lazy()`, `z.catch()`).
+
+## Checking schemas
+
+To make sure nothing is missing, inspect `Schema.obj`:
+
+```typescript
+// schema is a mongoose schema
+console.log(schema.obj);
+```
+
+## Raw object
+
+If you want the raw object produced from a Zod schema so you can modify it
+before constructing the `Schema`, use `zodSchemaRaw`:
+
+```typescript
+import { extendZod, zodSchemaRaw } from "@parziva-1/zod-mongoose";
+import { model, Schema } from "mongoose";
+import { z } from "zod";
+
+extendZod(z);
+
+const schema = zodSchemaRaw(zUser);
+schema.age.index = true;
+
+const userModel = model(
+  "User",
+  new Schema(schema, {
+    timestamps: true,
+  }),
+);
+```
+
+## ObjectID and UUID
+
+Use `zId(ref?: string)` and `zUUID(ref?: string)` to describe ObjectID and
+UUID fields, and to reference another collection:
+
+```typescript
+import { extendZod, zId, zUUID } from "@parziva-1/zod-mongoose";
+import { z } from "zod";
+
+extendZod(z);
+
+const zUser = z.object({
+  // Just the ID
+  someId: zId(),
+  wearable: zUUID(),
+
+  // With reference
+  companyId: zId("Company"), // equivalent to zId().ref("Company")
+  facilityId: zId().ref("Facility"),
+  device: zUUID("Device"), // equivalent to zUUID().ref("Device")
+  badgeId: zUUID().ref("Badge"),
+
+  // `refPath` support
+  storeId: zId().refPath("store"),
+  store: z.string(),
+  proxyId: zUUID().refPath("proxy"),
+  proxy: z.string(),
+});
+```
+
+## Validation
+
+Use Zod refinement to validate your Mongoose models:
+
+```typescript
+import { z } from "zod";
+import { extendZod, zodSchema } from "@parziva-1/zod-mongoose";
+
+extendZod(z);
+
+const zUser = z.object({
+  phone: z
+    .string()
+    .refine((v) => /^\d{3}-\d{3}-\d{4}$/.test(v), "Invalid phone number"),
+});
+```
+
+## Unique fields
+
+To make a String, Number, Date, ObjectId, or UUID field unique, call
+`.unique()`:
+
+```typescript
+const zUser = z.object({
+  phone: z.string().unique(),
+});
+```
+
+## Sparse fields
+
+To make a String, Number, Date, ObjectId, or UUID field sparse, call
+`.sparse()`:
+
+```typescript
+const zUser = z.object({
+  email: z.string().sparse(),
+  // combine with unique:
+  // email: z.string().unique().sparse(),
+});
+```
+
+## Warnings
+
+### ZodUnion types
+
+Plain unions are not supported by Mongoose. A union field is converted to its
+*first* inner type:
+
+```typescript
+const zUser = z.object({
+  access: z.union([z.string(), z.number()]),
+});
+
+// Becomes:
+// { access: { type: String } }
+```
+
+If you need every variant validated correctly, use `z.discriminatedUnion()`
+instead - see below.
+
+### ZodDiscriminatedUnion
+
+`z.discriminatedUnion()` maps to `SchemaTypes.Mixed`, validated by re-parsing
+the assigned value with the original discriminated-union schema itself
+(Mongoose has no native way to represent a discriminated shape on a plain
+nested field):
+
+```typescript
+const zEvent = z.object({
+  payload: z.discriminatedUnion("type", [
+    z.object({ type: z.literal("email"), address: z.string() }),
+    z.object({ type: z.literal("sms"), phone: z.string() }),
+  ]),
+});
+```
+
+### ZodTuple
+
+`z.tuple()` maps to a Mongoose array of `Mixed`, with a `validate` enforcing
+exact arity (or a minimum arity, if you used `.rest()`) and the correct type
+at each position:
+
+```typescript
+const zPoint = z.object({
+  coords: z.tuple([z.number(), z.number()]),
+});
+```
+
+### ZodIntersection
+
+`z.intersection()` is supported only when merging two object-shape schemas -
+the two shapes are flattened into one Mongoose sub-schema. Intersecting
+non-object schemas (e.g. `z.string().and(z.number())`) throws, since there's
+no sane flat-field representation for it.
+
+### ZodLazy
+
+`z.lazy()` supports recursive/self-referencing schemas (e.g. a comment with
+nested replies of the same shape) by unrolling the recursive getter up to a
+fixed depth (5 levels), then falling back to `Mixed` beyond that - Mongoose
+has no native concept of an infinitely recursive embedded subdocument.
+
+### ZodAny / ZodUnknown
+
+Both are converted to `SchemaTypes.Mixed`. Prefer a more specific type when
+possible.
+
+### ZodRecord
+
+`ZodRecord` is converted to `Map`. Prefer `z.map()` directly when possible.
+
+## Contributing
+
+Feel free to open issues and pull requests!
+
+- Fork the repository
+- Install the [Biome](https://biomejs.dev/) VS Code extension
+- Install dependencies: `npm install`
+- Make your changes
+- Run the full check suite: `npm run check` (lint, typecheck, test, build,
+  attw, publint)
+- Commit and push your changes
+- Open a pull request
+
+## License
+
+MIT - see [LICENSE](./LICENSE). Includes the original upstream copyright
+notice plus this fork's additions.

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+import { Schema, SchemaDefinition, SchemaOptions, SchemaTypeOptions, SchemaTypes, Types } from "mongoose";
+import { ZodObject, ZodRawShape, ZodType, z } from "zod";
+//#region src/mongoose.types.d.ts
+declare namespace zm {
+  interface zID extends z.ZodUnion<[z.ZodString, z.ZodType<Types.ObjectId, Types.ObjectId>]> {
+    __zm_type: "ObjectId";
+    __zm_ref?: string;
+    __zm_refPath?: string;
+    ref: (ref: string) => zID;
+    unique: (val?: boolean) => zID;
+    sparse: (val?: boolean) => zID;
+    refPath: (ref: string) => zID;
+  }
+  interface zUUID extends z.ZodUnion<[z.ZodString, z.ZodType<Types.UUID, Types.UUID>]> {
+    __zm_type: "UUID";
+    __zm_ref?: string;
+    __zm_refPath?: string;
+    unique: (val?: boolean) => zUUID;
+    sparse: (val?: boolean) => zUUID;
+    ref: (ref: string) => zUUID;
+    refPath: (ref: string) => zUUID;
+  }
+  type mDefault<T> = () => T;
+  interface _Field<T> {
+    required: boolean;
+    default?: mDefault<T>;
+    validate?: EffectValidator<T> | EffectValidator<T>[];
+    set?: (v: unknown) => T;
+  }
+  interface mString extends _Field<string> {
+    type: StringConstructor;
+    unique: boolean;
+    sparse: boolean;
+    enum?: string[];
+    match?: RegExp;
+    minLength?: number;
+    maxLength?: number;
+  }
+  interface mNumber extends _Field<number> {
+    type: NumberConstructor;
+    unique: boolean;
+    sparse: boolean;
+    min?: number;
+    max?: number;
+  }
+  interface mBoolean extends _Field<boolean> {
+    type: BooleanConstructor;
+  }
+  interface mDate extends _Field<Date> {
+    type: DateConstructor;
+    unique: boolean;
+    sparse: boolean;
+  }
+  interface mObjectId extends _Field<Types.ObjectId> {
+    type: typeof SchemaTypes.ObjectId;
+    unique?: boolean;
+    sparse?: boolean;
+    ref?: string;
+    refPath?: string;
+  }
+  interface mUUID extends _Field<Types.UUID> {
+    type: typeof SchemaTypes.UUID;
+    unique?: boolean;
+    sparse?: boolean;
+    ref?: string;
+    refPath?: string;
+  }
+  interface mArray<K> extends _Field<K[]> {
+    type: [_Field<K>];
+  }
+  interface mMixed<T> extends _Field<T> {
+    type: typeof SchemaTypes.Mixed;
+  }
+  type Constructor = StringConstructor | NumberConstructor | ObjectConstructor | DateConstructor | BooleanConstructor | BigIntConstructor | typeof SchemaTypes.ObjectId | typeof SchemaTypes.UUID;
+  interface mMap<T, K> extends _Field<Map<T, K>> {
+    type: typeof Map;
+    of?: zm._Field<K>;
+  }
+  interface mSubdocument<T> extends _Field<T> {
+    type: _Schema<T>;
+  }
+  type mField = mString | mNumber | mBoolean | mDate | mObjectId | mUUID | mMixed<unknown> | mArray<unknown> | _Schema<unknown> | mMap<unknown, unknown> | mSubdocument<unknown>;
+  type _Schema<T> = SchemaDefinition & { [K in keyof T]: (_Field<T[K]> & SchemaTypeOptions<T[K]>) | _Schema<T[K]>; };
+  type UnwrapZodType<T> = T extends ZodType<infer K> ? K : never;
+  type EffectValidator<T> = {
+    validator: (v: T) => boolean;
+    message?: string;
+  };
+  /**
+   * A field's `validate` option accepts either a single validator (the
+   * common case) or an array of them - Mongoose runs every entry in the
+   * array and reports all failing messages. Used when a field carries more
+   * than one `.refine()` check (e.g. one before and one after a
+   * `.transform()`).
+   */
+  type mValidate<T> = EffectValidator<T> | EffectValidator<T>[];
+}
+//#endregion
+//#region src/extension.d.ts
+declare module "zod" {
+  interface ZodString {
+    unique: (arg?: boolean) => ZodString;
+    sparse: (arg?: boolean) => ZodString;
+  }
+  interface ZodNumber {
+    unique: (arg?: boolean) => ZodNumber;
+    sparse: (arg?: boolean) => ZodNumber;
+  }
+  interface ZodDate {
+    unique: (arg?: boolean) => ZodDate;
+    sparse: (arg?: boolean) => ZodDate;
+  }
+  interface ZodType {
+    __zm_type?: string;
+    __zm_ref?: string;
+    __zm_refPath?: string;
+  }
+}
+/**
+ * Extends the Zod library with additional functionality.
+ *
+ * This function modifies the Zod library to add custom mongoose-specific
+ * metadata methods. It ensures that the extension is only applied once.
+ *
+ * @param z_0 - The Zod library to extend.
+ *
+ * @remarks
+ * - Adds a `unique` method to `ZodString`, `ZodNumber`, and `ZodDate` to mark them as unique.
+ * - Adds a `sparse` method to `ZodString`, `ZodNumber`, and `ZodDate` to mark them as sparse.
+ *
+ * As of Zod v4, refinement metadata (validator + message) no longer needs to
+ * be captured via a `refine()` override: Zod's own internal `checks` array
+ * already exposes the validator function and error message directly, so
+ * `zodSchema()` reads that straight off the schema instead.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { extendZod } from "./extension";
+ *
+ * extendZod(z);
+ *
+ * const schema = z.object({
+ *   name: z.string().unique();
+ * });
+ * ```
+ */
+declare function extendZod(z_0: typeof z): void;
+type TzmId = ReturnType<typeof createId> & {
+  unique: (arg?: boolean) => TzmId;
+  sparse: (arg?: boolean) => TzmId;
+  ref: (arg: string) => TzmId;
+  refPath: (arg: string) => TzmId;
+};
+declare const createId: () => z.ZodUnion<[z.ZodString, z.ZodCustom<Types.ObjectId, Types.ObjectId>]>;
+declare const zId: (ref?: string) => TzmId;
+type TzmUUID = ReturnType<typeof createUUID> & {
+  unique: (arg?: boolean) => TzmUUID;
+  sparse: (arg?: boolean) => TzmUUID;
+  ref: (arg: string) => TzmUUID;
+  refPath: (arg: string) => TzmUUID;
+};
+declare const createUUID: () => z.ZodUnion<[z.ZodString, z.ZodCustom<Types.UUID, Types.UUID>]>;
+declare const zUUID$1: (ref?: string) => TzmUUID;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Converts a Zod schema to a Mongoose schema
+ * @param schema zod schema to parse
+ * @returns mongoose schema
+ *
+ * @example
+ * import { extendZod, zodSchema } from '@zodyac/zod-mongoose';
+ * import { model } from 'mongoose';
+ * import { z } from 'zod';
+ *
+ * extendZod(z);
+ *
+ * const zUser = z.object({
+ *   name: z.string().min(3).max(255),
+ *   age: z.number().min(18).max(100),
+ *   active: z.boolean().default(false),
+ *   access: z.enum(['admin', 'user']).default('user'),
+ *   companyId: zId('Company'),
+ *   address: z.object({
+ *     street: z.string(),
+ *     city: z.string(),
+ *     state: z.enum(['CA', 'NY', 'TX']),
+ *   }),
+ *   tags: z.array(z.string()),
+ *   createdAt: z.date(),
+ *   updatedAt: z.date(),
+ * });
+ *
+ * const schema = zodSchema(zDoc);
+ * const userModel = model('User', schema);
+ */
+declare function zodSchema<T extends ZodRawShape>(schema: ZodObject<T>, options?: SchemaOptions<any>): Schema<z.infer<typeof schema>>;
+/**
+ * Converts a Zod schema to a raw Mongoose schema object
+ * @param schema zod schema to parse
+ * @returns mongoose schema
+ *
+ * @example
+ * import { extendZod, zodSchemaRaw } from '@zodyac/zod-mongoose';
+ * import { model, Schema } from 'mongoose';
+ * import { z } from 'zod';
+ *
+ * extendZod(z);
+ *
+ * const zUser = z.object({
+ *   name: z.string().min(3).max(255),
+ *   age: z.number().min(18).max(100),
+ *   active: z.boolean().default(false),
+ *   access: z.enum(['admin', 'user']).default('user'),
+ *   companyId: zId('Company'),
+ *   address: z.object({
+ *    street: z.string(),
+ *    city: z.string(),
+ *    state: z.enum(['CA', 'NY', 'TX']),
+ *   }),
+ *  tags: z.array(z.string()),
+ *  createdAt: z.date(),
+ *  updatedAt: z.date(),
+ * });
+ *
+ * const rawSchema = zodSchemaRaw(zDoc);
+ * const schema = new Schema(rawSchema);
+ * const userModel = model('User', schema);
+ */
+declare function zodSchemaRaw<T extends ZodRawShape>(schema: ZodObject<T>): zm._Schema<T>;
+//#endregion
+export { TzmId, TzmUUID, zodSchema as default, zodSchema, extendZod, zId, zUUID$1 as zUUID, zodSchemaRaw };
+//# sourceMappingURL=index.d.ts.map