@mandujs/core 0.9.2 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/client/index.ts

@@ -103,8 +103,9 @@ import { Link, NavLink } from "./Link";
 /**
  * Mandu Client namespace
  * v0.8.0: Hydration은 자동으로 처리됨 (generateRuntimeSource에서 생성)
+ * Note: Use `ManduClient` to avoid conflict with other Mandu exports
  */
-export const Mandu = {
+export const ManduClient = {
   /**
    * Create an island component
    * @see island

package/src/contract/client.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Mandu Contract Client Tests
+ *
+ * 클라이언트 타입 추론 및 기능 테스트
+ */
+
+import { describe, it, expect, mock } from "bun:test";
+import { z } from "zod";
+import { Mandu, createClient, contractFetch } from "./index";
+
+// === Test Contract ===
+const testContract = Mandu.contract({
+  description: "Test API",
+  tags: ["test"],
+  request: {
+    GET: {
+      query: z.object({
+        page: z.coerce.number().default(1),
+        search: z.string().optional(),
+      }),
+    },
+    POST: {
+      body: z.object({
+        name: z.string(),
+        email: z.string().email(),
+      }),
+    },
+    PUT: {
+      params: z.object({
+        id: z.string(),
+      }),
+      body: z.object({
+        name: z.string().optional(),
+      }),
+    },
+    DELETE: {
+      params: z.object({
+        id: z.string(),
+      }),
+    },
+  },
+  response: {
+    200: z.object({
+      data: z.array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+        })
+      ),
+      total: z.number(),
+    }),
+    201: z.object({
+      data: z.object({
+        id: z.string(),
+        name: z.string(),
+        email: z.string(),
+      }),
+    }),
+    204: z.undefined(),
+    404: z.object({
+      error: z.string(),
+    }),
+  },
+});
+
+describe("Contract Client", () => {
+  it("should create a client with all HTTP methods", () => {
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+    });
+
+    expect(client.GET).toBeDefined();
+    expect(client.POST).toBeDefined();
+    expect(client.PUT).toBeDefined();
+    expect(client.DELETE).toBeDefined();
+    expect(typeof client.GET).toBe("function");
+    expect(typeof client.POST).toBe("function");
+  });
+
+  it("should build query string correctly", async () => {
+    let capturedUrl = "";
+
+    const mockFetch = mock(async (url: string, _options: RequestInit) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    await client.GET({ query: { page: 2, search: "hello" } });
+
+    expect(capturedUrl).toContain("page=2");
+    expect(capturedUrl).toContain("search=hello");
+  });
+
+  it("should send JSON body for POST requests", async () => {
+    let capturedBody = "";
+    let capturedContentType = "";
+
+    const mockFetch = mock(async (_url: string, options: RequestInit) => {
+      capturedBody = options.body as string;
+      capturedContentType =
+        (options.headers as Record<string, string>)["Content-Type"] || "";
+      return new Response(
+        JSON.stringify({
+          data: { id: "1", name: "Test", email: "test@example.com" },
+        }),
+        {
+          status: 201,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    });
+
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    await client.POST({ body: { name: "Test", email: "test@example.com" } });
+
+    expect(capturedContentType).toBe("application/json");
+    expect(JSON.parse(capturedBody)).toEqual({
+      name: "Test",
+      email: "test@example.com",
+    });
+  });
+
+  it("should parse JSON response", async () => {
+    const mockData = {
+      data: [
+        { id: "1", name: "User 1" },
+        { id: "2", name: "User 2" },
+      ],
+      total: 2,
+    };
+
+    const mockFetch = mock(async () => {
+      return new Response(JSON.stringify(mockData), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    const result = await client.GET({ query: { page: 1 } });
+
+    expect(result.status).toBe(200);
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual(mockData);
+  });
+
+  it("should include default headers", async () => {
+    let capturedHeaders: Record<string, string> = {};
+
+    const mockFetch = mock(async (_url: string, options: RequestInit) => {
+      capturedHeaders = options.headers as Record<string, string>;
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      headers: {
+        Authorization: "Bearer token123",
+        "X-Custom-Header": "custom-value",
+      },
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    await client.GET();
+
+    expect(capturedHeaders["Authorization"]).toBe("Bearer token123");
+    expect(capturedHeaders["X-Custom-Header"]).toBe("custom-value");
+  });
+
+  it("should allow per-request headers", async () => {
+    let capturedHeaders: Record<string, string> = {};
+
+    const mockFetch = mock(async (_url: string, options: RequestInit) => {
+      capturedHeaders = options.headers as Record<string, string>;
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      headers: { "X-Default": "default" },
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    await client.GET({
+      headers: { "X-Custom": "per-request" },
+    });
+
+    expect(capturedHeaders["X-Default"]).toBe("default");
+    expect(capturedHeaders["X-Custom"]).toBe("per-request");
+  });
+});
+
+describe("contractFetch", () => {
+  it("should make type-safe fetch call", async () => {
+    const mockFetch = mock(async () => {
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const result = await contractFetch(
+      testContract,
+      "GET",
+      "http://localhost:3000/api/test",
+      { query: { page: 1 } },
+      { fetch: mockFetch as unknown as typeof fetch }
+    );
+
+    expect(result.status).toBe(200);
+    expect(result.ok).toBe(true);
+    expect(mockFetch).toHaveBeenCalled();
+  });
+
+  it("should handle path parameters", async () => {
+    let capturedUrl = "";
+
+    const mockFetch = mock(async (url: string) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    await contractFetch(
+      testContract,
+      "PUT",
+      "http://localhost:3000/api/test/:id",
+      { params: { id: "123" }, body: { name: "Updated" } },
+      { fetch: mockFetch as unknown as typeof fetch }
+    );
+
+    expect(capturedUrl).toBe("http://localhost:3000/api/test/123");
+  });
+});
+
+describe("Mandu.client", () => {
+  it("should be accessible via Mandu namespace", () => {
+    expect(Mandu.client).toBe(createClient);
+  });
+
+  it("should work via Mandu namespace", async () => {
+    const mockFetch = mock(async () => {
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = Mandu.client(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    const result = await client.GET({ query: { page: 1 } });
+
+    expect(result.status).toBe(200);
+    expect(result.data).toEqual({ data: [], total: 0 });
+  });
+});
+
+describe("Mandu.fetch", () => {
+  it("should be accessible via Mandu namespace", () => {
+    expect(Mandu.fetch).toBe(contractFetch);
+  });
+});
+
+describe("Type Safety (Compile-time)", () => {
+  it("should enforce query types", () => {
+    // This test verifies that the type system is working
+    // If the types are wrong, this won't compile
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+    });
+
+    // These are valid calls (would compile)
+    const _validGet = () => client.GET({ query: { page: 1 } });
+    const _validPost = () =>
+      client.POST({ body: { name: "Test", email: "test@example.com" } });
+
+    // Type-level assertions
+    expect(typeof client.GET).toBe("function");
+    expect(typeof client.POST).toBe("function");
+  });
+});

package/src/contract/client.ts

@@ -0,0 +1,345 @@
+/**
+ * Mandu Contract Client
+ * Contract 기반 타입 안전 클라이언트
+ *
+ * tRPC/Elysia Eden 패턴 채택:
+ * - Contract에서 클라이언트 타입 자동 추론
+ * - 타입 안전 fetch 호출
+ */
+
+import type { z } from "zod";
+import type {
+  ContractSchema,
+  ContractMethod,
+  MethodRequestSchema,
+} from "./schema";
+
+/**
+ * Client options for making requests
+ */
+export interface ClientOptions {
+  /** Base URL for API requests */
+  baseUrl: string;
+  /** Default headers for all requests */
+  headers?: Record<string, string>;
+  /** Custom fetch function (for SSR or testing) */
+  fetch?: typeof fetch;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+}
+
+/**
+ * Request options for a specific call
+ */
+export interface RequestOptions<
+  TQuery = unknown,
+  TBody = unknown,
+  TParams = unknown,
+  THeaders = Record<string, string>,
+> {
+  query?: TQuery;
+  body?: TBody;
+  params?: TParams;
+  headers?: THeaders;
+  signal?: AbortSignal;
+}
+
+/**
+ * Client response wrapper
+ */
+export interface ClientResponse<T> {
+  data: T;
+  status: number;
+  headers: Headers;
+  ok: boolean;
+}
+
+/**
+ * Infer request options from method schema
+ */
+type InferRequestOptions<T extends MethodRequestSchema | undefined> =
+  T extends MethodRequestSchema
+    ? RequestOptions<
+        T["query"] extends z.ZodTypeAny ? z.input<T["query"]> : undefined,
+        T["body"] extends z.ZodTypeAny ? z.input<T["body"]> : undefined,
+        T["params"] extends z.ZodTypeAny ? z.input<T["params"]> : undefined,
+        T["headers"] extends z.ZodTypeAny
+          ? z.input<T["headers"]>
+          : Record<string, string>
+      >
+    : RequestOptions<undefined, undefined, undefined, Record<string, string>>;
+
+/**
+ * Infer success response from contract
+ */
+type InferSuccessResponse<TResponse extends ContractSchema["response"]> =
+  TResponse[200] extends z.ZodTypeAny
+    ? z.infer<TResponse[200]>
+    : TResponse[201] extends z.ZodTypeAny
+      ? z.infer<TResponse[201]>
+      : unknown;
+
+/**
+ * Contract client method
+ */
+export type ContractClientMethod<
+  T extends MethodRequestSchema | undefined,
+  TResponse extends ContractSchema["response"],
+> = (
+  options?: InferRequestOptions<T>
+) => Promise<ClientResponse<InferSuccessResponse<TResponse>>>;
+
+/**
+ * Contract client interface
+ */
+export type ContractClient<T extends ContractSchema> = {
+  [M in Extract<keyof T["request"], ContractMethod>]: ContractClientMethod<
+    T["request"][M] extends MethodRequestSchema ? T["request"][M] : undefined,
+    T["response"]
+  >;
+};
+
+/**
+ * Build query string from object
+ */
+function buildQueryString(query: Record<string, unknown> | undefined): string {
+  if (!query) return "";
+
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null) {
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          params.append(key, String(v));
+        }
+      } else {
+        params.append(key, String(value));
+      }
+    }
+  }
+
+  const str = params.toString();
+  return str ? `?${str}` : "";
+}
+
+/**
+ * Replace path parameters in URL
+ */
+function replacePathParams(
+  path: string,
+  params: Record<string, unknown> | undefined
+): string {
+  if (!params) return path;
+
+  let result = path;
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replace(`:${key}`, encodeURIComponent(String(value)));
+    result = result.replace(`[${key}]`, encodeURIComponent(String(value)));
+  }
+  return result;
+}
+
+/**
+ * Create a type-safe client from a contract
+ *
+ * @example
+ * ```typescript
+ * const userContract = Mandu.contract({
+ *   request: {
+ *     GET: { query: z.object({ page: z.number() }) },
+ *     POST: { body: z.object({ name: z.string() }) },
+ *   },
+ *   response: {
+ *     200: z.object({ users: z.array(UserSchema) }),
+ *     201: z.object({ user: UserSchema }),
+ *   },
+ * });
+ *
+ * const client = createClient(userContract, {
+ *   baseUrl: "http://localhost:3000/api/users",
+ * });
+ *
+ * // Type-safe calls
+ * const users = await client.GET({ query: { page: 1 } });
+ * // users.data is typed as { users: User[] }
+ *
+ * const newUser = await client.POST({ body: { name: "Alice" } });
+ * // newUser.data is typed as { user: User }
+ * ```
+ */
+export function createClient<T extends ContractSchema>(
+  _contract: T,
+  options: ClientOptions
+): ContractClient<T> {
+  const {
+    baseUrl,
+    headers: defaultHeaders = {},
+    fetch: customFetch = fetch,
+    timeout = 30000,
+  } = options;
+
+  const methods: ContractMethod[] = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+  const client = {} as ContractClient<T>;
+
+  for (const method of methods) {
+    // @ts-expect-error - Dynamic method assignment
+    client[method] = async (
+      requestOptions: RequestOptions = {}
+    ): Promise<ClientResponse<unknown>> => {
+      const { query, body, params, headers = {}, signal } = requestOptions;
+
+      // Build URL
+      let url = replacePathParams(baseUrl, params as Record<string, unknown>);
+      url += buildQueryString(query as Record<string, unknown>);
+
+      // Build request options
+      const fetchOptions: RequestInit = {
+        method,
+        headers: {
+          ...defaultHeaders,
+          ...headers,
+        },
+        signal,
+      };
+
+      // Add body for non-GET methods
+      if (body && method !== "GET") {
+        fetchOptions.headers = {
+          ...fetchOptions.headers,
+          "Content-Type": "application/json",
+        };
+        fetchOptions.body = JSON.stringify(body);
+      }
+
+      // Add timeout
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      if (!signal) {
+        fetchOptions.signal = controller.signal;
+      }
+
+      try {
+        const response = await customFetch(url, fetchOptions);
+        clearTimeout(timeoutId);
+
+        let data: unknown;
+        const contentType = response.headers.get("content-type") || "";
+
+        if (contentType.includes("application/json")) {
+          data = await response.json();
+        } else {
+          data = await response.text();
+        }
+
+        return {
+          data,
+          status: response.status,
+          headers: response.headers,
+          ok: response.ok,
+        };
+      } catch (error) {
+        clearTimeout(timeoutId);
+        throw error;
+      }
+    };
+  }
+
+  return client;
+}
+
+/**
+ * Type-safe fetch wrapper for a single endpoint
+ *
+ * @example
+ * ```typescript
+ * const result = await contractFetch(userContract, "GET", "/api/users", {
+ *   query: { page: 1, limit: 10 },
+ * });
+ * // result.data is typed based on contract response
+ * ```
+ */
+export async function contractFetch<
+  T extends ContractSchema,
+  M extends Extract<keyof T["request"], ContractMethod>,
+>(
+  _contract: T,
+  method: M,
+  url: string,
+  options: InferRequestOptions<
+    T["request"][M] extends MethodRequestSchema ? T["request"][M] : undefined
+  > = {} as InferRequestOptions<
+    T["request"][M] extends MethodRequestSchema ? T["request"][M] : undefined
+  >,
+  clientOptions: Partial<ClientOptions> = {}
+): Promise<ClientResponse<InferSuccessResponse<T["response"]>>> {
+  const {
+    query,
+    body,
+    params,
+    headers = {},
+    signal,
+  } = options as RequestOptions;
+
+  const {
+    headers: defaultHeaders = {},
+    fetch: customFetch = fetch,
+    timeout = 30000,
+  } = clientOptions;
+
+  // Build URL
+  let finalUrl = replacePathParams(url, params as Record<string, unknown>);
+  finalUrl += buildQueryString(query as Record<string, unknown>);
+
+  // Build request options
+  const fetchOptions: RequestInit = {
+    method,
+    headers: {
+      ...defaultHeaders,
+      ...(headers as Record<string, string>),
+    },
+    signal,
+  };
+
+  // Add body for non-GET methods
+  if (body && method !== "GET") {
+    fetchOptions.headers = {
+      ...fetchOptions.headers,
+      "Content-Type": "application/json",
+    };
+    fetchOptions.body = JSON.stringify(body);
+  }
+
+  // Add timeout
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  if (!signal) {
+    fetchOptions.signal = controller.signal;
+  }
+
+  try {
+    const response = await customFetch(finalUrl, fetchOptions);
+    clearTimeout(timeoutId);
+
+    let data: unknown;
+    const contentType = response.headers.get("content-type") || "";
+
+    if (contentType.includes("application/json")) {
+      data = await response.json();
+    } else {
+      data = await response.text();
+    }
+
+    return {
+      data: data as InferSuccessResponse<T["response"]>,
+      status: response.status,
+      headers: response.headers,
+      ok: response.ok,
+    };
+  } catch (error) {
+    clearTimeout(timeoutId);
+    throw error;
+  }
+}