@gaonjs/vue 0.1.4 → 0.2.0

package/dist/api.d.ts

@@ -0,0 +1,52 @@
+import type { Serialized } from './serialize.js';
+/**
+ * 라우트 매니페스트 — .gaon/routes.d.ts 가 채우는 GaonRouteMap 옆에 함께
+ * 채워지는 런타임/타입 지도. 키는 'controller#action'.
+ *
+ * pageProps 는 타입만 알면 되지만 api() 는 실제 HTTP 메서드·경로를 알아야
+ * 요청을 보낼 수 있다 — 그래서 라우트 지도가 필요하다. 생성기가 declaration
+ * merging + 값 export 로 함께 채운다(추가 생성 파일 X · 기존 파일에 병합).
+ */
+export interface GaonRouteInfo {
+    readonly method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    readonly path: string;
+}
+declare global {
+    interface GaonRoutes {
+    }
+}
+/** GaonRouteMap[K] (액션 함수) 에서 render 결과 P 를 뽑아 낸다 — pageProps 와 동일. */
+type PropsOf<F> = F extends (...args: never[]) => infer R ? Awaited<R> extends {
+    page: string;
+    props: infer P;
+} ? P : Awaited<R> : never;
+/**
+ * 요청 파라미터 — 라우트에 :id 같은 자리표시자가 있으면 여기서 뽑고, 나머지는
+ * GET 이면 쿼리스트링, 그 외 메서드는 JSON 본문으로 붙는다. 값은 문자열
+ * 화된다(경로/쿼리 특성).
+ */
+export type ApiParams = Record<string, string | number | bigint | boolean | undefined | null>;
+export interface ApiOptions {
+    /** 기본 http 헤더에 얹어 보낸다(Authorization 등). */
+    readonly headers?: Record<string, string>;
+    /** AbortController 지원(취소·타임아웃). */
+    readonly signal?: AbortSignal;
+    /** URL prefix (앱 프리픽스가 web 이 아니면 지정). 생략 시 window.origin. */
+    readonly baseUrl?: string;
+    /** fetch 구현 주입(테스트·SSR). 생략 시 globalThis.fetch. */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * 라우트 키로 서버 액션을 부른다.
+ *  · 반환 타입: 액션 반환의 Serialized<> (직렬화 경계 재사용).
+ *  · 요청: 메서드는 라우트 정의에서, 경로는 :param 을 채워 완성.
+ *  · 실패: 4xx/5xx 는 예외로 던지고, ValidationError(422)는 issues 를 포함한다.
+ */
+export declare function api<K extends keyof GaonRouteMap>(key: K, params?: ApiParams, opts?: ApiOptions): Promise<Serialized<PropsOf<GaonRouteMap[K]>>>;
+/**
+ * 라우트 매니페스트를 등록한다 — 프론트엔드 부트스트랩(app 엔트리)이 한 번
+ * 호출하면 이후 api() 가 method·path 를 안다. 앱 빌드 시 .gaon/routes.d.ts
+ * 와 함께 생성되는 매니페스트 모듈이 이 함수를 호출한다.
+ */
+export declare function registerRoutes(routes: Record<string, GaonRouteInfo>): void;
+export {};

package/dist/api.js

@@ -0,0 +1,127 @@
+// @gaonjs/vue · api() — 타입드 클라이언트 (errata E-3 §C)
+//
+// pageProps 와 **같은 .gaon/routes.d.ts 브리지**를 재사용한다 — 추가 생성 파일
+// 없음. 라우트 키 하나로 서버 액션의 반환 타입을 클라이언트에서 그대로 안다.
+//
+//   import { api } from 'gaonjs/vue'
+//   const { results } = await api('posts#search', { q: keyword.value })
+//
+// 반환 타입은 액션 반환 타입의 **Serialized<>** (M4 render props 직렬화와 같은
+// 규칙 · 같은 매핑 재사용). 별도 직렬화 규칙을 두지 않는다(The One Way).
+//
+// 두 번째 인자는 라우트 파라미터 + 쿼리(HTTP 메서드는 라우트 정의에서 결정).
+// 라우트에 `:id` 처럼 자리표시자가 있으면 params 에서 뽑아 경로에 채우고,
+// 남는 값은 GET 은 쿼리스트링으로, POST/PUT/PATCH/DELETE 는 JSON 본문으로 실어
+// 보낸다. 서버 쪽 this.params 병합 우선순위(라우트>body>query)와 일치한다.
+// ── 런타임 ────────────────────────────────────────────────────
+/**
+ * 라우트 키로 서버 액션을 부른다.
+ *  · 반환 타입: 액션 반환의 Serialized<> (직렬화 경계 재사용).
+ *  · 요청: 메서드는 라우트 정의에서, 경로는 :param 을 채워 완성.
+ *  · 실패: 4xx/5xx 는 예외로 던지고, ValidationError(422)는 issues 를 포함한다.
+ */
+export async function api(key, params = {}, opts = {}) {
+    const routes = (globalThis.__GAON_ROUTES__) ??
+        {};
+    const info = routes[key];
+    if (!info) {
+        throw new Error(`[gaonjs/vue] 라우트 '${String(key)}' 를 찾을 수 없습니다.\n` +
+            `→ apps/<app>/routes.ts 에 정의돼 있는지, gaon dev/check 가 .gaon/routes.d.ts 를 재생성했는지 확인하세요.`);
+    }
+    const { url, leftovers } = buildUrl(info, params);
+    const method = info.method.toUpperCase();
+    const useBody = method !== 'GET' && method !== 'HEAD';
+    const headers = {
+        Accept: 'application/json',
+        ...(opts.headers ?? {}),
+    };
+    let body;
+    let finalUrl = url;
+    if (useBody) {
+        body = JSON.stringify(leftovers);
+        headers['Content-Type'] = 'application/json; charset=utf-8';
+        // CSRF: 세션 앱은 쿠키 기반 CSRF 를 쓴다 — 프론트 부트스트랩이 심어 놓은
+        // 메타 태그 값을 자동으로 붙여 준다(있으면).
+        const csrf = readCsrfToken();
+        if (csrf)
+            headers['X-CSRF-Token'] = csrf;
+    }
+    else if (Object.keys(leftovers).length > 0) {
+        const q = new URLSearchParams();
+        for (const [k, v] of Object.entries(leftovers)) {
+            if (v === undefined || v === null)
+                continue;
+            q.append(k, String(v));
+        }
+        finalUrl = url + (url.includes('?') ? '&' : '?') + q.toString();
+    }
+    const base = opts.baseUrl ?? '';
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    const res = await doFetch(base + finalUrl, {
+        method,
+        headers,
+        body,
+        signal: opts.signal,
+        credentials: 'same-origin',
+    });
+    if (!res.ok) {
+        // 422 는 서버 검증 실패(§7.5.3). 파싱 시도 후 issues 를 실어 재던진다.
+        let payload = undefined;
+        try {
+            payload = await res.json();
+        }
+        catch {
+            /* 본문 없음 */
+        }
+        const err = new Error(`[gaonjs/vue] ${String(key)} 요청 실패 (${res.status} ${res.statusText}).`);
+        err.status = res.status;
+        err.body = payload;
+        throw err;
+    }
+    // 204 No Content 는 빈 값으로.
+    if (res.status === 204)
+        return undefined;
+    const json = (await res.json());
+    return json;
+}
+/**
+ * 라우트 매니페스트를 등록한다 — 프론트엔드 부트스트랩(app 엔트리)이 한 번
+ * 호출하면 이후 api() 가 method·path 를 안다. 앱 빌드 시 .gaon/routes.d.ts
+ * 와 함께 생성되는 매니페스트 모듈이 이 함수를 호출한다.
+ */
+export function registerRoutes(routes) {
+    const g = globalThis;
+    g.__GAON_ROUTES__ = { ...(g.__GAON_ROUTES__ ?? {}), ...routes };
+}
+// ── 내부 ──────────────────────────────────────────────────────
+function buildUrl(info, params) {
+    const leftovers = {};
+    let url = info.path;
+    // 사용된 자리표시자는 leftovers 에서 빼고, 남는 값은 쿼리/본문에 실린다.
+    const used = new Set();
+    url = url.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, name) => {
+        used.add(name);
+        const v = params[name];
+        if (v === undefined || v === null) {
+            throw new Error(`[gaonjs/vue] 라우트 파라미터 ':${name}' 값이 없습니다 (path=${info.path}).\n` +
+                `→ api('${info.method} ${info.path}', { ${name}: ... }) 처럼 넘기세요.`);
+        }
+        return encodeURIComponent(String(v));
+    });
+    for (const [k, v] of Object.entries(params)) {
+        if (used.has(k) || v === undefined || v === null)
+            continue;
+        leftovers[k] = String(v);
+    }
+    return { url, leftovers };
+}
+function readCsrfToken() {
+    const doc = globalThis.document;
+    if (!doc)
+        return undefined;
+    const el = doc.querySelector('meta[name="csrf-token"]');
+    if (!el)
+        return undefined;
+    const c = el.getAttribute('content');
+    return c ?? undefined;
+}

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export declare const version: string;
 export declare const status: "planned";
 export { pageProps } from "./pageProps.js";
 export { serializeProps, type Serialized } from "./serialize.js";
+export { api, registerRoutes, type ApiParams, type ApiOptions, type GaonRouteInfo, } from "./api.js";

package/dist/index.js

@@ -12,3 +12,5 @@ export const status = "planned";
 export { pageProps } from "./pageProps.js";
 // 직렬화 경계 (M4) — Rec → JSON-safe 페이지 props (Date/bigint→string, hidden 제외)
 export { serializeProps } from "./serialize.js";
+// 타입드 클라이언트 (errata E-3) — 라우트 키 → Serialized 반환
+export { api, registerRoutes, } from "./api.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/vue",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Gaon 프론트엔드 어댑터: Vue 3 · Inertia 브리지 · 타입 전파 · SSR (구현 예정)",
   "type": "module",
   "license": "MIT",
@@ -24,8 +24,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@gaonjs/core": "0.1.3",
-    "@gaonjs/web": "0.2.0"
+    "@gaonjs/core": "0.1.4",
+    "@gaonjs/web": "0.3.0"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"