akanjs 3.0.0-alpha.1 → 3.0.0-alpha.2

package/base/symbols.ts

@@ -3,6 +3,7 @@ export const SLICE_META = Symbol.for("akan.slice");
 export const FILTER_META = Symbol.for("akan.filter");
 export const LOADER_META = Symbol.for("akan.loader");
 export const INJECT_META = Symbol.for("akan.inject");
+export const LIBS_REMOVE_HOOK = Symbol.for("akan.service.libsRemoveHook");
 export const ENDPOINT_META = Symbol.for("akan.endpoint");
 export const ENDPOINT_DICT_SHAPE: unique symbol = Symbol.for("akan.endpoint.dictShape") as never;
 export const SLICE_DICT_SHAPE: unique symbol = Symbol.for("akan.slice.dictShape") as never;

package/constant/cascadePaths.ts

@@ -1,32 +1,103 @@
+import { type Cls, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
 import type { ConstantField, FieldObject } from "./fieldInfo";
 import type { ConstantModelRef } from "./via";
 
-/** What happens to the documents a relation field points at when the owner is removed. */
-export const cascadeActions = ["remove"] as const;
+/**
+ * Which end of a relation goes away with the other. `removeRef` removes what the field points at when this
+ * document is removed; `removeWith` removes this document when what the field points at is removed. The two
+ * read identically on a relation field, so the value has to name the direction — a mistake here is a data loss.
+ */
+export const cascadeActions = ["removeRef", "removeWith"] as const;
 export type CascadeAction = (typeof cascadeActions)[number];
 
+/** How a `removeWith` field names the owner whose removal takes this document with it. */
+export interface CascadeWithPath {
+  readonly key: string;
+  /** Set when the field is a relation. Resolved to a refName later: the owner may not be registered yet. */
+  readonly modelRef: ConstantModelRef | null;
+  /** Set when the field declares `ref`, which names the owner at declaration. */
+  readonly refName: string | null;
+  /** Set when the field declares `refPath`: the sibling field holding the owner's refName. */
+  readonly typeKey: string | null;
+  /** The refNames `typeKey` may hold. Empty unless the field is polymorphic. */
+  readonly typeValues: readonly string[];
+}
+
+const idNames = new Set(["ID", "String"]);
+
 export class CascadePaths {
-  /** Field key → the model its ids point at. Resolved to a refName later: the target may not be registered yet. */
-  readonly remove = new Map<string, ConstantModelRef>();
+  /** Field key → the model its ids point at, removed when this document is. */
+  readonly removeRef = new Map<string, ConstantModelRef>();
+  /** Field key → the owner whose removal removes this document. */
+  readonly removeWith = new Map<string, CascadeWithPath>();
 
   collect(fieldMap: FieldObject) {
     for (const [key, field] of Object.entries(fieldMap)) {
       if (!field.cascade) continue;
-      this.#assertCascadable(key, field.cascade, field);
-      this.remove.set(key, field.modelRef);
+      this.#assertKnownAction(key, field.cascade);
+      if (field.cascade === "removeRef") this.removeRef.set(key, this.#readOwnedRelation(key, field));
+      else this.removeWith.set(key, this.#readOwnerPath(key, field, fieldMap));
     }
     return this;
   }
 
-  #assertCascadable(key: string, action: CascadeAction, field: ConstantField) {
-    
+  #assertKnownAction(key: string, action: CascadeAction) {
+
     if (!cascadeActions.includes(action)) {
       throw new Error(`Cascade field "${key}" declares cascade: "${action}", which is not one of ${cascadeActions}`);
     }
+  }
+
+  #readOwnedRelation(key: string, field: ConstantField) {
     
     if (!field.isClass || field.isScalar) {
       throw new Error(`Cascade field "${key}" is not a model reference and has no document to remove`);
     }
     if (field.arrDepth > 1) throw new Error(`Cascade field "${key}" is a nested array and cannot cascade`);
+    return field.modelRef;
+  }
+
+  #readOwnerPath(key: string, field: ConstantField, fieldMap: FieldObject): CascadeWithPath {
+
+    if (field.arrDepth > 0) throw new Error(`Cascade field "${key}" is an array and names more than one owner`);
+    if (field.isMap) throw new Error(`Cascade field "${key}" is a Map and names no owner`);
+    if (field.refPath) return this.#readPolymorphicOwner(key, field, fieldMap);
+    if (field.ref) {
+      this.#assertHoldsId(key, field);
+      return { key, modelRef: null, refName: field.ref, typeKey: null, typeValues: [] };
+    }
+    if (field.isClass && !field.isScalar) {
+      return { key, modelRef: field.modelRef, refName: null, typeKey: null, typeValues: [] };
+    }
+    throw new Error(
+      `Cascade field "${key}" declares cascade: "removeWith" but names no owner; make it a model reference, ` +
+        `or add ref: "<model>" / refPath: "<typeField>"`,
+    );
+  }
+
+  #readPolymorphicOwner(key: string, field: ConstantField, fieldMap: FieldObject): CascadeWithPath {
+    if (field.ref) throw new Error(`Cascade field "${key}" declares both ref and refPath; keep one`);
+    this.#assertHoldsId(key, field);
+    const typeKey = field.refPath as string;
+    const typeField = fieldMap[typeKey];
+    if (!typeField) throw new Error(`Cascade field "${key}" declares refPath: "${typeKey}", which is not a field`);
+
+    if (!typeField.enum) {
+      throw new Error(
+        `Cascade field "${key}" declares refPath: "${typeKey}", which must be an enumOf(...) naming the owner ` +
+          `refNames it may hold`,
+      );
+    }
+    const typeValues = typeField.enum.values.map((value) => String(value));
+    return { key, modelRef: null, refName: null, typeKey, typeValues };
+  }
+
+  #assertHoldsId(key: string, field: ConstantField) {
+    const modelRef = field.modelRef as unknown as Cls;
+    const refName = PrimitiveRegistry.has(modelRef)
+      ? PrimitiveRegistry.getName(modelRef as unknown as typeof PrimitiveScalar)
+      : null;
+    if (refName && idNames.has(refName)) return;
+    throw new Error(`Cascade field "${key}" declares ref or refPath and must hold an ID`);
   }
 }

