akanjs 2.2.4-rc.4 → 2.2.4

package/base/base.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+import { DataList, enumOf, Float, Int, isEnum } from ".";
+
+type TestItem = {
+  id: string;
+  name: string;
+  score: number;
+};
+
+describe("enumOf", () => {
+  test("creates a string enum with lookup helpers", () => {
+    class Role extends enumOf<"Role", string>("Role", ["admin", "member", "guest"] as const) {}
+
+    expect(isEnum(Role)).toBe(true);
+    expect(Role.refName).toBe("Role");
+    expect(Role.type).toBe(String);
+    expect(Role.values).toEqual(["admin", "member", "guest"]);
+    expect(Role.has("member")).toBe(true);
+    expect(Role.has("unknown")).toBe(false);
+    expect(Role.indexOf("guest")).toBe(2);
+    expect(Role.find((value) => value.startsWith("mem"))).toBe("member");
+    expect(Role.findIndex((value) => value === "guest")).toBe(2);
+    expect(Role.filter((value) => value.includes("e"))).toEqual(["member", "guest"]);
+    expect(Role.map((value, idx) => `${idx}:${value}`)).toEqual(["0:admin", "1:member", "2:guest"]);
+  });
+
+  test("uses Int for integer numeric enums and Float for decimal enums", () => {
+    const Status = enumOf("Status", [100, 200, 404] as const);
+    const Rate = enumOf("Rate", [0.5, 1, 1.5] as const);
+
+    expect(Status.type).toBe(Int);
+    expect(Status.indexOf(200)).toBe(1);
+    expect(Rate.type).toBe(Float);
+    expect(Rate.has(1.5)).toBe(true);
+  });
+
+  test("throws when enum values are empty or lookup misses", () => {
+    const Status = enumOf<"Status", number>("Status", [1, 2, 3] as const);
+
+    expect(() => enumOf("Empty", [])).toThrow("Enum values are empty");
+    expect(() => Status.indexOf(4)).toThrow("Value 4 is not in enum");
+    expect(() => Status.find((value) => value > 10)).toThrow("Value not found in enum");
+    expect(() => Status.findIndex((value) => value > 10)).toThrow("Value not found in enum");
+  });
+});
+
+describe("DataList", () => {
+  const items: TestItem[] = [
+    { id: "a", name: "Alpha", score: 10 },
+    { id: "b", name: "Beta", score: 20 },
+    { id: "a", name: "Alpha updated", score: 30 },
+  ];
+
+  test("deduplicates constructor data by id and keeps the latest value", () => {
+    const list = new DataList(items);
+
+    expect(list.length).toBe(2);
+    expect(list.values).toEqual([
+      { id: "a", name: "Alpha updated", score: 30 },
+      { id: "b", name: "Beta", score: 20 },
+    ]);
+    expect(list.has("a")).toBe(true);
+    expect(list.get("missing")).toBeUndefined();
+    expect(list.indexOf("b")).toBe(1);
+    expect(list.pick("a").name).toBe("Alpha updated");
+  });
+
+  test("sets, deletes, and reindexes values by id", () => {
+    const list = new DataList<TestItem>([
+      { id: "a", name: "Alpha", score: 10 },
+      { id: "b", name: "Beta", score: 20 },
+      { id: "c", name: "Gamma", score: 30 },
+    ]);
+
+    expect(list.set({ id: "b", name: "Beta updated", score: 25 })).toBe(list);
+    expect(list.length).toBe(3);
+    expect(list.pick("b").score).toBe(25);
+
+    list.set({ id: "d", name: "Delta", score: 40 });
+    expect(list.length).toBe(4);
+    expect(list.pickAt(3).id).toBe("d");
+
+    expect(list.delete("b")).toBe(list);
+    expect(list.length).toBe(3);
+    expect(list.values.map((value) => value.id)).toEqual(["a", "c", "d"]);
+    expect(list.indexOf("c")).toBe(1);
+    expect(list.indexOf("d")).toBe(2);
+    expect(list.has("b")).toBe(false);
+    expect(() => list.pick("b")).toThrow("Value b is not in list");
+    expect(() => list.pickAt(99)).toThrow("Value at 99 is undefined");
+  });
+
+  test("supports array-like helpers and returns DataList for derived lists", () => {
+    const list = new DataList<TestItem>([
+      { id: "a", name: "Alpha", score: 10 },
+      { id: "b", name: "Beta", score: 20 },
+      { id: "c", name: "Gamma", score: 30 },
+    ]);
+
+    expect(list.at(-1)?.id).toBe("c");
+    expect(list.find((value) => value.score > 15)?.id).toBe("b");
+    expect(list.findIndex((value) => value.id === "c")).toBe(2);
+    expect(list.some((value) => value.score === 20)).toBe(true);
+    expect(list.every((value) => value.score >= 10)).toBe(true);
+    expect(list.map((value) => value.name)).toEqual(["Alpha", "Beta", "Gamma"]);
+    expect(list.flatMap((value) => [value.id, value.name])).toEqual(["a", "Alpha", "b", "Beta", "c", "Gamma"]);
+    expect(list.reduce((sum, value) => sum + value.score, 0)).toBe(60);
+    expect([...list].map((value) => value.id)).toEqual(["a", "b", "c"]);
+
+    const filtered = list.filter((value) => value.score >= 20);
+    expect(filtered).toBeInstanceOf(DataList);
+    expect(filtered.values.map((value) => value.id)).toEqual(["b", "c"]);
+
+    const sliced = list.slice(1);
+    expect(sliced).toBeInstanceOf(DataList);
+    expect(sliced.values.map((value) => value.id)).toEqual(["b", "c"]);
+
+    const sorted = list.save().sort((a, b) => b.score - a.score);
+    expect(sorted).toBeInstanceOf(DataList);
+    expect(sorted.values.map((value) => value.id)).toEqual(["c", "b", "a"]);
+    expect(list.values.map((value) => value.id)).toEqual(["a", "b", "c"]);
+  });
+
+  test("copies from another DataList through save", () => {
+    const list = new DataList<TestItem>(items);
+    const saved = list.save();
+
+    expect(saved).toBeInstanceOf(DataList);
+    expect(saved).not.toBe(list);
+    expect(saved.values).toEqual(list.values);
+
+    list.set({ id: "c", name: "Gamma", score: 40 });
+    expect(saved.has("c")).toBe(false);
+  });
+});

