@web-ts-toolkit/moo 0.43.0 → 0.47.1

package/plugins/cascade-delete.d.mts

@@ -1,14 +1,58 @@
 import { Schema } from 'mongoose';
 
-type QueryFilter<TDocument extends Record<string, unknown> = Record<string, unknown>> = Partial<TDocument> & Record<string, unknown>;
+/**
+ * MongoDB query operators accepted for a single document field in
+ * {@link QueryFilter}. The runtime forwards relationship and full filters
+ * straight to Mongoose `find()`, so operator objects (for example
+ * `{ price: { $gt: 5 } }`) are evaluated by MongoDB rather than by this
+ * package. Each field therefore accepts either its plain document value or
+ * an operator object; top-level logical operators (`$and`/`$or`/`$not`/`$nor`)
+ * remain available through the trailing `Record<string, unknown>` index.
+ */
+type QueryOperators<TValue = unknown> = {
+    $eq?: TValue;
+    $ne?: TValue;
+    $gt?: TValue;
+    $gte?: TValue;
+    $lt?: TValue;
+    $lte?: TValue;
+    $in?: TValue[];
+    $nin?: TValue[];
+    $exists?: boolean;
+    $regex?: string | RegExp;
+    $type?: string | string[];
+    $not?: QueryOperators<TValue> | RegExp;
+    $size?: number;
+    $all?: TValue[];
+    $elemMatch?: Record<string, unknown>;
+};
+/**
+ * Typed dependent-collection filter. Each declared document field accepts its
+ * plain value, a {@link QueryOperators} object, or `null`; undeclared paths
+ * (including `$and`/`$or` operator payloads composed by
+ * `extraForeignFilter`) are accepted through the index signature and passed
+ * to Mongoose unchanged.
+ */
+type QueryFilter<TDocument extends Record<string, unknown> = Record<string, unknown>> = {
+    [K in keyof TDocument]?: TDocument[K] | QueryOperators<TDocument[K]> | null;
+} & Record<string, unknown>;
+/**
+ * Dependents grouped by configured model name. The no-argument
+ * `findDependents()`/`findOrphans()` overloads return a `Partial` map:
+ * entries whose lookup is unsupported (for example `findOrphans()` for a
+ * non-`_id` local key, dotted foreign path, dynamic `refPath`, or
+ * `foreignFilter`-only relationship) or whose resolver produced a
+ * nullish/non-object result are omitted rather than reported as empty
+ * arrays, matching the `mergeResults` runtime behavior.
+ */
 type CascadeDeleteDependencyMap<TModelName extends string, TDependentDocument = unknown> = Record<TModelName, TDependentDocument[]>;
 type CascadeDeleteDocumentMethods<TModelName extends string, TDependentDocument = unknown> = {
-    findDependents(): Promise<CascadeDeleteDependencyMap<TModelName, TDependentDocument> & Record<string, unknown[]>>;
+    findDependents(): Promise<Partial<CascadeDeleteDependencyMap<TModelName, TDependentDocument>> & Record<string, unknown[]>>;
     findDependents(modelName: TModelName): Promise<TDependentDocument[]>;
     findDependents(modelName: string): Promise<unknown[] | null>;
 };
 type CascadeDeleteModelStatics<TModelName extends string, TDependentDocument = unknown> = {
-    findOrphans(): Promise<CascadeDeleteDependencyMap<TModelName, TDependentDocument> & Record<string, unknown[]>>;
+    findOrphans(): Promise<Partial<CascadeDeleteDependencyMap<TModelName, TDependentDocument>> & Record<string, unknown[]>>;
     findOrphans(modelName: TModelName): Promise<TDependentDocument[] | null>;
     findOrphans(modelName: string): Promise<unknown[] | null>;
 };
@@ -19,7 +63,110 @@ interface CascadeDeletePluginOptions<TModelName extends string = string, TDepend
     foreignField?: string;
     foreignFilter?: FilterResolver<TDependentDocument>;
     extraForeignFilter?: FilterResolver<TDependentDocument>;
+    /**
+     * Maximum dependent deletes allowed in flight at once for this relationship.
+     * Must be an integer >= 1. Defaults to 8. Inside an active transaction the
+     * effective limit is forced to 1 (MOO-04 serialization) regardless of this
+     * value. Public `findDependents()` is unaffected: it still returns an array.
+     */
+    maxConcurrency?: number;
+    /**
+     * Maximum dependent `_id`s acquired per internal ID-page query. Must be an
+     * integer >= 1. Defaults to 100. Bounds acquisition memory; deletion work is
+     * never all materialized or scheduled up front.
+     */
+    batchSize?: number;
 }
