@dooboostore/simple-web-component 1.0.53 → 1.0.55

package/src/decorators/fetch.ts

@@ -25,45 +25,24 @@ export type FetchManualFn = (
   returnValue?: any
 ) => any | Promise<any>;
 
-/** 모드(선언형/수동형, before/after)와 무관한 공통 옵션 */
+/** filter 가 받는 것 */
+export type FetchFilterContext = { self: any; helper: HelperHostSet; args: any[] };
+
+/**
+ * 모드(선언형/수동형, before/after)와 무관한 공통 옵션.
+ * 결과 처리(then/catch/finally)는 @fetchPromise 로 받은 Promise 로 사용자가 직접 한다 — 그래서 훅이 없다.
+ */
 export type FetchType = {
   /**
    * 같은 메서드를 다시 부르면 진행 중인 이전 요청을 abort 한다 (검색 자동완성 등 마지막 요청만 살림).
-   * 끊긴 이전 호출은 조용히 undefined 로 끝난다.
+   * 끊긴 이전 호출의 Promise 는 끝나지 않는다 (떨어진 DOM 에 그리지 않고 조용히 끝남).
    */
   abortPrevious?: boolean;
-  /** false 를 리턴하면 이번 호출을 통째로 건너뛴다 (메서드도 fetch 도 실행 안 함, undefined 리턴). */
-  filter?: (
-    currentThis: any,
-    helper: HelperHostSet,
-    parameter: any[]
-  ) => boolean | Promise<boolean>;
-  /** filter 통과 후 가장 먼저 실행 (await). 리턴값은 무시. init 조립은 request 팩토리 담당. */
-  before?: (
-    currentThis: any,
-    helper: HelperHostSet,
-    parameter: any[]
-  ) => void | Promise<void>;
   /**
-   * fetch settled 후 호출 (fulfilled/rejected 모두). 호출만 하고 리턴값은 무시.
-   * 변환·복구가 필요하면 manual 로 직접 구현할 것.
+   * false 를 리턴하면 이번 호출을 통째로 건너뛴다 (요청도 메서드도 실행 안 함, undefined 리턴).
+   * 요청이 메서드보다 먼저 나가므로 "보낼지 말지"는 여기서만 정할 수 있다. 메서드를 동기로 유지하려고 동기만 받는다.
    */
-  after?: (
-    currentThis: any,
-    helper: HelperHostSet,
-    parameter: any[],
-    settled: PromiseSettledResult<any>
-  ) => void | Promise<void>;
-  /**
-   * 성공/실패 무관 항상 실행 (다른 데코레이터의 finally 와 같은 규칙). 에러는 삼키지 않고 전파.
-   * args: 메서드에 넘긴 인자, result: 이번 호출의 리턴값(before 모드 = 메서드 리턴, after 모드 = fetch 결과)
-   */
-  finally?: (
-    currentThis: any,
-    helper: HelperHostSet,
-    parameter: any[],
-    ctx: { args: any[]; result?: any; error?: any }
-  ) => any | Promise<any>;
+  filter?: (ctx: FetchFilterContext) => boolean;
 };
 
 /** before: 인자 기반 RequestInit 조립. 없으면 GET. */
