akanjs 2.2.4 → 2.2.6

package/types/signal/guard.d.ts

@@ -0,0 +1,10 @@
+import type { Cls } from "akanjs/base";
+import type { SignalContext } from "./signalContext.d.ts";
+export interface Guard {
+    canPass(context: SignalContext): boolean;
+}
+export type GuardCls<Name extends string = string> = Cls<Guard, {
+    readonly name: Name;
+}>;
+/** Creates a named guard base class for signal access checks. */
+export declare const guard: <T extends string>(name: T) => GuardCls<T>;

package/types/signal/guards.d.ts

@@ -0,0 +1,10 @@
+import type { Guard } from "./guard.d.ts";
+import type { SignalContext } from "./signalContext.d.ts";
+export declare class Public implements Guard {
+    static name: string;
+    canPass(context: SignalContext): boolean;
+}
+export declare class None implements Guard {
+    static name: string;
+    canPass(context: SignalContext): boolean;
+}

package/types/signal/index.d.ts

@@ -0,0 +1,19 @@
+export * from "./base.signal";
+export * from "./endpoint.d.ts";
+export * from "./endpointInfo.d.ts";
+export * from "./exception.d.ts";
+export * from "./guard.d.ts";
+export * from "./guards.d.ts";
+export * from "./intercept.d.ts";
+export * from "./internal.d.ts";
+export * from "./internalArg.d.ts";
+export * from "./internalInfo.d.ts";
+export * from "./middleware.d.ts";
+export * from "./serializer.d.ts";
+export * from "./serverSignal.d.ts";
+export * from "./signalContext.d.ts";
+export * from "./signalRegistry.d.ts";
+export * from "./slice.d.ts";
+export * from "./sliceInfo.d.ts";
+export * from "./trace.d.ts";
+export * from "./types.d.ts";

package/types/signal/intercept.d.ts

@@ -0,0 +1,17 @@
+import { type Cls, INJECT_META } from "akanjs/base";
+import { Logger } from "akanjs/common";
+import { type ExtractInjectInfoObject, type InjectBuilder, type InjectInfo } from "akanjs/service";
+import type { SignalContext } from "./signalContext.d.ts";
+export type InterceptorCls<Methods = {}, InjectMap extends {
+    [key: string]: InjectInfo;
+} = {}> = Cls<Methods & ExtractInjectInfoObject<InjectMap> & {
+    readonly logger: Logger;
+    onInit(): Promise<void>;
+    onDestroy(): Promise<void>;
+    intercept(context: SignalContext): AsyncGenerator<unknown> | Promise<unknown>;
+}, {
+    readonly [INJECT_META]: InjectMap;
+    readonly refName: string;
+}>;
+export declare function intercept<Name extends string>(name: Name): InterceptorCls;
+export declare function intercept<Name extends string, Injection extends InjectBuilder<"use" | "env" | "memory">>(refName: Name, injectBuilder: Injection): InterceptorCls<{}, ReturnType<Injection>>;

package/types/signal/internal.d.ts

@@ -0,0 +1,18 @@
+import { INTERNAL_META, type MergeAllKeyOfObjects } from "akanjs/base";
+import { type Adaptor, type AdaptorCls, type QueueAdaptor, type ScheduleAdaptor, type ServiceModel } from "akanjs/service";
+import { type BuildInternal, type InternalBuilder, type InternalInfo } from "./internalInfo.d.ts";
+export interface Internal extends Adaptor {
+    schedule: ScheduleAdaptor;
+    queue: QueueAdaptor;
+}
+export type InternalCls<SrvModule extends ServiceModel = ServiceModel, InternalInfoMap extends {
+    [key: string]: InternalInfo;
+} = {
+    [key: string]: InternalInfo;
+}> = AdaptorCls & {
+    refName: SrvModule["srv"]["refName"];
+    srv: SrvModule;
+    [INTERNAL_META]: InternalInfoMap;
+};
+/** Builds an internal adaptor for schedules, queues, processes, and server-only jobs. */
+export declare function internal<SrvModule extends ServiceModel, InternalInfoMap extends ReturnType<InternalBuilder<SrvModule>>, LibInternals extends InternalCls[]>(srv: SrvModule, internalBuilder: (builder: BuildInternal<SrvModule>) => InternalInfoMap, ...libInternals: LibInternals): InternalCls<SrvModule, MergeAllKeyOfObjects<LibInternals, typeof INTERNAL_META> & InternalInfoMap>;

package/types/signal/internalArg.d.ts