package/base/base.ts

@@ -76,7 +76,7 @@ export const enumOf = <RefName extends string, T = string | number>(
 
 /** Id-keyed list helper used for light model collections and immutable-style list updates. */
 export class DataList<Light extends { id: string }> {
-  
+  // [immerable] = true;
   #idMap: Map<string, number>;
   length: number;
   values: Light[];

package/base/baseEnv.test.ts

@@ -0,0 +1,146 @@
+import { afterAll, describe, expect, test } from "bun:test";
+
+type BaseEnvModule = typeof import("./baseEnv");
+
+const preservedEnv = { ...process.env };
+let importCount = 0;
+
+const envKeys = [
+  "AKAN_PUBLIC_APP_NAME",
+  "AKAN_PUBLIC_REPO_NAME",
+  "AKAN_PUBLIC_SERVE_DOMAIN",
+  "AKAN_PUBLIC_ENV",
+  "AKAN_PUBLIC_OPERATION_MODE",
+  "AKAN_PUBLIC_RENDER_ENV",
+  "AKAN_PUBLIC_CLIENT_HOST",
+  "AKAN_PUBLIC_CLIENT_PORT",
+  "SERVER_HOST",
+  "AKAN_PUBLIC_SERVER_PORT",
+  "SERVER_HTTP_PROTOCOL",
+  "SSH_TUNNEL_USERNAME",
+  "SSH_TUNNEL_PASSWORD",
+] as const;
+
+const resetEnv = () => {
+  for (const key of envKeys) delete process.env[key];
+  Object.assign(process.env, {
+    AKAN_PUBLIC_APP_NAME: "minimal",
+    AKAN_PUBLIC_REPO_NAME: "akan",
+    AKAN_PUBLIC_SERVE_DOMAIN: "example.com",
+  });
+};
+
+const loadBaseEnv = async (): Promise<BaseEnvModule> => {
+  importCount++;
+  return import(`./baseEnv.ts?test=${importCount}`);
+};
+
+describe("getEnv", () => {
+  test("throws when required public environment variables are missing", async () => {
+    resetEnv();
+    delete process.env.AKAN_PUBLIC_APP_NAME;
+
+    const { getEnv } = await loadBaseEnv();
+
+    expect(() => getEnv()).toThrow("environment variable AKAN_PUBLIC_APP_NAME is required");
+  });
+
+  test("builds default server-side cloud client environment", async () => {
+    resetEnv();
+    process.env.AKAN_PUBLIC_ENV = "main";
+
+    const { getEnv } = await loadBaseEnv();
+    const env = getEnv();
+
+    expect(env).toEqual({
+      repoName: "akan",
+      serveDomain: "example.com",
+      appName: "minimal",
+      environment: "main",
+      operationMode: "cloud",
+      tunnelUsername: "root",
+      tunnelPassword: "akan",
+      side: "server",
+      renderMode: "csr",
+      websocket: true,
+      clientHost: "localhost",
+      clientPort: 443,
+      clientHttpProtocol: "http:",
+      clientHttpUri: "http://localhost",
+      serverHost: "minimal-main.example.com",
+      serverPort: 8282,
+      serverHttpProtocol: "https:",
+      serverHttpUri: "https://minimal-main.example.com:8282/api",
+      serverWsProtocol: "wss:",
+      serverWsUri: "wss://minimal-main.example.com:8282",
+    });
+  });
+
+  test("uses local defaults for csr and ssr render modes", async () => {
+    resetEnv();
+    process.env.AKAN_PUBLIC_ENV = "local";
+
+    const csrModule = await loadBaseEnv();
+    expect(csrModule.getEnv().operationMode).toBe("local");
+    expect(csrModule.getEnv().clientPort).toBe(8282);
+    expect(csrModule.getEnv().serverHttpUri).toBe("http://localhost:8282/api");
+    expect(csrModule.getEnv().serverWsUri).toBe("ws://localhost:8282");
+
+    resetEnv();
+    process.env.AKAN_PUBLIC_ENV = "local";
+    process.env.AKAN_PUBLIC_RENDER_ENV = "ssr";
+
+    const ssrModule = await loadBaseEnv();
+    expect(ssrModule.getEnv().operationMode).toBe("local");
+    expect(ssrModule.getEnv().clientPort).toBe(8282);
+  });
+
+  test("honors explicit host, port, protocol, network, and tunnel overrides", async () => {
+    resetEnv();
+    Object.assign(process.env, {
+      AKAN_PUBLIC_ENV: "develop",
+      AKAN_PUBLIC_OPERATION_MODE: "edge",
+      AKAN_PUBLIC_NETWORK_TYPE: "debugnet",
+      AKAN_PUBLIC_CLIENT_HOST: "client.example.com",
+      AKAN_PUBLIC_CLIENT_PORT: "3000",
+      SERVER_HOST: "api.example.com",
+      AKAN_PUBLIC_SERVER_PORT: "9443",
+      SERVER_HTTP_PROTOCOL: "https:",
+      SSH_TUNNEL_USERNAME: "admin",
+      SSH_TUNNEL_PASSWORD: "secret",
+    });
+
+    const { getEnv } = await loadBaseEnv();
+    const env = getEnv();
+
+    expect(env.environment).toBe("develop");
+    expect(env.operationMode).toBe("edge");
+    expect(env.tunnelUsername).toBe("admin");
+    expect(env.tunnelPassword).toBe("secret");
+    expect(env.clientHost).toBe("client.example.com");
+    expect(env.clientPort).toBe(3000);
+    expect(env.clientHttpUri).toBe("https://client.example.com:3000");
+    expect(env.serverHost).toBe("api.example.com");
+    expect(env.serverPort).toBe(9443);
+    expect(env.serverHttpUri).toBe("https://api.example.com:9443/api");
+    expect(env.serverWsUri).toBe("wss://api.example.com:9443");
+  });
+
+  test("caches the computed environment per module instance", async () => {
+    resetEnv();
+
+    const { getEnv } = await loadBaseEnv();
+    const first = getEnv();
+
+    process.env.AKAN_PUBLIC_APP_NAME = "changed";
+    const second = getEnv();
+
+    expect(second).toBe(first);
+    expect(second.appName).toBe("minimal");
+  });
+});
+
+afterAll(() => {
+  for (const key of Object.keys(process.env)) delete process.env[key];
+  Object.assign(process.env, preservedEnv);
+});

package/base/primitiveRegistry.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from "bun:test";
+import {
+  Any,
+  dayjs,
+  Float,
+  ID,
+  Int,
+  PRIMITIVE_DEFAULT_VALUE,
+  PRIMITIVE_EXAMPLE_VALUE,
+  PrimitiveRegistry,
+  PrimitiveScalar,
+  Upload,
+} from ".";
+
+describe("PrimitiveRegistry", () => {
+  test("registers and resolves default primitive scalars", () => {
+    expect(PrimitiveRegistry.get("String")).toBe(String);
+    expect(PrimitiveRegistry.get("Boolean")).toBe(Boolean);
+    expect(PrimitiveRegistry.get("Date")).toBe(Date);
+    expect(PrimitiveRegistry.get("Int")).toBe(Int);
+    expect(PrimitiveRegistry.get("Float")).toBe(Float);
+    expect(PrimitiveRegistry.get("ID")).toBe(ID);
+    expect(PrimitiveRegistry.get("Any")).toBe(Any);
+    expect(PrimitiveRegistry.get("Upload")).toBe(Upload);
+
+    expect(PrimitiveRegistry.getName(Int)).toBe("Int");
+    expect(PrimitiveRegistry.has(Float)).toBe(true);
+    expect(PrimitiveRegistry.hasName("ID")).toBe(true);
+    expect(PrimitiveRegistry.getNames()).toEqual(["Int", "Float", "ID", "Any", "Upload", "String", "Boolean", "Date"]);
+    expect(PrimitiveRegistry.getAll()).toContain(String);
+  });
+
+  test("rejects duplicate primitive registration unless overwritten", () => {
+    class TestScalar extends PrimitiveScalar {
+      static override refName = "TestScalar";
+    }
+
+    PrimitiveRegistry.register(TestScalar);
+
+    expect(PrimitiveRegistry.get("TestScalar")).toBe(TestScalar);
+    expect(() => PrimitiveRegistry.register(TestScalar)).toThrow("Scalar TestScalar already registered");
+
+    class ReplacementScalar extends PrimitiveScalar {
+      static override refName = "TestScalar";
+    }
+
+    PrimitiveRegistry.register(ReplacementScalar, { overwrite: true });
+    expect(PrimitiveRegistry.get("TestScalar")).toBe(ReplacementScalar);
+    expect(PrimitiveRegistry.getName(ReplacementScalar)).toBe("TestScalar");
+  });
+
+  test("throws for missing primitive lookups", () => {
+    class MissingScalar extends PrimitiveScalar {
+      static override refName = "MissingScalar";
+    }
+
+    expect(() => PrimitiveRegistry.get("MissingScalar")).toThrow("Scalar MissingScalar not found");
+    expect(() => PrimitiveRegistry.getName(MissingScalar)).toThrow("Scalar");
+  });
+});
+
+describe("primitive scalars", () => {
+  test("parses, serializes, and validates Int values", () => {
+    expect(Int.validate(1)).toBe(true);
+    expect(Int.validate(1.5)).toBe(false);
+    expect(Int.validate(Number.MAX_SAFE_INTEGER + 1)).toBe(false);
+    expect(Int.parseValue("42")).toBe(42);
+    expect(Int.serializeValue(42)).toBe(42);
+    expect(Int._parse("42")).toBe(42);
+    expect(Int._serialize(42)).toBe(42);
+    expect(Int._parse(null, { optional: true })).toBeUndefined();
+    expect(() => Int._parse(1.5)).toThrow("Invalid Int value: 1.5");
+    expect(() => Int._serialize(null)).toThrow("Required Int value: null");
+  });
+
+  test("parses, serializes, and validates Float values", () => {
+    expect(Float.validate(1.5)).toBe(true);
+    expect(Float.validate(Number.POSITIVE_INFINITY)).toBe(false);
+    expect(Float.parseValue("3.14")).toBe(3.14);
+    expect(Float.serializeValue(3.14)).toBe(3.14);
+    expect(Float._parse("3.14")).toBe(3.14);
+    expect(Float._serialize(3.14)).toBe(3.14);
+    expect(() => Float._parse("NaN")).toThrow("Invalid Float value: NaN");
+  });
+
+  test("validates ID values", () => {
+    expect(ID.validate("1234567890abcdef12345678")).toBe(true);
+    expect(ID.validate("123")).toBe(false);
+    expect(ID.validate("not-a-valid-object-id")).toBe(false);
+    expect(ID._parse("")).toBe("");
+    expect(ID._serialize("")).toBe("");
+    expect(ID.parseValue(1234567890 as never)).toBe("1234567890");
+    expect(ID.serializeValue("1234567890abcdef12345678")).toBe("1234567890abcdef12345678");
+    expect(() => ID._parse("not-a-valid-object-id")).toThrow("Invalid ID value: not-a-valid-object-id");
+  });
+
+  test("adds scalar helpers to String, Boolean, and Date constructors", () => {
+    expect(String.refName).toBe("String");
+    expect(String[PRIMITIVE_DEFAULT_VALUE]).toBe("");
+    expect(String[PRIMITIVE_EXAMPLE_VALUE]).toBe("String");
+    expect(String._parse(123 as never)).toBe("123");
+    expect(String._serialize("akan")).toBe("akan");
+
+    expect(Boolean.refName).toBe("Boolean");
+    expect(Boolean[PRIMITIVE_DEFAULT_VALUE]).toBe(false);
+    expect(Boolean[PRIMITIVE_EXAMPLE_VALUE]).toBe(true);
+    expect(Boolean._parse(1 as never)).toBe(true);
+    expect(Boolean._serialize(false)).toBe(false);
+
+    const parsedDate = Date._parse("2025-01-01T00:00:00.000Z" as never);
+    expect(dayjs.isDayjs(parsedDate)).toBe(true);
+    expect(parsedDate.toISOString()).toBe("2025-01-01T00:00:00.000Z");
+    expect(Date._serialize(parsedDate)).toEqual(new Date("2025-01-01T00:00:00.000Z"));
+    expect(() => Date._parse("invalid-date" as never)).toThrow("Invalid Date value: Invalid Date");
+  });
+
+  test("exposes default metadata for object-like primitives", () => {
+    expect(Any.refName).toBe("Any");
+    expect(Any[PRIMITIVE_DEFAULT_VALUE]).toBeNull();
+    expect(Any[PRIMITIVE_EXAMPLE_VALUE]).toEqual({});
+
+    expect(Upload.refName).toBe("Upload");
+    expect(Upload[PRIMITIVE_DEFAULT_VALUE]).toBeNull();
+    expect(Upload[PRIMITIVE_EXAMPLE_VALUE]).toBe("FileUpload");
+    expect(new Upload().__TEMP_TYPE__).toBe("Upload");
+  });
+});

package/base/primitiveRegistry.ts

@@ -71,9 +71,9 @@ export class PrimitiveScalar {
     { optional = false }: { optional?: boolean } = {},
   ): PrimitiveValue {
     if (optional && (input === null || input === undefined)) return undefined;
-    
+    // biome-ignore lint/complexity/noThisInStatic: subclasses provide scalar-specific parsing.
     const value = this.parseValue(input);
-    
+    // biome-ignore lint/complexity/noThisInStatic: subclasses provide scalar-specific validation.
     this._checkValue(value, { optional });
     return value;
   }
@@ -82,10 +82,10 @@ export class PrimitiveScalar {
     value: PrimitiveValue,
     { optional = false }: { optional?: boolean } = {},
   ): PrimitiveValue {
-    
+    // biome-ignore lint/complexity/noThisInStatic: subclasses provide scalar-specific validation.
     this._checkValue(value, { optional });
     if (value === null || value === undefined) return undefined;
-    
+    // biome-ignore lint/complexity/noThisInStatic: subclasses provide scalar-specific serialization.
     return this.serializeValue(value);
   }
   static _checkValue(
@@ -95,9 +95,10 @@ export class PrimitiveScalar {
   ): void {
     if (value === null || value === undefined) {
       if (optional) return;
+      // biome-ignore lint/complexity/noThisInStatic: subclasses expose their own refName.
       else throw new Error(`Required ${this.refName} value: ${value}`);
     }
-    
+    // biome-ignore lint/complexity/noThisInStatic: subclasses provide scalar-specific validation.
     if (!this.validate(value)) throw new Error(`Invalid ${this.refName} value: ${value}`);
   }
 }
@@ -162,7 +163,7 @@ export class ID extends PrimitiveScalar {
   }
   static override _checkValue(value: PrimitiveValue, options: { optional?: boolean } = {}): void {
     if (value === ID[PRIMITIVE_DEFAULT_VALUE]) return;
-    
+    // biome-ignore lint/complexity/noThisInStatic: ID keeps shared primitive validation after allowing its default placeholder.
     super._checkValue(value, options);
   }
 }
@@ -285,6 +286,7 @@ const scalarPrimitiveStatics = {
   },
 };
 