+/**
+ * Cascades document `deleteOne()` to configured dependent models.
+ *
+ * Supported operations: only document `deleteOne()` (and legacy document
+ * `remove()` for dependents) is intercepted, through
+ * `pre('deleteOne', { document: true, query: false })` and
+ * `post('deleteOne', { document: true, query: false })`. Query helpers such
+ * as `deleteMany()`, `findOneAndDelete()`, `updateOne()`, and query
+ * `deleteOne()` bypass the cascade entirely. `findDependents()` is a
+ * document method; `findOrphans()` is a model static with the support matrix
+ * documented on {@link CascadeDeleteDependencyMap} (unsupported shapes
+ * resolve to `null` and are omitted from the no-argument map).
+ *
+ * Post-delete failure timing: the `post('deleteOne')` hook runs after the
+ * parent document is already removed. A later dependent failure therefore
+ * rejects the parent `deleteOne()` promise without restoring the parent —
+ * see the traversal contract below for the transactional abort path.
+ *
+ * Supported behavior: dependent models resolve through the owning model's
+ * connection (duplicate names on other connections stay isolated); the
+ * effective session (explicit `deleteOne({ session })` option, else the
+ * document-bound `$session()`) flows through dependent reads and deletes,
+ * including nested cascades; inside an active transaction dependent deletes run
+ * serially on that session so replica-set commit/abort covers parent and
+ * dependents together. Unsupported modes fail before the parent is removed: a
+ * session from a different connection/client, or an active transaction on a
+ * standalone (`Single`) topology.
+ *
+ * Predicate fail-closed contract (MOO-05):
+ *
+ * - Relationship mode (`localField` + `foreignField`) never issues a
+ *   destructive query without a valid relationship. Missing/`null`/empty
+ *   local keys (including empty reference arrays and arrays containing only
+ *   nullish entries) resolve to zero dependents and delete nothing, so
+ *   unrelated records with a missing/`null` foreign key survive. A local field
+ *   that was omitted by a projection is distinguished from an intentionally
+ *   empty relation: when the path is provably deselected (`$isSelected()`
+ *   returns `false`) the lookup throws instead of silently reporting zero
+ *   dependents.
+ * - Supplemental `extraForeignFilter` constraints are composed conjunctively
+ *   (`{ $and: [relationship, extra] }`). An extra filter on the relationship
+ *   field therefore intersects instead of replacing or widening the deletion
+ *   set; `$or`/`$and`/operator payloads inside the extra filter stay
+ *   constrained by the relationship predicate. An absent, nullish,
+ *   non-object, or empty extra filter leaves the relationship unchanged.
+ * - Explicit full-filter mode (`foreignFilter`) is a separately documented
+ *   contract: the resolved filter is used as-is with no relationship
+ *   predicate, and any configured `extraForeignFilter` is ignored. A resolver
+ *   returning `null`/`undefined`/non-object resolves to zero dependents.
+ *   Maintainer decision: an intentionally empty full filter (`{}`) is rejected
+ *   by default — statically at `schema.plugin(...)` time and dynamically when
+ *   a resolver returns `{}` — because it would match the whole dependent
+ *   collection. There is currently no broad-delete opt-in flag.
+ * - Option validation runs at `schema.plugin(...)` time: `model` must be a
+ *   non-empty string, relationship mode requires both `localField` and
+ *   `foreignField`, static `foreignFilter`/`extraForeignFilter` values must be
+ *   plain objects (or resolver functions), and a static empty `foreignFilter`
+ *   throws. Invalid runtime resolver results fail closed as described above.
+ *
+ * Traversal/bounds contract (MOO-06):
+ *
+ * - Deletion never uses bulk writes: every dependent is removed through its
+ *   own hydrated document `deleteOne()` (or legacy `remove()`), so nested
+ *   cascade middleware and custom document hooks always run with full field
+ *   state. Public `findDependents()` keeps its array-returning API for
+ *   convenience; internal deletion traversal pages `_id`s (`batchSize`,
+ *   default 100) and loads full documents per page instead.
+ * - In-flight deletes are bounded by `maxConcurrency` (default 8, integer
+ *   >= 1). Inside an active transaction the effective limit is forced to 1 to
+ *   preserve MOO-04 serialization. No new deletes start after the first
+ *   failure (fail-fast).
+ * - Partial failure: `post('deleteOne')` runs after the parent is already
+ *   removed. Outside a transaction a dependent failure rejects the parent
+ *   `deleteOne()` promise but cannot restore the parent or already-deleted
+ *   dependents; remaining batches are never fetched. Inside a transaction the
+ *   caller observes the rejection before commit and can abort to restore
+ *   parent and dependents together. A dependent row that is already gone when
+ *   re-loaded (concurrent diamond, delayed retry) is skipped, not treated as
+ *   a failure.
+ * - Repeated references to the same `_id` within one relationship delete that
+ *   row once per level (deduplicated by `_id`). Diamonds (two middles sharing
+ *   one leaf) and cycles (A <-> B) always terminate: deletions are monotonic
+ *   (deleted rows never reappear in later pages/levels) and every level
+ *   re-queries live state, so already-deleted parents resolve to zero further
+ *   dependents. Cross-level diamonds run leaf hooks at least once; concurrent
+ *   copies may each fire leaf middleware before either observes the other's
+ *   delete (at-least-once, never suppressed via bulk paths). No performance
+ *   claim beyond the measured fan-out experiment recorded with the tests is
+ *   made here.
+ */
 declare function cascadeDeletePlugin<TModelName extends string = string, TDependentDocument extends Record<string, unknown> = Record<string, unknown>>(schema: Schema, options: CascadeDeletePluginOptions<TModelName, TDependentDocument>): void;
 