package/document/database.ts

@@ -4,7 +4,7 @@ import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { CacheAdaptor, CacheSetOptions } from "akanjs/service";
 import type { DataLoader } from "./dataLoader";
 import type { ExtractQuery, ExtractSort, FilterInstance } from "./filterMeta";
-import type { CRUDEventType, Mdl, SaveEventType } from "./into";
+import type { CRUDEventType, Mdl, SaveEventType, UpdateResult } from "./into";
 import type { DataInputOf, FindQueryOption, ListQueryOption } from "./types";
 
 export class CacheDatabase<T = unknown> {
@@ -105,6 +105,7 @@ type DatabaseModelWithQuerySort<
   __create: (data: _DataInput) => Promise<Doc>;
   __update: (id: string, data: Partial<Doc>) => Promise<Doc>;
   __remove: (id: string) => Promise<Doc>;
+  __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
   __list(query: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
   __listIds(query: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
   __find(query: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;

package/document/databaseRegistry.ts

@@ -19,7 +19,7 @@ export interface DatabaseModel<
   model: ModelCls<Model>;
   filter: FilterCls<Filter>;
   obj: ConstantCls<Obj>;
-  insight: ConstantCls<Insight>;
+  insight: DatabaseCls<Insight>;
   _Input: Input;
   _Doc: Doc;
   _Model: Model;
@@ -92,7 +92,7 @@ export class DatabaseRegistry {
     doc: DatabaseCls<Doc>,
     model: ModelCls<Model>,
     obj: ConstantCls<Obj>,
-    insight: ConstantCls<Insight>,
+    insight: DatabaseCls<Insight>,
     filter: FilterCls<Filter>,
   ): DatabaseModel<T, Input, Doc, Model, Obj, Insight, Filter, _Query, _Sort> {
     const dbInfo = {

package/document/into.ts

@@ -85,14 +85,15 @@ export type Mdl<
     options?: DocumentUpdateOptions,
   ): Promise<UpdateResult>;
   updateMany(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>): Promise<UpdateResult>;
-  deleteMany(query: _RawQuery): Promise<UpdateResult>;
+  removeMany(query: _RawQuery): Promise<UpdateResult>;
   bulkWrite(operations: BulkWriteOperation<Raw, _RawDoc, _RawQuery>[]): Promise<UpdateResult>;
 };
 
-interface IntoConstantModel<T extends string, _CapitalizedRefName extends string, Raw> {
+interface IntoConstantModel<T extends string, _CapitalizedRefName extends string, Raw, Insight> {
   refName: T;
   _CapitalizedRefName: _CapitalizedRefName;
   _Full: Raw;
+  _Insight: Insight;
 }
 type NoInferType<T> = [T][T extends unknown ? 0 : never];
 type IntoModelActions<
@@ -100,6 +101,8 @@ type IntoModelActions<
   _CapitalizedRefName extends string,
   Doc,
   Raw,
+  
+  Insight,
   _Query,
   _Sort,
   _QueryOfDoc = QueryOf<Doc>,
@@ -121,13 +124,14 @@ type IntoModelActions<
   [K in `update${_CapitalizedRefName}`]: (id: string, data: Partial<Doc>) => Promise<Doc>;
 } & {
   [K in `remove${_CapitalizedRefName}`]: (id: string) => Promise<Doc>;
-} & QueryMethodPart<_Query, _Sort, Raw, Doc, unknown, unknown, unknown, _QueryOfDoc>;
+} & QueryMethodPart<_Query, _Sort, Raw, Doc, DocumentModel<Insight>, unknown, unknown, _QueryOfDoc>;
 
 export const into = <
   Doc,
   FilterRef extends FilterCls,
   T extends string,
   Raw,
+  Insight,
   AddDbModels extends ModelCls[],
   _CapitalizedRefName extends string,
   _QueryOfDoc = QueryOf<Doc>,
@@ -137,11 +141,11 @@ export const into = <
 >(
   docRef: Cls<Doc>,
   filterRef: FilterRef,
-  cnst: IntoConstantModel<T, _CapitalizedRefName, Raw>,
+  cnst: IntoConstantModel<T, _CapitalizedRefName, Raw, Insight>,
   loaderBuilder: _LoaderBuilder,
   ...addMdls: [...AddDbModels]
 ): ModelCls<
-  IntoModelActions<T, _CapitalizedRefName, Doc, Raw, _Query, _Sort, _QueryOfDoc>,
+  IntoModelActions<T, _CapitalizedRefName, Doc, Raw, Insight, _Query, _Sort, _QueryOfDoc>,
   ReturnType<_LoaderBuilder>
 > => {
   const loaderInfoMap = loaderBuilder(makeLoaderBuilder<Doc>());
@@ -162,7 +166,7 @@ export const into = <
     });
   });
   return DefaultModel as unknown as ModelCls<
-    IntoModelActions<T, _CapitalizedRefName, Doc, Raw, _Query, _Sort, _QueryOfDoc>,
+    IntoModelActions<T, _CapitalizedRefName, Doc, Raw, Insight, _Query, _Sort, _QueryOfDoc>,
     ReturnType<_LoaderBuilder>
   >;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/di/diLifecycle.ts

@@ -21,7 +21,7 @@ import { SignalRegistry } from "../../signal/signalRegistry";
 import type { AkanLib, DatabaseModule, ScalarModule, ServiceModule } from "../akanLib";
 import { createDefaultAkanOption } from "../akanOption";
 import type { WebProxyRegistration } from "../proxy";
