@gaonjs/vue 0.1.3 → 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

@@ -1,3 +1,5 @@
 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

@@ -10,3 +10,7 @@ export const version = VERSION;
 export const status = "planned";
 // 타입 브리지 (M3) — GaonRouteMap[K] → 페이지 props 타입
 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/dist/pageProps.d.ts

@@ -1,4 +1,5 @@
 import type { Rendered } from '@gaonjs/web';
+import type { Serialized } from './serialize.js';
 declare global {
     interface GaonRouteMap {
     }
@@ -7,7 +8,8 @@ type PropsOf<F> = F extends (...args: never[]) => infer R ? Awaited<R> extends R
 /**
  * 페이지의 props 타입을 라우트 이름으로 가져온다.
  * `const { posts } = pageProps<'posts#index'>()`
- * 런타임 값은 Inertia 가 주입한 실제 페이지 props 로 대체된다(M4 브리지).
+ * 런타임 값은 Inertia 가 주입한 실제 페이지 props 로 대체된다(M4 브리지 —
+ * serializeProps 를 통과한 JSON-safe 값).
  */
-export declare function pageProps<K extends keyof GaonRouteMap>(): PropsOf<GaonRouteMap[K]>;
+export declare function pageProps<K extends keyof GaonRouteMap>(): Serialized<PropsOf<GaonRouteMap[K]>>;
 export {};

package/dist/pageProps.js

@@ -8,12 +8,15 @@
 // 체인의 마지막 고리다. 스키마에서 컬럼을 지우면 .vue 템플릿의 사용
 // 지점에서 vue-tsc 가 에러를 낸다(완료 기준).
 //
-// M3 는 raw props(P)를 그대로 돌려준다. 깊은 직렬화(Rec→SerializedOf,
-// hidden 제외)는 M4 다 — 그때 반환 타입을 SerializedOf<P> 로 승격한다.
+// 반환 타입은 깊은 직렬화 경계 Serialized<P> 로 승격된다(M4). 컨트롤러가
+// 넘긴 raw props(Date·bigint·모델 메서드·hidden 포함)가 아니라, 페이지가
+// 실제로 받는 JSON-safe 모양이다 — Date/bigint 는 문자열, hidden 컬럼은
+// 존재하지 않으므로 접근 시 컴파일 에러가 난다(§4.2 완료 기준).
 /**
  * 페이지의 props 타입을 라우트 이름으로 가져온다.
  * `const { posts } = pageProps<'posts#index'>()`
- * 런타임 값은 Inertia 가 주입한 실제 페이지 props 로 대체된다(M4 브리지).
+ * 런타임 값은 Inertia 가 주입한 실제 페이지 props 로 대체된다(M4 브리지 —
+ * serializeProps 를 통과한 JSON-safe 값).
  */
 export function pageProps() {
     return undefined;

package/dist/serialize.d.ts

@@ -0,0 +1,17 @@
+import type { IsHidden } from '@gaonjs/core';
+/**
+ * 서버 타입 `T`(Date·bigint·메서드·hidden 포함) → 페이지가 받는 JSON-safe 타입.
+ *
+ * 규칙: Date→string, bigint→string, 함수→제외, 배열·객체는 재귀.
+ * 객체에서 hidden 브랜드가 붙은 키와 함수 값 키는 결과에서 빠진다.
+ */
+export type Serialized<T> = T extends Date ? string : T extends bigint ? string : T extends (...args: never[]) => unknown ? never : T extends ReadonlyArray<infer U> ? Array<Serialized<U>> : T extends object ? SerializedObject<T> : T;
+type SerializedObject<T> = {
+    [K in keyof T as IsHidden<T[K]> extends true ? never : T[K] extends (...args: never[]) => unknown ? never : K]: Serialized<T[K]>;
+};
+/**
+ * 컨트롤러 props 를 JSON-safe 페이지 props 로 변환한다(Inertia 브리지).
+ * Date→ISO 문자열, bigint→문자열, 함수 제거, hidden 컬럼 제외, 중첩 재귀.
+ */
+export declare function serializeProps<T>(value: T): Serialized<T>;
+export {};

package/dist/serialize.js

@@ -0,0 +1,51 @@
+// @gaonjs/vue · 직렬화 경계 (M4 — Rec → Serialized 깊은 매핑 + 런타임)
+//
+// 서버의 레코드는 그대로 JSON 이 아니다(§4.4). 모델 메서드·관계 함수가
+// 붙어 있고, Date·bigint 는 JSON 위에서 문자열이 되며(bigint 는 애초에
+// JSON.stringify 가 던진다), hidden 컬럼은 노출되면 안 된다(§4.2).
+//
+// 이 경계에서 두 가지가 맞물린다:
+//  · 타입: Serialized<P> 가 페이지가 실제로 받는 JSON-safe 모양을 계산한다
+//    (Date/bigint → string, 함수·hidden 제외, 중첩·배열 재귀). pageProps<K>()
+//    의 반환 타입을 이 매핑으로 승격한다.
+//  · 런타임: serializeProps() 가 컨트롤러 props 를 같은 규칙으로 변환한다.
+//    Inertia 브리지가 페이지에 넘기기 직전 이 함수를 통과시킨다.
+//
+// hidden 지식의 출처는 @gaonjs/data 다(RowOf 브랜딩 + 레코드의 HIDDEN_COLUMNS
+// 마커). 여기서는 그 브랜드/마커를 감지해 떨구기만 한다 — 책임 분리(§13.5 M4).
+import { HIDDEN_COLUMNS } from '@gaonjs/core';
+// ── 런타임 ────────────────────────────────────────────────────
+/**
+ * 컨트롤러 props 를 JSON-safe 페이지 props 로 변환한다(Inertia 브리지).
+ * Date→ISO 문자열, bigint→문자열, 함수 제거, hidden 컬럼 제외, 중첩 재귀.
+ */
+export function serializeProps(value) {
+    return serialize(value);
+}
+function serialize(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(serialize);
+    if (typeof value === 'object') {
+        // 모델 레코드는 HIDDEN_COLUMNS 마커(비열거)로 제외할 컬럼명을 싣는다.
+        const hidden = value[HIDDEN_COLUMNS];
+        const out = {};
+        for (const key of Object.keys(value)) {
+            if (hidden && hidden.includes(key))
+                continue;
+            const v = value[key];
+            if (typeof v === 'function')
+                continue; // 메서드·관계 함수는 직렬화하지 않는다
+            out[key] = serialize(v);
+        }
+        return out;
+    }
+    if (typeof value === 'function')
+        return undefined;
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/vue",
-  "version": "0.1.3",
+  "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.2",
-    "@gaonjs/web": "0.1.3"
+    "@gaonjs/core": "0.1.4",
+    "@gaonjs/web": "0.3.0"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"