@@ -0,0 +1,31 @@
+import type { Cls, PromiseOrObject } from "akanjs/base";
+import type { SignalContext } from "./signalContext.d.ts";
+export interface InternalArg<ArgType = unknown> {
+    getArg: (context: SignalContext) => PromiseOrObject<ArgType | null>;
+}
+export type InternalArgCls<ArgType = unknown> = Cls<InternalArg<ArgType>>;
+/** Injects the current Bun request into an endpoint/internal handler. */
+export declare class Req implements InternalArg {
+    getArg(context: SignalContext): Bun.BunRequest;
+}
+/** Injects the current mutable response context into an endpoint/internal handler. */
+export declare class Res implements InternalArg {
+    getArg(context: SignalContext): {
+        new (body?: BodyInit | null, init?: ResponseInit): Response;
+        prototype: Response;
+        error(): Response;
+        json(data: any, init?: ResponseInit): Response;
+        redirect(url: string | URL, status?: number): Response;
+    };
+}
+/** Injects websocket state and subscription hooks into message/pubsub handlers. */
+export declare class Ws implements InternalArg {
+    onDisconnect?: () => void;
+    onUnsubscribe?: () => void;
+    getArg(context: SignalContext): {
+        ws: Bun.ServerWebSocket<unknown>;
+        subscribe: boolean;
+        on: (event: "disconnect" | "unsubscribe", handler: () => void) => void;
+        off: (event: "disconnect" | "unsubscribe", handler: () => void) => void;
+    };
+}

package/types/signal/internalInfo.d.ts

@@ -0,0 +1,45 @@
+import { Any, type FIELD_META, type PromiseOrObject } from "akanjs/base";
+import type { ConstantCls, ConstantField, ConstantFieldTypeInput, DocumentModel, FieldObject, FieldToValue, PlainTypeToFieldType } from "akanjs/constant";
+import type { AkanJob, ServiceModel } from "akanjs/service";
+import { type ArgInfo, type InternalArgInfo, type ReturnInfo } from "./endpointInfo.d.ts";
+import type { InternalArgCls } from "./internalArg.d.ts";
+import type { SignalOption } from "./types.d.ts";
+type InternalType = "resolveField" | "interval" | "cron" | "timeout" | "init" | "destroy" | "process";
+interface InternalArgProps<Nullable extends boolean = false> {
+    nullable?: Nullable;
+}
+export declare class InternalInfo<ReqType extends InternalType = InternalType, Srvs extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}, Args extends any[] = any, InternalArgs extends any[] = any, DefaultArgs extends any[] = any, Returns extends ConstantFieldTypeInput = ConstantFieldTypeInput, ServerReturns = any, Nullable extends boolean = boolean> {
+    readonly type: ReqType;
+    readonly args: ArgInfo<InternalArgProps<boolean>>[];
+    readonly internalArgs: InternalArgInfo<boolean>[];
+    readonly defaultArgs: string[];
+    readonly returns: ReturnInfo<Returns, Nullable>;
+    readonly signalOption: SignalOption<Returns, Nullable>;
+    execFn: ((...args: [...Args, ...DefaultArgs, ...InternalArgs]) => ServerReturns) | null;
+    constructor(type: ReqType, returnRef: Returns, signalOption?: SignalOption<Returns, Nullable>);
+    msg<ExplicitType, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, Nullable extends boolean = false, _FieldToValue = FieldToValue<Arg>>(name: string, arg: Arg, option?: InternalArgProps<Nullable>): InternalInfo<ReqType, Srvs, [...Args, arg: _FieldToValue | (Nullable extends true ? undefined : never)], InternalArgs, DefaultArgs, Returns, ServerReturns, Nullable>;
+    with<ArgType, Optional extends boolean = false>(argRef: InternalArgCls<ArgType>, option?: InternalArgProps<Optional>): InternalInfo<ReqType, Srvs, Args, [...InternalArgs, arg: NonNullable<ArgType> | (Optional extends true ? null : ReqType extends "resolveField" ? null : never)], DefaultArgs, Returns, ServerReturns, Nullable>;
+    exec<ExecReturn extends ReqType extends "process" | "resolveField" ? PromiseOrObject<DocumentModel<FieldToValue<Returns>> | (Nullable extends true ? null : never)> : PromiseOrObject<void>>(execFn: (this: Srvs, ...args: [...Args, ...DefaultArgs, ...InternalArgs]) => ExecReturn): InternalInfo<ReqType, Srvs, Args, InternalArgs, DefaultArgs, Returns, ExecReturn, Nullable>;
+}
+export type BuildInternal<SrvModule extends ServiceModel, ParentDoc = SrvModule["db"]["_Doc"]> = {
+    resolveField: <Returns extends ConstantFieldTypeInput, Nullable extends boolean = false>(returnRef: Returns, signalOption?: Pick<SignalOption<Returns, Nullable>, "nullable">) => InternalInfo<"resolveField", SrvModule["srvMap"], [], [], [ParentDoc], Returns, never, Nullable>;
+    interval: <Nullable extends boolean = false>(scheduleTime: number, signalOption?: SignalOption<typeof Any, Nullable>) => InternalInfo<"interval", SrvModule["srvMap"], [], [], [], typeof Any, never, Nullable>;
+    cron: <Nullable extends boolean = false>(scheduleCron: string, signalOption?: SignalOption<typeof Any, Nullable>) => InternalInfo<"cron", SrvModule["srvMap"], [], [], [], typeof Any, never, Nullable>;
+    timeout: <Nullable extends boolean = false>(timeout: number, signalOption?: SignalOption<typeof Any, Nullable>) => InternalInfo<"timeout", SrvModule["srvMap"], [], [], [], typeof Any, never, Nullable>;
+    initialize: <Nullable extends boolean = false>(signalOption?: SignalOption<typeof Any, Nullable>) => InternalInfo<"init", SrvModule["srvMap"], [], [], [], typeof Any, never, Nullable>;
+    destroy: <Nullable extends boolean = false>(signalOption?: SignalOption<typeof Any, Nullable>) => InternalInfo<"destroy", SrvModule["srvMap"], [], [], [], typeof Any, never, Nullable>;
+    process: <Returns extends ConstantFieldTypeInput, Nullable extends boolean = false>(returnRef: Returns, signalOption?: SignalOption<Returns, Nullable>) => InternalInfo<"process", SrvModule["srvMap"], [], [], [AkanJob], Returns, never, Nullable>;
+};
+export type InternalBuilder<SrvModule extends ServiceModel, _FullCls extends ConstantCls = SrvModule["cnst"]["full"], _FieldObj extends FieldObject = _FullCls[typeof FIELD_META], _ResolveFieldObj extends FieldObject = {
+    [K in keyof _FieldObj as _FieldObj[K] extends ConstantField<"resolve", any, any, any, any, any> ? K : never]: _FieldObj[K];
+}> = (builder: BuildInternal<SrvModule>) => SrvModule["cnst"] extends never ? {
+    [key: string]: InternalInfo<Exclude<InternalType, "resolveField">>;
+} : {
+    [K in keyof _ResolveFieldObj]: _ResolveFieldObj[K] extends ConstantField<"resolve", infer Value, any, any, infer Nullable> ? InternalInfo<"resolveField", any, any, any, any, NonNullable<Value>, Nullable> : InternalInfo<Exclude<InternalType, "resolveField">>;
+};
+export declare const buildInternal: BuildInternal<any, any>;
+export {};

