akanjs 2.2.4-rc.4 → 2.2.4

package/signal/signalContext.ts

@@ -360,7 +360,7 @@ export class HttpExecutionContext<Appended = unknown> {
   async getArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
     if (endpointInfo.args.length === 0) return [];
     this.params = this.req.params;
-    
+    // TODO: Optimize the efficiency of this code
     const hasBodyArgs = endpointInfo.args.some((arg) => arg.type === "body");
     const hasUploadArgs = hasBodyArgs && endpointInfo.args.some((arg) => arg.type === "body" && arg.argRef === Upload);
     if (endpointInfo.type === "mutation" && hasBodyArgs && this.req.body) {

package/signal/signalRegistry.ts

@@ -56,6 +56,11 @@ export class ServiceSignal<
   }
 }
 
+// TODO: add scalar signal for resolve field
+// export interface ScalarSignal {
+//   internal: InternalCls;
+// }
+
 /** Registry for database and service signals used by routing and fetch serialization. */
 export class SignalRegistry {
   static readonly #database = new Map<string, DatabaseSignal<InternalCls, EndpointCls, SliceCls, ServerSignalCls>>();

package/signal/sliceInfo.ts

@@ -202,6 +202,9 @@ export const buildSlice =
       signalOption,
     );
 
+// --- Accessors ---
+// Named projections for SliceInfo's 11 generics. Use these to avoid repeating
+// 11-slot `extends SliceInfo<any, any, ..., infer X, any, any>` patterns.
 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> =

package/signal/trace.ts

@@ -81,6 +81,13 @@ export class SignalTrace {
   }
 }
 
