@mongorm/orm 0.1.1-beta.4 → 0.1.1

package/dist/index.d.mts

@@ -1,5 +1,171 @@
 import { Collection, Condition, Db as Db$1, DeleteResult, Document, FindCursor, IndexDescription, IndexDirection, MongoClientOptions, ObjectId, ObjectId as ObjectId$1, RootFilterOperators, WithId } from "mongodb";
 import { z } from "zod";
+//#region src/schema/scalars.d.ts
+declare module 'zod' {
+  interface ZodType {
+    hidden(): this & {
+      readonly __hidden: true;
+    };
+  }
+}
+/** A schema field that can be marked as hidden from default query results. */
+type HiddenCapable<T extends z.ZodType> = Omit<T, 'optional' | 'nullable' | 'nullish'> & HiddenMethods<T>;
+/** A schema field marked as hidden from default query results. */
+type HiddenSchema<T extends z.ZodType> = Omit<T, 'optional' | 'nullable' | 'nullish'> & HiddenMethods<T> & {
+  readonly __hidden: true;
+};
+type HiddenMethods<T extends z.ZodType> = {
+  hidden(): HiddenSchema<T>;
+  optional(): HiddenCapable<z.ZodOptional<T>>;
+  nullable(): HiddenCapable<z.ZodNullable<T>>;
+  nullish(): HiddenCapable<z.ZodOptional<z.ZodNullable<T>>>;
+};
+/** Create a MongoDB ObjectId schema. */
+declare const objectId: () => HiddenCapable<z.ZodInstanceOf<ObjectId$1>>;
+//#endregion
+//#region src/schema/options.d.ts
+/** Built-in persistence behavior applied by a schema. */
+interface SchemaOptions {
+  readonly timestamps?: boolean;
+  readonly softdelete?: boolean;
+  /** Hide Mongorm-managed fields from default query results. */
+  readonly hideManaged?: boolean;
+}
+type ManagedSchema<Field extends z.ZodType, Options extends SchemaOptions> = Options['hideManaged'] extends true ? HiddenSchema<Field> : Field;
+type TimestampShape<Options extends SchemaOptions> = {
+  createdAt: ManagedSchema<z.ZodDefault<z.ZodDate>, Options>;
+  updatedAt: ManagedSchema<z.ZodDefault<z.ZodDate>, Options>;
+};
+type SoftDeleteShape<Options extends SchemaOptions> = {
+  deletedAt: ManagedSchema<z.ZodDefault<z.ZodNullable<z.ZodDate>>, Options>;
+};
+type ManagedShape<Options extends SchemaOptions> = (Options['timestamps'] extends true ? TimestampShape<Options> : {}) & (Options['softdelete'] extends true ? SoftDeleteShape<Options> : {});
+type ManagedField<Options extends SchemaOptions> = (Options['timestamps'] extends true ? 'createdAt' | 'updatedAt' : never) | (Options['softdelete'] extends true ? 'deletedAt' : never);
+type SoftDeleteEnabled<Options extends SchemaOptions> = Options['softdelete'] extends true ? true : false;
+export declare const hasSoftDelete: (options: SchemaOptions) => boolean;
+//#endregion
+//#region src/schema/contracts.d.ts
+/** A Zod object shape used as the source of truth for a model. */
+type SchemaShape = z.ZodRawShape;
+/** The runtime Zod object generated from a schema shape. */
+type SchemaDefinition<Shape extends SchemaShape> = z.ZodObject<Shape>;
+/** Population scopes keyed by scope name. */
+type ScopeDefinitions = Record<string, readonly object[]>;
+//#endregion
+//#region src/query/cursor/cursor.d.ts
+/** A lazy async iterable for one cursor-pagination page. */
+export declare class ModelCursor<Shape extends SchemaShape, Result extends object> implements AsyncIterable<Result> {
+  private readonly open;
+  private readonly pageSize;
+  private readonly transform?;
+  next: ObjectId$1 | null;
+  constructor(open: () => FindCursor<WithId<StoredDocument<Shape>>>, pageSize: number, transform?: ((documents: Result[]) => Promise<Result[]>) | undefined);
+  [Symbol.asyncIterator](): AsyncGenerator<Result>;
+}
+//#endregion
+//#region src/query/types/document.d.ts
+/** Persisted data inferred from a schema, including MongoDB's generated identifier. */
+type ModelDocument<Shape extends SchemaShape> = z.output<SchemaDefinition<Shape>> & {
+  _id: ObjectId$1;
+};
+/** Document type passed to MongoDB's collection APIs. */
+type StoredDocument<Shape extends SchemaShape> = ModelDocument<Shape> & Document;
+type HiddenKey<Shape extends SchemaShape> = { [Key in keyof Shape]: Shape[Key] extends {
+  readonly __hidden: true;
+} ? Key : never; }[keyof Shape];
+type HiddenDocumentKey<Shape extends SchemaShape> = Extract<HiddenKey<Shape>, keyof ModelDocument<Shape>> & string;
+/** Fields exposed by an unprojected model query. */
+type VisibleDocument<Shape extends SchemaShape> = Omit<ModelDocument<Shape>, Extract<HiddenKey<Shape>, keyof ModelDocument<Shape>>>;
+type CursorMethod<Shape extends SchemaShape, Result extends object, Ready extends boolean> = Ready extends true ? (after?: ObjectId$1) => ModelCursor<Shape, Result> : undefined;
+//#endregion
+//#region src/query/types/filter.d.ts
+type NestedFilterKey<Value, Prefix extends string = ''> = Value extends object ? Value extends ObjectId$1 | Date | readonly unknown[] ? never : { [Key in Extract<keyof Value, string>]: NonNullable<Value[Key]> extends object ? `${Prefix}${Key}` | `${Prefix}${Key}.${NestedFilterKey<NonNullable<Value[Key]>>}` : `${Prefix}${Key}`; }[Extract<keyof Value, string>] : never;
+type NestedFilterValue<Value, Path extends string> = Path extends `${infer Head}.${infer Tail}` ? Head extends keyof Value ? NestedFilterValue<NonNullable<Value[Head]>, Tail> : never : Path extends keyof Value ? Value[Path] : never;
+type FilterForDocument<DocumentShape extends Document, FieldShape extends object> = Partial<{ [Key in keyof FieldShape]: Condition<FieldShape[Key]>; }> & Partial<{ [Path in NestedFilterKey<FieldShape>]: Condition<NestedFilterValue<FieldShape, Path>>; }> & Partial<Pick<RootFilterOperators<DocumentShape>, '$comment' | '$expr' | '$jsonSchema' | '$text' | '$where'>> & {
+  $and?: FilterForDocument<DocumentShape, FieldShape>[];
+  $nor?: FilterForDocument<DocumentShape, FieldShape>[];
+  $or?: FilterForDocument<DocumentShape, FieldShape>[];
+};
+/** Schema-checked MongoDB filters, including nested dot-notation paths. */
+type ModelFilter<Shape extends SchemaShape> = FilterForDocument<StoredDocument<Shape>, ModelDocument<Shape>>;
+/** MongoDB sort directions supported by the model query API. */
+type SortDirection = 'asc' | 'desc';
+/** Schema-checked sort specifications. */
+type ModelSort<Shape extends SchemaShape> = Partial<Record<Extract<keyof ModelDocument<Shape>, string>, SortDirection>>;
+//#endregion
+//#region src/query/types/utils.d.ts
+/** Flatten mapped and intersection types to make editor hints easier to read. */
+type Simplify<Value> = { [Key in keyof Value]: Value[Key]; };
+/** Convert a union into an intersection when merging selected field paths. */
+type UnionToIntersection<Value> = (Value extends unknown ? (input: Value) => void : never) extends ((input: infer Intersection) => void) ? Intersection : never;
+//#endregion
+//#region src/query/types/selection.d.ts
+type NestedDocumentKeys<Value> = Value extends object ? Value extends ObjectId$1 | Date ? never : { [Key in Extract<keyof Value, string>]: NonNullable<Value[Key]> extends object ? Key | `${Key}.${NestedDocumentKeys<NonNullable<Value[Key]>>}` : Key; }[Extract<keyof Value, string>] : never;
+type NestedSelectableKey<Shape extends SchemaShape> = { [Key in Extract<keyof Shape, string>]: Key extends keyof ModelDocument<Shape> ? NonNullable<ModelDocument<Shape>[Key]> extends object ? `${Key}.${NestedDocumentKeys<NonNullable<ModelDocument<Shape>[Key]>>}` : never : never; }[Extract<keyof Shape, string>];
+/** Field paths accepted by `.select()`. */
+type SelectableKey<Shape extends SchemaShape> = Exclude<Extract<keyof ModelDocument<Shape>, string>, '_id' | HiddenDocumentKey<Shape>> | NestedSelectableKey<Shape>;
+type PathSelection<Value, Path extends string> = Path extends `${infer Head}.${infer Tail}` ? Head extends keyof Value ? { [Key in Head]: PathSelection<NonNullable<Value[Head]>, Tail>; } : never : Path extends keyof Value ? Pick<Value, Path> : never;
+/** Projected result type that preserves the structure of selected nested paths. */
+type SelectedDocument<Shape extends SchemaShape, Key extends SelectableKey<Shape>> = [Key] extends [never] ? VisibleDocument<Shape> : Simplify<Pick<ModelDocument<Shape>, '_id'> & UnionToIntersection<PathSelection<ModelDocument<Shape>, Extract<Key, string>>>>;
+//#endregion
+//#region src/query/population/types.d.ts
+type RelationTarget<Relation> = Relation extends {
+  resolve: () => infer Target;
+} ? Target : never;
+type RelationDocument<Relation> = Infer<RelationTarget<Relation>>;
+type RelationMapOf$1<Relation> = Relation extends {
+  readonly __targetRelations?: infer Relations;
+} ? NonNullable<Relations> extends SchemaRelationMap ? NonNullable<Relations> : {} : RelationTarget<Relation> extends {
+  readonly relationMap: infer TargetRelations;
+} ? TargetRelations extends SchemaRelationMap ? TargetRelations : {} : {};
+type RelationSelect<Relation> = RelationTarget<Relation> extends Schema<infer TargetShape, any> ? Exclude<SelectableKey<TargetShape>, '_id'> : never;
+type ScopeName<Scopes> = Extract<keyof Scopes, string>;
+type PopulationMode = 'none' | 'populate' | 'scope';
+/** A typed description of one declared relation to load. */
+type PopulateSpec<Relations extends SchemaRelationMap> = { [Name in Extract<keyof Relations, string>]: {
+  ref: Name;
+  select?: readonly RelationSelect<Relations[Name]>[];
+  populate?: PopulateSpecs<RelationMapOf$1<Relations[Name]>>;
+}; }[Extract<keyof Relations, string>];
+/** A list of relation-population specifications. */
+type PopulateSpecs<Relations extends SchemaRelationMap> = readonly PopulateSpec<Relations>[];
+/** Query result after replacing relation IDs with populated documents. */
+type PopulatedResult<Result extends object, Relations extends SchemaRelationMap, Specs extends PopulateSpecs<Relations>> = Simplify<Omit<Result, Extract<Specs[number]['ref'], keyof Result>> & { [Spec in Specs[number] as Spec['ref']]: PopulatedRelation<Relations[Spec['ref']], Spec> | null; }>;
+type PopulatedRelation<Relation, Spec> = Spec extends {
+  populate: infer Nested extends PopulateSpecs<RelationMapOf$1<Relation>>;
+} ? RelationDocument<Relation> extends (infer PopulatedDocument extends object) ? PopulatedResult<PopulatedDocument, RelationMapOf$1<Relation>, Nested> : never : RelationDocument<Relation>;
+//#endregion
+//#region src/schema/indexes.d.ts
+type IndexFieldMap<Shape extends SchemaShape> = Record<Extract<keyof Shape, string>, IndexDirection>;
+/** Non-empty, schema-checked MongoDB index keys. */
+type SchemaIndexFields<Shape extends SchemaShape> = { [Key in keyof IndexFieldMap<Shape>]: Pick<IndexFieldMap<Shape>, Key> & Partial<Omit<IndexFieldMap<Shape>, Key>>; }[keyof IndexFieldMap<Shape>];
+/** Partial-index filter restricted to this schema's fields and operators. */
+type SchemaPartialFilter<Shape extends SchemaShape> = ModelFilter<Shape>;
+type SchemaIndexOptions<Shape extends SchemaShape> = Omit<IndexDescription, 'key' | 'partialFilterExpression'> & {
+  readonly partialFilterExpression?: SchemaPartialFilter<Shape>;
+};
+type SchemaIndex<Shape extends SchemaShape> = {
+  readonly fields: SchemaIndexFields<Shape>;
+  readonly options?: SchemaIndexOptions<Shape>;
+};
+type ExactPartialFilter<Shape extends SchemaShape, Filter> = Filter & Record<Exclude<keyof Filter, keyof SchemaPartialFilter<Shape>>, never>;
+type ValidateIndexDefinition<Shape extends SchemaShape, Definition> = Definition extends {
+  readonly options?: infer Options;
+} ? Definition & {
+  readonly options?: Options extends {
+    readonly partialFilterExpression?: infer Filter;
+  } ? Options & {
+    readonly partialFilterExpression?: ExactPartialFilter<Shape, Filter>;
+  } : Options;
+} : Definition;
+type ValidateIndexDefinitions<Shape extends SchemaShape, Definitions extends readonly unknown[]> = { [Key in keyof Definitions]: ValidateIndexDefinition<Shape, Definitions[Key]>; };
+/** Explicit names declared for typed per-model index management. */
+type SchemaIndexNames<Indexes extends readonly SchemaIndex<any>[]> = Extract<Indexes[number] extends (infer Index) ? Index extends {
+  readonly options?: {
+    readonly name?: infer Name;
+  };
+} ? Name : never : never, string>;
+//#endregion
 //#region src/schema/inference.d.ts
 /** The raw parsed shape produced by a schema before persistence fields are added. */
 type InferShape<T> = T extends {
@@ -14,21 +180,40 @@ type Infer<T> = InferShape<T> & {
   _id: ObjectId$1;
 };
 //#endregion
-//#region src/schema/contracts.d.ts
-/** A Zod object shape used as the source of truth for a model. */
-type SchemaShape = z.ZodRawShape;
-/** The runtime Zod object generated from a schema shape. */
-type SchemaDefinition<Shape extends SchemaShape> = z.ZodObject<Shape>;
+//#region src/relations/ref-fields.d.ts
+/** ObjectId Zod field carrying a lazily resolved relation target. */
+type RefField<Target extends SchemaLike = SchemaLike> = z.ZodType<ObjectId$1> & {
+  readonly __ref?: RefDefinition<Target>;
+  optional(): OptionalRefField<Target>;
+  nullable(): NullableRefField<Target>;
+  nullish(): NullishRefField<Target>;
+};
+type OptionalRefField<Target extends SchemaLike = SchemaLike> = z.ZodOptional<RefField<Target>> & {
+  readonly __ref?: RefDefinition<Target>;
+};
+type NullableRefField<Target extends SchemaLike = SchemaLike> = z.ZodNullable<RefField<Target>> & {
+  readonly __ref?: RefDefinition<Target>;
+};
+type NullishRefField<Target extends SchemaLike = SchemaLike> = z.ZodOptional<NullableRefField<Target>> & {
+  readonly __ref?: RefDefinition<Target>;
+};
+type RelationDefinition<Field> = Field extends {
+  readonly __ref?: infer Definition;
+} ? NonNullable<Definition> : Field extends z.ZodOptional<infer Inner> ? RelationDefinition<Inner> : Field extends z.ZodNullable<infer Inner> ? RelationDefinition<Inner> : never;
+/** Relation fields inferred from a schema shape. */
+type RelationMap<Shape extends SchemaShape> = { [Key in keyof Shape as RelationDefinition<Shape[Key]> extends never ? never : Key]: RelationDefinition<Shape[Key]>; };
 //#endregion
-//#region src/model/model.d.ts
+//#region src/model/types.d.ts
 type CreateInput<Shape extends SchemaShape, Options extends SchemaOptions> = Omit<InferInput<Schema<Shape, {}, {}, Options>>, '_id'>;
 type UpdateInput<Shape extends SchemaShape, Options extends SchemaOptions> = Partial<Omit<InferInput<Schema<Shape, {}, {}, Options>>, '_id'>>;
-type ModelDocument$1<Shape extends SchemaShape, Relations extends SchemaRelationMap, Scopes extends ScopeDefinitions, Options extends SchemaOptions> = Infer<Schema<Shape, Relations, Scopes, Options>>;
+type ModelResult<Shape extends SchemaShape, Relations extends SchemaRelationMap, Scopes extends ScopeDefinitions, Options extends SchemaOptions> = Infer<Schema<Shape, Relations, Scopes, Options>>;
 type IndexNames<Indexes extends readonly SchemaIndex<any>[]> = SchemaIndexNames<Indexes>;
 type IndexManager<Indexes extends readonly SchemaIndex<any>[]> = {
   readonly drop: (names: readonly IndexNames<Indexes>[]) => Promise<void>;
   readonly purge: () => Promise<void>;
 };
+//#endregion
+//#region src/model/model.d.ts
 /** A MongoDB collection with CRUD operations derived from a schema. */
 export declare class Model<Shape extends SchemaShape, Relations extends SchemaRelationMap = {}, Scopes extends ScopeDefinitions = {}, Options extends SchemaOptions = {}, Indexes extends readonly SchemaIndex<any>[] = []> {
   private readonly db;
@@ -36,9 +221,9 @@ export declare class Model<Shape extends SchemaShape, Relations extends SchemaRe
   private readonly schema;
   readonly index: IndexManager<Indexes>;
   readonly bulk: {
-    create: (inputs: readonly CreateInput<Shape, Options>[]) => Promise<ModelDocument$1<Shape, Relations, Scopes, Options>[]>;
+    create: (inputs: readonly CreateInput<Shape, Options>[]) => Promise<ModelResult<Shape, Relations, Scopes, Options>[]>;
   };
-  readonly restore: SoftDeleteEnabled<Options> extends true ? (filter: ModelFilter<Shape>) => Promise<Infer<Schema<Shape, Relations, Scopes, Options>> | null> : never;
+  readonly restore: SoftDeleteEnabled<Options> extends true ? (filter: ModelFilter<Shape>) => Promise<ModelResult<Shape, Relations, Scopes, Options> | null> : never;
   readonly purge: SoftDeleteEnabled<Options> extends true ? (filter: ModelFilter<Shape>) => Promise<DeleteResult> : never;
   /** Create a model bound to a database collection and schema. */
   constructor(db: Db, name: string, schema: Schema<Shape, Relations, Scopes, Options, Indexes>);
@@ -46,13 +231,13 @@ export declare class Model<Shape extends SchemaShape, Relations extends SchemaRe
   private dropIndexes;
   private activeFilter;
   /** Validate and insert one document, generating its ObjectId. */
-  create(input: CreateInput<Shape, Options>): Promise<ModelDocument$1<Shape, Relations, Scopes, Options>>;
+  create(input: CreateInput<Shape, Options>): Promise<ModelResult<Shape, Relations, Scopes, Options>>;
   private prepareDocument;
   private bulkCreate;
   /** Build a query for all documents matching a MongoDB filter. */
   find(filter?: ModelFilter<Shape>): ModelQuery<Shape, VisibleDocument<Shape>, true, Relations, Scopes, 'none', SoftDeleteEnabled<Options>>;
   /** Validate and apply a partial update to the first matching document. */
-  update(filter: ModelFilter<Shape>, patch: UpdateInput<Shape, Options>): Promise<Infer<Schema<Shape, Relations, Scopes, Options>> | null>;
+  update(filter: ModelFilter<Shape>, patch: UpdateInput<Shape, Options>): Promise<ModelResult<Shape, Relations, Scopes, Options> | null>;
   /** Restore matching soft-deleted documents. */
   private restoreDocument;
   /** Delete every document matching a MongoDB filter. */
@@ -61,9 +246,10 @@ export declare class Model<Shape extends SchemaShape, Relations extends SchemaRe
   private purgeDocuments;
 }
 //#endregion
-//#region src/connection/database.d.ts
+//#region src/connection/types.d.ts
+/** Schema registry supplied to a database handle. */
 type SchemaRegistry = Record<string, SchemaLike>;
-/** Configuration for a MongoDB connection. */
+/** Configuration for a MongoDB connection and its registered collections. */
 interface DbOptions<Registry extends SchemaRegistry = SchemaRegistry> {
   /** MongoDB connection string. */
   uri: string;
@@ -71,14 +257,17 @@ interface DbOptions<Registry extends SchemaRegistry = SchemaRegistry> {
   database: string;
   /** Optional native MongoDB client options. */
   clientOptions?: MongoClientOptions;
-  /** Schemas registered as plural database model properties. */
-  schema?: Registry;
+  /** Registered schemas, exposed as matching model properties and collection names. */
+  schemas?: Registry;
 }
 type ModelForSchema<SchemaType> = SchemaType extends Schema<infer Shape, infer Relations, infer Scopes, infer Options, infer Indexes extends readonly SchemaIndex<any>[]> ? Model<Shape, Relations, Scopes, Options, Indexes> : never;
+/** Model properties generated from a schema registry. */
 type DatabaseModels<Registry extends SchemaRegistry> = { readonly [Name in keyof Registry]: ModelForSchema<Registry[Name]>; };
 type RegistryOfBuilder<Builder extends {
   readonly __registry?: SchemaRegistry;
 }> = NonNullable<Builder['__registry']>;
+//#endregion
+//#region src/connection/database.d.ts
 /** Owns a MongoDB client and creates schema-bound models. */
 export declare class Db<Registry extends SchemaRegistry = SchemaRegistry> {
   private readonly options;
@@ -105,74 +294,17 @@ export declare class Db<Registry extends SchemaRegistry = SchemaRegistry> {
 }
 /** Create a disconnected MongoDB database handle. */
 export declare function createDatabase<const Registry extends SchemaRegistry>(options: DbOptions<Registry> & {
-  schema: Registry;
+  schemas: Registry;
 }): Db<Registry> & DatabaseModels<Registry>;
 export declare function createDatabase<const Builder extends {
   readonly __registry?: SchemaRegistry;
-}>(options: Omit<DbOptions<RegistryOfBuilder<Builder>>, 'schema'> & {
-  schema: Builder;
+}>(options: Omit<DbOptions<RegistryOfBuilder<Builder>>, 'schemas'> & {
+  schemas: Builder;
 }): Db<RegistryOfBuilder<Builder>> & DatabaseModels<RegistryOfBuilder<Builder>>;
 export declare function createDatabase(options: DbOptions): Db;
 //#endregion
-//#region src/query/cursor.d.ts
-/** A lazy async iterable for one cursor-pagination page. */
-export declare class ModelCursor<Shape extends SchemaShape, Result extends object> implements AsyncIterable<Result> {
-  private readonly open;
-  private readonly pageSize;
-  private readonly transform?;
-  next: ObjectId$1 | null;
-  constructor(open: () => FindCursor<WithId<StoredDocument<Shape>>>, pageSize: number, transform?: ((documents: Result[]) => Promise<Result[]>) | undefined);
-  [Symbol.asyncIterator](): AsyncGenerator<Result>;
-}
-//#endregion
-//#region src/query/types.d.ts
-type StoredDocument<Shape extends SchemaShape> = Infer<Schema<Shape>> & Document;
-type ModelFilterForDocument<DocumentShape extends Document, FieldShape extends object = DocumentShape> = Partial<{ [Key in keyof FieldShape]: Condition<FieldShape[Key]>; }> & Partial<{ [Path in NestedFilterKey<FieldShape>]: Condition<NestedFilterValue<FieldShape, Path>>; }> & Partial<Pick<RootFilterOperators<DocumentShape>, '$comment' | '$expr' | '$jsonSchema' | '$text' | '$where'>> & {
-  $and?: ModelFilterForDocument<DocumentShape, FieldShape>[];
-  $nor?: ModelFilterForDocument<DocumentShape, FieldShape>[];
-  $or?: ModelFilterForDocument<DocumentShape, FieldShape>[];
-};
-type NestedFilterKey<Value, Prefix extends string = ''> = Value extends object ? Value extends ObjectId$1 | Date | readonly unknown[] ? never : { [Key in Extract<keyof Value, string>]: NonNullable<Value[Key]> extends object ? `${Prefix}${Key}` | `${Prefix}${Key}.${NestedFilterKey<NonNullable<Value[Key]>>}` : `${Prefix}${Key}`; }[Extract<keyof Value, string>] : never;
-type NestedFilterValue<Value, Path extends string> = Path extends `${infer Head}.${infer Tail}` ? Head extends keyof Value ? NestedFilterValue<NonNullable<Value[Head]>, Tail> : never : Path extends keyof Value ? Value[Path] : never;
-type ModelFilter<Shape extends SchemaShape> = ModelFilterForDocument<StoredDocument<Shape>, Infer<Schema<Shape>>>;
-type SortDirection = 'asc' | 'desc';
-type ModelSort<Shape extends SchemaShape> = Partial<Record<Extract<keyof Infer<Schema<Shape>>, string>, SortDirection>>;
-type ModelDocument<Shape extends SchemaShape> = Infer<Schema<Shape>>;
-type HiddenKey<Shape extends SchemaShape> = { [Key in keyof Shape]: Shape[Key] extends {
-  readonly __hidden: true;
-} ? Key : never; }[keyof Shape];
-type HiddenDocumentKey<Shape extends SchemaShape> = Extract<HiddenKey<Shape>, keyof ModelDocument<Shape>> & string;
-type NestedDocumentKeys<Value, Prefix extends string = ''> = Value extends object ? Value extends ObjectId$1 | Date ? never : { [Key in Extract<keyof Value, string>]: NonNullable<Value[Key]> extends object ? `${Prefix}${Key}` | `${Prefix}${Key}.${NestedDocumentKeys<NonNullable<Value[Key]>>}` : `${Prefix}${Key}`; }[Extract<keyof Value, string>] : never;
-type NestedSelectableKey<Shape extends SchemaShape> = { [Key in Extract<keyof Shape, string>]: Key extends keyof ModelDocument<Shape> ? NonNullable<ModelDocument<Shape>[Key]> extends object ? `${Key}.${NestedDocumentKeys<NonNullable<ModelDocument<Shape>[Key]>>}` : never : never; }[Extract<keyof Shape, string>];
-type CursorMethod<Shape extends SchemaShape, Result extends object, Ready extends boolean> = Ready extends true ? (after?: ObjectId$1) => ModelCursor<Shape, Result> : undefined;
-type SelectableKey<Shape extends SchemaShape> = Exclude<Extract<keyof ModelDocument<Shape>, string>, '_id' | HiddenDocumentKey<Shape>> | NestedSelectableKey<Shape>;
-type PathSelection<Value, Path extends string> = Path extends `${infer Head}.${infer Tail}` ? Head extends keyof Value ? { [Key in Head]: PathSelection<NonNullable<Value[Key]>, Tail>; } : never : Path extends keyof Value ? Pick<Value, Path> : never;
-type UnionToIntersection<Value> = (Value extends unknown ? (input: Value) => void : never) extends ((input: infer Intersection) => void) ? Intersection : never;
-type Simplify<Value> = { [Key in keyof Value]: Value[Key]; };
-type VisibleDocument<Shape extends SchemaShape> = Omit<ModelDocument<Shape>, Extract<HiddenKey<Shape>, keyof ModelDocument<Shape>>>;
-type SelectedDocument<Shape extends SchemaShape, Key extends SelectableKey<Shape>> = [Key] extends [never] ? VisibleDocument<Shape> : Simplify<Pick<ModelDocument<Shape>, '_id'> & UnionToIntersection<PathSelection<ModelDocument<Shape>, Extract<Key, string>>>>;
-type RelationTarget<Relation> = Relation extends {
-  resolve: () => infer Target;
-} ? Target : never;
-type RelationDocument<Relation> = RelationTarget<Relation> extends Schema<infer TargetShape, any> ? Infer<Schema<TargetShape>> : never;
-type RelationMapOf$1<Relation> = RelationTarget<Relation> extends {
-  readonly relationMap: infer TargetRelations;
-} ? TargetRelations extends SchemaRelationMap ? TargetRelations : {} : {};
-type ScopeName<Scopes> = Extract<keyof Scopes, string>;
-type PopulationMode = 'none' | 'populate' | 'scope';
-type RelationSelect<Relation> = RelationTarget<Relation> extends Schema<infer TargetShape, any> ? Exclude<SelectableKey<TargetShape>, '_id'> : never;
-type PopulateSpec<Relations extends SchemaRelationMap> = { [Name in Extract<keyof Relations, string>]: {
-  ref: Name;
-  select?: readonly RelationSelect<Relations[Name]>[];
-  populate?: PopulateSpecs<RelationMapOf$1<Relations[Name]>>;
-}; }[Extract<keyof Relations, string>];
-type PopulateSpecs<Relations extends SchemaRelationMap> = readonly PopulateSpec<Relations>[];
-type PopulatedResult<Result extends object, Relations extends SchemaRelationMap, Specs extends PopulateSpecs<Relations>> = Omit<Result, Extract<Specs[number]['ref'], keyof Result>> & { [Spec in Specs[number] as Spec['ref']]: PopulatedRelation<Relations[Spec['ref']], Spec> | null; };
-type PopulatedRelation<Relation, Spec> = Spec extends {
-  populate: infer Nested extends PopulateSpecs<RelationMapOf$1<Relation>>;
-} ? RelationDocument<Relation> extends (infer PopulatedDocument extends object) ? PopulatedResult<PopulatedDocument, RelationMapOf$1<Relation>, Nested> : never : RelationDocument<Relation>;
-//#endregion
-//#region src/query/many-query.d.ts
+//#region src/query/builder/find-query.d.ts
+type ScopeResult<Result extends object, Relations extends SchemaRelationMap, Scopes extends ScopeDefinitions, Name extends ScopeName<Scopes>> = PopulatedResult<Result, Relations, Extract<Scopes[Name], PopulateSpecs<Relations>>>;
 /** A typed, awaitable MongoDB find query. */
 export declare class ModelQuery<Shape extends SchemaShape, Result extends object = VisibleDocument<Shape>, CursorReady extends boolean = true, Relations extends SchemaRelationMap = {}, Scopes extends ScopeDefinitions = {}, Mode extends PopulationMode = 'none', SoftDelete extends boolean = false> implements PromiseLike<Result[]> {
   private readonly collection;
@@ -198,6 +330,7 @@ export declare class ModelQuery<Shape extends SchemaShape, Result extends object
   /** Include both active and soft-deleted documents in this query. */
   private deletedMode;
   private effectiveFilter;
+  private executionContext;
   /** Sort results by one or more schema fields. */
   sort(spec: ModelSort<Shape>): ModelQuery<Shape, Result, false, Relations, Scopes, Mode, SoftDelete>;
   /** Skip a non-negative number of matching documents. */
@@ -211,91 +344,18 @@ export declare class ModelQuery<Shape extends SchemaShape, Result extends object
   /** Populate declared one-way relations, including nested relation arrays. */
   populate<Specs extends PopulateSpecs<Relations>>(this: Mode extends 'scope' ? never : ModelQuery<Shape, Result, CursorReady, Relations, Scopes, Mode, SoftDelete>, specs: Specs): ModelQuery<Shape, PopulatedResult<Result, Relations, Specs>, CursorReady, Relations, Scopes, 'populate', SoftDelete>;
   /** Apply a named population scope. */
-  with<Name extends ScopeName<Scopes>>(this: Mode extends 'populate' ? never : ModelQuery<Shape, Result, CursorReady, Relations, Scopes, Mode, SoftDelete>, name: Name): ModelQuery<Shape, PopulatedResult<Result, Relations, Scopes[Name] & PopulateSpecs<Relations>>, CursorReady, Relations, Scopes, 'scope', SoftDelete>;
+  with<Name extends ScopeName<Scopes>>(this: Mode extends 'populate' ? never : ModelQuery<Shape, Result, CursorReady, Relations, Scopes, Mode, SoftDelete>, name: Name): ModelQuery<Shape, ScopeResult<Result, Relations, Scopes, Name>, CursorReady, Relations, Scopes, 'scope', SoftDelete>;
   /** Count matching documents, optionally using MongoDB's collection estimate. */
   count(estimate?: boolean): Promise<number>;
-  /** Return one `_id`-ordered page and the cursor for the next page. */
+  /** Return one bounded `_id`-ordered page and its continuation cursor. */
   private createCursor;
   private execute;
   first(): Promise<Result | null>;
-  private createQueryCursor;
   then<TResult1 = Result[], TResult2 = never>(onfulfilled?: ((value: Result[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
 }
 //#endregion
-//#region src/schema/scalars.d.ts
-declare module 'zod' {
-  interface ZodType {
-    hidden(): this & {
-      readonly __hidden: true;
-    };
-  }
-}
-/** A schema field that can be marked as hidden from default query results. */
-type HiddenCapable<T extends z.ZodType> = Omit<T, 'optional' | 'nullable' | 'nullish'> & HiddenMethods<T>;
-/** A schema field marked as hidden from default query results. */
-type HiddenSchema<T extends z.ZodType> = Omit<T, 'optional' | 'nullable' | 'nullish'> & HiddenMethods<T> & {
-  readonly __hidden: true;
-};
-type HiddenMethods<T extends z.ZodType> = {
-  hidden(): HiddenSchema<T>;
-  optional(): HiddenCapable<z.ZodOptional<T>>;
-  nullable(): HiddenCapable<z.ZodNullable<T>>;
-  nullish(): HiddenCapable<z.ZodOptional<z.ZodNullable<T>>>;
-};
-/** Create a MongoDB ObjectId schema. */
-declare const objectId: () => HiddenCapable<z.ZodInstanceOf<ObjectId$1>>;
-//#endregion
 //#region src/schema/schema.d.ts
-/** Built-in persistence behavior applied by a schema. */
-interface SchemaOptions {
-  readonly timestamps?: boolean;
-  readonly softdelete?: boolean;
-  /** Hide Mongorm-managed fields from default query results. */
-  readonly hideManaged?: boolean;
-}
-type IndexFieldMap<Shape extends SchemaShape> = Record<Extract<keyof Shape, string>, IndexDirection>;
-/** A non-empty, autocomplete-friendly MongoDB index key definition. */
-type SchemaIndexFields<Shape extends SchemaShape> = { [Key in keyof IndexFieldMap<Shape>]: Pick<IndexFieldMap<Shape>, Key> & Partial<Omit<IndexFieldMap<Shape>, Key>>; }[keyof IndexFieldMap<Shape>];
-/** A schema-aware MongoDB partial-index filter. */
-type SchemaPartialFilter<Shape extends SchemaShape> = ModelFilter<Shape>;
-type SchemaIndexOptions<Shape extends SchemaShape> = Omit<IndexDescription, 'key' | 'partialFilterExpression'> & {
-  /** Restrict indexed documents using schema-aware MongoDB filter operators. */
-  readonly partialFilterExpression?: SchemaPartialFilter<Shape>;
-};
-type SchemaIndex<Shape extends SchemaShape> = {
-  readonly fields: SchemaIndexFields<Shape>;
-  readonly options?: SchemaIndexOptions<Shape>;
-};
-type ExactPartialFilter<Shape extends SchemaShape, Filter> = Filter & Record<Exclude<keyof Filter, keyof SchemaPartialFilter<Shape>>, never>;
-type ValidateIndexDefinition<Shape extends SchemaShape, Definition> = Definition extends {
-  readonly options?: infer Options;
-} ? Definition & {
-  readonly options?: Options extends {
-    readonly partialFilterExpression?: infer Filter;
-  } ? Options & {
-    readonly partialFilterExpression?: ExactPartialFilter<Shape, Filter>;
-  } : Options;
-} : Definition;
-type ValidateIndexDefinitions<Shape extends SchemaShape, Definitions extends readonly unknown[]> = { [Key in keyof Definitions]: ValidateIndexDefinition<Shape, Definitions[Key]>; };
-type SchemaIndexNames<Indexes extends readonly SchemaIndex<any>[]> = Extract<Indexes[number] extends (infer Index) ? Index extends {
-  readonly options?: {
-    readonly name?: infer Name;
-  };
-} ? Name : never : never, string>;
-type ManagedSchema<T extends z.ZodType, Options extends SchemaOptions> = Options['hideManaged'] extends true ? HiddenSchema<T> : T;
-type TimestampShape<Options extends SchemaOptions> = {
-  createdAt: ManagedSchema<z.ZodDefault<z.ZodDate>, Options>;
-  updatedAt: ManagedSchema<z.ZodDefault<z.ZodDate>, Options>;
-};
-type SoftDeleteShape<Options extends SchemaOptions> = {
-  deletedAt: ManagedSchema<z.ZodDefault<z.ZodNullable<z.ZodDate>>, Options>;
-};
-type ManagedShape<Options extends SchemaOptions> = (Options['timestamps'] extends true ? TimestampShape<Options> : {}) & (Options['softdelete'] extends true ? SoftDeleteShape<Options> : {});
-type ManagedField<Options extends SchemaOptions> = (Options['timestamps'] extends true ? 'createdAt' | 'updatedAt' : never) | (Options['softdelete'] extends true ? 'deletedAt' : never);
-type SoftDeleteEnabled<Options extends SchemaOptions> = Options['softdelete'] extends true ? true : false;
-export declare const hasSoftDelete: (options: SchemaOptions) => boolean;
 type ObjectIdFieldKeys<Shape extends SchemaShape> = { [Key in keyof InferShape<Schema<Shape>>]-?: NonNullable<InferShape<Schema<Shape>>[Key]> extends ObjectId$1 ? Key : never; }[keyof InferShape<Schema<Shape>>];
-type ScopeDefinitions = Record<string, readonly object[]>;
 /** A typed, runtime-validated schema definition. */
 export declare class Schema<Shape extends SchemaShape, Relations extends SchemaRelationMap = {}, Scopes extends ScopeDefinitions = {}, Options extends SchemaOptions = {}, Indexes extends readonly SchemaIndex<any>[] = []> {
   /** The underlying Zod object for advanced validation use cases. */
@@ -320,7 +380,6 @@ export declare class Schema<Shape extends SchemaShape, Relations extends SchemaR
   constructor(shape: Shape, relations?: Relations, scopeMap?: Scopes, optionsConfig?: Options, indexDefinitions?: Indexes);
   /** Enable managed timestamps and/or soft deletion for this schema. */
   options<const Enabled extends SchemaOptions>(options: Enabled): Schema<Shape & ManagedShape<Enabled>, Relations, Scopes, Enabled, Indexes>;
-  private managedField;
   /** Declare MongoDB indexes for explicit synchronization with the database. */
   indexes<const Definitions extends readonly SchemaIndex<Shape>[]>(definitions: readonly SchemaIndex<Shape>[] & ValidateIndexDefinitions<Shape, Definitions>): Schema<Shape, Relations, Scopes, Options, Definitions>;
   /** Add one or more one-way relations without requiring circular schema declarations. */
@@ -338,69 +397,51 @@ export declare class Schema<Shape extends SchemaShape, Relations extends SchemaR
 }
 //#endregion
 //#region src/relations/definitions.d.ts
-/** A schema-like target resolved lazily to support circular module imports. */
-type SchemaLike = Schema<SchemaShape, any, any, any, readonly SchemaIndex<any>[]>;
-/** Metadata attached to a forward relation field. */
+/** Schema object accepted as a lazy relation target or registry entry. */
+type SchemaLike = Schema<any, any, any, any, any>;
+/** Metadata for a schema target resolved lazily to support circular imports. */
 interface RefDefinition<Target extends SchemaLike = SchemaLike> {
-  /** Resolve the related schema after module initialization completes. */
   resolve: () => Target;
 }
-/** Metadata for a one-way relation between two MongoDB schemas. */
-interface SchemaRelation<Target extends SchemaLike = SchemaLike, LocalField extends string = string, ForeignField extends string = string> {
+/** Metadata for a one-way relation between two registered schemas. */
+interface SchemaRelation<Target extends SchemaLike = SchemaLike, LocalField extends string = string, ForeignField extends string = string, TargetRelations = Target extends {
+  readonly relationMap: infer Relations;
+} ? Relations : {}> {
   readonly resolve: () => Target;
   readonly localField: LocalField;
   readonly foreignField: ForeignField;
+  /** Target relations are carried separately to avoid recursively wrapping its schema type. */
+  readonly __targetRelations?: TargetRelations;
 }
-/** Relation metadata attached to a schema. */
 type SchemaRelationMap = Record<string, SchemaRelation>;
-/** A relation target declaration accepted by Schema.relations(). */
+/** Relation target declaration accepted by `Schema.relations()`. */
 type RelationInput<Target extends SchemaLike = SchemaLike> = (() => Target) | {
   target: () => Target;
   foreignField?: string;
 };
-/** Extract a relation target from a relation declaration. */
 type RelationInputTarget<Input> = Input extends (() => infer Target) ? Target : Input extends {
   target: () => infer Target;
 } ? Target : never;
-/** A string identifier field carrying a typed relation target. */
-type RefField<Target extends SchemaLike = SchemaLike> = z.ZodType<ObjectId$1> & {
-  readonly __ref?: RefDefinition<Target>;
-  optional(): OptionalRefField<Target>;
-  nullable(): NullableRefField<Target>;
-  nullish(): NullishRefField<Target>;
-};
-/** An optional relation field that retains its target metadata. */
-type OptionalRefField<Target extends SchemaLike = SchemaLike> = z.ZodOptional<RefField<Target>> & {
-  readonly __ref?: RefDefinition<Target>;
-};
-/** A nullable relation field that retains its target metadata. */
-type NullableRefField<Target extends SchemaLike = SchemaLike> = z.ZodNullable<RefField<Target>> & {
-  readonly __ref?: RefDefinition<Target>;
-};
-/** An optional and nullable relation field that retains its target metadata. */
-type NullishRefField<Target extends SchemaLike = SchemaLike> = z.ZodOptional<NullableRefField<Target>> & {
-  readonly __ref?: RefDefinition<Target>;
-};
-type RelationDefinition<Field> = Field extends {
-  readonly __ref?: infer Definition;
-} ? NonNullable<Definition> : Field extends z.ZodOptional<infer Inner> ? RelationDefinition<Inner> : Field extends z.ZodNullable<infer Inner> ? RelationDefinition<Inner> : never;
-/** The relation metadata inferred from a schema shape. */
-type RelationMap<Shape extends SchemaShape> = { [Key in keyof Shape as RelationDefinition<Shape[Key]> extends never ? never : Key]: RelationDefinition<Shape[Key]>; };
 //#endregion
-//#region src/relations/registry.d.ts
+//#region src/relations/registry-types.d.ts
 type ObjectIdKeys<Shape extends SchemaShape> = { [Key in keyof InferShape<Schema<Shape>>]-?: NonNullable<InferShape<Schema<Shape>>[Key]> extends ObjectId$1 ? Key : never; }[keyof InferShape<Schema<Shape>>];
+/** Valid local ObjectId fields and targets accepted by `defineRelations`. */
 type RelationDefinitions<Registry extends Record<string, SchemaLike>> = { [Name in keyof Registry]?: Registry[Name] extends Schema<infer Shape, any, any, any> ? Partial<Record<Extract<ObjectIdKeys<Shape>, string>, Extract<keyof Registry, string>>> : never; };
-type EnrichedSchema<Registry extends Record<string, SchemaLike>, AllDefinitions extends RelationDefinitions<Registry>, Name> = Name extends keyof Registry ? Registry[Name] extends Schema<infer Shape, infer Relations, infer Scopes, infer Options> ? Schema<Shape, Relations & RelationsFor<Registry, AllDefinitions, NonNullable<AllDefinitions[Name]>>, Scopes, Options, Registry[Name] extends Schema<any, any, any, any, infer Indexes extends readonly SchemaIndex<any>[]> ? Indexes : []> : never : never;
-type RelationsFor<Registry extends Record<string, SchemaLike>, AllDefinitions extends RelationDefinitions<Registry>, Definitions> = { [Field in keyof Definitions & string]: Definitions[Field] extends keyof Registry ? SchemaRelation<EnrichedSchema<Registry, AllDefinitions, Definitions[Field]>, Field, '_id'> : never; };
+type RelationsFor<Registry extends Record<string, SchemaLike>, AllDefinitions extends RelationDefinitions<Registry>, Definitions> = { [Field in keyof Definitions & string]: Definitions[Field] extends keyof Registry ? SchemaRelation<Registry[Definitions[Field]], Field, '_id', RelationsFor<Registry, AllDefinitions, NonNullable<AllDefinitions[Definitions[Field]]>>> : never; };
 type RegistryWithRelations<Registry extends Record<string, SchemaLike>, Definitions extends RelationDefinitions<Registry>> = { [Name in keyof Registry]: Registry[Name] extends Schema<infer Shape, infer Relations, infer Scopes, infer Options> ? Schema<Shape, Relations & RelationsFor<Registry, Definitions, NonNullable<Definitions[Name]>>, Scopes, Options, Registry[Name] extends Schema<any, any, any, any, infer Indexes extends readonly SchemaIndex<any>[]> ? Indexes : []> : Registry[Name]; };
-type RelationMapOf<Value> = Value extends Schema<any, infer Relations, any, any> ? Relations : {};
+type RelationMapOf<Value> = Value extends SchemaRelation<any, any, any, infer Relations> ? Relations : Value extends Schema<any, infer Relations, any, any> ? Relations : {};
+/** Scope declarations accepted for each registered model. */
 type ScopeDefinitionsBySchema<Registry extends Record<string, SchemaLike>> = { [Name in keyof Registry]?: Record<string, PopulateSpecs<RelationMapOf<Registry[Name]>>>; };
 type RegistryWithScopes<Registry extends Record<string, SchemaLike>, Definitions extends ScopeDefinitionsBySchema<Registry>> = { [Name in keyof Registry]: Registry[Name] extends Schema<infer Shape, infer Relations, infer Scopes, infer Options> ? Schema<Shape, Relations, Scopes & (Definitions[Name] extends ScopeDefinitions ? Definitions[Name] : {}), Options, Registry[Name] extends Schema<any, any, any, any, infer Indexes extends readonly SchemaIndex<any>[]> ? Indexes : []> : Registry[Name]; };
+/** Typed registry builder API, with relations and scopes reflected in model types. */
 type SchemaRegistryBuilder<Registry extends Record<string, SchemaLike>> = Registry & {
   readonly __registry?: Registry;
   defineRelations<const Definitions extends RelationDefinitions<Registry>>(definitions: Definitions): SchemaRegistryBuilder<RegistryWithRelations<Registry, Definitions>>;
   defineScopes<const Definitions extends ScopeDefinitionsBySchema<Registry>>(definitions: Definitions): SchemaRegistryBuilder<RegistryWithScopes<Registry, Definitions>>;
 };
+//#endregion
+//#region src/relations/registry.d.ts
+/** Create a registry of named schemas with typed relation and scope builders. */
 declare const createSchemaRegistry: <const Registry extends Record<string, SchemaLike>>(registry: Registry) => SchemaRegistryBuilder<Registry>;
 //#endregion
 //#region src/api.d.ts
@@ -450,4 +491,4 @@ export declare class EstimatedCountError extends InvalidQueryError {
   constructor();
 }
 //#endregion
-export { type DatabaseModels, type DbOptions, type HiddenDocumentKey, type Infer, type InferInput, type InferShape, type ManagedField, type ModelFilter, type ModelSort, ObjectId, type OrmApi, type OrmErrorCode, type PopulateSpec, type PopulateSpecs, type PopulatedResult, type RefDefinition, type RefField, type RelationDefinitions, type RelationMap, type SchemaDefinition, type SchemaIndex, type SchemaIndexFields, type SchemaLike, type SchemaOptions, type SchemaRegistry, type SchemaRegistryBuilder, type SchemaRelation, type SchemaRelationMap, type SchemaShape, type ScopeDefinitionsBySchema, type SelectableKey, type SelectedDocument, type SoftDeleteEnabled, type StoredDocument, type VisibleDocument };
+export { type DatabaseModels, type DbOptions, type HiddenDocumentKey, type Infer, type InferInput, type InferShape, type ManagedField, type ModelFilter, type ModelSort, type NullableRefField, type NullishRefField, ObjectId, type OptionalRefField, type OrmApi, type OrmErrorCode, type PopulateSpec, type PopulateSpecs, type PopulatedResult, type RefDefinition, type RefField, type RelationDefinitions, type RelationMap, type SchemaDefinition, type SchemaIndex, type SchemaIndexFields, type SchemaLike, type SchemaOptions, type SchemaRegistry, type SchemaRegistryBuilder, type SchemaRelation, type SchemaRelationMap, type SchemaShape, type ScopeDefinitionsBySchema, type SelectableKey, type SelectedDocument, type SoftDeleteEnabled, type StoredDocument, type VisibleDocument };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { MongoClient, ObjectId, ObjectId as ObjectId$1 } from "mongodb";
 import { z } from "zod";
-//#region src/relations/definitions.ts
-/** Create a string ID field linked to a lazily resolved target schema. */
+//#region src/relations/ref-fields.ts
+/** Create a typed ObjectId field linked to a lazily resolved schema. */
 const createRef = (resolve) => {
 	const field = z.instanceof(ObjectId$1);
 	const createOptional = field.optional.bind(field);
@@ -37,22 +37,21 @@ const attachRef = (field, resolve) => {
 	});
 	return field;
 };
-/** Collect relation metadata from a schema shape without evaluating targets. */
-const collectRefs = (shape) => {
-	return Object.fromEntries(Object.entries(shape).filter(([, field]) => "__ref" in field).map(([name, field]) => [name, field.__ref]));
-};
+/** Collect ref field metadata without evaluating target schemas. */
+const collectRefs = (shape) => Object.fromEntries(Object.entries(shape).filter(([, field]) => "__ref" in field).map(([name, field]) => [name, field.__ref]));
 //#endregion
 //#region src/relations/registry.ts
+/** Attach relation/scope builder methods and apply definitions to schema metadata. */
 const attachMethods = (registry) => {
 	const defineRelations = (definitions) => {
 		for (const [name, relations] of Object.entries(definitions)) {
-			const targetSchema = registry[name];
-			if (!targetSchema) throw new Error(`Unknown schema "${name}" in relation definitions`);
+			const source = registry[name];
+			if (!source) throw new Error(`Unknown schema "${name}" in relation definitions`);
 			for (const [field, targetName] of Object.entries(relations ?? {})) {
 				const target = registry[targetName];
 				if (!target) throw new Error(`Unknown relation target "${targetName}"`);
-				if (!(field in targetSchema.definition.shape)) throw new Error(`Unknown relation field "${name}.${field}"`);
-				targetSchema.relationMap[field] = {
+				if (!(field in source.definition.shape)) throw new Error(`Unknown relation field "${name}.${field}"`);
+				source.relationMap[field] = {
 					resolve: () => target,
 					localField: field,
 					foreignField: "_id"
@@ -63,9 +62,9 @@ const attachMethods = (registry) => {
 	};
 	const defineScopes = (definitions) => {
 		for (const [name, scopes] of Object.entries(definitions)) {
-			const targetSchema = registry[name];
-			if (!targetSchema) throw new Error(`Unknown schema "${name}" in scope definitions`);
-			Object.assign(targetSchema.scopeMap, scopes);
+			const schema = registry[name];
+			if (!schema) throw new Error(`Unknown schema "${name}" in scope definitions`);
+			Object.assign(schema.scopeMap, scopes);
 		}
 		return attachMethods(registry);
 	};
@@ -88,6 +87,7 @@ const attachMethods = (registry) => {
 	});
 	return registry;
 };
+/** Create a registry of named schemas with typed relation and scope builders. */
 const createSchemaRegistry = (registry) => attachMethods(registry);
 //#endregion
 //#region src/schema/scalars.ts
@@ -133,8 +133,11 @@ const withZodNamespace = (namespace) => new Proxy(namespace, { get(target, prope
 /** Create a MongoDB ObjectId schema. */
 const objectId = () => withHidden(z.instanceof(ObjectId$1));
 //#endregion
-//#region src/schema/schema.ts
+//#region src/schema/options.ts
 const hasSoftDelete = (options) => options.softdelete === true;
+const managedField = (field, options) => options.hideManaged ? withHidden(field).hidden() : field;
+//#endregion
+//#region src/schema/schema.ts
 /** A typed, runtime-validated schema definition. */
 var Schema = class Schema {
 	/** The underlying Zod object for advanced validation use cases. */
@@ -171,19 +174,16 @@ var Schema = class Schema {
 		if (options.softdelete && "deletedAt" in this.definition.shape) throw new Error("The deletedAt field is managed by Mongorm");
 		const managedShape = {
 			...options.timestamps ? {
-				createdAt: this.managedField(z.date().default(() => /* @__PURE__ */ new Date()), options),
-				updatedAt: this.managedField(z.date().default(() => /* @__PURE__ */ new Date()), options)
+				createdAt: managedField(z.date().default(() => /* @__PURE__ */ new Date()), options),
+				updatedAt: managedField(z.date().default(() => /* @__PURE__ */ new Date()), options)
 			} : {},
-			...options.softdelete ? { deletedAt: this.managedField(z.date().nullable().default(null), options) } : {}
+			...options.softdelete ? { deletedAt: managedField(z.date().nullable().default(null), options) } : {}
 		};
 		return new Schema({
 			...this.definition.shape,
 			...managedShape
 		}, this.relationMap, this.scopeMap, options, this.indexDefinitions);
 	}
-	managedField(field, options) {
-		return options.hideManaged ? withHidden(field).hidden() : field;
-	}
 	/** Declare MongoDB indexes for explicit synchronization with the database. */
 	indexes(definitions) {
 		if (definitions.some(({ fields }) => Object.keys(fields).length === 0)) throw new Error("Index definitions must include at least one field");
@@ -274,40 +274,8 @@ var EstimatedCountError = class extends InvalidQueryError {
 	}
 };
 //#endregion
-//#region src/query/cursor.ts
-/** A lazy async iterable for one cursor-pagination page. */
-var ModelCursor = class {
-	open;
-	pageSize;
-	transform;
-	next = null;
-	constructor(open, pageSize, transform) {
-		this.open = open;
-		this.pageSize = pageSize;
-		this.transform = transform;
-	}
-	async *[Symbol.asyncIterator]() {
-		const cursor = this.open();
-		try {
-			const documents = [];
-			for (let index = 0; index < this.pageSize && await cursor.hasNext(); index += 1) documents.push(await cursor.next());
-			const transformed = this.transform ? await this.transform(documents) : documents;
-			for (const document of transformed) yield document;
-			const last = transformed.at(-1);
-			this.next = await cursor.hasNext() && last ? last._id : null;
-		} finally {
-			await cursor.close();
-		}
-	}
-};
-//#endregion
-//#region src/model/soft-delete.ts
-const applySoftDeleteFilter = (filter, mode) => {
-	if (mode === "all") return filter;
-	return { $and: [mode === "deleted" ? { deletedAt: { $ne: null } } : { deletedAt: null }, filter] };
-};
-//#endregion
-//#region src/query/runtime.ts
+//#region src/query/projection/runtime.ts
+/** Remove duplicate and ancestor-overlapping MongoDB projection paths. */
 const normalizeProjectionFields = (fields) => {
 	const unique = new Set(fields);
 	return [...unique].filter((field) => {
@@ -319,6 +287,7 @@ const normalizeProjectionFields = (fields) => {
 		return true;
 	});
 };
+/** Build the MongoDB projection from schema visibility and query selections. */
 const projectionFor = (fields, hiddenFields, selectedFields, shownFields) => {
 	const effectiveSelectedFields = selectedFields?.length ? selectedFields : void 0;
 	if (!effectiveSelectedFields && hiddenFields.length === 0 && shownFields.length === 0) return;
@@ -326,25 +295,9 @@ const projectionFor = (fields, hiddenFields, selectedFields, shownFields) => {
 	const visibleFields = effectiveSelectedFields ?? fields.filter((field) => !hidden.has(field));
 	return Object.fromEntries(normalizeProjectionFields([...visibleFields, ...shownFields]).map((field) => [field, 1]));
 };
-var SoftDeleteState = class {
-	enabled;
-	mode = "active";
-	constructor(enabled) {
-		this.enabled = enabled;
-	}
-	includeDeleted() {
-		this.mode = "all";
-	}
-	deleted(mode) {
-		this.mode = mode === "include" ? "all" : "deleted";
-	}
-	isFiltered() {
-		return this.enabled && this.mode !== "all";
-	}
-	effectiveFilter(filter) {
-		return applySoftDeleteFilter(filter, this.mode);
-	}
-};
+//#endregion
+//#region src/query/population/executor.ts
+/** Executes already-validated population instructions against related collections. */
 var PopulationExecutor = class {
 	db;
 	relations;
@@ -375,9 +328,111 @@ var PopulationExecutor = class {
 		document[spec.ref] = related;
 	}
 };
+//#endregion
+//#region src/model/soft-delete.ts
+const applySoftDeleteFilter = (filter, mode) => {
+	if (mode === "all") return filter;
+	return { $and: [mode === "deleted" ? { deletedAt: { $ne: null } } : { deletedAt: null }, filter] };
+};
+//#endregion
+//#region src/query/soft-delete/state.ts
+/** Query-local state for composing a schema's default soft-delete filter. */
+var SoftDeleteState = class {
+	enabled;
+	mode = "active";
+	constructor(enabled) {
+		this.enabled = enabled;
+	}
+	includeDeleted() {
+		this.mode = "all";
+	}
+	deleted(mode) {
+		this.mode = mode === "include" ? "all" : "deleted";
+	}
+	isFiltered() {
+		return this.enabled && this.mode !== "all";
+	}
+	effectiveFilter(filter) {
+		return applySoftDeleteFilter(filter, this.mode);
+	}
+};
+//#endregion
+//#region src/query/cursor/cursor.ts
+/** A lazy async iterable for one cursor-pagination page. */
+var ModelCursor = class {
+	open;
+	pageSize;
+	transform;
+	next = null;
+	constructor(open, pageSize, transform) {
+		this.open = open;
+		this.pageSize = pageSize;
+		this.transform = transform;
+	}
+	async *[Symbol.asyncIterator]() {
+		const cursor = this.open();
+		try {
+			const documents = [];
+			for (let index = 0; index < this.pageSize && await cursor.hasNext(); index += 1) documents.push(await cursor.next());
+			const transformed = this.transform ? await this.transform(documents) : documents;
+			for (const document of transformed) yield document;
+			const last = transformed.at(-1);
+			this.next = await cursor.hasNext() && last ? last._id : null;
+		} finally {
+			await cursor.close();
+		}
+	}
+};
+//#endregion
+//#region src/query/cursor/filter.ts
+/** Add the `_id` continuation boundary used by cursor pagination. */
 const createCursorFilter = (filter, after) => after ? { $and: [filter, { _id: { $gt: after } }] } : filter;
 //#endregion
-//#region src/query/many-query.ts
+//#region src/query/builder/executor.ts
+/** Execute a list query or MongoDB's estimated collection count. */
+const countQuery = async (context, estimate) => {
+	if (estimate) {
+		if (Object.keys(context.filter).length > 0 || context.softDelete.isFiltered()) throw new EstimatedCountError();
+		return context.collection.estimatedDocumentCount();
+	}
+	return context.collection.countDocuments(context.effectiveFilter);
+};
+/** Open an `_id`-ordered, bounded cursor page. */
+const createCursorPage = (context, after) => {
+	if (context.limitCount === void 0 || context.limitCount === 0) throw new CursorQueryError("Cursor queries require a positive limit");
+	if (context.skipCount !== void 0) throw new CursorQueryError("Cursor queries do not support skip");
+	if (context.sortSpec) {
+		if (Object.keys(context.sortSpec).length !== 1 || context.sortSpec._id !== "asc") throw new CursorQueryError("Cursor queries require the default _id ascending sort");
+	}
+	const filter = createCursorFilter(context.effectiveFilter, after);
+	return new ModelCursor(() => {
+		let cursor = context.collection.find(filter).sort({ _id: 1 }).limit(context.limitCount + 1);
+		const projection = projectionFor(context.fields, context.hiddenFields, context.selectedFields, context.shownFields);
+		if (projection) cursor = cursor.project(projection);
+		return cursor;
+	}, context.limitCount, (documents) => context.population.apply(documents, context.populateSpecs));
+};
+/** Execute a list query and populate its results. */
+const executeQuery = async (context) => {
+	const documents = await createFindCursor(context).toArray();
+	return context.population.apply(documents, context.populateSpecs);
+};
+/** Execute a query for its first matching document. */
+const executeFirst = async (context) => {
+	const documents = await createFindCursor(context).limit(1).toArray();
+	return (await context.population.apply(documents, context.populateSpecs))[0] ?? null;
+};
+const createFindCursor = (context) => {
+	let cursor = context.collection.find(context.effectiveFilter);
+	if (context.sortSpec) cursor = cursor.sort(context.sortSpec);
+	if (context.skipCount !== void 0) cursor = cursor.skip(context.skipCount);
+	if (context.limitCount !== void 0) cursor = cursor.limit(context.limitCount);
+	const projection = projectionFor(context.fields, context.hiddenFields, context.selectedFields, context.shownFields);
+	if (projection) cursor = cursor.project(projection);
+	return cursor;
+};
+//#endregion
+//#region src/query/builder/find-query.ts
 /** A typed, awaitable MongoDB find query. */
 var ModelQuery = class {
 	collection;
@@ -423,6 +478,34 @@ var ModelQuery = class {
 	effectiveFilter() {
 		return this.softDelete.effectiveFilter(this.filterSpec);
 	}
+	executionContext() {
+		const context = {
+			collection: this.collection,
+			filter: this.filterSpec,
+			effectiveFilter: this.effectiveFilter(),
+			fields: this.fields,
+			hiddenFields: this.hiddenFields,
+			selectedFields: this.selectedFields,
+			shownFields: this.shownFields,
+			sortSpec: this.sortSpec,
+			skipCount: this.skipCount,
+			limitCount: this.limitCount,
+			softDelete: this.softDelete,
+			population: this.population,
+			populateSpecs: this.populateSpecs
+		};
+		Object.defineProperties(context, {
+			effectiveFilter: { get: () => this.effectiveFilter() },
+			selectedFields: { get: () => this.selectedFields },
+			shownFields: { get: () => this.shownFields },
+			sortSpec: { get: () => this.sortSpec },
+			skipCount: { get: () => this.skipCount },
+			limitCount: { get: () => this.limitCount },
+			softDelete: { get: () => this.softDelete },
+			populateSpecs: { get: () => this.populateSpecs }
+		});
+		return context;
+	}
 	/** Sort results by one or more schema fields. */
 	sort(spec) {
 		this.sortSpec = spec;
@@ -465,43 +548,18 @@ var ModelQuery = class {
 		return this;
 	}
 	/** Count matching documents, optionally using MongoDB's collection estimate. */
-	async count(estimate = false) {
-		if (estimate) {
-			if (Object.keys(this.filterSpec).length > 0 || this.softDelete.isFiltered()) throw new EstimatedCountError();
-			return this.collection.estimatedDocumentCount();
-		}
-		return this.collection.countDocuments(this.effectiveFilter());
+	count(estimate = false) {
+		return countQuery(this.executionContext(), estimate);
 	}
-	/** Return one `_id`-ordered page and the cursor for the next page. */
+	/** Return one bounded `_id`-ordered page and its continuation cursor. */
 	createCursor(after) {
-		if (this.limitCount === void 0 || this.limitCount === 0) throw new CursorQueryError("Cursor queries require a positive limit");
-		if (this.skipCount !== void 0) throw new CursorQueryError("Cursor queries do not support skip");
-		if (this.sortSpec) {
-			if (Object.keys(this.sortSpec).length !== 1 || this.sortSpec._id !== "asc") throw new CursorQueryError("Cursor queries require the default _id ascending sort");
-		}
-		const filter = createCursorFilter(this.effectiveFilter(), after);
-		return new ModelCursor(() => {
-			let cursor = this.collection.find(filter).sort({ _id: 1 }).limit(this.limitCount + 1);
-			const projection = projectionFor(this.fields, this.hiddenFields, this.selectedFields, this.shownFields);
-			if (projection) cursor = cursor.project(projection);
-			return cursor;
-		}, this.limitCount, (documents) => this.population.apply(documents, this.populateSpecs));
+		return createCursorPage(this.executionContext(), after);
 	}
 	execute() {
-		return this.createQueryCursor().toArray().then((documents) => this.population.apply(documents, this.populateSpecs));
-	}
-	async first() {
-		const documents = await this.createQueryCursor().limit(1).toArray();
-		return (await this.population.apply(documents, this.populateSpecs))[0] ?? null;
-	}
-	createQueryCursor() {
-		let cursor = this.collection.find(this.effectiveFilter());
-		if (this.sortSpec) cursor = cursor.sort(this.sortSpec);
-		if (this.skipCount !== void 0) cursor = cursor.skip(this.skipCount);
-		if (this.limitCount !== void 0) cursor = cursor.limit(this.limitCount);
-		const projection = projectionFor(this.fields, this.hiddenFields, this.selectedFields, this.shownFields);
-		if (projection) cursor = cursor.project(projection);
-		return cursor;
+		return executeQuery(this.executionContext());
+	}
+	first() {
+		return executeFirst(this.executionContext());
 	}
 	then(onfulfilled, onrejected) {
 		return this.execute().then(onfulfilled, onrejected);
@@ -629,7 +687,7 @@ var Db = class {
 	constructor(options) {
 		this.options = options;
 		this.client = new MongoClient(options.uri, options.clientOptions);
-		for (const [name, schema] of Object.entries(options.schema ?? {})) {
+		for (const [name, schema] of Object.entries(options.schemas ?? {})) {
 			this.registerSchema(schema, name);
 			let model;
 			Object.defineProperty(this, name, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mongorm/orm",
-  "version": "0.1.1-beta.4",
+  "version": "0.1.1",
   "description": "A TypeScript-first MongoDB ORM for applications that want strong types without hiding MongoDB",
   "keywords": [
     "mongodb",