akanjs 3.0.0-alpha.0 → 3.0.0-alpha.2

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/cachePolicy.d.ts

@@ -78,14 +78,45 @@ export declare function shouldStoreRouteCache(input: {
 }): RouteCacheRenderState;
 export declare function hasRouteCacheInvalidationScope(invalidation?: RouteCacheInvalidation): boolean;
 export declare function shouldInvalidateRouteCacheEntry(metadata: RouteCacheMetadata, invalidation: RouteCacheInvalidation): boolean;
+export interface LruTtlCacheOptions<T> {
+    /**
+     * Measures one entry's payload. Entry count alone says nothing about a cache whose entries span
+     * three orders of magnitude, and a byte ceiling needs a running total to enforce. The default
+     * reports 0 rather than guessing, so `byteSize` stays honest about not knowing.
+     */
+    sizeOf?: (value: T) => number;
+    /** Total payload ceiling. 0 leaves the cache bounded only by `maxEntries`. */
+    maxBytes?: number;
+    /** An entry over this is not stored at all, rather than evicting everything else to fit it. */
+    maxEntryBytes?: number;
+    /**
+     * Cadence of the idle sweep. Without one a filled cache never shrinks: an entry is dropped only
+     * when its own key is fetched after expiry or when a write evicts it, so a pod that stops
+     * serving holds its peak forever — measured at 100 entries / 21.4 MiB still resident 310s after
+     * the last request, with a 30s TTL. 0 disables it.
+     */
+    sweepIntervalMs?: number;
+}
 export declare class LruTtlCache<T> {
     #private;
     readonly maxEntries: number;
-    constructor(maxEntries?: number);
+    constructor(maxEntries?: number, options?: LruTtlCacheOptions<T>);
     get size(): number;
+    get byteSize(): number;
     get(key: string): T | null;
-    set(key: string, value: T, ttlSeconds: number): void;
+    /** Returns whether the entry was stored; a payload over `maxEntryBytes` is rejected. */
+    set(key: string, value: T, ttlSeconds: number): boolean;
+    /**
+     * Drops every expired entry. Deliberately a full scan rather than a walk from the oldest that
+     * stops at the first live entry: insertion order is *LRU* order because `get` reinserts, and TTLs
+     * differ per entry, so expiry is not monotonic in map order and an early break would leave
+     * expired entries behind. The map is bounded by `maxEntries`, so the scan is cheap.
+     */
+    sweepExpired(now?: number): number;
+    /** Stops the idle sweep. The cache stays usable; only the timer goes away. */
+    dispose(): void;
     delete(key: string): boolean;
     invalidate(predicate: (key: string, value: T) => boolean): number;
     clear(): void;
+    static parseByteCeiling(value: string | undefined | null, fallback?: number): number;
 }

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/server/rscWorkerHost.d.ts

@@ -49,6 +49,19 @@ export declare function nextRscHostPendingChunkCount(currentPendingChunks: numbe
 export declare function isRscHostPendingChunkOverflow(pendingChunks: number, maxPendingChunks: number): boolean;
 export declare function createIdempotentRscRenderCancel(onCancel: (reason?: unknown) => void): (reason?: unknown) => void;
 export declare function createRscWorkerInvalidateCacheMessage(invalidation?: string | RouteCacheInvalidation): RscWorkerInvalidateCacheMessage;
+/**
+ * The RSC worker samples its own process with the same `ProcessMetricsCollector.collect` its host
+ * replica uses, so its report carries `pid` / `rssBytes` / `role` / … under the identical names.
+ * `AkanServer` spreads the host's report into its own `collect({ role, ...webRouter.getMetrics() })`
+ * and `collect` spreads `extra` last (`processMetricsCollector.ts:122`) — so passing these through
+ * unprefixed silently overwrote the replica's own process fields, and the replica's RSS was reported
+ * nowhere. Rename them onto `rscWorker*`; the `rsc*` render counters, which only the worker
+ * produces, pass through untouched.
+ *
+ * XXX A new process-level field in `ProcessMetricsCollector.collect` must be added here too, or it
+ * starts shadowing the replica again.
+ */
+export declare function projectRscWorkerProcessMetrics(metrics: AkanMetricsReport): AkanMetricsReport;
 export declare function createRscHostRenderStream(input: {
     setPending: (pending: RscPending) => void;
     deletePending: () => void;

package/types/service/ipcTypes.d.ts

@@ -59,6 +59,25 @@ export interface AkanMetricsReport {
     rscWorkerRestartCount?: number;
     rscWorkerRecycleCount?: number;
     rscWorkerLastRecycleReason?: string;
+    rscWorkerReportedAt?: number;
+    rscWorkerRssBytes?: number;
+    rscWorkerHeapTotalBytes?: number;
+    rscWorkerHeapUsedBytes?: number;
+    rscWorkerExternalBytes?: number;
+    rscWorkerArrayBuffersBytes?: number;
+    rscWorkerCpuUserMicros?: number;
+    rscWorkerCpuSystemMicros?: number;
+    rscWorkerMaxRssKb?: number;
+    rscWorkerJscHeapSizeBytes?: number;
+    rscWorkerJscHeapCapacityBytes?: number;
+    /** Off-heap bytes JSC attributes to JS objects — typed-array backing stores, i.e. cached Flight chunks. */
+    rscWorkerJscExtraMemorySizeBytes?: number;
+    rscWorkerJscObjectCount?: number;
+    rscWorkerJscProtectedObjectCount?: number;
+    rscWorkerEventLoopLagMeanMs?: number;
+    rscWorkerEventLoopLagP99Ms?: number;
+    rscWorkerEventLoopLagMaxMs?: number;
+    rscWorkerGcDurationMs?: number;
     rscPendingRenderCount?: number;
     rscQueuedSendCount?: number;
     rscHostPendingChunkOverflowCount?: number;
@@ -94,9 +113,13 @@ export interface AkanMetricsReport {
     rscLastRenderLoadedModuleDelta?: number;
     rscLastRenderLoadedModules?: string[];
     rscResultCacheEntries?: number;
+    rscResultCacheBytes?: number;
+    rscPatchResultCacheEntries?: number;
+    rscPatchResultCacheBytes?: number;
     rscResultCacheHits?: number;
     rscResultCacheMisses?: number;
     rscResultCacheBypass?: number;
+    /** Keys the SSR chunk registry tracks — NOT a memory bound; the modules stay in Bun's ESM registry. */
     ssrChunkRegistrySize?: number;
     ssrChunkLoadCount?: number;
     ssrChunkCacheHitCount?: number;
@@ -107,6 +130,7 @@ export interface AkanMetricsReport {
     httpCsrCount?: number;
     httpImageCount?: number;
     httpHtmlCacheEntries?: number;
+    httpHtmlCacheBytes?: number;
     httpHtmlCacheHits?: number;
     httpHtmlCacheMisses?: number;
     httpHtmlCacheBypass?: number;

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>;