akanjs 3.0.0-alpha.92 → 3.0.0-alpha.93

package/constant/cascadePaths.ts

@@ -19,8 +19,10 @@ export interface CascadeWithPath {
   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. */
+  /** The refNames `typeKey` may hold. Empty unless the field is polymorphic over an enum. */
   readonly typeValues: readonly string[];
+  /** Set by `polymorphic: "any"`: `typeKey` is free-form, so the owner is whatever refName the row holds. */
+  readonly anyOwner: boolean;
 }
 
 const idNames = new Set(["ID", "String"]);
@@ -33,6 +35,7 @@ export class CascadePaths {
 
   collect(fieldMap: FieldObject) {
     for (const [key, field] of Object.entries(fieldMap)) {
+      this.#assertPolymorphicIsWiredUp(key, field);
       if (!field.cascade) continue;
       this.#assertKnownAction(key, field.cascade);
       if (field.cascade === "removeRef") this.removeRef.set(key, this.#readOwnedRelation(key, field));
@@ -41,6 +44,16 @@ export class CascadePaths {
     return this;
   }
 
+  /** `polymorphic` widens one thing and nothing else, so anywhere else it is a declaration that does nothing. */
+  #assertPolymorphicIsWiredUp(key: string, field: ConstantField) {
+    if (!field.polymorphic) return;
+    if (field.cascade === "removeWith" && field.refPath) return;
+    throw new Error(
+      `Field "${key}" declares polymorphic: "${field.polymorphic}", which only widens a ` +
+        `cascade: "removeWith" field that names its owner type with refPath`,
+    );
+  }
+
   #assertKnownAction(key: string, action: CascadeAction) {
 
     if (!cascadeActions.includes(action)) {
@@ -64,10 +77,10 @@ export class CascadePaths {
     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: [] };
+      return { key, modelRef: null, refName: field.ref, typeKey: null, typeValues: [], anyOwner: false };
     }
     if (field.isClass && !field.isScalar) {
-      return { key, modelRef: field.modelRef, refName: null, typeKey: null, typeValues: [] };
+      return { key, modelRef: field.modelRef, refName: null, typeKey: null, typeValues: [], anyOwner: false };
     }
     throw new Error(
       `Cascade field "${key}" declares cascade: "removeWith" but names no owner; make it a model reference, ` +
@@ -81,23 +94,44 @@ export class CascadePaths {
     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 (field.polymorphic === "any") return this.#readAnyOwner(key, typeKey, typeField);
 
     if (!typeField.enum) {
       throw new Error(
         `Cascade field "${key}" declares refPath: "${typeKey}", which must be an enumOf(...) naming the owner ` +
-          `refNames it may hold`,
+          `refNames it may hold; declare polymorphic: "any" to pay for a sweep on every removal instead`,
       );
     }
     const typeValues = typeField.enum.values.map((value) => String(value));
-    return { key, modelRef: null, refName: null, typeKey, typeValues };
+    return { key, modelRef: null, refName: null, typeKey, typeValues, anyOwner: false };
+  }
+
+  #readAnyOwner(key: string, typeKey: string, typeField: ConstantField): CascadeWithPath {
+    
+    if (typeField.enum) {
+      throw new Error(
+        `Cascade field "${key}" declares polymorphic: "any" and a refPath naming an enumOf(...); keep one`,
+      );
+    }
+
+    if (this.#primitiveNameOf(typeField) !== "String") {
+      throw new Error(
+        `Cascade field "${key}" declares polymorphic: "any", so refPath: "${typeKey}" must be a String field ` +
+          `holding the owner's refName`,
+      );
+    }
+    return { key, modelRef: null, refName: null, typeKey, typeValues: [], anyOwner: true };
   }
 
   #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;
+    const refName = this.#primitiveNameOf(field);
     if (refName && idNames.has(refName)) return;
     throw new Error(`Cascade field "${key}" declares ref or refPath and must hold an ID`);
   }
+
+  #primitiveNameOf(field: ConstantField) {
+    const modelRef = field.modelRef as unknown as Cls;
+    if (!PrimitiveRegistry.has(modelRef)) return null;
+    return PrimitiveRegistry.getName(modelRef as unknown as typeof PrimitiveScalar);
+  }
 }

