akanjs 2.2.7 → 2.2.9

package/CHANGELOG.md

@@ -4,8 +4,17 @@
 
 ### Patch Changes
 
-- fix: base dictionary translation failed in some cases
-- fix: file upload contract workaround on shared Field.Img component
+- bf51564: fix: base dictionary translation failed in some cases
+- bf51564: fix: file upload contract workaround on shared Field.Img component
+
+## 2.2.5
+
+### Patch Changes
+
+- d636456: add rich Map methods on memory() helper service
+- a1ee4e8: fill nested constant defaults for arrays on document save and load, normalize date fields to a consistent epoch representation on store (accepting legacy ISO-string values on read), and correct falsy defaults in getDefault
+- 5cdb05e: reverse dependency of file upload api
+- a7da50e: remove dependency from radix dialog
 
 ## 2.2.3
 

package/client/clientRuntime.ts

@@ -96,6 +96,9 @@ export const msg = new Proxy({} as ClientRuntime["msg"], {
   get(_target, prop, receiver) {
     return Reflect.get(getClientRuntime().msg, prop, receiver);
   },
+  set(_target, prop, value) {
+    return Reflect.set(getClientRuntime().msg, prop, value);
+  },
 });
 
 const ErrTarget = function AkanClientRuntimeErr(...args: ConstructorParameters<RuntimeErr>) {

package/client/csrTypes.ts

@@ -119,6 +119,7 @@ export interface LayoutModule {
   manifest?: WebAppManifest;
   theme?: string;
   reconnect?: boolean;
+  wsConnect?: boolean;
   layoutStyle?: "mobile" | "web";
   gaTrackingId?: string;
   Loading?: LayoutLoadingRender;

package/client/makePageProto.tsx

@@ -25,8 +25,11 @@ const getPageInfo = (): { locale: string; path: string } => {
   const localeSet = new Set(locales);
   if (getEnv().side !== "server") {
     const [, firstSegment = "", ...rest] = window.location.pathname.split("/");
-    if (localeSet.has(firstSegment)) return { locale: firstSegment, path: `/${rest.join("/")}` };
-    return { locale: defaultLocale, path: window.location.pathname };
+    const hasLocalePrefix = localeSet.has(firstSegment);
+
+    const activeLocale = Translator.getActiveLocale();
+    const locale = activeLocale ?? (hasLocalePrefix ? firstSegment : defaultLocale);
+    return { locale, path: hasLocalePrefix ? `/${rest.join("/")}` : window.location.pathname };
   }
   const h = headers();
 

package/client/translator.ts

@@ -44,6 +44,12 @@ export class Translator {
   static getActiveLocale(): string | undefined {
     return getTranslatorState().activeLocale;
   }
+  static translateByLocale(lang: string, key: string, param?: Record<string, string | number>): string {
+    const dictionary = getTranslatorState().langDictionaryMap.get(lang);
+    if (!dictionary) return key;
+    const msg = (pathGet(key, dictionary, ".", { t: key }) as { t: string }).t;
+    return param ? msg.replace(/{([^}]+)}/g, (_, key: string) => param[key] as string) : msg;
+  }
 
   static seed(lang: string, dict: Dictionary | undefined) {
     if (!dict) return;
@@ -58,10 +64,7 @@ export class Translator {
     state.langDictionaryMap.set(lang, existingDictionary);
   }
   translate(lang: string, key: string, param?: Record<string, string | number>): string {
-    const dictionary = getTranslatorState().langDictionaryMap.get(lang);
-    if (!dictionary) return key;
-    const msg = (pathGet(key, dictionary, ".", { t: key }) as { t: string }).t;
-    return param ? msg.replace(/{([^}]+)}/g, (_, key: string) => param[key] as string) : msg;
+    return Translator.translateByLocale(lang, key, param);
   }
   async getDictionary(lang: string) {
     const dictionary = getTranslatorState().langDictionaryMap.get(lang);

package/common/fileUpload.ts

@@ -2,7 +2,7 @@ interface FileUploadSerializedEndpoint {
   fileUpload?: boolean;
 }
 
-export interface FileUploadSerializedSignal {
+interface FileUploadSerializedSignal {
   prefix?: string;
   endpoint: Record<string, FileUploadSerializedEndpoint>;
 }

package/common/index.ts

@@ -1,7 +1,11 @@
 export { applyMixins } from "./applyMixins";
 export { capitalize } from "./capitalize";
 export { deepObjectify } from "./deepObjectify";
-export * from "./fileUpload";
+export {
+  type FileUploadCapability,
+  fileUploadContract,
+  resolveFileUploadCapability,
+} from "./fileUpload";
 export { formatNumber } from "./formatNumber";
 export { formatPhone } from "./formatPhone";
 export { getAllPropertyDescriptors } from "./getAllPropertyDescriptors";

package/constant/getDefault.ts

@@ -6,7 +6,7 @@ export const getDefault = <T>(fieldObj: FieldObject): DefaultOf<T> => {
   const result: Record<string, unknown> = {};
   for (const [key, field] of Object.entries(fieldObj)) {
     if (field.fieldType === "hidden") result[key] = null;
-    else if (field.default) {
+    else if (field.default !== undefined && field.default !== null) {
       if (typeof field.default === "function") result[key] = (field.default as () => object)();
       else result[key] = field.default as object;
     } else if (field.isArray) result[key] = [];

package/dictionary/base.dictionary.ts

@@ -20,7 +20,6 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       .arg((t) => ({
         id: t(["ID", "아이디"]),
       })),
-    cleanup: fn(["Cleanup", "Cleanup"]).desc(["Cleanup operation", "정리 작업"]),
     wsPing: fn(["Socket.io Ping", "Socket.io Ping"])
       .desc(["Socket.io Ping test", "Socket.io Ping 테스트"])
       .arg((t) => ({

package/fetch/client/fetchClient.ts

@@ -1,12 +1,5 @@
 import { DataList, getEnv, PrimitiveRegistry, type PromiseOrObject } from "akanjs/base";
-import {
-  capitalize,
-  type FetchPolicy,
-  type FileUploadSerializedSignal,
-  fileUploadContract,
-  Logger,
-  resolveFileUploadCapability,
-} from "akanjs/common";
+import { capitalize, type FetchPolicy, fileUploadContract, Logger, resolveFileUploadCapability } from "akanjs/common";
 import { type BaseInsight, type BaseObject, ConstantRegistry, deserialize, serialize } from "akanjs/constant";
 import type {
   DatabaseSignal,
@@ -180,6 +173,10 @@ export class FetchClient {
     if (!handler) throw new Error(`${owner} requires fetch handler "${key}", but it is not registered`);
     return handler as T;
   }
+  #setHandlerFactory(key: string, factory: FetchHandlerFactory) {
+    this.#handlerFactory.set(key, factory);
+    delete this.#handlerStore[key];
+  }
   connect() {
     this.ws.connect();
   }
@@ -263,15 +260,15 @@ export class FetchClient {
   #registerEndpoint(key: string, endpoint: SerializedEndpoint, prefix?: string) {
     switch (endpoint.type) {
       case "query": {
-        this.#handlerFactory.set(key, () => this.#makeHttpFn(key, endpoint, prefix));
+        this.#setHandlerFactory(key, () => this.#makeHttpFn(key, endpoint, prefix));
         return;
       }
       case "mutation": {
-        this.#handlerFactory.set(key, () => this.#makeHttpFn(key, endpoint, prefix));
+        this.#setHandlerFactory(key, () => this.#makeHttpFn(key, endpoint, prefix));
         return;
       }
       case "pubsub": {
-        this.#handlerFactory.set(`subscribe${capitalize(key)}`, () => {
+        this.#setHandlerFactory(`subscribe${capitalize(key)}`, () => {
           const roomArgs = endpoint.args.filter((arg) => arg.type === "room");
           const roomArgLength = roomArgs.length;
           const serializerMap = this.#makeArgSerializer(endpoint.args);
@@ -299,7 +296,7 @@ export class FetchClient {
         return;
       }
       case "message": {
-        this.#handlerFactory.set(key, () => {
+        this.#setHandlerFactory(key, () => {
           const msgArgs = endpoint.args.filter((arg) => arg.type === "msg");
           const msgArgLength = msgArgs.length;
           const serializerMap = this.#makeArgSerializer(endpoint.args);
@@ -309,7 +306,7 @@ export class FetchClient {
             this.ws.emit(key, data);
           };
         });
-        this.#handlerFactory.set(`listen${capitalize(key)}`, () => {
+        this.#setHandlerFactory(`listen${capitalize(key)}`, () => {
           const parseReturn = this.#makeReturnParser(endpoint.returns);
           const wrappedListeners = new WeakMap<(data: unknown) => void, (data: unknown) => void>();
           return ((handleEvent: (data: unknown) => void, fetchPolicy: FetchPolicy = {}) => {
@@ -414,11 +411,11 @@ export class FetchClient {
     };
     const endpoint = FetchClient.getBaseEndpoint(refName, signal);
     Object.entries(endpoint).forEach(([key, value]) => {
-      this.#handlerFactory.set(key, () => this.#makeHttpFn(key, value, signal.prefix));
+      this.#setHandlerFactory(key, () => this.#makeHttpFn(key, value, signal.prefix));
     });
 
     if (signal.cruGuards) {
-      this.#handlerFactory.set(
+      this.#setHandlerFactory(
         names.viewModel,
         () =>
           (async (id: string, option?: FetchPolicy) => {
@@ -432,7 +429,7 @@ export class FetchClient {
             };
           }) as FetchHandler,
       );
-      this.#handlerFactory.set(
+      this.#setHandlerFactory(
         names.getModelView,
         () =>
           (async (id: string, option?: FetchPolicy) => {
@@ -441,7 +438,7 @@ export class FetchClient {
             return { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() };
           }) as FetchHandler,
       );
-      this.#handlerFactory.set(
+      this.#setHandlerFactory(
         names.editModel,
         () =>
           (async (id: string, option?: FetchPolicy) => {
@@ -455,7 +452,7 @@ export class FetchClient {
             };
           }) as FetchHandler,
       );
-      this.#handlerFactory.set(
+      this.#setHandlerFactory(
         names.getModelEdit,
         () =>
           (async (id: string, option?: FetchPolicy) => {
@@ -464,7 +461,7 @@ export class FetchClient {
             return { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() };
           }) as FetchHandler,
       );
-      this.#handlerFactory.set(
+      this.#setHandlerFactory(
         names.mergeModel,
         () =>
           (async (modelOrId: string | { id: string }, data: UnknownRecord, option?: FetchPolicy) => {
@@ -475,11 +472,11 @@ export class FetchClient {
       );
     }
 
-    this.#handlerFactory.set(
+    this.#setHandlerFactory(
       names.addModelFiles,
       () =>
         (async (fileList: FileList, parentId?: string, option?: FetchPolicy) => {
-          const cap = resolveFileUploadCapability(this.serializedSignal as Record<string, FileUploadSerializedSignal>);
+          const cap = resolveFileUploadCapability(this.serializedSignal);
           const endpoint = cap ? this.serializedSignal[cap.refName]?.endpoint[cap.endpointKey] : undefined;
           if (!cap || !endpoint)
             throw new Error(
@@ -536,12 +533,12 @@ export class FetchClient {
 
     const endpoint = FetchClient.getEndpointFromSlice(refName, suffix, slice);
     Object.entries(endpoint).forEach(([key, value]) => {
-      this.#handlerFactory.set(key, () => this.#makeHttpFn(key, value, prefix));
+      this.#setHandlerFactory(key, () => this.#makeHttpFn(key, value, prefix));
     });
 
     const argLength = slice.args.length;
     this.slice[sliceName] = { refName, sliceName, argLength };
-    this.#handlerFactory.set(names.init, () => async (...argData: unknown[]) => {
+    this.#setHandlerFactory(names.init, () => async (...argData: unknown[]) => {
       const cnst = ConstantRegistry.getDatabase(refName);
       const queryArgs = normalizeQueryArgs(
         Array.from({ length: Math.min(argData.length, argLength) }, (_, idx) => argData[idx]),
@@ -583,7 +580,7 @@ export class FetchClient {
         [`${refName}Insight${capSuffix}`]: modelInsight,
       };
     });
-    this.#handlerFactory.set(names.getInit, () => async (...args: unknown[]) => {
+    this.#setHandlerFactory(names.getInit, () => async (...args: unknown[]) => {
       const initFn = this.#requireHandler<(...args: unknown[]) => Promise<Record<string, unknown>>>(
         names.init,
         names.getInit,

package/fetch/client/wsClient.ts

@@ -53,6 +53,7 @@ export class WsClient {
   }
 
   connect() {
+    if (this.#ws && this.#ws.readyState !== WebSocket.CLOSED) return;
     this.logger.debug(`Connecting to ${this.url}`);
     this.#destroyed = false;
     this.#reconnectAttempts = 0;
@@ -201,9 +202,15 @@ export class WsClient {
     const hasRoom = roomSub ? roomSub.listener.size > 0 : false;
     return hasGeneric || hasRoom;
   }
+  #warnNotConnected(action: "emit" | "subscribe", key: string) {
+    console.warn(
+      `[akanjs] WebSocket is not connected. Call fetch.instance.connect() or enable root layout "wsConnect" before ${action} "${key}".`,
+    );
+  }
   emit(key: string, data: WsRequestPayload) {
     if (this.#ws?.readyState !== WebSocket.OPEN) {
       this.logger.warn("WebSocket not connected");
+      this.#warnNotConnected("emit", key);
       return this;
     }
     const payload: WebsocketReqData = { key, data: Array.isArray(data) ? data : [data] };
@@ -212,6 +219,7 @@ export class WsClient {
   }
   subscribe(option: { key: string; data: unknown[]; handleEvent: (data: unknown) => void }) {
     const roomId = WsClient.makeRoomId(option.key, option.data);
+    if (!this.#ws) this.#warnNotConnected("subscribe", option.key);
     if (!this.#roomSubscribeMap.has(roomId)) {
       this.#roomSubscribeMap.set(roomId, { key: option.key, data: option.data, listener: new Set() });
       if (this.#ws?.readyState === WebSocket.OPEN) {

package/fetch/serializer/fetch.serializer.ts

@@ -67,6 +67,7 @@ export class FetchSerializer {
       ...(endpointInfo.signalOption.globalPrefix !== undefined
         ? { globalPrefix: endpointInfo.signalOption.globalPrefix }
         : {}),
+      ...(endpointInfo.signalOption.fileUpload ? { fileUpload: true } : {}),
       ...(guards?.length ? { guards } : {}),
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.2.7",
+  "version": "2.2.9",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -175,7 +175,6 @@
     "@capgo/capacitor-updater": "^8.46.1",
     "@libsql/client": "^0.17.3",
     "@playwright/test": "^1.60.0",
-    "@radix-ui/react-dialog": "^1.1.15",
     "@react-spring/web": "^10.1.0",
     "@use-gesture/react": "^10.3.1",
     "bullmq": "^5.76.10",
@@ -250,9 +249,6 @@
     "@playwright/test": {
       "optional": true
     },
-    "@radix-ui/react-dialog": {
-      "optional": true
-    },
     "@react-spring/web": {
       "optional": true
     },

package/server/hmr/devHmrController.ts

@@ -362,6 +362,7 @@ export class DevHmrController {
       `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}src${path.sep}ssrFromRscRenderer.tsx`,
     ];
     if (files.some((file) => runtimeRoots.some((needle) => path.resolve(file).includes(needle)))) return true;
+    if (files.some((file) => path.basename(file).endsWith(".signal.ts"))) return true;
 
     return (
       routeIds === undefined &&

package/server/routeTreeBuilder.ts

@@ -53,6 +53,7 @@ export class RouteTreeBuilder {
     "manifest",
     "theme",
     "reconnect",
+    "wsConnect",
     "layoutStyle",
     "gaTrackingId",
     "Loading",

package/server/ssrFromRscRenderer.tsx

@@ -69,7 +69,6 @@ export class SsrFromRscRenderer {
 
     const renderHtml = () =>
       renderToReadableStream(<Root />, {
-        bootstrapModules: input.bootstrapModules,
         bootstrapScriptContent: bootstrap,
       });
     const htmlStream =
@@ -77,6 +76,7 @@ export class SsrFromRscRenderer {
 
     const withHeadScripts = SsrFromRscRenderer.#injectHeadScriptsIntoHead(htmlStream, {
       importmap: input.importmap,
+      bootstrapModules: input.bootstrapModules,
       theme: input.theme,
       injectThemeInitScript: input.injectThemeInitScript,
     });
@@ -84,6 +84,7 @@ export class SsrFromRscRenderer {
     return SsrFromRscRenderer.#appendRscScriptsAfterHtml(
       withHeadScripts,
       SsrFromRscRenderer.#sanitizeFlightForClient(rscForClient),
+      input.bootstrapModules,
       input.request,
     );
   }
@@ -124,32 +125,35 @@ export class SsrFromRscRenderer {
    * tag in the outgoing HTML stream.
    *
    * We do this as a stream transform (rather than as a React child inside
-   * `<head>`) because React 19's Float pipeline hoists
-   * `<link rel="modulepreload">` for every entry in `bootstrapModules` to the
-   * top of `<head>`. An importmap rendered via JSX ends up *after* those
-   * hoisted preloads, which — per the HTML spec — is too late: once the
-   * browser starts a module script fetch for a preload, the document's
-   * "allow-import-maps" bit flips to false and no further importmap can be
-   * acquired. By writing the importmap before any of React's own `<head>`
-   * output reaches the wire, we guarantee the browser sees it first.
+   * `<head>`) so importmaps are acquired before any modulepreload can start.
+   * The spec is strict: once the browser starts a module script fetch for a
+   * preload, the document's "allow-import-maps" bit flips to false and no
+   * further importmap can be acquired.
    *
    * The transform operates on UTF-8 bytes until it has spliced the tag, then
    * becomes a pure passthrough to avoid any further per-chunk overhead.
    */
   static #injectHeadScriptsIntoHead(
     stream: ReadableStream<Uint8Array>,
-    options: { importmap?: Record<string, string>; theme?: AkanTheme; injectThemeInitScript?: boolean },
+    options: {
+      importmap?: Record<string, string>;
+      bootstrapModules?: string[];
+      theme?: AkanTheme;
+      injectThemeInitScript?: boolean;
+    },
   ): ReadableStream<Uint8Array> {
     const encoder = new TextEncoder();
     const decoder = new TextDecoder();
-    const { importmap, theme, injectThemeInitScript } = options;
+    const { importmap, bootstrapModules, theme, injectThemeInitScript } = options;
     const htmlTheme = theme && theme !== "css" && theme !== "system" ? theme : undefined;
     const importmapTag =
       importmap && Object.keys(importmap).length > 0
         ? `<script type="importmap">${JSON.stringify({ imports: importmap })}</script>`
         : "";
+    const modulePreloadTags = SsrFromRscRenderer.#createBootstrapModulePreloadTags(bootstrapModules);
     const shouldInjectThemeScript = theme === "system" || (theme === undefined && injectThemeInitScript);
-    const tags = `${shouldInjectThemeScript ? SsrFromRscRenderer.#themeInitScript : ""}${importmapTag}`;
+    const themeInitTag = shouldInjectThemeScript ? SsrFromRscRenderer.#themeInitScript : "";
+    const tags = `${themeInitTag}${importmapTag}${modulePreloadTags}`;
     if (!tags && !htmlTheme) return stream;
     const htmlOpenRe = /<html(\s[^>]*)?>/i;
     const headOpenRe = /<head(\s[^>]*)?>/i;
@@ -200,6 +204,20 @@ export class SsrFromRscRenderer {
     return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
   }
 
+  static #createBootstrapModulePreloadTags(bootstrapModules?: string[]): string {
+    if (!bootstrapModules?.length) return "";
+    return bootstrapModules
+      .map((src) => `<link rel="modulepreload" href="${SsrFromRscRenderer.#escapeHtmlAttr(src)}">`)
+      .join("");
+  }
+
+  static #createBootstrapModuleScriptTags(bootstrapModules?: string[]): string {
+    if (!bootstrapModules?.length) return "";
+    return bootstrapModules
+      .map((src) => `<script type="module" src="${SsrFromRscRenderer.#escapeHtmlAttr(src)}"></script>`)
+      .join("");
+  }
+
   static #sanitizeFlightForClient(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
     const decoder = new TextDecoder();
     const encoder = new TextEncoder();
@@ -227,9 +245,11 @@ export class SsrFromRscRenderer {
   static #appendRscScriptsAfterHtml(
     htmlStream: ReadableStream<Uint8Array>,
     rscClientStream: ReadableStream<Uint8Array>,
+    bootstrapModules?: string[],
     request?: Request,
   ): ReadableStream<Uint8Array> {
     const encoder = new TextEncoder();
+    const bootstrapModuleScripts = SsrFromRscRenderer.#createBootstrapModuleScriptTags(bootstrapModules);
 
     return new ReadableStream<Uint8Array>({
       start(controller) {
@@ -253,6 +273,8 @@ export class SsrFromRscRenderer {
             reader.releaseLock();
           }
 
+          if (bootstrapModuleScripts && !errored) controller.enqueue(encoder.encode(bootstrapModuleScripts));
+
           const rscReader = rscClientStream.getReader();
           try {
             while (true) {

package/server/ssrTypes.ts

@@ -35,12 +35,11 @@ export interface SsrFromRscInput {
    * guaranteeing one React instance across rscClient and every route
    * chunk.
    *
-   * Injection happens via a stream transform, not React children, because
-   * React Fizz hoists `<link rel="modulepreload">` (generated from
-   * `bootstrapModules`) to the top of `<head>`, which would otherwise sit
-   * before any importmap rendered via JSX. The spec is strict: import maps
-   * must be acquired before any module script fetch starts, including
-   * modulepreload.
+   * Injection happens via a stream transform, not React children, because the
+   * spec is strict: import maps must be acquired before any module script fetch
+   * starts, including modulepreload. Akan writes bootstrap module preloads
+   * directly after this importmap and delays the executable module script until
+   * the Fizz HTML stream has completed.
    */
   importmap?: Record<string, string>;
   theme?: AkanTheme;

package/service/base.service.ts

@@ -9,10 +9,6 @@ export class BaseService extends serve("base" as const, ({ env, signal, memory }
   publishPing() {
     this.baseSignal.pubsubPing("ping");
   }
-  async cleanup() {
-    if (!this.onCleanup) throw new Error("onCleanup is not defined");
-    await this.onCleanup();
-  }
 }
 
 export const srv = { base: new ServiceModel(BaseService) };

package/service/injectInfo.ts

@@ -254,20 +254,47 @@ export class InjectInfo<
         enumerable: true,
       });
     } else if (injectInfo.isMap) {
+      const topic = `akan:memory:${injectInfo.parentRefName}`;
+      const getter = injectInfo.get as unknown as (value: unknown) => unknown;
+      const setter = injectInfo.set as unknown as (value: unknown) => string | number | Buffer;
+      const get = async (key: string) => {
+        const value = await cacheAdaptor.hget(topic, propKey, key);
+        return value === undefined || value === null ? undefined : getter(value);
+      };
+      const set = async (key: string, value: unknown) => {
+        const setValue = setter(value);
+        await cacheAdaptor.hset(topic, propKey, key, setValue);
+      };
       Object.defineProperty(instance, propKey, {
         value: {
-          get: async (key: string) => {
-            const getter = injectInfo.get as unknown as (value: unknown) => unknown;
-            const value = await cacheAdaptor.hget(`akan:memory:${injectInfo.parentRefName}`, propKey, key);
-            return value === null ? value : getter(value);
+          get,
+          set,
+          delete: async (key: string) => {
+            await cacheAdaptor.hdelete(topic, propKey, key);
           },
-          set: async (key: string, value: unknown) => {
-            const setter = injectInfo.set as unknown as (value: unknown) => string | number | Buffer;
-            const setValue = setter(value);
-            await cacheAdaptor.hset(`akan:memory:${injectInfo.parentRefName}`, propKey, key, setValue);
+          getOrInsert: async (key: string, value: unknown) => {
+            const existingValue = await get(key);
+            if (existingValue !== undefined) return existingValue;
+            await set(key, value);
+            return value;
           },
-          delete: async (key: string) => {
-            await cacheAdaptor.hdelete(`akan:memory:${injectInfo.parentRefName}`, propKey, key);
+          getOrInsertComputed: async (key: string, compute: (key: string) => unknown | Promise<unknown>) => {
+            const existingValue = await get(key);
+            if (existingValue !== undefined) return existingValue;
+            const value = await compute(key);
+            await set(key, value);
+            return value;
+          },
+          keys: async () => await cacheAdaptor.hkeys(topic, propKey),
+          entries: async () => {
+            const entries = await cacheAdaptor.hentries(topic, propKey);
+            return entries.map(([key, value]) => [key, getter(value)]);
+          },
+          forEach: async (callback: (value: unknown, key: string) => void | Promise<void>) => {
+            for (const [key, value] of await cacheAdaptor.hentries(topic, propKey)) await callback(getter(value), key);
+          },
+          clear: async () => {
+            await cacheAdaptor.hclear(topic, propKey);
           },
         },
       });
@@ -346,6 +373,7 @@ export const injectionBuilder = (parentRefName: string) => ({
     const isMap = modelRef === Map;
     if (isMap && !opts.of) throw new Error("of should be provided when modelRef is Map");
     type FieldValue = never extends GetFn ? GetFieldValue<ValueRef, ExplicitType, MapValue> : ReturnType<GetFn>;
+    type MapFieldValue = never extends GetFn ? FieldToValue<MapValue> : ReturnType<GetFn>;
     type IsNullable = DefaultValue extends never ? true : false;
     type UseValue = IsNullable extends true ? FieldValue | null : FieldValue;
     return new InjectInfo<
@@ -356,9 +384,18 @@ export const injectionBuilder = (parentRefName: string) => ({
           : UseValue
         : MapConstructor extends ValueRef
           ? {
-              get: (key: string) => Promise<FieldToValue<MapValue>>;
-              set: (key: string, value: FieldToValue<MapValue>) => Promise<void>;
+              get: (key: string) => Promise<MapFieldValue | undefined>;
+              set: (key: string, value: MapFieldValue) => Promise<void>;
               delete: (key: string) => Promise<void>;
+              getOrInsert: (key: string, value: MapFieldValue) => Promise<MapFieldValue>;
+              getOrInsertComputed: (
+                key: string,
+                compute: (key: string) => MapFieldValue | Promise<MapFieldValue>,
+              ) => Promise<MapFieldValue>;
+              keys: () => Promise<string[]>;
+              entries: () => Promise<[string, MapFieldValue][]>;
+              forEach: (callback: (value: MapFieldValue, key: string) => void | Promise<void>) => Promise<void>;
+              clear: () => Promise<void>;
             }
           : { get: () => Promise<UseValue>; set: (value: UseValue) => Promise<void>; delete: () => Promise<void> },
       never,

package/service/predefinedAdaptor/cache.adaptor.ts

@@ -16,6 +16,9 @@ export interface CacheAdaptor {
   ): Promise<void>;
   hget<T extends string | number | Buffer>(topic: string, key: string, subKey: string): Promise<T | undefined>;
   hdelete(topic: string, key: string, subKey: string): Promise<void>;
+  hkeys(topic: string, key: string): Promise<string[]>;
+  hentries<T extends string | number | Buffer>(topic: string, key: string): Promise<[string, T][]>;
+  hclear(topic: string, key: string): Promise<void>;
 }
 
 interface RedisEnv extends BaseEnv {
@@ -96,6 +99,16 @@ export class RedisCache
   async hdelete(topic: string, key: string, subKey: string): Promise<void> {
     await this.redis.hdel(`${topic}:${key}`, subKey);
   }
+  async hkeys(topic: string, key: string): Promise<string[]> {
+    return await this.redis.hkeys(`${topic}:${key}`);
+  }
+  async hentries<T extends string | number | Buffer>(topic: string, key: string): Promise<[string, T][]> {
+    const values = await this.redis.hgetall(`${topic}:${key}`);
+    return Object.entries(values) as [string, T][];
+  }
+  async hclear(topic: string, key: string): Promise<void> {
+    await this.redis.del(`${topic}:${key}`);
+  }
   getClient(): Redis {
     return this.redis;
   }