-import { DatabaseResolver, ServiceResolver, SignalResolver } from "../resolver";
+import { CascadeRunner, DatabaseResolver, ServiceResolver, SignalResolver } from "../resolver";
 import type { SignalRoutes, WebsocketRoutes } from "../types";
 import { getPredefinedAdaptor, predefinedAdaptorRole } from "./predefinedAdaptor";
 import { collectAdaptors, resolveAdaptorHierarchy } from "./resolveAdaptorHierarchy";
@@ -63,6 +63,7 @@ export class DiLifecycle {
   readonly disabledModules = new Map<string, string>();
   readonly #predefinedAdaptor;
   readonly #predefinedAdaptorRole = predefinedAdaptorRole;
+  readonly #cascade = new CascadeRunner();
 
   /** Read-only view of the resolved module maps, for tooling that needs to describe the container. */
   get modules(): {
@@ -122,8 +123,9 @@ export class DiLifecycle {
       this.#service.set(refName, module as ServiceModule);
     });
     this.#database.forEach((mod) => {
-      const databaseAdaptor = DatabaseResolver.resolveDatabase(mod.constant, mod.database);
-      this.#adaptor.set(databaseAdaptor.refName, databaseAdaptor);
+      const { adaptor, schema } = DatabaseResolver.resolveDatabase(mod.constant, mod.database);
+      this.#adaptor.set(adaptor.refName, adaptor);
+      this.#cascade.register(mod.constant, schema, mod.service.srv);
     });
     const services = [
       ...[...this.#service.values()].map((mod) => mod.service.srv),
@@ -457,13 +459,7 @@ export class DiLifecycle {
             if (serviceCls.type === "database") {
               const databaseModule = this.#database.get(serviceCls.refName);
               if (!databaseModule) throw new Error(`Database "${serviceCls.refName}" is not registered`);
-              ServiceResolver.resolveDatabaseService(
-                databaseModule.constant,
-                databaseModule.database,
-                serviceCls,
-
-                (refName) => this.getService(refName),
-              );
+              ServiceResolver.resolveDatabaseService(databaseModule.database, serviceCls, this.#cascade);
             }
             const service = new serviceCls();
             await InjectInfo.resolveInjection(service, serviceCls, this.registry, this.#env);
@@ -476,6 +472,8 @@ export class DiLifecycle {
         })),
       );
     }
+
+    this.#cascade.seal((refName) => this.getService(refName));
   }
 
   async #initializeInternal() {

package/server/resolver/CascadeRunner.ts