package/constant/fieldInfo.ts

@@ -106,6 +106,11 @@ export interface ConstantFieldProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
+  /**
+   * Widens a `cascade: "removeWith"` field whose `refPath` names a free-form `String` instead of an `enumOf`:
+   * the owner is whatever refName the row happens to hold, found by sweeping at removal time.
+   */
+  polymorphic?: "any";
   /**
    * Renders on the page, never reaches an agent. Stripped wherever a value is masked for an AI caller — the
    * in-page agent's reads and every MCP result — and left untouched everywhere else, so a `File`'s blur
@@ -204,6 +209,7 @@ interface ConstantFieldBuildProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
+  polymorphic?: "any";
   visual: boolean;
   modelRef: ConstantModelRef;
   arrDepth: number;
@@ -329,6 +335,7 @@ export class ConstantField<
   readonly validate?: (value: FieldValue, model: any) => boolean;
   readonly text?: TextFieldRole;
   readonly cascade?: CascadeAction;
+  readonly polymorphic?: "any";
   readonly visual: boolean;
   readonly modelRef: ConstantModelRef;
   readonly arrDepth: number;
@@ -362,6 +369,7 @@ export class ConstantField<
     this.validate = props.validate;
     this.text = props.text;
     this.cascade = props.cascade;
+    this.polymorphic = props.polymorphic;
     this.visual = props.visual;
     this.modelRef = props.modelRef;
     this.arrDepth = props.arrDepth;
@@ -442,6 +450,7 @@ export class ConstantField<
       validate: option.validate,
       text: option.text,
       cascade: option.cascade,
+      polymorphic: option.polymorphic,
       visual: option.visual ?? false,
       modelRef,
       arrDepth: arrDepth,
@@ -489,6 +498,7 @@ export class ConstantField<
       validate: this.validate,
       text: this.text,
       cascade: this.cascade,
+      polymorphic: this.polymorphic,
       visual: this.visual,
       modelRef: this.modelRef,
       arrDepth: this.arrDepth,

package/package.json

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

package/server/di/utils.ts

@@ -71,7 +71,8 @@ export const getModuleDependencyRefNames = (mod: DatabaseModule | ServiceModule)
 /**
  * The modules a cascade edge forces this one to be mounted with: a `removeRef` target and a monomorphic
  * `removeWith` owner both fail `CascadeRunner.seal` when they are absent, so they are boot dependencies the
- * inject graph cannot see. A polymorphic owner list is exempt — it spans optional modules by design.
+ * inject graph cannot see. A polymorphic owner is exempt — an enum list spans optional modules by design, and
+ * `polymorphic: "any"` names no module at all.
  */
 export const getModuleCascadeRefNames = (mod: DatabaseModule | ServiceModule) => {
   const dependencies = new Set<string>();
@@ -79,7 +80,7 @@ export const getModuleCascadeRefNames = (mod: DatabaseModule | ServiceModule) =>
   const { cascade } = mod.constant.full;
   for (const modelRef of cascade.removeRef.values()) dependencies.add(ConstantRegistry.getRefName(modelRef));
   for (const path of cascade.removeWith.values()) {
-    if (path.typeValues.length) continue;
+    if (path.anyOwner || path.typeValues.length) continue;
     dependencies.add(path.refName ?? ConstantRegistry.getRefName(path.modelRef as never));
   }
   return dependencies;

package/server/resolver/CascadeRunner.ts

@@ -43,6 +43,8 @@ const drainSize = 200;
 export class CascadeRunner {
   readonly #modules = new Map<string, CascadeModule>();
   readonly #plans = new Map<string, CascadePlan>();
+  /** `polymorphic: "any"` edges: the owner is unknowable at boot, so every model's removal has to sweep them. */
+  readonly #anyEdges: WithEdge[] = [];
   readonly #bulk = new Set<string>();
   readonly #context = new AsyncLocalStorage<CascadeContext>();
   readonly #logger = new Logger("Cascade");
@@ -71,7 +73,8 @@ export class CascadeRunner {
 
   async run(refName: string, doc: Record<string, unknown>) {
     const plan = this.#plans.get(refName);
-    if (!plan?.refEdges.length && !plan?.withEdges.length) return;
+    if (!plan) return;
+    if (!plan.refEdges.length && !plan.withEdges.length && !this.#anyEdges.length) return;
     const parent = this.#context.getStore();
     const seen = parent?.seen ?? new Set<string>();
     const depth = (parent?.depth ?? 0) + 1;
@@ -83,7 +86,9 @@ export class CascadeRunner {
     }
     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);
+      if (!id) return;
+      for (const edge of plan.withEdges) await this.#removeWith(edge, refName, id, seen);
+      for (const edge of this.#anyEdges) await this.#removeWith(edge, refName, id, seen);
     });
   }
 
@@ -136,6 +141,10 @@ export class CascadeRunner {
 
   #collectWithEdges(childRef: string, mod: CascadeModule) {
     for (const [key, path] of mod.constant.full.cascade.removeWith) {
+      if (path.anyOwner) {
+        this.#anyEdges.push({ refName: childRef, key, typeKey: path.typeKey });
+        continue;
+      }
       for (const owner of this.#resolveOwners(childRef, key, path)) {
         this.#plans.get(owner)?.withEdges.push({ refName: childRef, key, typeKey: path.typeKey });
       }
@@ -163,6 +172,8 @@ export class CascadeRunner {
   #hasRemoveSideEffect(refName: string) {
     const mod = this.#modules.get(refName);
     if (!mod) return true;
+
+    if (this.#anyEdges.length) 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 };
@@ -184,10 +195,20 @@ export class CascadeRunner {
         lines.push(`${refName} removeWith ${edge.refName}.${path} (${this.#strategy(edge.refName)})`);
       }
     }
+    for (const edge of this.#anyEdges) {
+      lines.push(`<any> removeWith ${edge.refName}.${edge.key}+${edge.typeKey} (${this.#strategy(edge.refName)})`);
+    }
     if (!lines.length) return;
     const bulk = lines.filter((line) => line.endsWith("(bulk)")).length;
     this.#logger.verbose(`${lines.length} cascade edge(s), ${bulk} in one query`);
     for (const line of lines) this.#logger.verbose(line);
+
+    if (!this.#anyEdges.length) return;
+    const wildcards = this.#anyEdges.map((edge) => `${edge.refName}.${edge.key}`).join(", ");
+    this.#logger.info(
+      `${this.#anyEdges.length} wildcard removeWith edge(s) (${wildcards}): every removal probes them, ` +
+        `and no cascade removes in one query`,
+    );
   }
 
   #strategy(refName: string) {

package/service/injectInfo.ts

@@ -1,4 +1,4 @@
-import { type BackendEnv, type Cls, INJECT_META } from "akanjs/base";
+import { type BackendEnv, type Cls, INJECT_META, PrimitiveRegistry } from "akanjs/base";
 import {
   type ConstantFieldTypeInput,
   ConstantRegistry,
@@ -389,6 +389,9 @@ export const injectionBuilder = (parentRefName: string) => ({
       throw new Error("get and set should be both provided or not provided");
     const isMap = modelRef === Map;
     if (isMap && !opts.of) throw new Error("of should be provided when modelRef is Map");
+    const valueRef = (isMap ? opts.of : modelRef) as Cls;
+
+    const isStructured = Array.isArray(valueRef) || !PrimitiveRegistry.has(valueRef);
     type FieldValue = never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>;
     type MapFieldValue = never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>;
     type IsNullable = DefaultValue extends never ? true : false;
@@ -425,16 +428,14 @@ export const injectionBuilder = (parentRefName: string) => ({
     >("memory", {
       local: opts.local,
       get: (serializedValue: never) => {
-        const rawValue = serializedValue as object | null;
-        return (
-          ConstantRegistry.deserialize(isMap ? (opts.of as Cls) : (modelRef as Cls), rawValue ?? opts.default, true) ??
-          null
-        );
+        const stored = serializedValue as unknown;
+        
+        const rawValue = isStructured && typeof stored === "string" ? JSON.parse(stored) : stored;
+        return ConstantRegistry.deserialize(valueRef, (rawValue as object | null) ?? opts.default, true) ?? null;
       },
       set: (value: never) => {
-        return (
-          ConstantRegistry.serialize(isMap ? (opts.of as Cls) : (modelRef as Cls), value, true) ?? opts.default ?? null
-        );
+        const serialized = ConstantRegistry.serialize(valueRef, value, true) ?? opts.default ?? null;
+        return isStructured ? JSON.stringify(serialized) : serialized;
       },
       default: opts.default as unknown,
       isMap,

package/types/constant/cascadePaths.d.ts

@@ -16,8 +16,10 @@ export interface CascadeWithPath {
     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. */
+    /** The refNames `typeKey` may hold. Empty unless the field is polymorphic over an enum. */
     readonly typeValues: readonly string[];
+    /** Set by `polymorphic: "any"`: `typeKey` is free-form, so the owner is whatever refName the row holds. */
+    readonly anyOwner: boolean;
 }
 export declare class CascadePaths {
     #private;

package/types/constant/fieldInfo.d.ts

@@ -47,6 +47,11 @@ export interface ConstantFieldProps<FieldType extends ConstantFieldKind = Consta
     validate?: (value: FieldValue, model: any) => boolean;
     text?: TextFieldRole;
     cascade?: CascadeAction;
+    /**
+     * Widens a `cascade: "removeWith"` field whose `refPath` names a free-form `String` instead of an `enumOf`:
+     * the owner is whatever refName the row happens to hold, found by sweeping at removal time.
+     */
+    polymorphic?: "any";
     /**
      * Renders on the page, never reaches an agent. Stripped wherever a value is masked for an AI caller — the
      * in-page agent's reads and every MCP result — and left untouched everywhere else, so a `File`'s blur
@@ -101,6 +106,7 @@ interface ConstantFieldBuildProps<FieldType extends ConstantFieldKind = any, Fie
     validate?: (value: FieldValue, model: any) => boolean;
     text?: TextFieldRole;
     cascade?: CascadeAction;
+    polymorphic?: "any";
     visual: boolean;
     modelRef: ConstantModelRef;
     arrDepth: number;
@@ -147,6 +153,7 @@ export declare class ConstantField<FieldType extends ConstantFieldKind = Constan
     readonly validate?: (value: FieldValue, model: any) => boolean;
     readonly text?: TextFieldRole;
     readonly cascade?: CascadeAction;
+    readonly polymorphic?: "any";
     readonly visual: boolean;
     readonly modelRef: ConstantModelRef;
     readonly arrDepth: number;

package/types/server/di/utils.d.ts

@@ -18,7 +18,8 @@ export declare const getModuleDependencyRefNames: (mod: DatabaseModule | Service
 /**
  * The modules a cascade edge forces this one to be mounted with: a `removeRef` target and a monomorphic
  * `removeWith` owner both fail `CascadeRunner.seal` when they are absent, so they are boot dependencies the
- * inject graph cannot see. A polymorphic owner list is exempt — it spans optional modules by design.
+ * inject graph cannot see. A polymorphic owner is exempt — an enum list spans optional modules by design, and
+ * `polymorphic: "any"` names no module at all.
  */
 export declare const getModuleCascadeRefNames: (mod: DatabaseModule | ServiceModule) => Set<string>;
 export interface Registration {