-export { type CascadeDeleteDependencyMap, type CascadeDeleteDocumentMethods, type CascadeDeleteModelStatics, type CascadeDeletePluginOptions, type FilterResolver, type QueryFilter, cascadeDeletePlugin };
+export { type CascadeDeleteDependencyMap, type CascadeDeleteDocumentMethods, type CascadeDeleteModelStatics, type CascadeDeletePluginOptions, type FilterResolver, type QueryFilter, type QueryOperators, cascadeDeletePlugin };

package/plugins/cascade-delete.d.ts

@@ -1,14 +1,58 @@
 import { Schema } from 'mongoose';
 
-type QueryFilter<TDocument extends Record<string, unknown> = Record<string, unknown>> = Partial<TDocument> & Record<string, unknown>;
+/**
+ * MongoDB query operators accepted for a single document field in
+ * {@link QueryFilter}. The runtime forwards relationship and full filters
+ * straight to Mongoose `find()`, so operator objects (for example
+ * `{ price: { $gt: 5 } }`) are evaluated by MongoDB rather than by this
+ * package. Each field therefore accepts either its plain document value or
+ * an operator object; top-level logical operators (`$and`/`$or`/`$not`/`$nor`)
+ * remain available through the trailing `Record<string, unknown>` index.
+ */
+type QueryOperators<TValue = unknown> = {
+    $eq?: TValue;
+    $ne?: TValue;
+    $gt?: TValue;
+    $gte?: TValue;
+    $lt?: TValue;
+    $lte?: TValue;
+    $in?: TValue[];
+    $nin?: TValue[];
+    $exists?: boolean;
+    $regex?: string | RegExp;
+    $type?: string | string[];
+    $not?: QueryOperators<TValue> | RegExp;
+    $size?: number;
+    $all?: TValue[];
+    $elemMatch?: Record<string, unknown>;
+};
+/**
+ * Typed dependent-collection filter. Each declared document field accepts its
+ * plain value, a {@link QueryOperators} object, or `null`; undeclared paths
+ * (including `$and`/`$or` operator payloads composed by
+ * `extraForeignFilter`) are accepted through the index signature and passed
+ * to Mongoose unchanged.
+ */
+type QueryFilter<TDocument extends Record<string, unknown> = Record<string, unknown>> = {
+    [K in keyof TDocument]?: TDocument[K] | QueryOperators<TDocument[K]> | null;
+} & Record<string, unknown>;
+/**
+ * Dependents grouped by configured model name. The no-argument
+ * `findDependents()`/`findOrphans()` overloads return a `Partial` map:
+ * entries whose lookup is unsupported (for example `findOrphans()` for a
+ * non-`_id` local key, dotted foreign path, dynamic `refPath`, or
+ * `foreignFilter`-only relationship) or whose resolver produced a
+ * nullish/non-object result are omitted rather than reported as empty
+ * arrays, matching the `mergeResults` runtime behavior.
+ */
 type CascadeDeleteDependencyMap<TModelName extends string, TDependentDocument = unknown> = Record<TModelName, TDependentDocument[]>;
 type CascadeDeleteDocumentMethods<TModelName extends string, TDependentDocument = unknown> = {
-    findDependents(): Promise<CascadeDeleteDependencyMap<TModelName, TDependentDocument> & Record<string, unknown[]>>;
+    findDependents(): Promise<Partial<CascadeDeleteDependencyMap<TModelName, TDependentDocument>> & Record<string, unknown[]>>;
     findDependents(modelName: TModelName): Promise<TDependentDocument[]>;
     findDependents(modelName: string): Promise<unknown[] | null>;
 };
 type CascadeDeleteModelStatics<TModelName extends string, TDependentDocument = unknown> = {
-    findOrphans(): Promise<CascadeDeleteDependencyMap<TModelName, TDependentDocument> & Record<string, unknown[]>>;
+    findOrphans(): Promise<Partial<CascadeDeleteDependencyMap<TModelName, TDependentDocument>> & Record<string, unknown[]>>;
     findOrphans(modelName: TModelName): Promise<TDependentDocument[] | null>;
     findOrphans(modelName: string): Promise<unknown[] | null>;
 };