@@ -0,0 +1,201 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { LIBS_REMOVE_HOOK } from "akanjs/base";
+import { Logger } from "akanjs/common";
+import { type CascadeWithPath, type ConstantModel, ConstantRegistry } from "akanjs/constant";
+import { type DocumentSchema, documentQueryHelper } from "akanjs/document";
+import type { DatabaseService, ServiceCls } from "akanjs/service";
+
+/** A relation the removed document owns: the ids it holds name documents to remove. */
+interface RefEdge {
+  readonly key: string;
+  readonly refName: string;
+}
+
+/** A model that declared itself removable with this one: its rows name the removed document as their owner. */
+interface WithEdge {
+  readonly refName: string;
+  readonly key: string;
+  readonly typeKey: string | null;
+}
+
+interface CascadeModule {
+  readonly constant: ConstantModel;
+  readonly schema: DocumentSchema;
+  readonly srvRef: ServiceCls;
+}
+
+interface CascadePlan {
+  readonly refEdges: RefEdge[];
+  readonly withEdges: WithEdge[];
+}
+
+/** One cascade in flight. Shared down the chain so a cycle is caught wherever it closes. */
+interface CascadeContext {
+  readonly seen: Set<string>;
+  readonly depth: number;
+}
+
+/** How deep one removal may cascade before the chain is treated as runaway and abandoned. */
+const maxDepth = 16;
+/** Ids taken per query while draining children one document at a time. */
+const drainSize = 200;
+
+export class CascadeRunner {
+  readonly #modules = new Map<string, CascadeModule>();
+  readonly #plans = new Map<string, CascadePlan>();
+  readonly #bulk = new Set<string>();
+  readonly #context = new AsyncLocalStorage<CascadeContext>();
+  readonly #logger = new Logger("Cascade");
+  #getService: ((refName: string) => DatabaseService) | null = null;
+
+  register(constant: ConstantModel, schema: DocumentSchema, srvRef: ServiceCls) {
+    this.#modules.set(constant.refName, { constant, schema, srvRef });
+  }
+
+  /**
+   * Called once every service is live. A `_postRemove` and a `listenPost("remove")` registered during boot both
+   * count against bulk removal, so the strategy cannot be decided before the last service has initialized.
+   */
+  seal(getService: (refName: string) => DatabaseService) {
+    this.#getService = getService;
+    for (const [refName, mod] of this.#modules) {
+      this.#plans.set(refName, { refEdges: this.#collectRefEdges(refName, mod), withEdges: [] });
+    }
+    for (const [refName, mod] of this.#modules) this.#collectWithEdges(refName, mod);
+    for (const refName of this.#modules.keys()) {
+      if (this.#hasRemoveSideEffect(refName)) continue;
+      this.#bulk.add(refName);
+    }
+    this.#report();
+  }
+
+  async run(refName: string, doc: Record<string, unknown>) {
+    const plan = this.#plans.get(refName);
+    if (!plan?.refEdges.length && !plan?.withEdges.length) return;
+    const parent = this.#context.getStore();
+    const seen = parent?.seen ?? new Set<string>();
+    const depth = (parent?.depth ?? 0) + 1;
+    const id = typeof doc.id === "string" ? doc.id : null;
+    if (id) seen.add(`${refName}:${id}`);
+    if (depth > maxDepth) {
+      this.#logger.error(`Cascade from ${refName} exceeded depth ${maxDepth} and was abandoned`);
+      return;
+    }
+    await this.#context.run({ seen, depth }, async () => {
+      for (const edge of plan.refEdges) await this.#removeRef(edge, doc, seen);
+      if (id) for (const edge of plan.withEdges) await this.#removeWith(edge, refName, id, seen);
+    });
+  }
+
+  async #removeRef(edge: RefEdge, doc: Record<string, unknown>, seen: Set<string>) {
+    const value = doc[edge.key];
+    const ids = (Array.isArray(value) ? value : [value]).filter(
+      (item): item is string => typeof item === "string" && !seen.has(`${edge.refName}:${item}`),
+    );
+    if (!ids.length) return;
+    const service = this.#service(edge.refName);
+    if (this.#bulk.has(edge.refName)) {
+      await service.__removeMany({ id: documentQueryHelper.oneOf(ids) });
+      return;
+    }
+
+    for (const id of ids) await service.__remove(id);
+  }
+
+  async #removeWith(edge: WithEdge, ownerRef: string, ownerId: string, seen: Set<string>) {
+    const service = this.#service(edge.refName);
+    const query = edge.typeKey ? { [edge.key]: ownerId, [edge.typeKey]: ownerRef } : { [edge.key]: ownerId };
+    if (this.#bulk.has(edge.refName)) {
+      await service.__removeMany(query);
+      return;
+    }
+
+    for (;;) {
+      const ids = await service.__listIds(query, { limit: drainSize });
+      if (!ids.length) return;
+      let removed = 0;
+      for (const id of ids) {
+        if (seen.has(`${edge.refName}:${id}`)) continue;
+        await service.__remove(id);
+        removed += 1;
+      }
+      if (!removed) return;
+    }
+  }
+
+  #collectRefEdges(refName: string, mod: CascadeModule) {
+    return [...mod.constant.full.cascade.removeRef].map(([key, modelRef]) => {
+      const target = ConstantRegistry.getRefName(modelRef);
+
+      if (!this.#modules.has(target)) {
+        throw new Error(`Cascade field "${refName}.${key}" removes "${target}", which this app does not mount`);
+      }
+      return { key, refName: target };
+    });
+  }
+
+  #collectWithEdges(childRef: string, mod: CascadeModule) {
+    for (const [key, path] of mod.constant.full.cascade.removeWith) {
+      for (const owner of this.#resolveOwners(childRef, key, path)) {
+        this.#plans.get(owner)?.withEdges.push({ refName: childRef, key, typeKey: path.typeKey });
+      }
+    }
+  }
+
+  #resolveOwners(childRef: string, key: string, path: CascadeWithPath) {
+    if (path.typeValues.length) {
+
+      const mounted = path.typeValues.filter((owner) => this.#modules.has(owner));
+      for (const owner of path.typeValues) {
+        if (mounted.includes(owner)) continue;
+        this.#logger.warn(`Cascade field "${childRef}.${key}" names owner "${owner}", which this app does not mount`);
+      }
+      return mounted;
+    }
+    const owner = path.refName ?? ConstantRegistry.getRefName(path.modelRef as never);
+    if (!this.#modules.has(owner)) {
+      throw new Error(`Cascade field "${childRef}.${key}" is owned by "${owner}", which this app does not mount`);
+    }
+    return [owner];
+  }
+
+  /** Everything a bulk `removeMany` would skip. All of it absent means the two paths leave the same rows behind. */
+  #hasRemoveSideEffect(refName: string) {
+    const mod = this.#modules.get(refName);
+    if (!mod) return true;
+    if (mod.schema.preHooks.get("remove")?.length || mod.schema.postHooks.get("remove")?.length) return true;
+    if ((mod.srvRef as unknown as { [LIBS_REMOVE_HOOK]?: boolean })[LIBS_REMOVE_HOOK]) return true;
+    const proto = mod.srvRef.prototype as { _preRemove?: unknown; _postRemove?: unknown };
+    if (typeof proto._preRemove === "function" || typeof proto._postRemove === "function") return true;
+    const plan = this.#plans.get(refName);
+    return !!plan?.refEdges.length || !!plan?.withEdges.length;
+  }
+
+  /** Neither the strategy nor the edge list is visible from the source, and adding a `_postRemove` to a target
+   * silently flips it from one query back to one per document. A quiet cascade is the one nobody can explain. */
+  #report() {
+    const lines: string[] = [];
+    for (const [refName, plan] of this.#plans) {
+      for (const edge of plan.refEdges) {
+        lines.push(`${refName}.${edge.key} removeRef ${edge.refName} (${this.#strategy(edge.refName)})`);
+      }
+      for (const edge of plan.withEdges) {
+        const path = edge.typeKey ? `${edge.key}+${edge.typeKey}` : edge.key;
+        lines.push(`${refName} removeWith ${edge.refName}.${path} (${this.#strategy(edge.refName)})`);
+      }
+    }
+    if (!lines.length) return;
+    const bulk = lines.filter((line) => line.endsWith("(bulk)")).length;
+    this.#logger.info(`${lines.length} cascade edge(s), ${bulk} in one query`);
+    for (const line of lines) this.#logger.verbose(line);
+  }
+
+  #strategy(refName: string) {
+    return this.#bulk.has(refName) ? "bulk" : "per document";
+  }
+
+  #service(refName: string) {
+    if (!this.#getService) throw new Error(`Cascade ran before the plan was sealed: ${refName}`);
+    return this.#getService(refName);
+  }
+}

package/server/resolver/database.resolver.ts