package/types/signal/middleware.d.ts

@@ -0,0 +1,51 @@
+import type { BaseEnv, Cls, PromiseOrObject } from "akanjs/base";
+import type { SignalContext } from "./signalContext.d.ts";
+export interface Middleware<Env extends BaseEnv = BaseEnv> {
+    use(env: Env): PromiseOrObject<(context: SignalContext, next: () => Promise<unknown>) => PromiseOrObject<unknown>>;
+}
+export type MiddlewareCls = Cls<Middleware, {
+    readonly refName: string;
+}>;
+export declare const middleware: (refName: string) => {
+    new (): {
+        use(env: BaseEnv): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
+    };
+    refName: string;
+};
+declare const Logging_base: {
+    new (): {
+        use(env: BaseEnv): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
+    };
+    refName: string;
+};
+export declare class Logging extends Logging_base {
+    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
+}
+declare const Cache_base: {
+    new (): {
+        use(env: BaseEnv): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
+    };
+    refName: string;
+};
+export declare class Cache extends Cache_base {
+    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<any>>;
+}
+declare const Timeout_base: {
+    new (): {
+        use(env: BaseEnv): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
+    };
+    refName: string;
+};
+export declare class Timeout extends Timeout_base {
+    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
+}
+declare const Retry_base: {
+    new (): {
+        use(env: BaseEnv): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
+    };
+    refName: string;
+};
+export declare class Retry extends Retry_base {
+    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
+}
+export {};

package/types/signal/serializer/fetch.serializer.d.ts

@@ -0,0 +1,14 @@
+import { Logger } from "akanjs/common";
+import type { LiveRegistry } from "akanjs/service";
+import type { EndpointCls, SerializedSignal, SliceCls } from "akanjs/signal";
+export declare class FetchSerializer {
+    #private;
+    static logger: Logger;
+    static serializeDatabaseSignal(sliceCls: SliceCls, endpointCls: EndpointCls): SerializedSignal;
+    static serializeServiceSignal(endpointCls: EndpointCls): SerializedSignal;
+    static serializeRegistry({ endpointCls, sliceCls }: LiveRegistry): {
+        signal: {
+            [key: string]: SerializedSignal;
+        };
+    };
+}

package/types/signal/serializer/index.d.ts

@@ -0,0 +1 @@
+export * from "./fetch.serializer";

package/types/signal/serializer.d.ts

@@ -0,0 +1 @@
+export * from "./serializer/index.d.ts";

package/types/signal/serverSignal.d.ts

