akanjs 2.2.4-rc.4 → 2.2.4

package/constant/constant.test.ts

@@ -0,0 +1,374 @@
+import { describe, expect, test } from "bun:test";
+import { dayjs, enumOf, FIELD_META, ID, Int, type PrimitiveScalar } from "akanjs/base";
+import { immerable } from "immer";
+import { ConstantField, ConstantRegistry, deserialize, immerify, serialize, via } from ".";
+
+const Role = enumOf("ConstantTestRole", ["admin", "user"] as const);
+
+const CoordinateInput = via((f) => ({
+  lat: f(Int, { default: 37 }),
+  lng: f(Int, { default: 127 }),
+}));
+ConstantRegistry.buildScalar("constantTestCoordinate", CoordinateInput, { CoordinateInput });
+
+const AddressInput = via((f) => ({
+  city: f(String),
+  zip: f(Int, { default: 10000 }),
+  coordinate: f(CoordinateInput),
+}));
+ConstantRegistry.buildScalar("constantTestAddress", AddressInput, { AddressInput });
+
+const ComplexInput = via((f) => ({
+  settings: f(Map, { of: String }),
+  cube: f([[[[Int]]]] as never),
+  addressCube: f([[[AddressInput]]] as never),
+  primaryAddress: f(AddressInput),
+  addressBook: f(Map, { of: AddressInput as unknown as typeof PrimitiveScalar }),
+}));
+ConstantRegistry.buildScalar("constantTestComplex", ComplexInput, { ComplexInput });
+
+const UserInput = via((f) => ({
+  name: f(String),
+  age: f(Int, { default: 20 }),
+  role: f(String, { default: "user" }),
+  tags: f([String]),
+  metadata: f(Map, { of: String }),
+  password: f.secret(String),
+}));
+const UserObject = via(UserInput, (f) => ({
+  note: f(String).optional(),
+}));
+const UserLight = via(UserObject, ["name", "role"] as const, (r) => ({
+  profileText: r(String, { text: "search" }),
+}));
+const UserFull = via(UserObject, UserLight, (r) => ({
+  addressLabel: r(String, { text: "filter" }),
+}));
+const UserInsight = via(UserFull, (f) => ({
+  activeCount: f(Int, { default: 0, accumulate: { role: "admin" } }),
+}));
+const userModel = ConstantRegistry.buildModel(
+  "constantTestUser",
+  UserInput,
+  UserObject,
+  UserFull,
+  UserLight,
+  UserInsight,
+  { UserInput, UserObject, UserFull, UserLight, UserInsight, Role, statusLabel: "active" },
+);
+
+const TeamInput = via((f) => ({
+  owner: f(UserLight),
+  members: f([UserLight]),
+}));
+const TeamObject = via(TeamInput, (f) => ({
+  title: f(String),
+}));
+const TeamLight = via(TeamObject, ["owner", "members", "title"] as const, (r) => ({}));
+const TeamFull = via(TeamObject, TeamLight, (r) => ({}));
+const TeamInsight = via(TeamFull, (f) => ({}));
+ConstantRegistry.buildModel("constantTestTeam", TeamInput, TeamObject, TeamFull, TeamLight, TeamInsight, {
+  TeamInput,
+  TeamObject,
+  TeamFull,
+  TeamLight,
+  TeamInsight,
+});
+
+const validUserId = "1234567890abcdef12345678";
+const validChildId = "abcdefabcdefabcdefabcdef";
+const complexInput = (input: Record<string, unknown>) => input as never;
+
+const createUser = () =>
+  new UserFull({
+    id: validUserId,
+    name: "Ada",
+    age: 31,
+    role: "admin",
+    tags: ["founder", "engineer"],
+    metadata: { locale: "ko" } as never,
+    password: "secret",
+    note: "hello",
+    profileText: "Ada profile",
+    addressLabel: "Seoul",
+    createdAt: "2026-01-01T00:00:00.000Z" as never,
+    updatedAt: "2026-01-02T00:00:00.000Z" as never,
+  });
+
+describe("via and ConstantField", () => {
+  test("builds field metadata and default values", () => {
+    expect(UserInput.modelType).toBe("input");
+    expect(UserObject.modelType).toBe("object");
+    expect(UserLight.modelType).toBe("light");
+    expect(UserFull.modelType).toBe("full");
+    expect(UserInsight.modelType).toBe("insight");
+
+    const nameField = UserFull[FIELD_META].name;
+    const metadataField = UserFull[FIELD_META].metadata;
+    const passwordField = UserFull[FIELD_META].password;
+
+    expect(nameField).toBeInstanceOf(ConstantField);
+    expect(nameField.modelRef).toBe(String);
+    expect(metadataField.isMap).toBe(true);
+    expect(metadataField.of).toBe(String);
+    expect(passwordField.fieldType).toBe("hidden");
+    expect(passwordField.select).toBe(false);
+
+    expect(UserFull.getDefault()).toMatchObject({
+      name: "",
+      age: 20,
+      role: "user",
+      tags: [],
+      metadata: undefined,
+      note: null,
+      addressLabel: "",
+      password: null,
+    });
+    expect(UserFull.text.search.has("profileText")).toBe(true);
+    expect(UserFull.text.filter.has("addressLabel")).toBe(true);
+  });
+
+  test("crystalizes constructor input into typed runtime values", () => {
+    const user = createUser();
+
+    expect(user.createdAt.toISOString()).toBe(dayjs("2026-01-01T00:00:00.000Z").toISOString());
+    expect(user.metadata).toBeInstanceOf(Map);
+    expect(user.metadata.get("locale")).toBe("ko");
+
+    user.set({ age: 32 });
+
+    expect(user.age).toBe(32);
+
+    const address = new AddressInput({ city: "Seoul" } as never);
+    expect(address.city).toBe("Seoul");
+    expect(address.zip).toBe(10000);
+  });
+
+  test("supports maps, deep nested objects, and high-dimensional arrays", () => {
+    const cube = [
+      [
+        [
+          [1, 2],
+          [3, 4],
+        ],
+      ],
+    ];
+    const addressCube = [
+      [
+        [
+          { city: "Seoul", zip: 12345, coordinate: { lat: 37, lng: 127 } },
+          { city: "Busan", zip: 23456, coordinate: { lat: 35, lng: 129 } },
+        ],
+      ],
+    ];
+    const complex = new ComplexInput(
+      complexInput({
+        settings: { theme: "dark", locale: "ko" } as never,
+        cube,
+        addressCube,
+        primaryAddress: { city: "Jeju", coordinate: { lat: 33, lng: 126 } },
+        addressBook: {
+          home: { city: "Seoul", zip: 12345, coordinate: { lat: 37, lng: 127 } },
+          office: { city: "Pangyo", coordinate: { lat: 37, lng: 127 } },
+        } as never,
+      }),
+    );
+    const cubeField = ComplexInput[FIELD_META].cube;
+    const addressCubeField = ComplexInput[FIELD_META].addressCube;
+    const primaryAddressField = ComplexInput[FIELD_META].primaryAddress;
+    const addressBookField = ComplexInput[FIELD_META].addressBook;
+
+    expect(cubeField.arrDepth).toBe(4);
+    expect(cubeField.modelRef).toBe(Int as unknown as typeof cubeField.modelRef);
+    expect(addressCubeField.arrDepth).toBe(3);
+    expect(addressCubeField.modelRef).toBe(AddressInput as unknown as typeof addressCubeField.modelRef);
+    expect(addressCubeField.isScalar).toBe(true);
+    expect(primaryAddressField.isClass).toBe(true);
+    expect(primaryAddressField.isScalar).toBe(true);
+    expect(addressBookField.isMap).toBe(true);
+    expect(addressBookField.of).toBe(AddressInput as unknown as typeof addressBookField.of);
+
+    const complexValue = complex as {
+      settings: Map<string, string>;
+      cube: number[][][][];
+      primaryAddress: InstanceType<typeof AddressInput>;
+      addressCube: InstanceType<typeof AddressInput>[][][];
+      addressBook: Map<string, InstanceType<typeof AddressInput>>;
+    };
+    expect(complexValue.settings).toBeInstanceOf(Map);
+    expect(complexValue.settings.get("theme")).toBe("dark");
+    expect(complexValue.cube).toEqual(cube);
+    expect(complexValue.primaryAddress).toBeInstanceOf(AddressInput);
+    expect(complexValue.primaryAddress.coordinate).toBeInstanceOf(CoordinateInput);
+    expect(complexValue.primaryAddress.zip).toBe(10000);
+    expect(complexValue.addressCube[0][0][1]).toBeInstanceOf(AddressInput);
+    expect(complexValue.addressCube[0][0][1].coordinate.lat).toBe(35);
+    expect(complexValue.addressBook).toBeInstanceOf(Map);
+    expect(complexValue.addressBook.get("office")?.zip).toBe(10000);
+  });
+});
+
+describe("ConstantRegistry", () => {
+  test("registers model refs and resolves model names", () => {
+    expect(ConstantRegistry.getDatabase("constantTestUser")).toBe(userModel);
+    expect(ConstantRegistry.getScalar("constantTestAddress").model).toBe(AddressInput as never);
+    expect(ConstantRegistry.getRefName(UserFull)).toBe("constantTestUser");
+    expect(ConstantRegistry.getModelName(UserInput)).toBe("ConstantTestUserInput");
+    expect(ConstantRegistry.getModelName(UserObject)).toBe("ConstantTestUserObject");
+    expect(ConstantRegistry.getModelName(UserLight)).toBe("LightConstantTestUser");
+    expect(ConstantRegistry.getModelName(UserFull)).toBe("ConstantTestUser");
+    expect(ConstantRegistry.getModelName(UserInsight)).toBe("ConstantTestUserInsight");
+    expect(ConstantRegistry.getModelName(ID)).toBe("ID");
+    expect(ConstantRegistry.value.get("statusLabel")).toBe("active");
+  });
+
+  test("serializes and deserializes primitive and model values", () => {
+    expect(ConstantRegistry.serialize(Int, 7 as never)).toBe(7 as never);
+    expect(ConstantRegistry.deserialize(Int, "7")).toBe(7 as never);
+
+    const user = createUser();
+    const serialized = ConstantRegistry.serialize(UserFull, user);
+
+    expect(serialized).toMatchObject({
+      id: validUserId,
+      name: "Ada",
+      age: 31,
+      role: "admin",
+      tags: ["founder", "engineer"],
+      metadata: { locale: "ko" },
+    });
+    expect(serialized.createdAt).toBeInstanceOf(Date);
+
+    const deserialized = ConstantRegistry.deserialize(UserFull, serialized);
+
+    expect(deserialized.createdAt.toISOString()).toBe(user.createdAt.toISOString());
+    expect(deserialized.metadata).toEqual({ locale: "ko" } as never);
+  });
+});
+
+describe("serialize, deserialize, purify, and immerify", () => {
+  test("handles arrays and nullable values", () => {
+    const serialized = serialize(String, 1, ["a", "b"], "object", {});
+    expect(serialized).toEqual(["a", "b"] as never);
+    expect(serialize(String, 0, null, "object", { nullable: true })).toBeNull();
+    expect(() => serialize(String, 0, null, "object", { key: "name" })).toThrow("Invalid Value (Nullable)");
+
+    expect(deserialize(String, 1, ["a", "b"], {})).toEqual(["a", "b"] as never);
+    expect(deserialize(String, 0, null, { nullable: true })).toBeNull();
+    expect(() => deserialize(String, 0, null, { key: "name" })).toThrow("Invalid Value (Nullable)");
+  });
+
+  test("serializes and deserializes complex schema shapes", () => {
+    const complex = new ComplexInput(
+      complexInput({
+        settings: { theme: "dark" } as never,
+        cube: [[[[1, 2, 3]]]],
+        addressCube: [[[{ city: "Seoul", coordinate: { lat: 37, lng: 127 } }]]],
+        primaryAddress: { city: "Jeju", coordinate: { lat: 33, lng: 126 } },
+        addressBook: {
+          home: { city: "Seoul", coordinate: { lat: 37, lng: 127 } },
+        } as never,
+      }),
+    );
+
+    const serialized = serialize(ComplexInput, 0, complex, "object", {});
+
+    expect(serialized).toMatchObject({
+      settings: { theme: "dark" },
+      cube: [[[[1, 2, 3]]]],
+      addressCube: [[[{ city: "Seoul", zip: 10000, coordinate: { lat: 37, lng: 127 } }]]],
+      primaryAddress: { city: "Jeju", zip: 10000, coordinate: { lat: 33, lng: 126 } },
+      addressBook: { home: { city: "Seoul", zip: 10000, coordinate: { lat: 37, lng: 127 } } },
+    });
+
+    const deserialized = deserialize(ComplexInput, 0, serialized, {}) as unknown as {
+      settings: Record<string, string>;
+      cube: number[][][][];
+      addressCube: { coordinate: { lat: number; lng: number } }[][][];
+      primaryAddress: { coordinate: { lng: number } };
+      addressBook: Record<string, { coordinate: { lng: number } }>;
+    };
+
+    expect(deserialized.settings).toEqual({ theme: "dark" });
+    expect(deserialized.cube).toEqual([[[[1, 2, 3]]]]);
+    expect(deserialized.addressCube[0][0][0].coordinate.lat).toBe(37);
+    expect(deserialized.primaryAddress.coordinate.lng).toBe(126);
+    expect(deserialized.addressBook.home.coordinate.lng).toBe(127);
+  });
+
+  test("preserves resolved relation objects when serializing response objects", () => {
+    const user = createUser();
+    const team = new TeamFull({
+      id: validChildId,
+      owner: user,
+      members: [user],
+      title: "Core",
+      createdAt: "2026-01-01T00:00:00.000Z" as never,
+      updatedAt: "2026-01-02T00:00:00.000Z" as never,
+    });
+
+    const objectSerialized = serialize(TeamFull, 0, team, "object", {}) as unknown as {
+      owner: { id: string; name: string };
+      members: { id: string; name: string }[];
+    };
+    const inputSerialized = serialize(TeamFull, 0, team, "input", {}) as unknown as {
+      owner: string;
+      members: string[];
+    };
+
+    expect(objectSerialized.owner).toMatchObject({ id: validUserId, name: "Ada" });
+    expect(objectSerialized.members[0]).toMatchObject({ id: validUserId, name: "Ada" });
+    expect(inputSerialized.owner).toBe(validUserId);
+    expect(inputSerialized.members).toEqual([validUserId]);
+  });
+
+  test("purifies valid input and rejects invalid values", () => {
+    const user = createUser();
+    const purified = UserFull.purify(user);
+
+    expect(purified).toMatchObject({
+      id: validUserId,
+      name: "Ada",
+      role: "admin",
+      metadata: { locale: "ko" },
+    });
+
+    expect(UserFull.purify({ ...UserFull.getDefault(), id: "bad-user" })).toBeNull();
+    expect(UserObject.purify({ id: validChildId } as never, true)).toBe(validChildId as never);
+    expect(() => UserObject.purify({} as never, true)).toThrow("Invalid Value (No ID)");
+  });
+
+  test("purifies complex schema shapes", () => {
+    const complex = new ComplexInput(
+      complexInput({
+        settings: { theme: "dark" } as never,
+        cube: [[[[1]]]],
+        addressCube: [[[{ city: "Seoul", coordinate: { lat: 37, lng: 127 } }]]],
+        primaryAddress: { city: "Jeju", coordinate: { lat: 33, lng: 126 } },
+        addressBook: {
+          home: { city: "Seoul", coordinate: { lat: 37, lng: 127 } },
+        } as never,
+      }),
+    );
+
+    expect(ComplexInput.purify(complex)).toMatchObject({
+      settings: { theme: "dark" },
+      cube: [[[[1]]]],
+      addressCube: [[[{ city: "Seoul", zip: 10000, coordinate: { lat: 37, lng: 127 } }]]],
+      primaryAddress: { city: "Jeju", zip: 10000, coordinate: { lat: 33, lng: 126 } },
+      addressBook: { home: { city: "Seoul", zip: 10000, coordinate: { lat: 37, lng: 127 } } },
+    });
+
+    expect(ComplexInput.purify({ ...ComplexInput.getDefault(), cube: [[1]] } as never)).toBeNull();
+  });
+
+  test("marks plain model objects as immerable recursively", () => {
+    const user = createUser();
+    const plain = serialize(UserFull, 0, user, "object", {}) as unknown as typeof user;
+    const immered = immerify(UserFull as never, plain);
+
+    expect((immered as unknown as Record<symbol, unknown>)[immerable]).toBe(true);
+    const address = immerify(AddressInput as never, { city: "Seoul", zip: 12345 });
+    expect((address as Record<symbol, unknown>)[immerable]).toBe(true);
+  });
+});

