@mandujs/core 0.9.1 → 0.9.3

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;
+  }
+}

package/src/contract/handler.ts

@@ -0,0 +1,270 @@
+/**
+ * Mandu Contract Handler
+ * Contract 기반 타입 안전 핸들러 정의
+ *
+ * Elysia 패턴 채택: Contract → Handler 타입 자동 추론
+ */
+
+import type { z } from "zod";
+import type {
+  ContractSchema,
+  ContractMethod,
+  MethodRequestSchema,
+} from "./schema";
+
+/**
+ * Typed request context for a handler
+ * Contract에서 추론된 타입으로 요청 컨텍스트 제공
+ */
+export interface TypedContext<
+  TQuery = unknown,
+  TBody = unknown,
+  TParams = unknown,
+  THeaders = unknown,
+> {
+  /** Parsed and validated query parameters */
+  query: TQuery;
+  /** Parsed and validated request body */
+  body: TBody;
+  /** Parsed and validated path parameters */
+  params: TParams;
+  /** Parsed and validated headers */
+  headers: THeaders;
+  /** Original Request object */
+  request: Request;
+  /** Route path (e.g., "/users/:id") */
+  path: string;
+  /** HTTP method */
+  method: ContractMethod;
+}
+
+/**
+ * Infer context type from method schema
+ */
+type InferContextFromMethod<T extends MethodRequestSchema | undefined> =
+  T extends MethodRequestSchema
+    ? TypedContext<
+        T["query"] extends z.ZodTypeAny ? z.infer<T["query"]> : undefined,
+        T["body"] extends z.ZodTypeAny ? z.infer<T["body"]> : undefined,
+        T["params"] extends z.ZodTypeAny ? z.infer<T["params"]> : undefined,
+        T["headers"] extends z.ZodTypeAny ? z.infer<T["headers"]> : undefined
+      >
+    : TypedContext<undefined, undefined, undefined, undefined>;
+
+/**
+ * Handler function type for a specific method
+ */
+export type HandlerFn<TContext, TResponse> = (
+  ctx: TContext
+) => TResponse | Promise<TResponse>;
+
+/**
+ * Infer response type union from contract response schema
+ */
+type InferResponseUnion<TResponse extends ContractSchema["response"]> = {
+  [K in keyof TResponse]: TResponse[K] extends z.ZodTypeAny
+    ? z.infer<TResponse[K]>
+    : never;
+}[keyof TResponse];
+
+/**
+ * Handler definition for all methods in a contract
+ *
+ * @example
+ * ```typescript
+ * const contract = Mandu.contract({
+ *   request: {
+ *     GET: { query: z.object({ page: z.number() }) },
+ *     POST: { body: z.object({ name: z.string() }) },
+ *   },
+ *   response: {
+ *     200: z.object({ users: z.array(z.string()) }),
+ *     201: z.object({ user: z.string() }),
+ *   },
+ * });
+ *
+ * // handlers is typed: { GET: (ctx) => ..., POST: (ctx) => ... }
+ * const handlers = Mandu.handler(contract, {
+ *   GET: (ctx) => {
+ *     // ctx.query is { page: number }
+ *     return { users: [] };
+ *   },
+ *   POST: (ctx) => {
+ *     // ctx.body is { name: string }
+ *     return { user: ctx.body.name };
+ *   },
+ * });
+ * ```
+ */
+export type ContractHandlers<T extends ContractSchema> = {
+  [M in Extract<keyof T["request"], ContractMethod>]?: HandlerFn<
+    InferContextFromMethod<
+      T["request"][M] extends MethodRequestSchema ? T["request"][M] : undefined
+    >,
+    InferResponseUnion<T["response"]>
+  >;
+};
+
+/**
+ * Define type-safe handlers for a contract
+ *
+ * @param contract - The contract schema
+ * @param handlers - Handler implementations for each method
+ * @returns Typed handler object
+ *
+ * @example
+ * ```typescript
+ * const handlers = defineHandler(userContract, {
+ *   GET: async (ctx) => {
+ *     const { page, limit } = ctx.query; // Typed!
+ *     const users = await db.users.findMany({ skip: page * limit, take: limit });
+ *     return { data: users };
+ *   },
+ *   POST: async (ctx) => {
+ *     const user = await db.users.create({ data: ctx.body }); // Typed!
+ *     return { data: user };
+ *   },
+ * });
+ * ```
+ */
+export function defineHandler<T extends ContractSchema>(
+  _contract: T,
+  handlers: ContractHandlers<T>
+): ContractHandlers<T> {
+  return handlers;
+}
+
+/**
+ * Handler result with status code
+ * 응답에 상태 코드를 명시적으로 지정
+ */
+export interface HandlerResult<T = unknown> {
+  status: number;
+  data: T;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Create a typed response with status code
+ *
+ * @example
+ * ```typescript
+ * const handler = defineHandler(contract, {
+ *   POST: async (ctx) => {
+ *     const user = await createUser(ctx.body);
+ *     return response(201, { data: user });
+ *   },
+ * });
+ * ```
+ */
+export function response<T>(
+  status: number,
+  data: T,
+  headers?: Record<string, string>
+): HandlerResult<T> {
+  return { status, data, headers };
+}
+
+/**
+ * Type guard for HandlerResult
+ */
+export function isHandlerResult(value: unknown): value is HandlerResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "status" in value &&
+    "data" in value
+  );
+}
+
+/**
+ * Extract method-specific handler type from contract
+ *
+ * @example
+ * ```typescript
+ * type GetHandler = ExtractHandler<typeof userContract, "GET">;
+ * // (ctx: { query: { page: number }, ... }) => Promise<{ data: User[] }>
+ * ```
+ */
+export type ExtractHandler<
+  T extends ContractSchema,
+  M extends ContractMethod,
+> = M extends keyof T["request"]
+  ? HandlerFn<
+      InferContextFromMethod<
+        T["request"][M] extends MethodRequestSchema
+          ? T["request"][M]
+          : undefined
+      >,
+      InferResponseUnion<T["response"]>
+    >
+  : never;
+
+/**
+ * Utility to create a handler context from raw request
+ * 런타임에서 Request → TypedContext 변환
+ */
+export async function createContext<
+  TQuery = unknown,
+  TBody = unknown,
+  TParams = unknown,
+  THeaders = unknown,
+>(
+  request: Request,
+  path: string,
+  method: ContractMethod,
+  parsedData: {
+    query?: TQuery;
+    body?: TBody;
+    params?: TParams;
+    headers?: THeaders;
+  } = {}
+): Promise<TypedContext<TQuery, TBody, TParams, THeaders>> {
+  return {
+    query: parsedData.query as TQuery,
+    body: parsedData.body as TBody,
+    params: parsedData.params as TParams,
+    headers: parsedData.headers as THeaders,
+    request,
+    path,
+    method,
+  };
+}
+
+/**
+ * Combined contract + handler definition
+ * Contract와 Handler를 한 번에 정의
+ *
+ * @example
+ * ```typescript
+ * export default Mandu.route({
+ *   contract: {
+ *     request: {
+ *       GET: { query: z.object({ id: z.string() }) },
+ *     },
+ *     response: {
+ *       200: z.object({ user: UserSchema }),
+ *     },
+ *   },
+ *   handler: {
+ *     GET: async (ctx) => {
+ *       const user = await db.users.findUnique({ where: { id: ctx.query.id } });
+ *       return { user };
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export interface RouteDefinition<T extends ContractSchema> {
+  contract: T;
+  handler: ContractHandlers<T>;
+}
+
+/**
+ * Define a complete route with contract and handler
+ */
+export function defineRoute<T extends ContractSchema>(
+  definition: RouteDefinition<T>
+): RouteDefinition<T> {
+  return definition;
+}