@@ -0,0 +1,36 @@
+import { ENDPOINT_META, INJECT_META, INTERNAL_META } from "akanjs/base";
+import type { DocumentModel } from "akanjs/constant";
+import { type Adaptor, type AdaptorCls, type AkanJob, type AkanJobOptions, type QueueAdaptor } from "akanjs/service";
+import type { ServerWebSocket } from "bun";
+import type { EndpointInfo } from "./endpointInfo.d.ts";
+import type { InternalInfo } from "./internalInfo.d.ts";
+export interface ServerSignal extends Adaptor {
+    readonly websocket: ServerWebSocket;
+    readonly queue: QueueAdaptor;
+}
+type EndpointServerSignalMethods<EnpCls> = EnpCls extends {
+    [ENDPOINT_META]: infer EndpointInfoObj;
+} ? {
+    [K in keyof EndpointInfoObj as EndpointInfoObj[K] extends EndpointInfo<"pubsub", any, any, any, any, any, any, any, any> ? K : never]: EndpointInfoObj[K] extends EndpointInfo<any, any, any, any, any, infer ServerArgs, any, infer ClientReturns, any, any> ? (...args: [...ServerArgs, data: DocumentModel<ClientReturns>]) => void : never;
+} : never;
+type InternalServerSignalMethods<IntCls> = IntCls extends {
+    [INTERNAL_META]: infer InternalInfoObj;
+} ? {
+    [K in keyof InternalInfoObj as InternalInfoObj[K] extends InternalInfo<"process", any, any, any, any, any, any, any> ? K : never]: InternalInfoObj[K] extends InternalInfo<any, any, infer ServerArgs, any, any, any, infer ServerReturns> ? (...args: [...args: ServerArgs, jobOptions?: AkanJobOptions]) => Promise<AkanJob<any, ServerReturns>> : never;
+} : never;
+type ServerSignalClsStatics = {
+    readonly refName: string;
+    readonly [INJECT_META]: {
+        queue: QueueAdaptor;
+    };
+    readonly [ENDPOINT_META]: {
+        [key: string]: EndpointInfo;
+    };
+    readonly [INTERNAL_META]: {
+        [key: string]: InternalInfo;
+    };
+};
+export type ServerSignalCls<EnpCls = any, IntCls = any> = AdaptorCls<EndpointServerSignalMethods<EnpCls> & InternalServerSignalMethods<IntCls> & ServerSignal> & ServerSignalClsStatics;
+/** Composes endpoint and internal classes into a server-side signal class. */
+export declare const serverSignal: <EnpCls, IntCls>(endpointRef: EnpCls, internalRef: IntCls) => ServerSignalCls<EnpCls, IntCls>;
+export {};

package/types/signal/signalContext.d.ts

@@ -0,0 +1,96 @@
+import { type BaseEnv, type PromiseOrObject } from "akanjs/base";
+import { type ConstantFieldTypeInput } from "akanjs/constant";
+import type { Adaptor, AdaptorCls, DatabaseService, InjectRegistry, LiveRegistry } from "akanjs/service";
+import type { Internal, InternalInfo, MiddlewareCls } from ".";
+import type { EndpointInfo } from "./endpointInfo.d.ts";
+import { SignalTrace } from "./trace.d.ts";
+export type SignalTransportType = "http" | "websocket";
+interface WebSocketRequest {
+    ws: Bun.ServerWebSocket<unknown>;
+    data: unknown[];
+    eventType: WebSocketEventType;
+}
+type RuntimeRecord = Record<string, unknown>;
+export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketExecutionContext = HttpExecutionContext | WebSocketExecutionContext, Env extends BaseEnv = BaseEnv> {
+    #private;
+    key: string;
+    transport: SignalTransportType;
+    ctx: Ctx;
+    endpointInfo: EndpointInfo;
+    adaptor: Adaptor;
+    args: unknown[];
+    internalArgs: unknown[];
+    trace: SignalTrace | null;
+    constructor(key: string, reqOrWsReq: Bun.BunRequest | WebSocketRequest, { endpointInfo, adaptor, registry, env, live, middleware, }: {
+        endpointInfo: EndpointInfo;
+        adaptor: Adaptor;
+        registry: InjectRegistry;
+        env: Env;
+        live: LiveRegistry;
+        middleware: Map<string, MiddlewareCls>;
+    });
+    getAdaptor<T extends Adaptor>(adaptorCls: AdaptorCls<T>): T;
+    init(): Promise<this>;
+    exec(): Promise<Response | undefined>;
+    static try(endpoint: Adaptor, endpointInfo: EndpointInfo, key: string, fn: () => Promise<Response | undefined>): Promise<Response | undefined>;
+    static resolveReturn(value: unknown, { signalContext, returnRef, arrDepth, registry, live, }: {
+        signalContext: SignalContext | null;
+        returnRef: ConstantFieldTypeInput;
+        arrDepth: number;
+        registry: InjectRegistry;
+        live: LiveRegistry;
+    }): Promise<unknown>;
+    static loadNested(value: unknown, service: DatabaseService, { arrDepth, nullable }: {
+        arrDepth: number;
+        nullable: boolean;
+    }): Promise<unknown>;
+    getHttpContext<Appended = unknown>(): HttpExecutionContext<Appended>;
+    getWebSocketContext<Appended = unknown>(): WebSocketExecutionContext<Appended>;
+    getRoomId(key: string): string;
+    getEnv(): Env;
+}
+export declare class HttpExecutionContext<Appended = unknown> {
+    #private;
+    req: Bun.BunRequest & Appended;
+    res: {
+        new (body?: BodyInit | null, init?: ResponseInit): Response;
+        prototype: Response;
+        error(): Response;
+        json(data: any, init?: ResponseInit): Response;
+        redirect(url: string | URL, status?: number): Response;
+    };
+    params: RuntimeRecord;
+    searchParams: RuntimeRecord;
+    body: RuntimeRecord;
+    constructor(req: Bun.BunRequest);
+    get url(): URL;
+    getArgs(endpointInfo: EndpointInfo): Promise<unknown[]>;
+    makeResponse(result: unknown, endpointInfo: EndpointInfo): Response;
+}
+export type WebSocketEventType = "open" | "subscribe" | "unsubscribe" | "message" | "close";
+export declare class WebSocketExecutionContext<Appended = unknown> {
+    ws: Bun.ServerWebSocket<Appended>;
+    data: unknown[];
+    roomId: string;
+    eventType: WebSocketEventType;
+    onDisconnect: Set<() => PromiseOrObject<void>>;
+    onUnsubscribe: Set<() => PromiseOrObject<void>>;
+    constructor(wsReq: WebSocketRequest);
+    getArgs(endpointInfo: EndpointInfo): Promise<unknown[]>;
+    makeResponse(result: unknown, endpointInfo: EndpointInfo): Response;
+    on(event: "disconnect" | "unsubscribe", handler: () => void): void;
+    off(event: "disconnect" | "unsubscribe", handler: () => void): void;
+}
+export declare class ResolveFieldContext {
+    signalContext: SignalContext | null;
+    internalInfo: InternalInfo<"resolveField">;
+    internal: Internal;
+    parent: unknown;
+    constructor(parent: unknown, { signalContext, internalInfo, internal, }: {
+        signalContext: SignalContext | null;
+        internalInfo: InternalInfo<"resolveField">;
+        internal: Internal;
+    });
+    exec(): Promise<any>;
+}
+export {};