package/constant/fieldInfo.ts

@@ -78,7 +78,7 @@ export interface ConstantFieldProps<
   maxlength?: number;
   accumulate?: any;
   example?: FieldValue;
-  of?: MapValue; 
+  of?: MapValue; // for Map type fields
   validate?: (value: FieldValue, model: any) => boolean;
   text?: "search" | "filter";
   meta?: Metadata;
@@ -143,7 +143,7 @@ interface ConstantFieldBuildProps<
   maxlength?: number;
   accumulate?: any;
   example?: FieldValue;
-  of?: MapValue; 
+  of?: MapValue; // for Map type fields
   validate?: (value: FieldValue, model: any) => boolean;
   text?: "search" | "filter";
   modelRef: ConstantCls;
@@ -209,7 +209,7 @@ export class ConstantField<
   readonly maxlength?: number;
   readonly accumulate?: any;
   readonly example?: FieldValue;
-  readonly of?: MapValue; 
+  readonly of?: MapValue; // for Map type fields
   readonly validate?: (value: FieldValue, model: any) => boolean;
   readonly text?: "search" | "filter";
   readonly modelRef: ConstantCls;

package/constant/purify.ts

@@ -73,7 +73,7 @@ const purify = (
   value: unknown,
   self: Record<string, unknown>,
 ): unknown => {
-  
+  // 1. Check Data Validity
   if (
     field.nullable &&
     (value === null ||
@@ -147,6 +147,7 @@ const purify = (
   if (!field.nullable && !value && value !== 0 && value !== false)
     throw new Error(`Invalid Value (Nullable) in ${key} for value ${value}`);
 
+  // 2. Convert Value
   const purifyFn = getPurifyFn(field.modelRef);
   return purifyFn(value);
 };

package/constant/types.ts

@@ -51,6 +51,7 @@ export class BaseInsight {
   declare count: number;
 }
 
+// TODO: migrate this to shared
 export interface ProtoFile {
   id: string;
   filename: string;
@@ -69,6 +70,7 @@ export interface ProtoFile {
   lastModifiedAt: Dayjs;
 }
 
+// TODO: migrate this to shared
 export interface ProtoAppInfo {
   appId: string | null;
   appName: string;
@@ -83,6 +85,7 @@ export interface ProtoAppInfo {
   isEmulator: boolean | null;
 }
 
+// TODO: migrate this to shared
 export interface ProtoPatch {
   source: ProtoFile;
   build: ProtoFile;
@@ -101,5 +104,6 @@ export type NonFunctionalKeys<T> = keyof T extends (...args: never[]) => unknown
 export const unsetDate = dayjs(new Date("0000"));
 export const MAX_INT = 2147483647;
 
+// TODO: migrate this to akanjs/client
 export class Responsive extends enumOf("responsive", ["xl", "lg", "md", "sm", "xs"] as const) {}
 export const responsiveWidths = [1200, 992, 768, 576, 0] as const;

package/constant/via.ts

@@ -137,7 +137,7 @@ const getBaseConstantClass = (field: FieldObject, modelType: ConstantType = "sca
     }
     set(obj: Partial<typeof this>) {
       Object.entries(obj).forEach(([key, value]) => {
-        
+        //check field has key
         if (!(this.constructor as ConstantCls)[FIELD_META][key] as unknown as object | undefined) return;
         const field = (this.constructor as ConstantCls)[FIELD_META][key];
         if (!field) throw new Error(`Field ${key} not found`);
@@ -179,7 +179,7 @@ export type ConstantCls<Schema = any, FieldObj extends FieldObject = FieldObject
   ConstantStatics<Schema, FieldObj>;
 
 declare global {
-  
+  // dummy type matching for Date, String, Boolean, Map constructors
   interface DateConstructor extends ConstantStatics<unknown> {}
   interface StringConstructor extends ConstantStatics<unknown> {}
   interface BooleanConstructor extends ConstantStatics<unknown> {}
@@ -220,6 +220,7 @@ const applyConstantStatics = <Model>(model: ConstantCls<Model>, fieldMap: FieldO
   return model as unknown as ConstantCls<Model>;
 };
 
+// light via
 /** Builds Akan constant models such as scalar, input, object, light, full, and insight classes. */
 export function via<
   Obj extends BaseObject,
@@ -238,6 +239,7 @@ export function via<
   ...lightModelRefs: LightModels
 ): ConstantCls<_Schema, _FieldObj>;
 
+// input or scalar via
 export function via<
   BuildField extends (builder: FieldBuilder) => FieldInfoObject,
   Inputs extends Cls[],
@@ -246,6 +248,7 @@ export function via<
     FieldInfoObjectToFieldObject<ReturnType<BuildField>>,
 >(buildField: BuildField, ...extendInputRefs: Inputs): ConstantCls<_Schema, _FieldObj>;
 
+// insight via
 export function via<
   Full extends BaseObject,
   BuildField extends (builder: FieldBuilder) => FieldInfoObject,
@@ -255,6 +258,7 @@ export function via<
     FieldInfoObjectToFieldObject<ReturnType<BuildField>>,
 >(modelRef: Cls<Full>, buildField: BuildField, ...extendInsightRefs: Insights): ConstantCls<_Schema, _FieldObj>;
 
+// object via
 export function via<
   Input,
   InputFieldObj extends FieldObject,
@@ -270,6 +274,7 @@ export function via<
   ...extendObjectRefs: ObjectModels
 ): ConstantCls<_Schema, _FieldObj>;
 
+// full via
 export function via<
   Obj,
   ObjFieldObj extends FieldObject,
@@ -295,7 +300,7 @@ export function via(
   thirdRefOrResolveField?: Cls | ((resolve: FieldResolver) => FieldInfoObject),
   ...extendRefs: Cls[]
 ): any {
-  
+  // input via
   if (
     !firstRefOrBuildField.prototype ||
     !(firstRefOrBuildField as Cls<unknown, { modelType?: ConstantType }>).modelType
@@ -310,7 +315,7 @@ export function via(
     if (!secondRefOrFieldsOrBuildField) return makeBaseScalar(fieldMap);
     else return extendModelInputs(fieldMap, ...extendInputRefs);
   }
-  
+  // light via
   if (Array.isArray(secondRefOrFieldsOrBuildField)) {
     const resolveField = thirdRefOrResolveField as (resolve: FieldResolver) => FieldInfoObject;
     const fieldMap = resolveField(resolve);
@@ -322,13 +327,14 @@ export function via(
     );
   }
 
+  // insight or object via
   if (
     !(secondRefOrFieldsOrBuildField as Cls).prototype ||
     !(secondRefOrFieldsOrBuildField as Cls<unknown, { modelType?: ConstantType }>).modelType
   ) {
     const buildField = secondRefOrFieldsOrBuildField as (builder: FieldBuilder) => FieldInfoObject;
     const fieldMap = buildField(field);
-    
+    // object via
     if (ConstantRegistry.isScalar(firstRefOrBuildField as Cls<unknown, { modelType: ConstantType }>)) {
       if (!thirdRefOrResolveField) return objectModelOf(firstRefOrBuildField as ConstantCls, fieldMap);
       else
@@ -339,7 +345,7 @@ export function via(
           ...(extendRefs as ConstantCls[]),
         );
     }
-    
+    // insight via
     if (ConstantRegistry.isFull(firstRefOrBuildField as Cls<unknown, { modelType: ConstantType }>)) {
       const extendInsightRefs = [
         ...(thirdRefOrResolveField ? [thirdRefOrResolveField as Cls] : []),