+// Shared across bundle chunks (see traceAggregator note) so that span/db/cache helpers
+// invoked from other modules (database.resolver, middleware) observe the active trace.
+// Shared store pinned to `process`. The akan worker loads the app server bundle and the
+// framework runtime in separate module realms (each with its own `globalThis`), so the
+// signal layer that records spans and the metrics collector that reads them would otherwise
+// hold different singletons. `process` is the one object shared across realms in a single OS
+// process, so we hang the trace ALS + aggregator off it to guarantee a single instance.
 const traceProcessStore = process as unknown as {
   __akanTraceAls?: AsyncLocalStorage<SignalTrace>;
   __akanTraceAggregator?: TraceAggregator;
@@ -246,6 +253,10 @@ const round = (value: number, digits = 3): number => {
   return Math.round(value * factor) / factor;
 };
 
+// The akan build can bundle this module into more than one chunk (e.g. the signal layer
+// that writes spans vs. the metrics collector that reads them). A plain module-level
+// singleton would then diverge per chunk, so pin it to globalThis to guarantee that every
+// copy of this module shares one aggregator within the process.
 let aggregatorInstance = traceProcessStore.__akanTraceAggregator;
 if (!aggregatorInstance) {
   aggregatorInstance = new TraceAggregator();

package/signal/types.ts

@@ -4,6 +4,11 @@ import type { GuardCls } from "./guard";
 import type { MiddlewareCls } from "./middleware";
 import type { SliceCls } from "./slice";
 
+// --- ServiceModel projection helpers (D1) ---
+// Use these instead of re-typing `NonNullable<SrvModule["cnst"]>["_Full"]` /
+// `SlceCls["srv"]["cnst"]["_Full"]` everywhere. Centralizing the path keeps
+// type derivations consistent and dramatically reduces the amount of text
+// TypeScript has to re-evaluate at each callsite.
 export type CnstOf<S extends ServiceModel> = NonNullable<S["cnst"]>;
 export type DbOf<S extends ServiceModel> = NonNullable<S["db"]>;
 
@@ -23,6 +28,8 @@ export type CnstCapitalizedRefName<S extends ServiceModel> = CnstOf<S>["_Capital
 export type DbFilter<S extends ServiceModel> = DbOf<S>["_Filter"];
 export type DbSort<S extends ServiceModel> = DbOf<S>["_Sort"];
 
+// Slice-cls shortcuts (common in store/state/action). The branches that
+// include `SlceCls extends SliceCls` preserve `ServiceModel` inference.
 export type SlceSrv<S extends SliceCls> = S["srv"];
 export type SlceCnstRefName<S extends SliceCls> = S["srv"]["cnst"]["refName"];
 export type SlceCnstInput<S extends SliceCls> = S["srv"]["cnst"]["_Input"];
@@ -73,11 +80,13 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
   /** Marks this mutation as the framework file-upload endpoint (see resolveFileUploadCapability). */
   fileUpload?: boolean;
 
+  // * ==================== Schedule ==================== * //
   scheduleType?: "init" | "destroy" | "cron" | "interval" | "timeout";
   scheduleCron?: string;
   scheduleTime?: number;
   lock?: boolean;
   enabled?: boolean;
+  // * ==================== Schedule ==================== * //
 }
 
 interface SerializedSignalOption {
@@ -92,7 +101,7 @@ export interface SerializedSlice extends SerializedSignalOption {}
 
 export interface SerializedReturns {
   refName: Exclude<DefaultPrimitiveName, "Map" | "Upload"> | (string & {});
-  modelType?: "input" | "full" | "light" | "insight" | "scalar"; 
+  modelType?: "input" | "full" | "light" | "insight" | "scalar"; // undefined when primitive
   arrDepth?: number;
   partial?: string[];
   nullable?: boolean;
@@ -101,7 +110,7 @@ export interface SerializedArg {
   type: ArgType;
   refName: Exclude<DefaultPrimitiveName, "Map"> | (string & {});
   name: string;
-  modelType?: "input" | "object" | "insight" | "scalar"; 
+  modelType?: "input" | "object" | "insight" | "scalar"; // undefined when primitive
   arrDepth?: number;
   nullable?: boolean;
   example?: string | number | boolean | Date;

package/store/action.ts

@@ -783,6 +783,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
       const currentState = this.get() as { [key: string]: any };
       if (fullOrLightModels.length === 0) return;
 
+      // set the first model to the model state
       const firstModel = fullOrLightModels[0];
       const model = currentState[names.model] as Full | null;
       const isFull = firstModel instanceof modelRef;
@@ -797,6 +798,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
         this.set({ [names.model]: crystalizedModel });
       }
 
+      // set the rest of the models to the model list
       const lightModels = fullOrLightModels.map(
         (fullOrLightModel) => new cnst.light().set(fullOrLightModel) as unknown as Light,
       );
@@ -905,7 +907,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
           limit === limitOfModel &&
           isQueryEqual(sort as unknown as object, sortOfModel as unknown as object)
         )
-          return; 
+          return; // store-level cache hit
         else this.set({ [namesOfSlice.modelListLoading]: true });
         const fetchQueryArgs = expandQueryArgs(queryArgs, slice.args);
         const [modelDataList, modelInsight] = await Promise.all([
@@ -1044,7 +1046,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
         const sortOfModel = currentState[namesOfSlice.sortOfModel] as Sort;
         if (isQueryEqual(queryArgsOfModel, queryArgs)) {
           Logger.trace(`${namesOfSlice.queryArgsOfModel} store-level cache hit`);
-          return; 
+          return; // store-level cache hit
         }
         this.set({ [namesOfSlice.modelListLoading]: true });
         const fetchQueryArgs = expandQueryArgs(queryArgs, slice.args);
@@ -1077,7 +1079,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
         const queryArgsOfModel = currentState[namesOfSlice.queryArgsOfModel] as object[];
         const limitOfModel = currentState[namesOfSlice.limitOfModel] as number;
         const sortOfModel = currentState[namesOfSlice.sortOfModel] as Sort;
-        if (sortOfModel === sort) return; 
+        if (sortOfModel === sort) return; // store-level cache hit
         this.set({ [namesOfSlice.modelListLoading]: true });
         const fetchQueryArgs = expandQueryArgs(queryArgsOfModel, slice.args);
         const modelDataList = await (fetch[namesOfSlice.modelList] as (...args: any[]) => Promise<Light[]>)(

package/store/stateBuilder.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, mock, spyOn, test } from "bun:test";
+import { enumOf, Int } from "akanjs/base";
+import { ConstantRegistry, via } from "akanjs/constant";
+import {
+  createDerivedStateBuilder,
+  createWritableStateBuilder,
+  mergeDerivedMeta,
+  resolveDerivedState,
+  resolveWritableState,
+} from "./stateBuilder";
+
+class StateBuilderTestMode extends enumOf("StateBuilderTestMode", ["list", "grid"] as const) {}
+const StateBuilderTestAddress = via((f) => ({
+  city: f(String),
+  zip: f(Int, { default: 10000 }),
+}));
+ConstantRegistry.buildScalar("stateBuilderTestAddress", StateBuilderTestAddress, { StateBuilderTestAddress });
+
+const setupEnv = () => {
+  process.env.AKAN_PUBLIC_APP_NAME = "storetest";
+  process.env.AKAN_PUBLIC_REPO_NAME = "storetest";
+  process.env.AKAN_PUBLIC_SERVE_DOMAIN = "localhost";
+  process.env.AKAN_PUBLIC_ENV = "testing";
+};
+
+describe("makeDefaultFactory", () => {
+  test("preserves DataList instances when cloning default state", async () => {
+    setupEnv();
+
+    const [{ DataList }, { makeDefaultFactory }] = await Promise.all([import("akanjs/base"), import("./stateBuilder")]);
+    const original = new DataList([{ id: "project-1", name: "Project 1" }]);
+    const clone = makeDefaultFactory(original)();
+
+    expect(clone).toBeInstanceOf(DataList);
+    expect(clone).not.toBe(original);
+    expect(clone.map((project) => project.name)).toEqual(["Project 1"]);
+    expect(clone.get("project-1")?.name).toBe("Project 1");
+  });
+
+  test("keeps non-plain browser-like objects as opaque references", async () => {
+    setupEnv();
+
+    const { makeDefaultFactory } = await import("./stateBuilder");
+    class BrowserResource {
+      readonly id = "stream-1";
+      getTracks() {
+        return ["audio"];
+      }
+    }
+    const original = new BrowserResource();
+    const clone = makeDefaultFactory(original)();
+
+    expect(clone).toBe(original);
+    expect(clone.getTracks()).toEqual(["audio"]);
+  });
+});
+
+describe("state builder declarations", () => {
+  test("resolves persist and session metadata with typed defaults and codecs", () => {
+    setupEnv();
+    const builder = createWritableStateBuilder();
+    const state = {
+      count: builder.persist(Int, { default: 7, key: "countOverride" }),
+      tags: builder.session([String], { default: ["alpha"] }),
+      mode: builder.persist(StateBuilderTestMode, { default: "list" }),
+      address: builder.persist(StateBuilderTestAddress, {
+        default: () => new StateBuilderTestAddress({ city: "Seoul" }),
+      }),
+    };
+
+    const resolved = resolveWritableState("prefs", state);
+
+    expect(resolved.shape).toMatchObject({
+      count: 7,
+      tags: ["alpha"],
+      mode: "list",
+    });
+    expect(resolved.shape.address).toBeInstanceOf(StateBuilderTestAddress);
+    expect((resolved.shape.address as InstanceType<typeof StateBuilderTestAddress>).zip).toBe(10000);
+    expect(resolved.meta.persistSession.count).toMatchObject({
+      kind: "persist",
+      key: "count",
+    });
+    expect(resolved.meta.persistSession.count.storageKey).toContain(".prefs.countOverride");
+    expect(resolved.meta.persistSession.tags.kind).toBe("session");
+    expect(resolved.meta.persistSession.count.parse("9")).toBe(9);
+    expect(resolved.meta.persistSession.tags.parse(["a", "b"])).toEqual(["a", "b"]);
+    expect(resolved.meta.persistSession.mode.parse("grid")).toBe("grid");
+    expect(() => resolved.meta.persistSession.mode.parse("invalid")).toThrow("Invalid enum value");
+
+    const parsedAddress = resolved.meta.persistSession.address.parse({ city: "Busan", zip: "12345" });
+    expect(parsedAddress).toEqual({ city: "Busan", zip: 12345 });
+    expect(resolved.meta.persistSession.address.serialize(parsedAddress)).toEqual({ city: "Busan", zip: 12345 });
+  });
+
+  test("parses search state from repeated params and JSON object params", () => {
+    setupEnv();
+    const builder = createDerivedStateBuilder<{ searchParams: Record<string, string | string[]> }>();
+    const resolved = resolveDerivedState(
+      {
+        ids: builder.search("id", [Int], { default: [1] }),
+        modes: builder.search("mode", [StateBuilderTestMode], { default: ["list"] }),
+        addresses: builder.search("address", [StateBuilderTestAddress], { default: [] }),
+        enabled: builder.search("enabled", Boolean, { default: false }),
+      },
+      new Set(["searchParams"]),
+    );
+
+    expect(resolved.meta.search.ids.parseSearch({ id: ["3", "4"] })).toEqual([3, 4]);
+    expect(resolved.meta.search.modes.parseSearch({ mode: JSON.stringify(["grid", "list"]) })).toEqual([
+      "grid",
+      "list",
+    ]);
+    expect(
+      resolved.meta.search.addresses.parseSearch({
+        address: JSON.stringify([
+          { city: "Seoul", zip: 12345 },
+          { city: "Jeju", zip: 10000 },
+        ]),
+      }),
+    ).toEqual([
+      { city: "Seoul", zip: 12345 },
+      { city: "Jeju", zip: 10000 },
+    ]);
+    expect(resolved.meta.search.enabled.parseSearch({ enabled: "true" })).toBe(true);
+
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    expect(resolved.meta.search.ids.parseSearch({ id: "not-number" })).toEqual([1]);
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("Failed to parse search param id"));
+    warn.mockRestore();
+  });
+
+  test("validates computed dependencies and rejects duplicate derived metadata", () => {
+    setupEnv();
+    const builder = createDerivedStateBuilder<{ count: number; label: string }>();
+    const equals = mock((a: string, b: string) => a.toLowerCase() === b.toLowerCase());
+    const resolved = resolveDerivedState(
+      {
+        summary: builder.computed(["count", "label"], (count, label) => `${label}:${count}`, { equals }),
+      },
+      new Set(["count", "label"]),
+    );
+
+    expect(resolved.shape.summary).toBeUndefined();
+    expect(resolved.meta.derivedKeys.has("summary")).toBe(true);
+    expect(resolved.meta.computed.summary.deps).toEqual(["count", "label"]);
+    expect(resolved.meta.computed.summary.selector(2, "total")).toBe("total:2");
+    expect(resolved.meta.computed.summary.equals("TOTAL:2", "total:2")).toBe(true);
+    expect(equals).toHaveBeenCalled();
+
+    expect(() =>
+      resolveDerivedState({ broken: builder.computed(["missing" as never], () => "bad") }, new Set(["count"])),
+    ).toThrow("Computed broken has invalid deps: missing");
+    expect(() => mergeDerivedMeta(resolved.meta, resolved.meta)).toThrow("Duplicate state metadata key: summary");
+  });
+
+  test("rejects derived declarations that conflict with writable keys", () => {
+    setupEnv();
+    const builder = createDerivedStateBuilder<{ count: number }>();
+
+    expect(() => resolveDerivedState({ count: builder.search("count", Int) }, new Set(["count"]))).toThrow(
+      "Derived state key conflicts with writable state: count",
+    );
+    expect(() => resolveDerivedState({ count: 1 }, new Set(["value"]))).toThrow(
+      "Derived state count must be declared with search() or computed()",
+    );
+  });
+});

package/store/stateBuilder.ts

@@ -278,6 +278,7 @@ export const makeDefaultFactory = (value: unknown): StateInitializer => {
         try {
           return structuredClone(value);
         } catch {
+          // Fall back to recursive clone for class-like plain data.
         }
       }
       return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, makeDefaultFactory(val)()]));
@@ -414,6 +415,7 @@ const getSessionKey = () => {
       sessionStorage.setItem(key, next);
       return next;
     } catch {
+      // fall through
     }
   }
   memorySessionKey ??= Math.random().toString(36).slice(2);

package/store/stateInfo.ts

@@ -1,13 +1,14 @@
 import type { EnumInstance, PrimitiveScalar } from "akanjs/base";
 import type { ConstantFieldTypeInput, PlainTypeToFieldType } from "akanjs/constant";
 
+// not implemented
 export type StateType = "normal" | "storage" | "cookie" | "param" | "searchParam";
 
 export interface StateProps<FieldValue = any, MapValue = any, Nullable extends boolean = false> {
   nullable: Nullable;
   default?: FieldValue | ((doc: { id: string }) => FieldValue);
   enum?: EnumInstance;
-  of?: MapValue; 
+  of?: MapValue; // for Map type fields
 }
 
 export class StateInfo<