package/types/signal/signalRegistry.d.ts

@@ -0,0 +1,49 @@
+import type { EndpointCls } from "./endpoint.d.ts";
+import type { InternalCls } from "./internal.d.ts";
+import type { ServerSignalCls } from "./serverSignal.d.ts";
+import type { SliceCls } from "./slice.d.ts";
+import type { SerializedSignal } from "./types.d.ts";
+type SignalBaseRef<SigCls> = SigCls extends {
+    srv: {
+        srv: {
+            refName: infer RefName;
+        };
+    };
+} ? RefName : never;
+type SignalWithBase<RefName extends string, SigCls> = SignalBaseRef<SigCls> extends RefName ? SigCls : never;
+export declare class DatabaseSignal<IntlCls extends InternalCls = InternalCls, EndpCls extends EndpointCls = EndpointCls, SlceCls extends SliceCls = SliceCls, SrvrCls extends ServerSignalCls = ServerSignalCls> {
+    internal: IntlCls;
+    endpoint: EndpCls;
+    slice: SlceCls;
+    server: SrvrCls;
+    serializedSignal: SerializedSignal;
+    constructor(internal: IntlCls, endpoint: EndpCls, slice: SlceCls, server: SrvrCls);
+}
+export declare class ServiceSignal<IntlCls extends InternalCls = InternalCls, EndpCls extends EndpointCls = EndpointCls, SrvrCls extends ServerSignalCls = ServerSignalCls> {
+    internal: IntlCls;
+    endpoint: EndpCls;
+    server: SrvrCls;
+    serializedSignal: SerializedSignal;
+    constructor(internal: IntlCls, endpoint: EndpCls, server: SrvrCls);
+}
+/** Registry for database and service signals used by routing and fetch serialization. */
+export declare class SignalRegistry {
+    #private;
+    static registerDatabase<RefName extends string, IntlCls extends InternalCls, EndpCls extends EndpointCls, SlceCls extends SliceCls, SrvrCls extends ServerSignalCls>(refName: RefName, internal: SignalWithBase<RefName, IntlCls>, endpoint: SignalWithBase<RefName, EndpCls>, slice: SignalWithBase<RefName, SlceCls>, server: SrvrCls): DatabaseSignal<IntlCls, EndpCls, SlceCls, SrvrCls>;
+    static getDatabase(refName: string): DatabaseSignal<InternalCls, EndpointCls<import("../service.d.ts").ServiceModel<import("../service.d.ts").ServiceCls, any, any, {
+        [x: `${Uncapitalize<string>}Service`]: import("../service.d.ts").ExtractInjectInfoObject<{}> & import("../service.d.ts").Service;
+    }>, {
+        [key: string]: import("./endpointInfo.d.ts").EndpointInfo<import("./endpointInfo.d.ts").EndpointType, {
+            [key: string]: any;
+        }, any, any, any, any, import("../constant.d.ts").ConstantFieldTypeInput, never, never, boolean>;
+    }>, SliceCls, ServerSignalCls> | undefined;
+    static registerService<RefName extends string, IntlCls extends InternalCls, EndpCls extends EndpointCls, SrvrCls extends ServerSignalCls>(refName: RefName, internal: SignalWithBase<RefName, IntlCls>, endpoint: SignalWithBase<RefName, EndpCls>, server: SrvrCls): ServiceSignal<IntlCls, EndpCls, SrvrCls>;
+    static getService(refName: string): ServiceSignal<InternalCls, EndpointCls<import("../service.d.ts").ServiceModel<import("../service.d.ts").ServiceCls, any, any, {
+        [x: `${Uncapitalize<string>}Service`]: import("../service.d.ts").ExtractInjectInfoObject<{}> & import("../service.d.ts").Service;
+    }>, {
+        [key: string]: import("./endpointInfo.d.ts").EndpointInfo<import("./endpointInfo.d.ts").EndpointType, {
+            [key: string]: any;
+        }, any, any, any, any, import("../constant.d.ts").ConstantFieldTypeInput, never, never, boolean>;
+    }>, ServerSignalCls> | undefined;
+}
+export {};

