@xfilecom/xframe 0.1.34 → 0.1.36

package/template/web/shared/src/store/root-store.ts

@@ -0,0 +1,358 @@
+/**
+ * Root store — session, param, cache, indicator, execute/sendMessage (business-promotion 패턴 축소판)
+ */
+
+import { makeAutoObservable, runInAction } from 'mobx';
+import { setApiHooks } from '../api/client';
+import { sendRequest } from '../api/request';
+import type {
+  ApiMethodConfig,
+  ApiMethodEndpointCall,
+  ApiMethodStore,
+  CoreSdkWrapped,
+  ExecuteContext,
+} from '../api/types';
+import type { EndpointDef } from '@shared/endpoint';
+import {
+  methods,
+  screenParamSchemas,
+  type MethodName,
+} from '../api/methods';
+import { apiCacheStore } from './api-cache-store';
+import { sessionStore } from './session-store';
+import { ParamStore } from '../params/param-store';
+import type { ApiErrorItem, IndicatorState, SendMessageOptions, ToastItem } from '../types/ui';
+import type { ToastSeverity } from '../types/ui';
+
+function genId() {
+  return `id_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+}
+
+function unwrapCoreSdk<T>(res: T | CoreSdkWrapped<T>, unwrapDataArray: boolean): T | null {
+  if (!unwrapDataArray) return res as T;
+  const r = res as CoreSdkWrapped<T>;
+  if (r?.data != null) {
+    if (Array.isArray(r.data)) return (r.data[0] ?? null) as T | null;
+    return r.data as T;
+  }
+  return res as T;
+}
+
+function extractMessageString(value: unknown): string | null {
+  if (value == null) return null;
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) {
+    const first = value.find((x) => typeof x === 'string');
+    return first ?? (value.map((x) => (typeof x === 'string' ? x : String(x))).join(', ') || null);
+  }
+  if (typeof value === 'object' && 'message' in value) {
+    const inner = (value as { message: unknown }).message;
+    return extractMessageString(inner);
+  }
+  return null;
+}
+
+function getErrorMessage(e: unknown): string {
+  const err = e as { response?: { data?: { message?: unknown; error?: unknown } }; message?: string };
+  const raw = err?.response?.data?.message ?? err?.response?.data?.error ?? err?.message;
+  const extracted = extractMessageString(raw);
+  if (extracted) return extracted;
+  if (raw != null && typeof raw === 'string') return raw;
+  return (err as Error)?.message ?? 'Request failed';
+}
+
+export class RootStore {
+  readonly sessionStore = sessionStore;
+  readonly apiCacheStore = apiCacheStore;
+  readonly paramStore = new ParamStore(screenParamSchemas, {
+    getStore: () => this,
+  });
+
+  private _indicator: IndicatorState = { loading: false, methodLoading: null };
+  private _errors: ApiErrorItem[] = [];
+  private _toasts: ToastItem[] = [];
+  private _requestDepth = 0;
+  private _multiEndpointBatch = false;
+
+  /** 데모·useHealthStatus 용 타임스탬프 */
+  lastHealthAt: number | null = null;
+
+  constructor() {
+    makeAutoObservable(this);
+    this.sessionStore.registerLogoutCallback(() => {
+      runInAction(() => {
+        this.apiCacheStore.clear();
+      });
+    });
+    setApiHooks({
+      onRequestStart: () => {
+        if (this._multiEndpointBatch) return;
+        runInAction(() => this._startRequest());
+      },
+      onRequestEnd: () => {
+        if (this._multiEndpointBatch) return;
+        runInAction(() => this._endRequest());
+      },
+      onError: () => {},
+    });
+  }
+
+  get indicator(): IndicatorState {
+    return this._indicator;
+  }
+
+  get errors(): ApiErrorItem[] {
+    return this._errors;
+  }
+
+  get toasts(): ToastItem[] {
+    return this._toasts;
+  }
+
+  setLastHealthAt(t: number) {
+    this.lastHealthAt = t;
+  }
+
+  private _startRequest() {
+    this._requestDepth++;
+    if (this._requestDepth === 1) {
+      this._indicator = { ...this._indicator, loading: true };
+    }
+  }
+
+  private _endRequest() {
+    this._requestDepth = Math.max(0, this._requestDepth - 1);
+    if (this._requestDepth === 0) {
+      this._indicator = { ...this._indicator, loading: false };
+    }
+  }
+
+  setIndicator(loading: boolean, message?: string) {
+    this._indicator = { ...this._indicator, loading, message };
+  }
+
+  setMethodLoading(methodName: string | null) {
+    this._indicator = { ...this._indicator, methodLoading: methodName };
+  }
+
+  addError(message: string, code?: string | number) {
+    this._errors = [{ id: genId(), message, code, createdAt: Date.now() }, ...this._errors].slice(0, 50);
+  }
+
+  clearError(id: string) {
+    this._errors = this._errors.filter((e) => e.id !== id);
+  }
+
+  clearAllErrors() {
+    this._errors = [];
+  }
+
+  private static readonly TOAST_AUTO_DISMISS_MS = 2000;
+
+  addToast(message: string, severity: ToastSeverity = 'info') {
+    if (this._toasts.some((t) => t.message === message && t.severity === severity)) return;
+    const id = genId();
+    this._toasts = [...this._toasts, { id, message, severity, createdAt: Date.now() }].slice(-20);
+    setTimeout(() => {
+      runInAction(() => this.removeToast(id));
+    }, RootStore.TOAST_AUTO_DISMISS_MS);
+  }
+
+  removeToast(id: string) {
+    this._toasts = this._toasts.filter((t) => t.id !== id);
+  }
+
+  async execute<TPayload = unknown, TResult = unknown>(
+    config: ApiMethodConfig<TPayload, TResult>,
+    payload?: TPayload,
+    ctx?: ExecuteContext,
+  ): Promise<TResult> {
+    const store = this as unknown as ApiMethodStore;
+    const ok = config.validate ? config.validate(store, payload) : true;
+    if (!ok) throw new Error(config.ui?.errorMessage ?? 'Validation failed');
+
+    const ui = config.ui ?? {};
+    const showIndicator = ui.showIndicator ?? true;
+    const showErrorToast = ui.showErrorToast ?? true;
+    const showSuccessToast = ui.showSuccessToast ?? false;
+    const unwrapDataArray = ui.unwrapDataArray ?? true;
+    const startTime = Date.now();
+    const MIN_DELAY_MS = 300;
+
+    const useMulti = Array.isArray(config.endpoints) && config.endpoints.length > 0;
+
+    if (useMulti) {
+      this._multiEndpointBatch = true;
+      if (showIndicator) this.setIndicator(true, ui.indicatorMessage);
+      try {
+        const results: unknown[] = [];
+        for (const call of config.endpoints as ApiMethodEndpointCall<TPayload, ApiMethodStore>[]) {
+          const body = call.body
+            ? (call.body(store, payload) as unknown)
+            : config.body
+              ? (config.body(store, payload) as unknown)
+              : (payload as unknown);
+          const query = call.query ? call.query(store, payload) : config.query?.(store, payload);
+          const params = call.params ? call.params(store, payload) : config.params?.(store, payload);
+          const res = await sendRequest<unknown, unknown>(call.endpoint, {
+            body,
+            query,
+            params,
+          });
+          const unwrapped = unwrapCoreSdk<unknown>(res, unwrapDataArray);
+          if (unwrapped == null) throw new Error(ui.errorMessage ?? 'Request failed');
+          results.push(unwrapped);
+        }
+        const elapsed = Date.now() - startTime;
+        if (elapsed < MIN_DELAY_MS) {
+          await new Promise((r) => setTimeout(r, MIN_DELAY_MS - elapsed));
+        }
+        const result = results as TResult;
+        if (showSuccessToast && ui.successMessage) {
+          runInAction(() => this.addToast(ui.successMessage!, 'success'));
+        }
+        if (config.post) runInAction(() => config.post!(result, store, payload));
+        const effectiveCtx: ExecuteContext = {
+          redirectTo: ctx?.redirectTo,
+          navigate: ctx?.navigate,
+        };
+        if (config.redirectPath && effectiveCtx.navigate) {
+          const path =
+            typeof config.redirectPath === 'function'
+              ? config.redirectPath(result, payload, effectiveCtx)
+              : config.redirectPath;
+          effectiveCtx.navigate(path, { replace: true });
+        }
+        return result;
+      } catch (e) {
+        if (showErrorToast) {
+          runInAction(() => this.addToast(getErrorMessage(e), 'error'));
+        }
+        throw e;
+      } finally {
+        this._multiEndpointBatch = false;
+        if (showIndicator) this.setIndicator(false);
+      }
+    }
+
+    const ep = config.endpoint;
+    if (!ep) throw new Error('ApiMethodConfig: endpoint or endpoints required');
+
+    const res = await this.sendMessage<unknown, TResult | CoreSdkWrapped<TResult>>(ep, {
+      params: config.params ? config.params(store, payload) : undefined,
+      body: config.body ? (config.body(store, payload) as unknown) : (payload as unknown),
+      query: config.query ? config.query(store, payload) : undefined,
+      showIndicator,
+      indicatorMessage: ui.indicatorMessage,
+      showErrorToast,
+      showSuccessToast,
+      successMessage: ui.successMessage,
+    });
+
+    const elapsed = Date.now() - startTime;
+    if (elapsed < MIN_DELAY_MS) {
+      await new Promise((r) => setTimeout(r, MIN_DELAY_MS - elapsed));
+    }
+
+    const result = unwrapCoreSdk<TResult>(res, unwrapDataArray);
+    if (result == null && unwrapDataArray) throw new Error(ui.errorMessage ?? 'Request failed');
+    const finalResult = (unwrapDataArray ? result : res) as TResult;
+    if (config.post) runInAction(() => config.post!(finalResult, store, payload));
+
+    const effectiveCtx: ExecuteContext = {
+      redirectTo: ctx?.redirectTo,
+      navigate: ctx?.navigate,
+    };
+
+    if (config.redirectPath && effectiveCtx.navigate) {
+      const path =
+        typeof config.redirectPath === 'function'
+          ? config.redirectPath(finalResult, payload, effectiveCtx)
+          : config.redirectPath;
+      effectiveCtx.navigate(path, { replace: true });
+    }
+    return finalResult;
+  }
+
+  async executeMethod<K extends MethodName>(
+    methodName: K,
+    payload?: (typeof methods)[K] extends ApiMethodConfig<infer P, unknown> ? P : never,
+    ctx?: ExecuteContext,
+  ): Promise<
+    (typeof methods)[K] extends ApiMethodConfig<unknown, infer R> ? R : never
+  > {
+    const config = methods[methodName] as unknown as ApiMethodConfig<unknown, unknown>;
+    runInAction(() => this.setMethodLoading(methodName as string));
+    try {
+      return (await this.execute(config, payload, ctx)) as (typeof methods)[K] extends ApiMethodConfig<
+        unknown,
+        infer R
+      >
+        ? R
+        : never;
+    } finally {
+      runInAction(() => this.setMethodLoading(null));
+    }
+  }
+
+  async getCachedOrExecute<K extends MethodName>(
+    cacheKey: string,
+    methodName: K,
+    ttlMs?: number,
+    payload?: (typeof methods)[K] extends ApiMethodConfig<infer P, unknown> ? P : never,
+    ctx?: ExecuteContext,
+  ): Promise<(typeof methods)[K] extends ApiMethodConfig<unknown, infer R> ? R : never> {
+    const cached = this.apiCacheStore.get<
+      (typeof methods)[K] extends ApiMethodConfig<unknown, infer R> ? R : never
+    >(cacheKey);
+    if (cached !== undefined) return cached;
+    const result = await this.executeMethod(methodName, payload, ctx);
+    this.apiCacheStore.set(cacheKey, result, ttlMs);
+    return result;
+  }
+
+  /**
+   * `EndpointDef.post`·`timeoutMs` 는 `sendRequest` 에서 적용.
+   * `showIndicator` 는 options → `endpoint.showIndicator` → `true` 순으로 결정.
+   */
+  async sendMessage<T = unknown, R = unknown>(endpoint: EndpointDef, options: SendMessageOptions<T> = {}): Promise<R> {
+    const {
+      params,
+      query,
+      body,
+      showIndicator: showIndicatorOpt,
+      indicatorMessage,
+      showErrorToast = true,
+      showSuccessToast = false,
+      successMessage,
+    } = options;
+
+    const showIndicator =
+      showIndicatorOpt !== undefined ? showIndicatorOpt : (endpoint.showIndicator ?? true);
+
+    if (showIndicator) this.setIndicator(true, indicatorMessage);
+    try {
+      const data = await sendRequest<T, R>(endpoint, {
+        params,
+        query,
+        body,
+        skipGlobalIndicator: !showIndicator,
+      });
+      runInAction(() => {
+        if (showSuccessToast && successMessage) this.addToast(successMessage, 'success');
+      });
+      return data;
+    } catch (e) {
+      runInAction(() => {
+        if (showErrorToast) this.addToast(getErrorMessage(e), 'error');
+      });
+      throw e;
+    } finally {
+      runInAction(() => {
+        if (showIndicator) this.setIndicator(false);
+      });
+    }
+  }
+}
+
+export const rootStore = new RootStore();

package/template/web/shared/src/store/session-store.ts

@@ -0,0 +1,28 @@
+import { makeAutoObservable } from 'mobx';
+
+/** Bearer 토큰 등 — api/client 가 Authorization 헤더에 반영 */
+export class SessionStore {
+  token: string | null = null;
+  private _onLogout?: () => void;
+
+  constructor() {
+    makeAutoObservable(this);
+  }
+
+  /** RootStore 등에서 한 번 등록 — 토큰 제거 시 캐시 비우기 등 */
+  registerLogoutCallback(cb: () => void) {
+    this._onLogout = cb;
+  }
+
+  setToken(token: string | null) {
+    const had = this.token != null;
+    this.token = token;
+    if (had && token == null) this._onLogout?.();
+  }
+
+  logout() {
+    this.setToken(null);
+  }
+}
+
+export const sessionStore = new SessionStore();

package/template/web/shared/src/types/ui.ts

@@ -0,0 +1,37 @@
+/**
+ * indicator / toast / sendMessage 옵션 — RootStore·api/client 와 공유
+ */
+
+export type ToastSeverity = 'info' | 'success' | 'warn' | 'error';
+
+export interface ToastItem {
+  id: string;
+  message: string;
+  severity: ToastSeverity;
+  createdAt: number;
+}
+
+export interface ApiErrorItem {
+  id: string;
+  message: string;
+  code?: string | number;
+  createdAt: number;
+}
+
+export interface IndicatorState {
+  loading: boolean;
+  message?: string;
+  methodLoading?: string | null;
+}
+
+export interface SendMessageOptions<T = unknown> {
+  params?: Record<string, string>;
+  query?: Record<string, string | number | boolean | undefined>;
+  body?: T;
+  /** 미지정 시 `EndpointDef.showIndicator`, 그다음 기본 `true` */
+  showIndicator?: boolean;
+  indicatorMessage?: string;
+  showErrorToast?: boolean;
+  showSuccessToast?: boolean;
+  successMessage?: string;
+}

package/template/web/shared/tsconfig.json

@@ -10,7 +10,10 @@
     "declaration": true,
     "declarationMap": true,
     "outDir": "dist",
-    "rootDir": "src"
+    "baseUrl": ".",
+    "paths": {
+      "@shared/*": ["../../shared/*"]
+    }
   },
   "include": ["src/**/*"]
 }