@zodmon/core 0.0.0 → 0.2.0

package/dist/index.d.cts

@@ -1,2 +1,492 @@
+import { ZodPipe, ZodCustom, ZodTransform, z } from 'zod';
+import { ObjectId } from 'mongodb';
 
-export {  }
+/**
+ * Options controlling how a field-level MongoDB index is created.
+ *
+ * Passed to the `.index()` Zod extension method. Every property is optional;
+ * omitting all of them creates a standard ascending, non-unique index.
+ */
+type IndexOptions = {
+    /** When `true`, MongoDB enforces a unique constraint on this field. */
+    unique?: boolean;
+    /**
+     * When `true`, the index skips documents where the field is `null` or missing.
+     * Useful for optional fields that should be indexed only when present.
+     */
+    sparse?: boolean;
+    /** When `true`, creates a MongoDB text index for full-text search on this field. */
+    text?: boolean;
+    /**
+     * When `true`, the index is created in descending order (`-1`).
+     * Defaults to ascending (`1`) when omitted.
+     */
+    descending?: boolean;
+    /**
+     * TTL in seconds. MongoDB will automatically delete documents once the
+     * indexed `Date` field is older than this many seconds. Only valid on
+     * fields whose runtime type is `Date`.
+     */
+    expireAfter?: number;
+    /**
+     * A partial filter expression. Only documents matching this filter are
+     * included in the index. Maps directly to MongoDB's `partialFilterExpression`.
+     */
+    partial?: Record<string, unknown>;
+};
+/**
+ * Metadata stored in the WeakMap sidecar for every schema that has been
+ * marked with `.index()`. Always contains `indexed: true` plus any
+ * {@link IndexOptions} the caller provided.
+ */
+type IndexMetadata = {
+    /** Always `true` — acts as a discriminator for "this field is indexed". */
+    indexed: true;
+} & IndexOptions;
+declare module 'zod' {
+    interface ZodType {
+        /**
+         * Mark this field for indexing when `syncIndexes()` is called.
+         *
+         * Stores {@link IndexOptions} in a WeakMap sidecar so the collection
+         * factory can later introspect each field and build the appropriate
+         * MongoDB index specification.
+         *
+         * @param options - Optional index configuration (unique, sparse, etc.).
+         * @returns The same schema instance for chaining.
+         *
+         * @example
+         * ```ts
+         * const UserSchema = z.object({
+         *   email: z.string().index({ unique: true }),
+         *   age: z.number().index({ sparse: true }),
+         * })
+         * ```
+         */
+        index(options?: IndexOptions): this;
+        /**
+         * Shorthand for `.index({ unique: true })`.
+         *
+         * Creates a unique index on this field, causing MongoDB to reject
+         * duplicate values.
+         *
+         * @returns The same schema instance for chaining.
+         *
+         * @example
+         * ```ts
+         * const UserSchema = z.object({
+         *   email: z.string().unique(),
+         * })
+         * ```
+         */
+        unique(): this;
+        /**
+         * Shorthand for `.index({ text: true })`.
+         *
+         * Creates a MongoDB text index on this field, enabling `$text` queries
+         * for full-text search.
+         *
+         * @returns The same schema instance for chaining.
+         *
+         * @example
+         * ```ts
+         * const PostSchema = z.object({
+         *   body: z.string().text(),
+         * })
+         * ```
+         */
+        text(): this;
+        /**
+         * Shorthand for `.index({ expireAfter: seconds })`.
+         *
+         * Creates a TTL (Time-To-Live) index. MongoDB will automatically
+         * remove documents once the indexed `Date` field is older than
+         * the specified number of seconds.
+         *
+         * @param seconds - Number of seconds after which documents expire.
+         * @returns The same schema instance for chaining.
+         *
+         * @example
+         * ```ts
+         * const SessionSchema = z.object({
+         *   createdAt: z.date().expireAfter(3600), // 1 hour TTL
+         * })
+         * ```
+         */
+        expireAfter(seconds: number): this;
+    }
+}
+/**
+ * Retrieve the index metadata attached to a Zod schema, if any.
+ *
+ * Returns `undefined` when the schema was never marked with an index
+ * extension (`.index()`, `.unique()`, `.text()`, or `.expireAfter()`).
+ *
+ * @param schema - The Zod schema to inspect. Accepts `unknown` for
+ *   convenience; non-object values safely return `undefined`.
+ * @returns The {@link IndexMetadata} for the schema, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * const email = z.string().index({ unique: true })
+ * const meta = getIndexMetadata(email)
+ * // => { indexed: true, unique: true }
+ * ```
+ */
+declare function getIndexMetadata(schema: unknown): IndexMetadata | undefined;
+/**
+ * Monkey-patch Zod's `ZodType.prototype` with Zodmon extension methods
+ * (`.index()`, `.unique()`, `.text()`, `.expireAfter()`).
+ *
+ * In Zod v4, methods are copied from `ZodType.prototype` to each instance
+ * during construction via the internal `init` loop (`Object.keys(proto)` ->
+ * copy to instance). Extension methods use `enumerable: true` so they are
+ * picked up by this loop for every schema created after installation.
+ *
+ * The function is idempotent: calling it more than once is a safe no-op,
+ * guarded by a non-enumerable `Symbol.for('zodmon_extensions')` property
+ * on the prototype.
+ *
+ * This function is called at module level when `extensions.ts` is first
+ * imported, so consumers never need to call it manually. It is exported
+ * primarily for use in tests.
+ *
+ * @example
+ * ```ts
+ * import { installExtensions } from '@zodmon/core/schema/extensions'
+ * installExtensions() // safe to call multiple times
+ *
+ * const indexed = z.string().index({ unique: true })
+ * ```
+ */
+declare function installExtensions(): void;
+
+/**
+ * The Zod type produced by {@link objectId}. A pipeline that validates an
+ * input as either a `string` (24-char hex) or an `ObjectId` instance, then
+ * transforms it into a concrete `ObjectId`.
+ *
+ * Use `z.infer<ZodObjectId>` to extract the output type (`ObjectId`) and
+ * `z.input<ZodObjectId>` for the input type (`string | ObjectId`).
+ */
+type ZodObjectId = ZodPipe<ZodCustom<string | ObjectId, string | ObjectId>, ZodTransform<ObjectId, string | ObjectId>>;
+/**
+ * Create a Zod schema that validates and coerces values into MongoDB
+ * `ObjectId` instances.
+ *
+ * Accepts either:
+ * - An existing `ObjectId` instance (passed through unchanged).
+ * - A 24-character hexadecimal string (coerced to `ObjectId`).
+ *
+ * All other inputs are rejected with the message `"Invalid ObjectId"`.
+ *
+ * @returns A {@link ZodObjectId} schema.
+ *
+ * @example
+ * ```ts
+ * const schema = objectId()
+ *
+ * schema.parse(new ObjectId())                     // OK — pass-through
+ * schema.parse('64f1a2b3c4d5e6f7a8b9c0d1')        // OK — coerced to ObjectId
+ * schema.parse('not-valid')                        // throws ZodError
+ * ```
+ *
+ * @example Inside a z.object() shape:
+ * ```ts
+ * const UserSchema = z.object({
+ *   _id: objectId(),
+ *   name: z.string(),
+ * })
+ * ```
+ */
+declare function objectId(): ZodObjectId;
+
+/**
+ * A compound index definition declared at the collection level.
+ * Maps field paths to sort direction (1 ascending, -1 descending)
+ * with optional index-level configuration.
+ *
+ * Generic over `TKeys` so that only fields present in the collection
+ * schema are accepted — referencing a nonexistent field is a type error.
+ */
+type CompoundIndexDefinition<TKeys extends string = string> = {
+    fields: Partial<Record<TKeys, 1 | -1>>;
+    options?: {
+        unique?: boolean;
+        sparse?: boolean;
+        partial?: Record<string, unknown>;
+        name?: string;
+    };
+};
+/**
+ * A resolved field-level index extracted from schema metadata.
+ * Produced by walking the shape and calling getIndexMetadata() on each field.
+ */
+type FieldIndexDefinition = {
+    field: string;
+} & IndexOptions;
+/** Options passed to collection() as the third argument. */
+type CollectionOptions<TKeys extends string = string> = {
+    indexes?: CompoundIndexDefinition<TKeys>[];
+    validation?: 'strict' | 'strip' | 'passthrough';
+    warnUnindexedQueries?: boolean;
+    schemaVersion?: number;
+    migrate?: (doc: Record<string, unknown>, version: number) => Record<string, unknown>;
+    writeback?: boolean;
+};
+/**
+ * Resolves the final shape for a collection schema.
+ *
+ * If the user-provided shape already contains `_id`, it is used as-is.
+ * Otherwise, `_id: ZodObjectId` is prepended automatically.
+ * This allows custom id types (nanoid, UUID, etc.) when needed.
+ */
+type ResolvedShape<TShape extends z.core.$ZodShape> = '_id' extends keyof TShape ? TShape : {
+    _id: ZodObjectId;
+} & TShape;
+/**
+ * The document type inferred from a collection definition.
+ * Uses the compiled schema directly, so it reflects whatever `_id`
+ * type was provided (custom or default ObjectId).
+ *
+ * Uses a structural constraint (`{ schema: z.ZodType }`) instead of
+ * `CollectionDefinition<z.core.$ZodShape>` because the conditional
+ * `ResolvedShape` type creates variance issues with index signatures.
+ */
+type InferDocument<TDef extends {
+    readonly schema: z.ZodType;
+}> = z.infer<TDef['schema']>;
+/**
+ * The immutable definition object returned by collection().
+ * Holds everything needed to later create a live collection handle.
+ */
+type CollectionDefinition<TShape extends z.core.$ZodShape = z.core.$ZodShape> = {
+    readonly name: string;
+    readonly schema: z.ZodObject<ResolvedShape<TShape>>;
+    readonly shape: TShape;
+    readonly fieldIndexes: FieldIndexDefinition[];
+    readonly compoundIndexes: CompoundIndexDefinition<Extract<keyof TShape, string>>[];
+    readonly options: Required<Pick<CollectionOptions, 'validation'>> & Omit<CollectionOptions, 'indexes' | 'validation'>;
+};
+/** Erased collection type for use in generic contexts. */
+type AnyCollection = CollectionDefinition<z.core.$ZodShape>;
+
+/**
+ * Walk a Zod shape and extract field-level index metadata from each field.
+ *
+ * Returns an array of {@link FieldIndexDefinition} for every field that has
+ * been marked with `.index()`, `.unique()`, `.text()`, or `.expireAfter()`.
+ * Fields without index metadata are silently skipped.
+ *
+ * @param shape - A Zod shape object (the value passed to `z.object()`).
+ * @returns An array of field index definitions with the field name attached.
+ */
+declare function extractFieldIndexes(shape: z.core.$ZodShape): FieldIndexDefinition[];
+/**
+ * Define a MongoDB collection with a Zod schema.
+ *
+ * Creates a {@link CollectionDefinition} that:
+ * - Adds `_id: objectId()` if the shape doesn't already include `_id`
+ * - Uses the user-provided `_id` schema if one is present (e.g. nanoid, UUID)
+ * - Extracts field-level index metadata from the shape
+ * - Separates compound indexes from the rest of the options
+ * - Returns an immutable definition object
+ *
+ * @param name - The MongoDB collection name.
+ * @param shape - A Zod shape object defining the document fields. May include a custom `_id`.
+ * @param options - Optional collection-level configuration including compound indexes.
+ * @returns A {@link CollectionDefinition} ready for use with `createClient()`.
+ *
+ * @example
+ * ```ts
+ * const Users = collection('users', {
+ *   email: z.string().unique(),
+ *   name: z.string().index(),
+ *   age: z.number().optional(),
+ * })
+ * ```
+ */
+declare function collection<TShape extends z.core.$ZodShape>(name: string, shape: TShape, options?: CollectionOptions<Extract<keyof TShape, string>>): CollectionDefinition<TShape>;
+
+/**
+ * A builder for compound index definitions.
+ *
+ * Provides a fluent API for declaring compound indexes with options like
+ * `unique`, `sparse`, and custom `name`. Each method returns a new
+ * IndexBuilder instance (immutable pattern — the original is never mutated).
+ *
+ * IndexBuilder is structurally compatible with {@link CompoundIndexDefinition}
+ * so instances can be used directly in `CollectionOptions.indexes`.
+ *
+ * Dot-notation paths like `'address.city'` are accepted at the value level
+ * (any string satisfies `TKeys`), but type-level validation against nested
+ * schema paths is deferred to a future release.
+ *
+ * @example
+ * ```ts
+ * index({ email: 1, role: -1 }).unique().name('email_role_idx')
+ * ```
+ */
+
+type IndexDirection = 1 | -1;
+type CompoundIndexOptions = NonNullable<CompoundIndexDefinition['options']>;
+declare class IndexBuilder<TKeys extends string> {
+    readonly fields: Partial<Record<TKeys, IndexDirection>>;
+    readonly options: CompoundIndexOptions;
+    constructor(fields: Record<TKeys, IndexDirection>);
+    private _clone;
+    unique(): IndexBuilder<TKeys>;
+    sparse(): IndexBuilder<TKeys>;
+    name(name: string): IndexBuilder<TKeys>;
+}
+/**
+ * Create a compound index definition with a fluent builder API.
+ *
+ * Returns an {@link IndexBuilder} that is structurally compatible with
+ * `CompoundIndexDefinition`, so it can be used directly in
+ * `CollectionOptions.indexes` alongside plain objects.
+ *
+ * @param fields - An object mapping field names to sort direction (1 or -1).
+ * @returns An {@link IndexBuilder} instance.
+ *
+ * @example
+ * ```ts
+ * collection('users', { email: z.string(), role: z.string() }, {
+ *   indexes: [
+ *     index({ email: 1, role: -1 }).unique(),
+ *     { fields: { role: 1 } },
+ *   ],
+ * })
+ * ```
+ */
+declare function index<TKeys extends string>(fields: Record<TKeys, IndexDirection>): IndexBuilder<TKeys>;
+
+/**
+ * Create or coerce a MongoDB `ObjectId`.
+ *
+ * - Called with **no arguments**: generates a brand-new `ObjectId`.
+ * - Called with a **hex string**: coerces it to an `ObjectId` via
+ *   `ObjectId.createFromHexString`.
+ * - Called with an **existing `ObjectId`**: returns it unchanged.
+ *
+ * This is a convenience wrapper that removes the need for `new ObjectId()`
+ * boilerplate throughout application code.
+ *
+ * @param value - Optional hex string or `ObjectId` to coerce. Omit to
+ *   generate a new `ObjectId`.
+ * @returns An `ObjectId` instance.
+ *
+ * @example
+ * ```ts
+ * oid()                                      // new random ObjectId
+ * oid('64f1a2b3c4d5e6f7a8b9c0d1')           // coerce hex string
+ * oid(existingId)                            // pass-through
+ * ```
+ */
+declare function oid(): ObjectId;
+declare function oid(value: string): ObjectId;
+declare function oid(value: ObjectId): ObjectId;
+/**
+ * Type guard that narrows an `unknown` value to `ObjectId`.
+ *
+ * Uses `instanceof` internally, so it works with any value without risk
+ * of throwing.
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is an `ObjectId` instance.
+ *
+ * @example
+ * ```ts
+ * const raw: unknown = getFromDb()
+ * if (isOid(raw)) {
+ *   console.log(raw.toHexString()) // raw is narrowed to ObjectId
+ * }
+ * ```
+ */
+declare function isOid(value: unknown): value is ObjectId;
+
+/**
+ * Type-level marker that carries the target collection type through the
+ * type system. Intersected with the schema return type by `.ref()` so
+ * that `RefFields<T>` (future) can extract ref relationships.
+ *
+ * This is a phantom brand — no runtime value has this property.
+ */
+type RefMarker<TCollection extends AnyCollection = AnyCollection> = {
+    readonly _ref: TCollection;
+};
+/**
+ * Metadata stored in the WeakMap sidecar for schemas marked with `.ref()`.
+ * Holds a reference to the target collection definition object.
+ */
+type RefMetadata = {
+    readonly collection: AnyCollection;
+};
+/**
+ * Module augmentation: adds `.ref()` to all `ZodType` schemas.
+ *
+ * The intersection constraint `this['_zod']['output'] extends InferDocument<TCollection>['_id']`
+ * ensures compile-time type safety: the field's output type must match the
+ * target collection's `_id` type. Mismatches produce a type error.
+ *
+ * Supports both default ObjectId `_id` and custom `_id` types (string, nanoid, etc.):
+ * - `objectId().ref(Users)` compiles when Users has ObjectId `_id`
+ * - `z.string().ref(Orgs)` compiles when Orgs has string `_id`
+ * - `z.string().ref(Users)` is a type error (string ≠ ObjectId)
+ * - `objectId().ref(Orgs)` is a type error (ObjectId ≠ string)
+ */
+declare module 'zod' {
+    interface ZodType {
+        /**
+         * Declare a typed foreign key reference to another collection.
+         *
+         * Stores the target collection definition in metadata for runtime
+         * populate resolution, and brands the return type with
+         * `RefMarker<TCollection>` so `RefFields<T>` can extract refs
+         * at the type level.
+         *
+         * The field's output type must match the target collection's `_id` type.
+         * Mismatched types produce a compile error.
+         *
+         * Apply `.ref()` before wrapper methods like `.optional()` or `.nullable()`:
+         * `objectId().ref(Users).optional()` — not `objectId().optional().ref(Users)`.
+         *
+         * @param collection - The target collection definition object.
+         * @returns The same schema instance, branded with the ref marker.
+         *
+         * @example
+         * ```ts
+         * const Posts = collection('posts', {
+         *   authorId: objectId().ref(Users),
+         *   title: z.string(),
+         * })
+         * ```
+         */
+        ref<TCollection extends AnyCollection>(collection: TCollection & (this['_zod']['output'] extends InferDocument<TCollection>['_id'] ? unknown : never)): this & RefMarker<TCollection>;
+    }
+}
+/**
+ * Retrieve the ref metadata attached to a Zod schema, if any.
+ *
+ * Returns `undefined` when the schema was never marked with `.ref()`.
+ *
+ * @param schema - The Zod schema to inspect. Accepts `unknown` for
+ *   convenience; non-object values safely return `undefined`.
+ * @returns The {@link RefMetadata} for the schema, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * const authorId = objectId().ref(Users)
+ * const meta = getRefMetadata(authorId)
+ * // => { collection: Users }
+ * ```
+ */
+declare function getRefMetadata(schema: unknown): RefMetadata | undefined;
+/**
+ * Install the `.ref()` extension method on `ZodType.prototype`.
+ *
+ * Idempotent — safe to call multiple times.
+ */
+declare function installRefExtension(): void;
+
+export { type AnyCollection, type CollectionDefinition, type CollectionOptions, type CompoundIndexDefinition, type FieldIndexDefinition, IndexBuilder, type IndexMetadata, type IndexOptions, type InferDocument, type RefMarker, type RefMetadata, type ResolvedShape, type ZodObjectId, collection, extractFieldIndexes, getIndexMetadata, getRefMetadata, index, installExtensions, installRefExtension, isOid, objectId, oid };