@@ -84,8 +63,13 @@ export type ReturnRequestFactory = (
 export interface FetchMetadata {
   propertyKey: string | symbol;
   options: FetchOptions;
+  /** 필드(declare)에 붙었으면 true — 프레임워크가 요청 함수를 만든다 */
+  field?: boolean;
 }
 
+// 프레임워크가 만든 필드 요청 함수 표시 (덮어써졌는지 확인용)
+const FETCH_FIELD_FN = Symbol.for('simple-web-component:fetch-field-fn');
+
 /** 선언형: url/request/process 로 기술하면 프레임워크가 fetch 한다 */
 export type FetchDeclarative<R> = {
   url: RequestInfo | URL | FetchUrlFactory;
@@ -110,8 +94,8 @@ export type FetchManual = {
 };
 
 export type FetchOptions =
-  // before(기본): (선언형 fetch | manual) → settled를 @fetchSettled 자리에
-  // 주입해 메서드 실행. 메서드 결과 리턴. request 없으면 GET. valueKey 는 after 전용이라 금지.
+  // before(기본): 요청을 시작하고 그 Promise 를 @fetchPromise 자리에 넣어 메서드를 바로 호출한다.
+  // 메서드 반환값을 그대로 리턴 (동기 메서드는 동기 그대로). request 없으면 GET. valueKey 는 after 전용이라 금지.
   | (FetchType & { trigger?: 'before'; valueKey?: never } & (FetchDeclarative<RequestFactory> | FetchManual))
   // after: 메서드 실행 → 리턴값(valueKey 가 있으면 returnValue[valueKey])을 body(수동형이면 returnValue)로 → fetch. fetch 결과 리턴.
   // (valueKey 기본값 = FETCH_METADATA_KEY: Symbol 키 우선 조회, 없으면 통째 값)
@@ -141,19 +125,44 @@ const combineSignals = (user: AbortSignal | null | undefined, own: AbortSignal):
   return merged.signal;
 };
 
-function createFetch(optionsOrUrl: FetchOptions | string): MethodDecorator {
+/**
+ * @fetch 계열 데코레이터는 메서드와 필드 양쪽에 붙는다.
+ * - 메서드: 트리거가 부르는 핸들러용. 요청 Promise 를 @fetchPromise 로 주입하고 메서드를 쌓는다 (기존 방식)
+ * - 필드(declare): 직접 부르는 요청 함수용. `declare getPost: (id: number) => Promise<Post>` 의 몸통을 프레임워크가 만든다
+ */
+export type FetchDecorator = {
+  /**
+   * 필드: 선언 타입이 `(...args) => Promise<…>`(요청 함수) 또는 `Promise<…>`(값) 가 아니면 컴파일 에러.
+   * 옵셔널(`declare me?: Promise<T>`)도 된다 — 값 필드를 `this.me = undefined` 로 비우려면 strict 에선 옵셔널로 선언한다.
+   * (private / protected 필드는 TS 가 바깥 타입에서 못 봐서 검사 없이 통과 — 런타임 design:type 검사만 적용)
+   */
+  <T, K extends string | symbol>(target: T & (K extends keyof T ? { [P in K]?: ((...args: any[]) => Promise<any>) | Promise<any> } : unknown), propertyKey: K): void;
+  /** 메서드: 트리거 핸들러 (요청 Promise 는 @fetchPromise 로) */
+  (target: Object, propertyKey: string | symbol, descriptor: PropertyDescriptor): any;
+};
+
+// 건너뛰거나 끊긴 필드 호출이 돌려주는 Promise — 끝나지 않는다 (떨어진 DOM 에 그리지 않고 에러도 없음)
+const never = () => new Promise<never>(() => {});
+
+// 필드를 Promise 로 쓸 때 기억한 요청 — 엘리먼트 → (필드 이름 → Promise). 엘리먼트에 속성을 붙이지 않는다.
+const valueCache = new WeakMap<object, Map<string | symbol, Promise<any>>>();
+const cacheOf = (inst: object) => {
+  let m = valueCache.get(inst);
+  if (!m) valueCache.set(inst, (m = new Map()));
+  return m;
+};
+
+function createFetch(optionsOrUrl: FetchOptions | string): FetchDecorator {
   const options: FetchOptions = typeof optionsOrUrl === 'string' ? { url: optionsOrUrl } : optionsOrUrl;
-  return (target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => {
+  return ((target: Object, propertyKey: string | symbol, descriptor?: PropertyDescriptor) => {
     const constructor = target.constructor;
+    const isField = !descriptor;
     const list = (ReflectUtils.getOwnMetadata(FETCH_METADATA_KEY, constructor) as FetchMetadata[] | undefined) ?? [];
-    list.push({ propertyKey, options });
+    list.push({ propertyKey, options, field: isField });
     ReflectUtils.defineMetadata(FETCH_METADATA_KEY, list, constructor);
 
-    if (!descriptor) return descriptor;
-    const originalMethod = descriptor.value;
-
     const extractBody = (v: any) => {
-      const keyToUse = (options as { valueKey?: symbol | string }).valueKey ?? FETCH_METADATA_KEY;
+        const keyToUse = (options as { valueKey?: symbol | string }).valueKey ?? FETCH_METADATA_KEY;
       if (v && typeof v === 'object' && keyToUse in v) {
         return v[keyToUse];
       }
@@ -224,37 +233,26 @@ function createFetch(optionsOrUrl: FetchOptions | string): MethodDecorator {
       return readBody(res);
     };
 
-    // 호출 인자는 유지한 채, @fetchSettled 자리만 채운다
-    const injectSettled = (inst: any, methodName: string | symbol, args: any[], settled: PromiseSettledResult<any>): any[] => {
-      const saves = getParameterMetadata(inst, methodName);
-      if (!saves.length) return args;
-      const out = [...args];
-      for (const s of saves) {
-        if (s.kind === 'fetchSettled') out[s.index] = settled;
-      }
-      return out;
-    };
+    const trigger = (options as { trigger?: string }).trigger;
+    const isAfter = trigger === 'after' || (trigger !== 'before' && 'valueKey' in options);
+    const manual = (options as FetchManual).manual;
 
-    descriptor.value = async function (...args: any[]) {
-      const inst = this as any;
+    /**
+     * 호출 한 번을 시작한다. 건너뛸 호출(떨어진 뒤 시작 / filter false)이면 null.
+     * 프레임워크가 끊는 경우(disconnect / abortPrevious)는 에러가 아니라 "할 일 없음" — frameworkAborted() 로 구분한다.
+     */
+    const begin = (inst: any, args: any[]) => {
       let helper: HelperHostSet | undefined;
       try {
         helper = SwcUtils.getHelperAndHostSet(inst);
       } catch {
         helper = undefined;
       }
-
-      // disconnect 된 뒤에 새로 시작하는 호출(예: 떠나기 직전 걸어둔 setTimeout)도 조용히 건너뛴다.
+      // disconnect 된 뒤에 새로 시작하는 호출(예: 떠나기 직전 걸어둔 setTimeout)은 건너뛴다.
       // 한 번도 connect 안 된 요소는 해당 없음 (FetchLifeCycler 가 disconnect 때만 표시)
-      if (inst?.__swc_fetchDetached && inst.isConnected === false) return undefined;
+      if (inst?.__swc_fetchDetached && inst.isConnected === false) return null;
+      if (options.filter && !options.filter({ self: inst, helper: helper!, args })) return null;
 
-      // filter → before → (before 모드: fetch → 메서드 / after 모드: 메서드 → fetch) → finally
-      if (options.filter && !(await options.filter(inst, helper!, args))) return undefined;
-      if (options.before) await options.before(inst, helper!, args);
-
-      const manual = (options as FetchManual).manual;
-
-      // 프레임워크가 끊는 경우(disconnect / abortPrevious)는 에러가 아니라 "할 일 없음" → 조용히 undefined
       const controller = new AbortController();
       const active = getActiveControllers(inst);
       active.add(controller);
@@ -264,8 +262,12 @@ function createFetch(optionsOrUrl: FetchOptions | string): MethodDecorator {
         latest.set(propertyKey, controller);
       }
       const frameworkAborted = () => controller.signal.aborted;
+      const cleanup = () => {
+        active.delete(controller);
+        if (options.abortPrevious && getLatestControllers(inst).get(propertyKey) === controller) getLatestControllers(inst).delete(propertyKey);
+      };
 
-      // 사용자 manual 이 signal 을 무시해도 abort 즉시 호출이 끝나도록 abort 와 경쟁시킨다
+      // 사용자 manual 이 signal 을 무시해도 abort 즉시 끝나도록 abort 와 경쟁시킨다
       const aborted = new Promise<never>((_, reject) => {
         if (controller.signal.aborted) reject(controller.signal.reason);
         else controller.signal.addEventListener('abort', () => reject(controller.signal.reason), { once: true });
@@ -273,80 +275,163 @@ function createFetch(optionsOrUrl: FetchOptions | string): MethodDecorator {
       aborted.catch(() => {}); // race 에 안 쓰이고 끝나도 unhandled rejection 이 안 나게
 
       // 수동형이면 manual(…, signal, returnValue), 선언형이면 url/init 으로 기본 fetch
-      const runFetch = async (init?: RequestInit, returnValue?: any): Promise<PromiseSettledResult<any>> => {
-        let settled: PromiseSettledResult<any>;
-        try {
-          const pending = Promise.resolve(manual
-            ? manual(inst, helper!, args, controller.signal, returnValue)
-            : defaultFetching(helper, resolveUrl(inst, helper!, args), { ...init, signal: combineSignals(init?.signal, controller.signal) }));
-          pending.catch(() => {}); // abort 로 race 에서 진 뒤 늦게 reject 돼도 unhandled rejection 이 안 나게
-          settled = { status: 'fulfilled', value: await Promise.race([pending, aborted]) };
-        } catch (reason) {
-          settled = { status: 'rejected', reason };
-        }
-        // 떨어진 요소의 DOM 을 건드리지 않게, 프레임워크 abort 면 after 훅은 건너뛴다
-        if (options.after && !frameworkAborted()) await options.after(inst, helper!, args, settled);
-        return settled;
+      const doFetch = (init?: RequestInit, returnValue?: any): Promise<any> => {
+        const pending = Promise.resolve().then(() => manual
+          ? manual(inst, helper!, args, controller.signal, returnValue)
+          : defaultFetching(helper, resolveUrl(inst, helper!, args), { ...init, signal: combineSignals(init?.signal, controller.signal) }));
+        pending.catch(() => {}); // abort 로 race 에서 진 뒤 늦게 reject 돼도 unhandled rejection 이 안 나게
+        return Promise.race([pending, aborted]);
       };
 
-      let callArgs = args;
-      let result: any;
-      let error: any;
-      try {
-        const trigger = (options as { trigger?: string }).trigger;
-        const isAfter = trigger === 'after' || (trigger !== 'before' && 'valueKey' in options);
-        if (isAfter) {
-          // after: 메서드 실행 → body 추출 → request 와 합쳐 fetch → fetch 결과 리턴.
-          const returned = await originalMethod.apply(inst, callArgs);
-          const body = extractBody(returned);
-          let settled: PromiseSettledResult<any>;
-          if (manual) {
-            settled = await runFetch(undefined, body);
-          } else {
-            const reqOpt = (options as FetchDeclarative<ReturnRequestFactory>).request;
-            const reqInit: RequestInit | undefined = typeof reqOpt === 'string'
-              ? { method: reqOpt }
-              : typeof reqOpt === 'function' ? await reqOpt(inst, helper!, args, returned) : undefined;
-            settled = await runFetch({ ...reqInit, body: reqInit?.body ?? body });
-          }
-          if (frameworkAborted()) {
-            error = controller.signal.reason;
-            return undefined;
-          }
-          if (settled.status === 'rejected') throw settled.reason;
-          result = settled.value;
-        } else {
-          // before: request 조립 → fetch → settled 를 주입해 메서드 실행. 메서드 결과 리턴.
-          const reqOpt = manual ? undefined : (options as FetchDeclarative<RequestFactory>).request;
-          const init: RequestInit | undefined = typeof reqOpt === 'string' ? { method: reqOpt } : typeof reqOpt === 'function' ? await reqOpt(inst, helper!, args) : undefined;
-          const settled = await runFetch(init);
-          if (frameworkAborted()) {
-            // 떨어진 요소에 그리지 않게 메서드도 실행하지 않는다
-            error = controller.signal.reason;
-            return undefined;
-          }
-          callArgs = injectSettled(inst, propertyKey, args, settled);
-          result = await originalMethod.apply(inst, callArgs);
-        }
-        return result;
-      } catch (e) {
-        error = e;
-        throw e;
-      } finally {
-        active.delete(controller);
-        if (options.abortPrevious && getLatestControllers(inst).get(propertyKey) === controller) getLatestControllers(inst).delete(propertyKey);
-        // finally 는 정리용이라 프레임워크 abort 여도 실행 (ctx.error 에 AbortError)
-        if (options.finally) await options.finally(inst, helper!, args, { args: callArgs, result, error });
+      // before: request 조립(인자 기반) → fetch
+      const fetchBefore = () => {
+        const reqOpt = manual ? undefined : (options as FetchDeclarative<RequestFactory>).request;
+        return Promise.resolve()
+          .then(() => (typeof reqOpt === 'string' ? { method: reqOpt } : typeof reqOpt === 'function' ? reqOpt(inst, helper!, args) : undefined))
+          .then(init => doFetch(init));
+      };
+      // after: returned(메서드 리턴 / 필드면 마지막 인자)에서 body 를 뽑아 request 와 합쳐 fetch
+      const fetchAfter = async (returned: any) => {
+        const body = extractBody(returned);
+        if (manual) return doFetch(undefined, body);
+        const reqOpt = (options as FetchDeclarative<ReturnRequestFactory>).request;
+        const reqInit: RequestInit | undefined = typeof reqOpt === 'string'
+          ? { method: reqOpt }
+          : typeof reqOpt === 'function' ? await reqOpt(inst, helper!, args, returned) : undefined;
+        return doFetch({ ...reqInit, body: reqInit?.body ?? body });
+      };
+      // 결과 Promise: 프레임워크가 끊으면 끝나지 않는다. 사용자가 안 받아도 unhandled rejection 이 안 나게
+      const quiet = (run: Promise<any>): Promise<any> => {
+        const promise = new Promise<any>((resolve, reject) => {
+          run.then(v => { if (!frameworkAborted()) resolve(v); }, e => { if (!frameworkAborted()) reject(e); }).finally(cleanup);
+        });
+        promise.catch(() => {});
+        return promise;
+      };
+
+      return { frameworkAborted, cleanup, fetchBefore, fetchAfter, quiet };
+    };
+
+    // ── 필드: declare 필드의 값을 프레임워크가 만든다 ──
+    // 선언이 함수(`(…) => Promise<T>`)든 값(`Promise<T>`)든 데코레이터가 받는 건 (prototype, 이름) 뿐이고
+    // 타입은 런타임에 없다(빌드 도구에 따라 design:type 도 없음). 그래서 필드 값은 "부를 수 있는 함수이면서 Promise" 하나로 만든다:
+    //   - 부르면 (함수로 선언한 경우): 부를 때마다 새 요청. 인자 = url/request 재료, after(POST…)면 마지막 인자가 body
+    //   - then/catch/finally/await (Promise 로 선언한 경우): 기억된 요청. 처음이면 요청, 성공하면 기억, 실패하면 잊어서 다음에 다시
+    //   - 대입: undefined / null 이면 잊음, 다른 값/Promise 면 그걸 기억 (예: SSR 로 받은 값)
+    // 사용자는 선언한 타입대로만 쓴다 (TS 가 Promise 로 선언한 필드의 호출을 막는다).
+    if (isField) {
+      // 타입 정보가 있는 빌드(emitDecoratorMetadata)면 함수/Promise 가 아닌 선언을 바로 알린다 (없으면 컴파일 검사만)
+      const designType = ReflectUtils.getMetadata('design:type', target, propertyKey);
+      if (designType !== undefined && designType !== Function && designType !== Promise && designType !== Object) {
+        throw new Error(`[SWC] @fetch field "${String(propertyKey)}" must be a function returning a Promise (\`declare ${String(propertyKey)}: (…) => Promise<T>\`) or a Promise (\`declare ${String(propertyKey)}: Promise<T>\`), not ${designType?.name ?? String(designType)}.`);
+      }
+      // 같은 이름을 다른 데코레이터가 이미 차지했으면(접근자 등) 정의 시점에 바로 알린다
+      if (Object.prototype.hasOwnProperty.call(target, propertyKey)) {
+        throw new Error(`[SWC] "${String(propertyKey)}" is a @fetch field but something else already defines it. Put triggers/outputs on a method that calls this.${String(propertyKey)}().`);
+      }
+
+      // 기억된 요청 (Promise 로 쓸 때). body 는 request 팩토리로 (인자 없음 → args = [], returnValue = undefined)
+      const remembered = (inst: any): Promise<any> => {
+        const cache = cacheOf(inst);
+        const hit = cache.get(propertyKey);
+        if (hit) return hit;
+        const call = begin(inst, []);
+        if (!call) return never(); // 건너뛴 호출은 기억하지 않는다
+        const promise = call.quiet(isAfter ? call.fetchAfter(undefined) : call.fetchBefore());
+        cache.set(propertyKey, promise);
+        promise.catch(() => { if (cache.get(propertyKey) === promise) cache.delete(propertyKey); });
+        return promise;
+      };
+
+      // 인스턴스마다 필드 값(함수 겸 Promise) 하나 — 읽을 때마다 같은 값
+      const values = new WeakMap<object, any>();
+      const get = function (this: any) {
+        const inst = this;
+        let value = values.get(inst);
+        if (value) return value;
+        value = function (...args: any[]) {
+          const call = begin(inst, args);
+          if (!call) return never();
+          return call.quiet(isAfter ? call.fetchAfter(args[args.length - 1]) : call.fetchBefore());
+        };
+        value.then = (ok?: any, fail?: any) => remembered(inst).then(ok, fail);
+        value.catch = (fail?: any) => remembered(inst).catch(fail);
+        value.finally = (done?: any) => remembered(inst).finally(done);
+        // instanceof Promise 로 Promise 를 알아보는 코드(출력 데코레이터 등)도 Promise 로 보게 한다.
+        // then/catch/finally 는 위에서 직접 달았으니 Promise.prototype 의 것(내부 슬롯 필요)은 쓰이지 않는다.
+        Object.setPrototypeOf(value, Promise.prototype);
+        values.set(inst, value);
+        return value;
+      };
+      (get as any)[FETCH_FIELD_FN] = true;
+      Object.defineProperty(target, propertyKey, {
+        get,
+        set(this: any, v: any) {
+          const cache = cacheOf(this);
+          if (v === undefined || v === null) cache.delete(propertyKey);
+          else cache.set(propertyKey, Promise.resolve(v));
+        },
+        configurable: true,
+      });
+      return;
+    }
+
+    // ── 메서드: 트리거 핸들러용 ──
+    const originalMethod = descriptor!.value;
+
+    // after 모드는 fetch 결과를 리턴하므로 래퍼가 항상 Promise 를 돌려준다 — 동기 메서드면 선언과 어긋나니 알려준다
+    let warnedSync = false;
+    const isPromiseLike = (v: any) => v instanceof Promise || (v && typeof v.then === 'function');
+    const guardSync = (raw: any) => {
+      if (!warnedSync && originalMethod?.constructor?.name !== 'AsyncFunction' && !isPromiseLike(raw)) {
+        warnedSync = true;
+        console.warn(`[SWC] @fetch (after) on "${String(propertyKey)}" always returns a Promise: declare the method async (or with an explicit Promise return type) so the signature matches.`);
       }
     };
 
+    // 호출 인자는 유지한 채, @fetchPromise 자리만 채운다
+    const injectPromise = (inst: any, methodName: string | symbol, args: any[], promise: Promise<any>): any[] => {
+      const saves = getParameterMetadata(inst, methodName);
+      if (!saves.length) return args;
+      const out = [...args];
+      for (const s of saves) {
+        if (s.kind === 'fetchPromise') out[s.index] = promise;
+      }
+      return out;
+    };
+
+    descriptor!.value = function (...args: any[]) {
+      const inst = this as any;
+      const call = begin(inst, args);
+      if (!call) return undefined;
+
+      if (!isAfter) {
+        // before: 요청을 시작하고, 그 Promise 를 @fetchPromise 자리에 넣어 메서드를 바로 부른다. 메서드 반환값을 그대로 리턴.
+        return originalMethod.apply(inst, injectPromise(inst, propertyKey, args, call.quiet(call.fetchBefore())));
+      }
+
+      // after: 메서드 실행 → 리턴값에서 body → fetch → fetch 결과 리턴
+      return (async () => {
+        try {
+          const raw = originalMethod.apply(inst, args);
+          guardSync(raw);
+          return await call.fetchAfter(await raw);
+        } catch (e) {
+          if (call.frameworkAborted()) return undefined; // 끊긴 호출은 조용히
+          throw e;
+        } finally {
+          call.cleanup();
+        }
+      })();
+    };
+
     return descriptor;
-  };
+  }) as FetchDecorator;
 }
 
-export function fetch(url: string): MethodDecorator;
-export function fetch(options: FetchOptions): MethodDecorator;
-export function fetch(optionsOrUrl: FetchOptions | string): MethodDecorator {
+export function fetch(url: string): FetchDecorator;
+export function fetch(options: FetchOptions): FetchDecorator;
+export function fetch(optionsOrUrl: FetchOptions | string): FetchDecorator {
   return createFetch(optionsOrUrl);
 }
 
@@ -365,7 +450,7 @@ export type FetchManualOptions = FetchType & FetchTriggerOptions;
  * @fetchManual(fn, options?) = @fetch({ manual: fn, ...options })
  * 서비스 호출 등 요청을 직접 만들 때. 예: @fetchManual((self) => self.myService.getProfile({}))
  */
-export function fetchManual(manual: FetchManualFn, options?: FetchManualOptions): MethodDecorator {
+export function fetchManual(manual: FetchManualFn, options?: FetchManualOptions): FetchDecorator {
   return createFetch({ ...(options ?? {}), manual } as FetchOptions);
 }
 
@@ -376,7 +461,7 @@ export type FetchAfterMethodOptions = FetchType & Omit<FetchDeclarative<ReturnRe
 
 type FetchUrl = RequestInfo | URL | FetchUrlFactory;
 
-const beforeMethod = (method: string) => (url: FetchUrl, options?: FetchBeforeMethodOptions): MethodDecorator => {
+const beforeMethod = (method: string) => (url: FetchUrl, options?: FetchBeforeMethodOptions): FetchDecorator => {
   const { request, ...rest } = options ?? {};
   return createFetch({
     ...rest,
@@ -386,7 +471,7 @@ const beforeMethod = (method: string) => (url: FetchUrl, options?: FetchBeforeMe
   } as FetchOptions);
 };
 
-const afterMethod = (method: string) => (url: FetchUrl, options?: FetchAfterMethodOptions): MethodDecorator => {
+const afterMethod = (method: string) => (url: FetchUrl, options?: FetchAfterMethodOptions): FetchDecorator => {
   const { request, ...rest } = options ?? {};
   return createFetch({
     ...rest,
@@ -396,7 +481,7 @@ const afterMethod = (method: string) => (url: FetchUrl, options?: FetchAfterMeth
   } as FetchOptions);
 };
 
-/** @fetchGet(url, options?) — before 모드 GET. 결과는 @fetchSettled 으로 */
+/** @fetchGet(url, options?) — before 모드 GET. 요청 Promise 는 @fetchPromise 로 */
 export const fetchGet = beforeMethod('GET');
 /** @fetchDelete(url, options?) — before 모드 DELETE (body 없음) */
 export const fetchDelete = beforeMethod('DELETE');
@@ -411,20 +496,20 @@ export const fetchPatch = afterMethod('PATCH');
  * @fetchLatest(url | options) = @fetch({ ...options, abortPrevious: true })
  * 연달아 부르면 이전 요청을 끊고 마지막 것만 살린다 (검색 자동완성 등)
  */
-export function fetchLatest(url: string): MethodDecorator;
-export function fetchLatest(options: FetchOptions): MethodDecorator;
-export function fetchLatest(optionsOrUrl: FetchOptions | string): MethodDecorator {
+export function fetchLatest(url: string): FetchDecorator;
+export function fetchLatest(options: FetchOptions): FetchDecorator;
+export function fetchLatest(optionsOrUrl: FetchOptions | string): FetchDecorator {
   const options: FetchOptions = typeof optionsOrUrl === 'string' ? { url: optionsOrUrl } : optionsOrUrl;
   return createFetch({ ...options, abortPrevious: true } as FetchOptions);
 }
 
 /** @fetchBefore(options) = @fetch({ ...options, trigger: 'before' }) */
-export function fetchBefore(options: FetchType & (FetchDeclarative<RequestFactory> | FetchManual)): MethodDecorator {
+export function fetchBefore(options: FetchType & (FetchDeclarative<RequestFactory> | FetchManual)): FetchDecorator {
   return createFetch({ ...options, trigger: 'before' } as FetchOptions);
 }
 
 /** @fetchAfter(options) = @fetch({ ...options, trigger: 'after' }) */
-export function fetchAfter(options: FetchType & { valueKey?: string } & (FetchDeclarative<ReturnRequestFactory> | FetchManual)): MethodDecorator {
+export function fetchAfter(options: FetchType & { valueKey?: string } & (FetchDeclarative<ReturnRequestFactory> | FetchManual)): FetchDecorator {
   return createFetch({ ...options, trigger: 'after' } as FetchOptions);
 }
 
@@ -434,18 +519,63 @@ export const getFetchMetadata = (target: any): FetchMetadata[] | undefined => {
   return ReflectUtils.findAllMetadata<any[]>(FETCH_METADATA_KEY, constructor).flat();
 };
 
+// 메타데이터 값 안 어딘가가 이 이름(propertyKey)을 가리키는지 (Map 키 / 배열 / { propertyKey })
+const refersTo = (v: any, key: string | symbol): boolean => {
+  if (v instanceof Map) return v.has(key) || [...v.values()].some(x => refersTo(x, key));
+  if (Array.isArray(v)) return v.some(x => refersTo(x, key));
+  return !!v && typeof v === 'object' && v.propertyKey === key;
+};
+const findDescriptor = (proto: any, key: string | symbol): PropertyDescriptor | undefined => {
+  for (let p = proto; p && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
+    const d = Object.getOwnPropertyDescriptor(p, key);
+    if (d) return d;
+  }
+  return undefined;
+};
+const fieldHint = (key: string | symbol) => `Put triggers/outputs on a method that calls this.${String(key)}().`;
+
+/**
+ * @elementDefine 이 클래스 정의 시점에 부른다 (멤버 데코레이터가 다 붙은 뒤라 붙인 순서와 무관).
+ * 필드 @fetch 와 같은 이름에 다른 SWC 데코레이터가 붙었으면 에러 — 메서드 데코레이터는 TS 가 이미 막지만
+ * JS / `as any` 로 우회한 경우, 필드용 데코레이터(@attribute, @query, @property …)까지 잡는다.
+ */
+export const assertFetchFields = (constructor: any): void => {
+  const fields = (getFetchMetadata(constructor) ?? []).filter(m => m.field).map(m => m.propertyKey);
+  for (const key of fields) {
+    const d = findDescriptor(constructor.prototype, key);
+    if (!d?.value?.[FETCH_FIELD_FN] && !(d?.get as any)?.[FETCH_FIELD_FN]) {
+      throw new Error(`[SWC] "${String(key)}" is a @fetch field but another decorator replaced it. ${fieldHint(key)}`);
+    }
+    for (const mk of ReflectUtils.getMetadataKeys(constructor)) {
+      if (mk === FETCH_METADATA_KEY || typeof mk === 'string') continue; // design:* 등 TS 메타데이터는 제외
+      if (refersTo(ReflectUtils.getMetadata(mk, constructor), key)) {
+        const name = typeof mk === 'symbol' ? mk.description?.replace('simple-web-component:', '@') : String(mk);
+        throw new Error(`[SWC] "${String(key)}" is a @fetch field — it can't also have ${name}. ${fieldHint(key)}`);
+      }
+    }
+  }
+};
+
 /**
  * disconnect 시 진행 중인 @fetch 요청을 전부 abort (메서드/after 는 실행되지 않고 조용히 끝난다).
  * 떨어진 동안 새로 시작하는 호출도 건너뛰도록 표시하고, 다시 connect 되면 표시를 지운다.
  */
 export class FetchLifeCycler implements ElementDefineLifeCycler {
   onConnected(helperHostSet: HelperHostSet): void {
-    helperHostSet.$this.__swc_fetchDetached = false;
+    const inst = helperHostSet.$this;
+    inst.__swc_fetchDetached = false;
+    // declare 를 빠뜨리면 인스턴스 필드(undefined)가 프로토타입의 요청 함수를 가린다
+    for (const m of getFetchMetadata(inst) ?? []) {
+      if (m.field && Object.prototype.hasOwnProperty.call(inst, m.propertyKey)) {
+        throw new Error(`[SWC] @fetch field "${String(m.propertyKey)}" must be declared with \`declare\` (e.g. \`declare ${String(m.propertyKey)}: (…) => Promise<T>\`) — a plain field shadows the request function.`);
+      }
+    }
   }
 
   onDisconnected(helperHostSet: HelperHostSet): void {
     const inst = helperHostSet.$this;
     inst.__swc_fetchDetached = true;
+    valueCache.delete(inst); // 끊긴 요청은 끝나지 않으니, 다시 붙은 뒤 읽으면 새로 요청하도록 기억을 지운다
     const active: Set<AbortController> | undefined = inst.__swc_fetchControllers;
     if (!active?.size) return;
     for (const c of active) c.abort(abortError('element disconnected'));

package/src/decorators/index.ts

@@ -26,3 +26,4 @@ export * from './eventMedia';
 export * from './parameter';
 export * from './fetch';
 export * from './around';
+export * from './persistState';

package/src/decorators/intersectionObserver.ts

@@ -1,6 +1,6 @@
 import { ReflectUtils } from '@dooboostore/core';
 import { SpecialSelector, SwcQueryOptions, SwcFnSelector, SwcSelector, HelperHostSet } from '../types';
-import { buildSwcParameterArgs } from './parameter';
+import { buildSwcParameterArgs, buildCommonKindValues } from './parameter';
 
 // 공통 옵션 — IntersectionObserverInit + filter/removeObserver. root·delegate 제외.
 // 주의: 데코레이터의 root(light/shadow/all/auto) 는 셀렉터 스코프 선택용이다.
@@ -205,11 +205,10 @@ export class IntersectionObserverLifeCycler implements ElementDefineLifeCycler {
           void (async () => {
             const helper = SwcUtils.getHelperAndHostSet(inst);
             if (opts.filter && !(await opts.filter(matchedEls, { currentThis: inst, helper }))) return;
-            const hostSet = SwcUtils.getHostSet(inst);
-            const helperSet = SwcUtils.getHelperSet(helperHostSet.$w);
-            const legacyArgs = [matchedEls, entries, obs, { ...hostSet, $root: root }];
+            const common = buildCommonKindValues(inst, helperHostSet.$w);
+            const legacyArgs = [matchedEls, entries, obs, { ...common.hostSet, $root: root }];
             const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, m.propertyKey, {
-              hostSet, helperHostSet: helper, helperSet, intersectionObserverBeforeReturn: beforeReturn
+              ...common, intersectionObserverBeforeReturn: beforeReturn
             }, [...legacyArgs, beforeReturn]);
             let args = buildArgs(undefined);
             if (opts.before) { const br = await opts.before(matchedEls, { currentThis: inst, helper }); args = buildArgs(br); }

package/src/decorators/mutationObserver.ts

@@ -1,6 +1,6 @@
 import { ReflectUtils } from '@dooboostore/core';
 import { SpecialSelector, SwcQueryOptions, SwcSelector, SwcFnSelector, HelperHostSet } from '../types';
-import { buildSwcParameterArgs } from './parameter';
+import { buildSwcParameterArgs, buildCommonKindValues } from './parameter';
 
 // 공통 옵션 — root·delegate 없음 (MutationObserverInit + filter/removeObserver)
 export interface MutationObserverBaseOptions extends MutationObserverInit {
@@ -263,11 +263,10 @@ export class MutationObserverLifeCycler implements ElementDefineLifeCycler {
           void (async () => {
             const helper = SwcUtils.getHelperAndHostSet(inst);
             if (options.filter && !(await options.filter(matchedEls, { currentThis: inst, helper }))) return;
-            const hostSet = SwcUtils.getHostSet(inst);
-            const helperSet = SwcUtils.getHelperSet(helperHostSet.$w);
-            const legacyArgs = [matchedEls, records, obs, { ...hostSet, $root: root }];
+            const common = buildCommonKindValues(inst, helperHostSet.$w);
+            const legacyArgs = [matchedEls, records, obs, { ...common.hostSet, $root: root }];
             const buildArgs = (beforeReturn: any) => buildSwcParameterArgs(inst, meta.propertyKey, {
-              hostSet, helperHostSet: helper, helperSet, mutationObserverBeforeReturn: beforeReturn
+              ...common, mutationObserverBeforeReturn: beforeReturn
             }, [...legacyArgs, beforeReturn]);
             let args = buildArgs(undefined);
             if (options.before) { const br = await options.before(matchedEls, { currentThis: inst, helper }); args = buildArgs(br); }