package/types/signal/slice.d.ts

@@ -0,0 +1,42 @@
+import { type Assign, type Cls, type MergeAllKeyOfObjects, SLICE_META } from "akanjs/base";
+import type { DocumentModel, QueryOf } from "akanjs/constant";
+import type { FilterInstance } from "akanjs/document";
+import { type Adaptor, type AdaptorCls, type ServiceModel } from "akanjs/service";
+import type { Guard, GuardCls } from "./guard.d.ts";
+import { type SliceBuilder, type SliceInfo } from "./sliceInfo.d.ts";
+export interface Slice extends Adaptor {
+}
+export type SliceCls<SrvModule extends ServiceModel = ServiceModel, SliceInfoObj extends {
+    [key: string]: SliceInfo;
+} = {
+    [key: string]: SliceInfo;
+}> = AdaptorCls & {
+    baseName: SrvModule["srv"]["refName"];
+    srv: SrvModule;
+    [SLICE_META]: SliceInfoObj;
+    getGuards: GuardCls[];
+    cruGuards: GuardCls[];
+};
+interface RootSliceOption {
+    guards?: {
+        root?: Cls<Guard> | Cls<Guard>[];
+        get?: Cls<Guard> | Cls<Guard>[];
+        cru?: Cls<Guard> | Cls<Guard>[];
+    };
+    prefix?: string;
+}
+type ExtendSliceInfoObj<SrvModule extends ServiceModel, LibSlices extends SliceCls[], _Input = NonNullable<SrvModule["cnst"]>["_Input"], _Full = NonNullable<SrvModule["cnst"]>["_Full"], _Light = NonNullable<SrvModule["cnst"]>["_Light"], _Insight = NonNullable<SrvModule["cnst"]>["_Insight"], _Filter extends FilterInstance = any, _Merged = MergeAllKeyOfObjects<LibSlices, typeof SLICE_META>> = {
+    [K in keyof _Merged]: _Merged[K] extends SliceInfo<any, any, any, any, any, any, infer Srvs, infer ArgNames, infer Args, infer InternalArgs, infer ServerArgs> ? SliceInfo<SrvModule["srv"]["refName"], _Input, _Full, _Light, _Insight, _Filter, Srvs, ArgNames, Args, InternalArgs, ServerArgs> : never;
+};
+/** Builds database-backed slice APIs for list, insight, init, view, edit, create, update, and remove flows. */
+export declare function slice<SrvModule extends ServiceModel, BuildSlice extends SliceBuilder<SrvModule>, LibSlices extends SliceCls[], _Input = NonNullable<SrvModule["cnst"]>["_Input"], _Full = NonNullable<SrvModule["cnst"]>["_Full"], _Light = NonNullable<SrvModule["cnst"]>["_Light"], _Insight = NonNullable<SrvModule["cnst"]>["_Insight"], _Filter extends FilterInstance = NonNullable<SrvModule["db"]>["_Filter"], _Query = QueryOf<DocumentModel<_Full>>>(srv: SrvModule, option: RootSliceOption, sliceBuilder: BuildSlice, ...libSlices: LibSlices): SliceCls<SrvModule, Assign<ReturnType<BuildSlice>, LibSlices extends [] ? {
+    [""]: SliceInfo<SrvModule["srv"]["refName"], _Input, _Full, _Light, _Insight, _Filter, SrvModule["srvMap"], [
+        "query"
+    ], [
+        _Query
+    ], [
+    ], [
+        _Query
+    ]>;
+} : ExtendSliceInfoObj<SrvModule, LibSlices>>>;
+export {};