@@ -19,7 +63,110 @@ interface CascadeDeletePluginOptions<TModelName extends string = string, TDepend
     foreignField?: string;
     foreignFilter?: FilterResolver<TDependentDocument>;
     extraForeignFilter?: FilterResolver<TDependentDocument>;
+    /**
+     * Maximum dependent deletes allowed in flight at once for this relationship.
+     * Must be an integer >= 1. Defaults to 8. Inside an active transaction the
+     * effective limit is forced to 1 (MOO-04 serialization) regardless of this
+     * value. Public `findDependents()` is unaffected: it still returns an array.
+     */
+    maxConcurrency?: number;
+    /**
+     * Maximum dependent `_id`s acquired per internal ID-page query. Must be an
+     * integer >= 1. Defaults to 100. Bounds acquisition memory; deletion work is
+     * never all materialized or scheduled up front.
+     */
+    batchSize?: number;
 }
+/**
+ * Cascades document `deleteOne()` to configured dependent models.
+ *
+ * Supported operations: only document `deleteOne()` (and legacy document
+ * `remove()` for dependents) is intercepted, through
+ * `pre('deleteOne', { document: true, query: false })` and
+ * `post('deleteOne', { document: true, query: false })`. Query helpers such
+ * as `deleteMany()`, `findOneAndDelete()`, `updateOne()`, and query
+ * `deleteOne()` bypass the cascade entirely. `findDependents()` is a
+ * document method; `findOrphans()` is a model static with the support matrix
+ * documented on {@link CascadeDeleteDependencyMap} (unsupported shapes
+ * resolve to `null` and are omitted from the no-argument map).
+ *
+ * Post-delete failure timing: the `post('deleteOne')` hook runs after the
+ * parent document is already removed. A later dependent failure therefore
+ * rejects the parent `deleteOne()` promise without restoring the parent —
+ * see the traversal contract below for the transactional abort path.
+ *
+ * Supported behavior: dependent models resolve through the owning model's
+ * connection (duplicate names on other connections stay isolated); the
+ * effective session (explicit `deleteOne({ session })` option, else the
+ * document-bound `$session()`) flows through dependent reads and deletes,
+ * including nested cascades; inside an active transaction dependent deletes run
+ * serially on that session so replica-set commit/abort covers parent and
+ * dependents together. Unsupported modes fail before the parent is removed: a
+ * session from a different connection/client, or an active transaction on a
+ * standalone (`Single`) topology.
+ *
+ * Predicate fail-closed contract (MOO-05):
+ *
+ * - Relationship mode (`localField` + `foreignField`) never issues a
+ *   destructive query without a valid relationship. Missing/`null`/empty
+ *   local keys (including empty reference arrays and arrays containing only
+ *   nullish entries) resolve to zero dependents and delete nothing, so
+ *   unrelated records with a missing/`null` foreign key survive. A local field
+ *   that was omitted by a projection is distinguished from an intentionally
+ *   empty relation: when the path is provably deselected (`$isSelected()`
+ *   returns `false`) the lookup throws instead of silently reporting zero
+ *   dependents.
+ * - Supplemental `extraForeignFilter` constraints are composed conjunctively
+ *   (`{ $and: [relationship, extra] }`). An extra filter on the relationship
+ *   field therefore intersects instead of replacing or widening the deletion
+ *   set; `$or`/`$and`/operator payloads inside the extra filter stay
+ *   constrained by the relationship predicate. An absent, nullish,
+ *   non-object, or empty extra filter leaves the relationship unchanged.
+ * - Explicit full-filter mode (`foreignFilter`) is a separately documented
+ *   contract: the resolved filter is used as-is with no relationship
+ *   predicate, and any configured `extraForeignFilter` is ignored. A resolver
+ *   returning `null`/`undefined`/non-object resolves to zero dependents.
+ *   Maintainer decision: an intentionally empty full filter (`{}`) is rejected
+ *   by default — statically at `schema.plugin(...)` time and dynamically when
+ *   a resolver returns `{}` — because it would match the whole dependent
+ *   collection. There is currently no broad-delete opt-in flag.
+ * - Option validation runs at `schema.plugin(...)` time: `model` must be a
+ *   non-empty string, relationship mode requires both `localField` and
+ *   `foreignField`, static `foreignFilter`/`extraForeignFilter` values must be
+ *   plain objects (or resolver functions), and a static empty `foreignFilter`
+ *   throws. Invalid runtime resolver results fail closed as described above.
+ *
+ * Traversal/bounds contract (MOO-06):
+ *
+ * - Deletion never uses bulk writes: every dependent is removed through its
+ *   own hydrated document `deleteOne()` (or legacy `remove()`), so nested
+ *   cascade middleware and custom document hooks always run with full field
+ *   state. Public `findDependents()` keeps its array-returning API for
+ *   convenience; internal deletion traversal pages `_id`s (`batchSize`,
+ *   default 100) and loads full documents per page instead.
+ * - In-flight deletes are bounded by `maxConcurrency` (default 8, integer
+ *   >= 1). Inside an active transaction the effective limit is forced to 1 to
+ *   preserve MOO-04 serialization. No new deletes start after the first
+ *   failure (fail-fast).
+ * - Partial failure: `post('deleteOne')` runs after the parent is already
+ *   removed. Outside a transaction a dependent failure rejects the parent
+ *   `deleteOne()` promise but cannot restore the parent or already-deleted
+ *   dependents; remaining batches are never fetched. Inside a transaction the
+ *   caller observes the rejection before commit and can abort to restore
+ *   parent and dependents together. A dependent row that is already gone when
+ *   re-loaded (concurrent diamond, delayed retry) is skipped, not treated as
+ *   a failure.
+ * - Repeated references to the same `_id` within one relationship delete that
+ *   row once per level (deduplicated by `_id`). Diamonds (two middles sharing
+ *   one leaf) and cycles (A <-> B) always terminate: deletions are monotonic
+ *   (deleted rows never reappear in later pages/levels) and every level
+ *   re-queries live state, so already-deleted parents resolve to zero further
+ *   dependents. Cross-level diamonds run leaf hooks at least once; concurrent
+ *   copies may each fire leaf middleware before either observes the other's
+ *   delete (at-least-once, never suppressed via bulk paths). No performance
+ *   claim beyond the measured fan-out experiment recorded with the tests is
+ *   made here.
+ */
 declare function cascadeDeletePlugin<TModelName extends string = string, TDependentDocument extends Record<string, unknown> = Record<string, unknown>>(schema: Schema, options: CascadeDeletePluginOptions<TModelName, TDependentDocument>): void;
 
-export { type CascadeDeleteDependencyMap, type CascadeDeleteDocumentMethods, type CascadeDeleteModelStatics, type CascadeDeletePluginOptions, type FilterResolver, type QueryFilter, cascadeDeletePlugin };
+export { type CascadeDeleteDependencyMap, type CascadeDeleteDocumentMethods, type CascadeDeleteModelStatics, type CascadeDeletePluginOptions, type FilterResolver, type QueryFilter, type QueryOperators, cascadeDeletePlugin };