+// String
 Object.assign(String, scalarPrimitiveStatics, {
   refName: "String",
   [PRIMITIVE_DEFAULT_VALUE]: "",
@@ -301,6 +303,7 @@ Object.assign(String, scalarPrimitiveStatics, {
 });
 PrimitiveRegistry.register(String);
 
+// Boolean
 Object.assign(Boolean, {
   ...scalarPrimitiveStatics,
   refName: "Boolean",
@@ -318,6 +321,7 @@ Object.assign(Boolean, {
 });
 PrimitiveRegistry.register(Boolean);
 
+// Date
 Object.assign(Date, {
   ...scalarPrimitiveStatics,
   refName: "Date",

package/base/symbols.test.ts

@@ -0,0 +1,29 @@
+import {
+  ACTION_META,
+  ENDPOINT_META,
+  FIELD_META,
+  FILTER_META,
+  INJECT_META,
+  INTERNAL_META,
+  LOADER_META,
+  SLICE_META,
+  STATE_DERIVED_META,
+  STATE_INIT_META,
+  STATE_META,
+} from ".";
+
+describe("metadata symbols", () => {
+  test("exports stable global symbols", () => {
+    expect(Symbol.keyFor(FIELD_META)).toBe("akanjs.field");
+    expect(Symbol.keyFor(SLICE_META)).toBe("akanjs.slice");
+    expect(Symbol.keyFor(FILTER_META)).toBe("akanjs.filter");
+    expect(Symbol.keyFor(LOADER_META)).toBe("akanjs.loader");
+    expect(Symbol.keyFor(INJECT_META)).toBe("akanjs.inject");
+    expect(Symbol.keyFor(ENDPOINT_META)).toBe("akanjs.endpoint");
+    expect(Symbol.keyFor(INTERNAL_META)).toBe("akanjs.internal");
+    expect(Symbol.keyFor(STATE_META)).toBe("akanjs.state");
+    expect(Symbol.keyFor(STATE_INIT_META)).toBe("akanjs.state.init");
+    expect(Symbol.keyFor(STATE_DERIVED_META)).toBe("akanjs.state.derived");
+    expect(Symbol.keyFor(ACTION_META)).toBe("akanjs.action");
+  });
+});

package/base/types.ts

@@ -41,6 +41,9 @@ type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) exten
 export type MergedValues<T> = UnionToIntersection<MergeObjectValues<T>>;
 export type Assign<A, B> = Omit<A, keyof B> & B;
 
+// NOTE: All `MergeAll*` utilities below use accumulator-style tail recursion so that
+// TS does not allocate a new intersection node at every frame of the recursion. This
+// keeps type-checking roughly linear (vs. quadratic for the naive `T & Recurse<Rest>`).
 export type ObjectAssign<Objects extends object[], Acc = unknown> = Objects extends [
   infer First extends object,
   ...infer Rest extends object[],
@@ -104,7 +107,7 @@ export type MergeAllDoubleKeyOfObjects<
     : MergeAllDoubleKeyOfObjects<Rest, Key, SubKey, Acc>
   : Acc;
 
-export type Primitive = string | number | boolean | null | undefined; 
+export type Primitive = string | number | boolean | null | undefined; // | symbol | bigint;
 
 export type NestedKeysWithAllowed<T, Allowed = Primitive> = T extends Primitive
   ? never

package/base/utils.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import { applyFnToArrayObjects, arraiedModel, getNonArrayModel } from ".";
+
+describe("array model utilities", () => {
+  test("unwraps array-shaped model references and reports array depth", () => {
+    const modelRef = { refName: "TestModel" };
+
+    expect(getNonArrayModel(modelRef)).toEqual([modelRef, 0]);
+    expect(getNonArrayModel([modelRef])).toEqual([modelRef, 1]);
+    expect(getNonArrayModel([[modelRef]] as unknown as typeof modelRef)).toEqual([modelRef, 2]);
+  });
+
+  test("wraps model references by requested array depth", () => {
+    const modelRef = { refName: "TestModel" };
+
+    expect(arraiedModel(modelRef)).toBe(modelRef);
+    expect(arraiedModel(modelRef, 1)).toEqual([modelRef]);
+    expect(arraiedModel<unknown>(modelRef, 3)).toEqual([[[modelRef]]]);
+  });
+
+  test("applies a function to nested array leaf values while preserving shape", () => {
+    const result = applyFnToArrayObjects([1, [2, 3], [[4]]] as const, (value: number) => value * 10);
+
+    expect(result).toEqual([10, [20, 30], [[40]]]);
+  });
+
+  test("applies a function directly to non-array values", () => {
+    expect(applyFnToArrayObjects("akan", (value: string) => value.toUpperCase())).toBe("AKAN");
+  });
+});