package/types/signal/sliceInfo.d.ts

@@ -0,0 +1,51 @@
+import type { Cls, PromiseOrObject } from "akanjs/base";
+import type { BaseInsight, BaseObject, ConstantFieldTypeInput, DocumentModel, FieldToValue, ParamFieldType, PlainTypeToFieldType, PurifiedModel, QueryOf } from "akanjs/constant";
+import type { ExtractSort, FilterCls, FilterInstance } from "akanjs/document";
+import type { ServiceModel } from "akanjs/service";
+import { type ArgInfo, type EndpointArgProps, type InternalArgInfo, type InternalArgProps } from "./endpointInfo.d.ts";
+import type { InternalArgCls } from "./internalArg.d.ts";
+import type { SignalOption } from "./types.d.ts";
+export declare class SliceInfo<RefName extends string = string, Input = any, Full = any, Light = any, Insight = any, Filter extends FilterInstance = any, Srvs extends {
+    [key: string]: any;
+} = {
+    [key: string]: any;
+}, ArgNames extends string[] = any, Args extends any[] = any, InternalArgs extends any[] = any, ServerArgs extends any[] = any> {
+    readonly refName: RefName;
+    readonly input: Cls<Input>;
+    readonly full: Cls<Full>;
+    readonly light: Cls<Light>;
+    readonly insight: Cls<Insight>;
+    readonly filter: FilterCls<Filter>;
+    readonly argNames: ArgNames;
+    readonly args: ArgInfo<EndpointArgProps<boolean>>[];
+    readonly internalArgs: InternalArgInfo<boolean>[];
+    readonly signalOption: SignalOption;
+    execFn: ((...args: [...ServerArgs, ...InternalArgs]) => QueryOf<DocumentModel<Full>>) | null;
+    constructor(refName: RefName, input: Cls<Input>, full: Cls<Full>, light: Cls<Light>, insight: Cls<Insight>, filter: FilterCls<Filter>, signalOption?: SignalOption);
+    param<ArgName extends string, Arg extends ParamFieldType, _ClientArg = FieldToValue<Arg>, _ServerArg = DocumentModel<_ClientArg>>(name: ArgName, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg]>;
+    body<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, Optional extends boolean = false, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], Optional extends true ? [...Args, arg?: _ClientArg | null] : [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg | (Optional extends true ? undefined : never)]>;
+    search<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], [...Args, arg?: _ClientArg | null], InternalArgs, [...ServerArgs, arg: _ServerArg | undefined]>;
+    with<ArgType, Optional extends boolean = false>(argRef: InternalArgCls<ArgType>, option?: InternalArgProps<Optional>): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, ArgNames, Args, [...InternalArgs, arg: NonNullable<ArgType> | (Optional extends true ? null : never)], ServerArgs>;
+    exec(query: (this: {
+        [K in keyof Srvs as K extends string ? Uncapitalize<K> : never]: Srvs[K];
+    }, ...args: [...ServerArgs, ...InternalArgs]) => PromiseOrObject<QueryOf<DocumentModel<Full>>>): this;
+}
+export declare const buildSlice: <T extends string, Input extends Cls<any>, Full extends BaseObject, Light extends BaseObject, Insight extends BaseInsight, Filter extends FilterInstance, SrvModule extends ServiceModel>(refName: T, input: Cls<Input>, full: Cls<Full>, light: Cls<Light>, insight: Cls<Insight>, filter: FilterCls<Filter>) => (signalOption?: SignalOption) => SliceInfo<T, Input, Full, Light, Insight, Filter, SrvModule["srvMap"], [], [], [], []>;
+export type SliceInfoRefName<S> = S extends SliceInfo<infer R, any, any, any, any, any, any, any, any, any, any> ? R : never;
+export type SliceInfoInput<S> = S extends SliceInfo<any, infer I, any, any, any, any, any, any, any, any, any> ? I : never;
+export type SliceInfoFull<S> = S extends SliceInfo<any, any, infer F, any, any, any, any, any, any, any, any> ? F : never;
+export type SliceInfoLight<S> = S extends SliceInfo<any, any, any, infer L, any, any, any, any, any, any, any> ? L : never;
+export type SliceInfoInsight<S> = S extends SliceInfo<any, any, any, any, infer I, any, any, any, any, any, any> ? I : never;
+export type SliceInfoFilter<S> = S extends SliceInfo<any, any, any, any, any, infer F, any, any, any, any, any> ? F : never;
+export type SliceInfoSrvs<S> = S extends SliceInfo<any, any, any, any, any, any, infer S2, any, any, any, any> ? S2 : never;
+export type SliceInfoArgNames<S> = S extends SliceInfo<any, any, any, any, any, any, any, infer N, any, any, any> ? N : never;
+export type SliceInfoArgs<S> = S extends SliceInfo<any, any, any, any, any, any, any, any, infer A, any, any> ? A : never;
+export type SliceInfoInternalArgs<S> = S extends SliceInfo<any, any, any, any, any, any, any, any, any, infer I, any> ? I : never;
+export type SliceInfoServerArgs<S> = S extends SliceInfo<any, any, any, any, any, any, any, any, any, any, infer S2> ? S2 : never;
+export type SliceBuilder<SrvModule extends ServiceModel, _Input = NonNullable<SrvModule["cnst"]>["_Input"], _Full = NonNullable<SrvModule["cnst"]>["_Full"], _Light = NonNullable<SrvModule["cnst"]>["_Light"], _Insight = NonNullable<SrvModule["cnst"]>["_Insight"], _Filter extends FilterInstance = NonNullable<SrvModule["db"]>["_Filter"], _Sort = ExtractSort<_Filter>> = (init: (signalOption?: SignalOption) => SliceInfo<SrvModule["srv"]["refName"], _Input, _Full, _Light, _Insight, _Filter, SrvModule["srvMap"], [
+], [
+], [
+], [
+]>) => {
+    [key: string]: SliceInfo<SrvModule["srv"]["refName"], _Input, _Full, _Light, _Insight, _Filter, SrvModule["srvMap"]>;
+};