@@ -47,7 +47,11 @@ const timedQuery = async <T>(fn: () => Promise<T>): Promise<T> => {
 };
 
 export class DatabaseResolver {
-  static resolveDatabase(constant: ConstantModel, database: DatabaseModel): AdaptorCls<DatabaseInstance> {
+  /** Returns the schema alongside the adaptor: the cascade planner reads its `remove` hooks to pick a strategy. */
+  static resolveDatabase(
+    constant: ConstantModel,
+    database: DatabaseModel,
+  ): { adaptor: AdaptorCls<DatabaseInstance>; schema: DocumentSchema } {
     const [modelName, className]: [string, string] = [database.refName, capitalize(database.refName)];
 
     const resolveSort = (sortKey?: string | null) =>
@@ -85,6 +89,16 @@ export class DatabaseResolver {
       schema.index(fields);
     }
 
+    for (const path of constant.full.cascade.removeWith.values()) {
+      const fields = path.typeKey
+        ? { removedAt: 1, [path.typeKey]: 1, [path.key]: 1 }
+        : { removedAt: 1, [path.key]: 1 };
+      const key = Object.keys(fields).join(",");
+      if (indexedSortFieldKeys.has(key)) continue;
+      indexedSortFieldKeys.add(key);
+      schema.index(fields as { [key: string]: 1 | -1 });
+    }
+
     class DatabaseModelInstance extends adapt(`${modelName}Model`, ({ plug }) => ({
       __database: plug(DatabaseAdaptorRole, (database) => database),
       __cache: plug(CacheAdaptorRole, (cache) => new CacheDatabase(modelName, cache)),
@@ -222,7 +236,7 @@ export class DatabaseResolver {
           updateOne: (query: QueryOf<any>, update: DocumentUpdateInput, options?: { upsert?: boolean }) =>
             store.updateOneByQuery(query, update, options),
           updateMany: (query: QueryOf<any>, update: DocumentUpdateInput) => store.updateManyByQuery(query, update),
-          deleteMany: (query: QueryOf<any>) => store.deleteManyByQuery(query),
+          removeMany: (query: QueryOf<any>) => store.removeManyByQuery(query),
           bulkWrite: (
             operations: { updateOne: { filter: QueryOf<any>; update: DocumentUpdateInput; upsert?: boolean } }[],
           ) => store.bulkWrite(operations),
@@ -322,6 +336,9 @@ export class DatabaseResolver {
       async __remove(id: string) {
         return await this.__store.remove(id);
       }
+      async __removeMany(query: QueryOf<any>) {
+        return await timedQuery(() => this.__store.removeManyByQuery(query));
+      }
       async [`remove${className}`](id: string) {
         return this.__remove(id);
       }
@@ -389,6 +406,9 @@ export class DatabaseResolver {
       });
     });
     applyMixins(DatabaseModelInstance, [database.model]);
-    return DatabaseModelInstance as unknown as AdaptorCls<DatabaseInstance<any, any, any, any, any, any>>;
+    return {
+      adaptor: DatabaseModelInstance as unknown as AdaptorCls<DatabaseInstance<any, any, any, any, any, any>>,
+      schema,
+    };
   }
 }

package/server/resolver/index.ts

@@ -1,3 +1,4 @@
+export * from "./CascadeRunner";
 export * from "./database.resolver";
 export * from "./service.resolver";
 export * from "./signal.resolver";

package/server/resolver/service.resolver.ts

@@ -1,6 +1,6 @@
 import type { PromiseOrObject } from "akanjs/base";
 import { capitalize } from "akanjs/common";
-import { type ConstantModel, ConstantRegistry, type QueryOf } from "akanjs/constant";
+import type { QueryOf } from "akanjs/constant";
 import {
   type CRUDEventType,
   type DatabaseModel,
@@ -15,13 +15,10 @@ import {
   type SaveEventType,
 } from "akanjs/document";
 import type { DatabaseService, ServiceCls } from "akanjs/service";
+import type { CascadeRunner } from "./CascadeRunner";
 
 export class ServiceResolver {
-  static #getDefaultDbServiceMethods(
-    className: string,
-    cascades: [string, string][],
-    getService: (refName: string) => DatabaseService,
-  ) {
+  static #getDefaultDbServiceMethods(refName: string, className: string, cascade: CascadeRunner) {
     const dbServiceMethods = {
       async __get(this: DatabaseService, id: string) {
         return await this.__databaseModel.__get(id);
@@ -99,37 +96,24 @@ export class ServiceResolver {
         return this.__update(id, data);
       },
       async __remove(this: DatabaseService, id: string): Promise<Doc> {
-
-        const targets = cascades.map(([key, refName]) => [key, getService(refName)] as const);
         await this.__libsPreRemove(id);
         const doc = await this.__databaseModel.__remove(id);
         const removed = await this.__libsPostRemove(doc);
-        for (const [key, target] of targets) {
-          const value = (removed as Record<string, unknown>)[key];
-          const ids = (Array.isArray(value) ? value : [value]).filter((v): v is string => typeof v === "string");
-
-          for (const targetId of ids) await target.__remove(targetId);
-        }
+        await cascade.run(refName, removed as Record<string, unknown>);
         return removed;
       },
       async [`remove${className}`](this: DatabaseService, id: string): Promise<Doc> {
         return this.__remove(id);
       },
+      async __removeMany(this: DatabaseService, query: QueryOf<any>) {
+        return await this.__databaseModel.__removeMany(query);
+      },
     };
     return dbServiceMethods;
   }
-  static resolveDatabaseService(
-    constant: ConstantModel,
-    database: DatabaseModel,
-    srvRef: ServiceCls,
-    getService: (refName: string) => DatabaseService,
-  ): ServiceCls {
+  static resolveDatabaseService(database: DatabaseModel, srvRef: ServiceCls, cascade: CascadeRunner): ServiceCls {
     const className = capitalize(database.refName);
-
-    const cascades = [...constant.full.cascade.remove].map(
-      ([key, modelRef]) => [key, ConstantRegistry.getRefName(modelRef)] as [string, string],
-    );
-    Object.assign(srvRef.prototype, ServiceResolver.#getDefaultDbServiceMethods(className, cascades, getService));
+    Object.assign(srvRef.prototype, ServiceResolver.#getDefaultDbServiceMethods(database.refName, className, cascade));
     const getQueryDataFromKey = (queryKey: string, args: any): { query: any; queryOption: any } => {
       const lastArg = args.at(-1);
       const hasQueryOption =

package/service/predefinedAdaptor/database.adaptor.ts

@@ -95,7 +95,7 @@ export interface DocumentStore {
     query: DocumentQuery,
     update: DocumentUpdateInput,
   ): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number }>;
-  deleteManyByQuery(
+  removeManyByQuery(
     query: DocumentQuery,
   ): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number }>;
   bulkWrite(
@@ -1081,8 +1081,8 @@ export class SqlDocumentStore {
     return { acknowledged: true, matchedCount: changes, modifiedCount: changes };
   }
 
-  async deleteManyByQuery(query: DocumentQuery) {
-    
+  async removeManyByQuery(query: DocumentQuery) {
+
     return this.updateManyByQuery(query, { removedAt: dayjs() });
   }
 

package/service/serve.ts

@@ -1,4 +1,4 @@
-import { type Cls, INJECT_META } from "akanjs/base";
+import { type Cls, INJECT_META, LIBS_REMOVE_HOOK } from "akanjs/base";
 import { applyMixins, capitalize, Logger, lowerlize } from "akanjs/common";
 import type { DatabaseModel } from "akanjs/document";
 
@@ -146,6 +146,10 @@ export function serve(
     const postUpdateFns = extSrvs.map((srv) => srv.prototype._postUpdate);
     const preRemoveFns = extSrvs.map((srv) => srv.prototype._preRemove);
     const postRemoveFns = extSrvs.map((srv) => srv.prototype._postRemove);
+
+    Object.assign(srvRef, {
+      [LIBS_REMOVE_HOOK]: preRemoveFns.some(Boolean) || postRemoveFns.some(Boolean),
+    });
     Object.assign(srvRef.prototype, {
       async __libsPreCreate(this: DatabaseService, data: DatabaseServiceData) {
         let result = data;

package/service/types.ts

@@ -11,6 +11,7 @@ import type {
   ListQueryOption,
   QueryMethodPart,
   SaveEventType,
+  UpdateResult,
 } from "akanjs/document";
 
 type ServiceMixinOmitKey =
@@ -101,6 +102,7 @@ export type DatabaseService<
   __create: (data: _DataInputOfDoc) => Promise<Doc>;
   __update: (id: string, data: Partial<Doc>) => Promise<Doc>;
   __remove: (id: string) => Promise<Doc>;
+  __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
   __list(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
   __listIds(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
   __find(query?: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;

package/types/base/symbols.d.ts

@@ -3,6 +3,7 @@ export declare const SLICE_META: unique symbol;
 export declare const FILTER_META: unique symbol;
 export declare const LOADER_META: unique symbol;
 export declare const INJECT_META: unique symbol;
+export declare const LIBS_REMOVE_HOOK: unique symbol;
 export declare const ENDPOINT_META: unique symbol;
 export declare const ENDPOINT_DICT_SHAPE: unique symbol;
 export declare const SLICE_DICT_SHAPE: unique symbol;

package/types/constant/cascadePaths.d.ts

@@ -1,11 +1,29 @@
 import type { FieldObject } from "./fieldInfo.d.ts";
 import type { ConstantModelRef } from "./via.d.ts";
-/** What happens to the documents a relation field points at when the owner is removed. */
-export declare const cascadeActions: readonly ["remove"];
+/**
+ * Which end of a relation goes away with the other. `removeRef` removes what the field points at when this
+ * document is removed; `removeWith` removes this document when what the field points at is removed. The two
+ * read identically on a relation field, so the value has to name the direction — a mistake here is a data loss.
+ */
+export declare const cascadeActions: readonly ["removeRef", "removeWith"];
 export type CascadeAction = (typeof cascadeActions)[number];
+/** How a `removeWith` field names the owner whose removal takes this document with it. */
+export interface CascadeWithPath {
+    readonly key: string;
+    /** Set when the field is a relation. Resolved to a refName later: the owner may not be registered yet. */
+    readonly modelRef: ConstantModelRef | null;
+    /** Set when the field declares `ref`, which names the owner at declaration. */
+    readonly refName: string | null;
+    /** Set when the field declares `refPath`: the sibling field holding the owner's refName. */
+    readonly typeKey: string | null;
+    /** The refNames `typeKey` may hold. Empty unless the field is polymorphic. */
+    readonly typeValues: readonly string[];
+}
 export declare class CascadePaths {
     #private;
-    /** Field key → the model its ids point at. Resolved to a refName later: the target may not be registered yet. */
-    readonly remove: Map<string, ConstantModelRef>;
+    /** Field key → the model its ids point at, removed when this document is. */
+    readonly removeRef: Map<string, ConstantModelRef>;
+    /** Field key → the owner whose removal removes this document. */
+    readonly removeWith: Map<string, CascadeWithPath>;
     collect(fieldMap: FieldObject): this;
 }

package/types/document/database.d.ts

@@ -4,7 +4,7 @@ import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { CacheAdaptor, CacheSetOptions } from "akanjs/service";
 import type { DataLoader } from "./dataLoader.d.ts";
 import type { ExtractQuery, ExtractSort, FilterInstance } from "./filterMeta.d.ts";
-import type { CRUDEventType, Mdl, SaveEventType } from "./into.d.ts";
+import type { CRUDEventType, Mdl, SaveEventType, UpdateResult } from "./into.d.ts";
 import type { DataInputOf, FindQueryOption, ListQueryOption } from "./types.d.ts";
 export declare class CacheDatabase<T = unknown> {
     private readonly refName;
@@ -57,6 +57,7 @@ type DatabaseModelWithQuerySort<T extends string, Input, Doc, Obj, Insight, Quer
     __create: (data: _DataInput) => Promise<Doc>;
     __update: (id: string, data: Partial<Doc>) => Promise<Doc>;
     __remove: (id: string) => Promise<Doc>;
+    __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
     __list(query: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
     __listIds(query: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
     __find(query: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;

package/types/document/databaseRegistry.d.ts

@@ -8,7 +8,7 @@ export interface DatabaseModel<T extends string = string, Input = any, Doc = any
     model: ModelCls<Model>;
     filter: FilterCls<Filter>;
     obj: ConstantCls<Obj>;
-    insight: ConstantCls<Insight>;
+    insight: DatabaseCls<Insight>;
     _Input: Input;
     _Doc: Doc;
     _Model: Model;
@@ -32,6 +32,6 @@ export declare class DatabaseRegistry {
     static getScalar<AllowEmpty extends boolean = false>(refName: string, { allowEmpty }?: {
         allowEmpty?: AllowEmpty;
     }): AllowEmpty extends true ? DatabaseCls | undefined : DatabaseCls;
-    static buildModel<T extends string, Input, Doc, Model, Obj, Insight, Filter extends FilterInstance, _Query extends ExtractQuery<Filter> = ExtractQuery<Filter>, _Sort extends ExtractSort<Filter> = ExtractSort<Filter>>(refName: T, input: DatabaseCls<Input>, doc: DatabaseCls<Doc>, model: ModelCls<Model>, obj: ConstantCls<Obj>, insight: ConstantCls<Insight>, filter: FilterCls<Filter>): DatabaseModel<T, Input, Doc, Model, Obj, Insight, Filter, _Query, _Sort>;
+    static buildModel<T extends string, Input, Doc, Model, Obj, Insight, Filter extends FilterInstance, _Query extends ExtractQuery<Filter> = ExtractQuery<Filter>, _Sort extends ExtractSort<Filter> = ExtractSort<Filter>>(refName: T, input: DatabaseCls<Input>, doc: DatabaseCls<Doc>, model: ModelCls<Model>, obj: ConstantCls<Obj>, insight: DatabaseCls<Insight>, filter: FilterCls<Filter>): DatabaseModel<T, Input, Doc, Model, Obj, Insight, Filter, _Query, _Sort>;
     static buildScalar<T extends string, Model>(refName: T, Model: DatabaseCls<Model>): DatabaseCls<Model>;
 }

package/types/document/into.d.ts

@@ -60,16 +60,17 @@ export type Mdl<Doc, Raw, _RawDoc = DocumentModel<Raw>, _RawQuery extends Docume
     exists(query: _RawQuery): Promise<string | null>;
     updateOne(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>, options?: DocumentUpdateOptions): Promise<UpdateResult>;
     updateMany(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>): Promise<UpdateResult>;
-    deleteMany(query: _RawQuery): Promise<UpdateResult>;
+    removeMany(query: _RawQuery): Promise<UpdateResult>;
     bulkWrite(operations: BulkWriteOperation<Raw, _RawDoc, _RawQuery>[]): Promise<UpdateResult>;
 };
-interface IntoConstantModel<T extends string, _CapitalizedRefName extends string, Raw> {
+interface IntoConstantModel<T extends string, _CapitalizedRefName extends string, Raw, Insight> {
     refName: T;
     _CapitalizedRefName: _CapitalizedRefName;
     _Full: Raw;
+    _Insight: Insight;
 }
 type NoInferType<T> = [T][T extends unknown ? 0 : never];
-type IntoModelActions<T extends string, _CapitalizedRefName extends string, Doc, Raw, _Query, _Sort, _QueryOfDoc = QueryOf<Doc>> = {
+type IntoModelActions<T extends string, _CapitalizedRefName extends string, Doc, Raw, Insight, _Query, _Sort, _QueryOfDoc = QueryOf<Doc>> = {
     [key in _CapitalizedRefName]: Mdl<Doc, Raw>;
 } & {
     [key in `${Uncapitalize<_CapitalizedRefName>}Loader`]: DataLoader<string, Doc, string>;
@@ -87,6 +88,6 @@ type IntoModelActions<T extends string, _CapitalizedRefName extends string, Doc,
     [K in `update${_CapitalizedRefName}`]: (id: string, data: Partial<Doc>) => Promise<Doc>;
 } & {
     [K in `remove${_CapitalizedRefName}`]: (id: string) => Promise<Doc>;
-} & QueryMethodPart<_Query, _Sort, Raw, Doc, unknown, unknown, unknown, _QueryOfDoc>;
-export declare const into: <Doc, FilterRef extends FilterCls, T extends string, Raw, AddDbModels extends ModelCls[], _CapitalizedRefName extends string, _QueryOfDoc = QueryOf<Doc>, _Query = FilterQueryOf<FilterRef>, _Sort = FilterSortOf<FilterRef>, _LoaderBuilder extends LoaderBuilder<NoInferType<Doc>> = LoaderBuilder<Doc>>(docRef: Cls<Doc>, filterRef: FilterRef, cnst: IntoConstantModel<T, _CapitalizedRefName, Raw>, loaderBuilder: _LoaderBuilder, ...addMdls: [...AddDbModels]) => ModelCls<IntoModelActions<T, _CapitalizedRefName, Doc, Raw, _Query, _Sort, _QueryOfDoc>, ReturnType<_LoaderBuilder>>;
+} & QueryMethodPart<_Query, _Sort, Raw, Doc, DocumentModel<Insight>, unknown, unknown, _QueryOfDoc>;
+export declare const into: <Doc, FilterRef extends FilterCls, T extends string, Raw, Insight, AddDbModels extends ModelCls[], _CapitalizedRefName extends string, _QueryOfDoc = QueryOf<Doc>, _Query = FilterQueryOf<FilterRef>, _Sort = FilterSortOf<FilterRef>, _LoaderBuilder extends LoaderBuilder<NoInferType<Doc>> = LoaderBuilder<Doc>>(docRef: Cls<Doc>, filterRef: FilterRef, cnst: IntoConstantModel<T, _CapitalizedRefName, Raw, Insight>, loaderBuilder: _LoaderBuilder, ...addMdls: [...AddDbModels]) => ModelCls<IntoModelActions<T, _CapitalizedRefName, Doc, Raw, Insight, _Query, _Sort, _QueryOfDoc>, ReturnType<_LoaderBuilder>>;
 export {};

package/types/server/resolver/CascadeRunner.d.ts

@@ -0,0 +1,13 @@
+import { type ConstantModel } from "akanjs/constant";
+import { type DocumentSchema } from "akanjs/document";
+import type { DatabaseService, ServiceCls } from "akanjs/service";
+export declare class CascadeRunner {
+    #private;
+    register(constant: ConstantModel, schema: DocumentSchema, srvRef: ServiceCls): void;
+    /**
+     * Called once every service is live. A `_postRemove` and a `listenPost("remove")` registered during boot both
+     * count against bulk removal, so the strategy cannot be decided before the last service has initialized.
+     */
+    seal(getService: (refName: string) => DatabaseService): void;
+    run(refName: string, doc: Record<string, unknown>): Promise<void>;
+}

package/types/server/resolver/database.resolver.d.ts

@@ -1,6 +1,10 @@
 import { type ConstantModel } from "akanjs/constant";
-import { type DatabaseInstance, type DatabaseModel } from "akanjs/document";
+import { type DatabaseInstance, type DatabaseModel, DocumentSchema } from "akanjs/document";
 import { type AdaptorCls } from "akanjs/service";
 export declare class DatabaseResolver {
-    static resolveDatabase(constant: ConstantModel, database: DatabaseModel): AdaptorCls<DatabaseInstance>;
+    /** Returns the schema alongside the adaptor: the cascade planner reads its `remove` hooks to pick a strategy. */
+    static resolveDatabase(constant: ConstantModel, database: DatabaseModel): {
+        adaptor: AdaptorCls<DatabaseInstance>;
+        schema: DocumentSchema;
+    };
 }

package/types/server/resolver/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./CascadeRunner.d.ts";
 export * from "./database.resolver";
 export * from "./service.resolver";
 export * from "./signal.resolver";

package/types/server/resolver/service.resolver.d.ts

@@ -1,7 +1,7 @@
-import { type ConstantModel } from "akanjs/constant";
 import { type DatabaseModel } from "akanjs/document";
-import type { DatabaseService, ServiceCls } from "akanjs/service";
+import type { ServiceCls } from "akanjs/service";
+import type { CascadeRunner } from "./CascadeRunner.d.ts";
 export declare class ServiceResolver {
     #private;
-    static resolveDatabaseService(constant: ConstantModel, database: DatabaseModel, srvRef: ServiceCls, getService: (refName: string) => DatabaseService): ServiceCls;
+    static resolveDatabaseService(database: DatabaseModel, srvRef: ServiceCls, cascade: CascadeRunner): ServiceCls;
 }

package/types/service/predefinedAdaptor/database.adaptor.d.ts

@@ -56,7 +56,7 @@ export interface DocumentStore {
         matchedCount: number;
         modifiedCount: number;
     }>;
-    deleteManyByQuery(query: DocumentQuery): Promise<{
+    removeManyByQuery(query: DocumentQuery): Promise<{
         acknowledged: boolean;
         matchedCount: number;
         modifiedCount: number;
@@ -309,7 +309,7 @@ export declare class SqlDocumentStore {
         matchedCount: number;
         modifiedCount: number;
     }>;
-    deleteManyByQuery(query: DocumentQuery): Promise<{
+    removeManyByQuery(query: DocumentQuery): Promise<{
         acknowledged: boolean;
         matchedCount: number;
         modifiedCount: number;

package/types/service/types.d.ts

@@ -1,7 +1,7 @@
 import type { Cls, MergeAllTypes, PromiseOrObject } from "akanjs/base";
 import type { Logger } from "akanjs/common";
 import type { QueryOf } from "akanjs/constant";
-import type { CRUDEventType, DatabaseModel, DataInputOf, FilterInstance, FindQueryOption, GetDocObject, ListQueryOption, QueryMethodPart, SaveEventType } from "akanjs/document";
+import type { CRUDEventType, DatabaseModel, DataInputOf, FilterInstance, FindQueryOption, GetDocObject, ListQueryOption, QueryMethodPart, SaveEventType, UpdateResult } from "akanjs/document";
 type ServiceMixinOmitKey = "onInit" | "onDestroy" | "_libsOnInit" | "_libsOnDestroy" | "_preCreate" | "_postCreate" | "_preUpdate" | "_postUpdate" | "_preRemove" | "_postRemove" | "_libsPreCreate" | "_libsPostCreate" | "_libsPreUpdate" | "_libsPostUpdate" | "_libsPreRemove" | "_libsPostRemove";
 type DatabaseQueryMethods<Query, Sort, Obj, Doc, Insight, FindQueryOption, ListQueryOption, DocQuery> = QueryMethodPart<Query, Sort, Obj, Doc, Insight, FindQueryOption, ListQueryOption, DocQuery>;
 type DocumentLike = {
@@ -31,6 +31,7 @@ export type DatabaseService<T extends string = string, Input = any, Doc = any, O
     __create: (data: _DataInputOfDoc) => Promise<Doc>;
     __update: (id: string, data: Partial<Doc>) => Promise<Doc>;
     __remove: (id: string) => Promise<Doc>;
+    __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
     __list(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
     __listIds(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
     __find(query?: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;