package/types/signal/trace.d.ts

@@ -0,0 +1,97 @@
+/** Whether request tracing is enabled. Cached after first read. */
+export declare const isTraceEnabled: () => boolean;
+/** Override the trace flag at runtime (tests / harness control). */
+export declare const setTraceEnabled: (enabled: boolean) => void;
+export interface SpanRecord {
+    name: string;
+    durationMs: number;
+}
+/** Per-request trace context. Threaded via {@link AsyncLocalStorage}. */
+export declare class SignalTrace {
+    #private;
+    readonly traceId: string;
+    readonly endpointKey: string;
+    readonly endpointType: string;
+    readonly startedAt: number;
+    readonly spans: SpanRecord[];
+    dbQueryCount: number;
+    dbQueryMs: number;
+    cacheHits: number;
+    cacheMisses: number;
+    dataLoaderBatchCount: number;
+    dataLoaderKeyCount: number;
+    constructor(endpointKey: string, endpointType: string);
+    recordSpan(name: string, durationMs: number): void;
+    countDbQuery(durationMs: number): void;
+    countCache(hit: boolean): void;
+    countDataLoaderBatch(keyCount: number): void;
+    finalize(): void;
+}
+export declare const getCurrentTrace: () => SignalTrace | undefined;
+/** Run `fn` with `trace` as the ambient request trace. */
+export declare const runWithTrace: <T>(trace: SignalTrace, fn: () => T) => T;
+/**
+ * Time an async stage under the current trace. When tracing is off (or no trace is
+ * active) this is a thin passthrough with no measurement overhead.
+ */
+export declare const traceSpan: <T>(name: string, fn: () => Promise<T>) => Promise<T>;
+/** Record a DB query duration against the current trace (no-op when untraced). */
+export declare const traceDbQuery: (durationMs: number) => void;
+/** Record a cache hit/miss against the current trace (no-op when untraced). */
+export declare const traceCache: (hit: boolean) => void;
+/** Record a DataLoader batch against the current trace (no-op when untraced). */
+export declare const traceDataLoaderBatch: (keyCount: number) => void;
+/**
+ * Process-wide aggregator. Keeps rolling per-endpoint, per-span statistics with a
+ * bounded sample ring per span so percentiles stay representative of steady state
+ * without unbounded memory growth.
+ */
+declare class TraceAggregator {
+    #private;
+    ingest(trace: SignalTrace): void;
+    reset(): void;
+    /** Summarized snapshot suitable for JSON exposure on the metrics endpoint. */
+    snapshot(): {
+        enabled: boolean;
+        endpoints: {
+            endpoint: string;
+            requests: number;
+            avgDbQueriesPerRequest: number;
+            avgDbQueryMsPerRequest: number;
+            cacheHitRatio: number | null;
+            avgDataLoaderBatchSize: number | null;
+            spans: {
+                name: string;
+                count: number;
+                meanMs: number;
+                p50Ms: number;
+                p95Ms: number;
+                p99Ms: number;
+                maxMs: number;
+            }[];
+        }[];
+    };
+}
+export declare const traceAggregator: TraceAggregator;
+/** Snapshot of all aggregated trace stats. Safe to call when tracing is disabled. */
+export declare const getTraceSnapshot: () => {
+    enabled: boolean;
+    endpoints: {
+        endpoint: string;
+        requests: number;
+        avgDbQueriesPerRequest: number;
+        avgDbQueryMsPerRequest: number;
+        cacheHitRatio: number | null;
+        avgDataLoaderBatchSize: number | null;
+        spans: {
+            name: string;
+            count: number;
+            meanMs: number;
+            p50Ms: number;
+            p95Ms: number;
+            p99Ms: number;
+            maxMs: number;
+        }[];
+    }[];
+};
+export {};