@mandujs/core 0.9.1 → 0.9.3

package/src/contract/index.ts

@@ -1,13 +1,23 @@
 /**
  * Mandu Contract Module
  * Contract-first API 정의 시스템
+ *
+ * Elysia DNA 패턴 채택:
+ * - Contract → Handler 타입 자동 추론
+ * - TypedContext로 요청 데이터 접근
+ * - z.object({...}) 스키마 기반 검증
  */
 
 export * from "./schema";
 export * from "./types";
 export * from "./validator";
+export * from "./handler";
+export * from "./client";
 
-import type { ContractDefinition, ContractInstance } from "./schema";
+import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
+import type { ContractHandlers, RouteDefinition } from "./handler";
+import { defineHandler, defineRoute } from "./handler";
+import { createClient, contractFetch, type ClientOptions } from "./client";
 
 /**
  * Create a Mandu API Contract
@@ -61,3 +71,129 @@ export function createContract<T extends ContractDefinition>(definition: T): T &
     _validated: false,
   };
 }
+
+/**
+ * Mandu Namespace
+ *
+ * Contract-first API 개발을 위한 메인 인터페이스
+ *
+ * @example
+ * ```typescript
+ * import { Mandu } from "@mandujs/core";
+ * import { z } from "zod";
+ *
+ * // 1. Contract 정의
+ * const userContract = Mandu.contract({
+ *   request: {
+ *     GET: { query: z.object({ id: z.string() }) },
+ *     POST: { body: z.object({ name: z.string(), email: z.string().email() }) },
+ *   },
+ *   response: {
+ *     200: z.object({ user: z.object({ id: z.string(), name: z.string() }) }),
+ *     201: z.object({ user: z.object({ id: z.string(), name: z.string() }) }),
+ *   },
+ * });
+ *
+ * // 2. Handler 정의 (타입 자동 추론)
+ * const handlers = Mandu.handler(userContract, {
+ *   GET: async (ctx) => {
+ *     // ctx.query.id는 string 타입으로 자동 추론
+ *     const user = await db.users.findUnique({ where: { id: ctx.query.id } });
+ *     return { user };
+ *   },
+ *   POST: async (ctx) => {
+ *     // ctx.body.name, ctx.body.email 자동 추론
+ *     const user = await db.users.create({ data: ctx.body });
+ *     return { user };
+ *   },
+ * });
+ *
+ * // 3. 또는 Route로 한 번에 정의
+ * export default Mandu.route({
+ *   contract: userContract,
+ *   handler: handlers,
+ * });
+ * ```
+ */
+/**
+ * Contract-specific Mandu functions
+ * Note: Use `ManduContract` to avoid conflict with other Mandu exports
+ */
+export const ManduContract = {
+  /**
+   * Create a typed Contract
+   * Contract 스키마 정의 및 타입 추론
+   */
+  contract: createContract,
+
+  /**
+   * Create typed handlers for a contract
+   * Contract 기반 타입 안전 핸들러 정의
+   *
+   * @example
+   * ```typescript
+   * const handlers = Mandu.handler(contract, {
+   *   GET: (ctx) => {
+   *     // ctx.query, ctx.body, ctx.params 모두 타입 추론
+   *     return { data: ctx.query.id };
+   *   },
+   * });
+   * ```
+   */
+  handler: defineHandler,
+
+  /**
+   * Define a complete route with contract and handler
+   * Contract와 Handler를 한 번에 정의
+   *
+   * @example
+   * ```typescript
+   * export default Mandu.route({
+   *   contract: {
+   *     request: { GET: { query: z.object({ id: z.string() }) } },
+   *     response: { 200: z.object({ data: z.string() }) },
+   *   },
+   *   handler: {
+   *     GET: (ctx) => ({ data: ctx.query.id }),
+   *   },
+   * });
+   * ```
+   */
+  route: defineRoute,
+
+  /**
+   * Create a type-safe API client from contract
+   * Contract 기반 타입 안전 클라이언트 생성
+   *
+   * @example
+   * ```typescript
+   * const client = Mandu.client(userContract, {
+   *   baseUrl: "http://localhost:3000/api/users",
+   * });
+   *
+   * // Type-safe API calls
+   * const users = await client.GET({ query: { page: 1 } });
+   * const newUser = await client.POST({ body: { name: "Alice" } });
+   * ```
+   */
+  client: createClient,
+
+  /**
+   * Single type-safe fetch call
+   * 단일 타입 안전 fetch 호출
+   *
+   * @example
+   * ```typescript
+   * const result = await Mandu.fetch(contract, "GET", "/api/users", {
+   *   query: { page: 1 },
+   * });
+   * ```
+   */
+  fetch: contractFetch,
+} as const;
+
+/**
+ * Alias for backward compatibility within contract module
+ * 외부에서는 메인 index.ts의 Mandu를 사용하세요
+ */
+export const Mandu = ManduContract;

package/src/contract/infer.test.ts

@@ -0,0 +1,346 @@
+/**
+ * Mandu Contract Type Inference Tests
+ *
+ * 이 테스트는 타입 추론이 올바르게 동작하는지 검증합니다.
+ * - Contract → Handler 타입 추론
+ * - TypedContext 타입 추론
+ * - Response 타입 추론
+ */
+
+import { describe, it, expect } from "bun:test";
+import { z } from "zod";
+import { Mandu, type InferContract, type InferQuery, type InferBody, type InferResponse } from "./index";
+
+// === Test Schemas ===
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string().min(2),
+  createdAt: z.string().datetime(),
+});
+
+const CreateUserSchema = UserSchema.omit({ id: true, createdAt: true });
+
+const PaginationSchema = z.object({
+  page: z.coerce.number().default(1),
+  limit: z.coerce.number().default(10),
+});
+
+// === Test Contract ===
+const userContract = Mandu.contract({
+  description: "User Management API",
+  tags: ["users"],
+  request: {
+    GET: {
+      query: PaginationSchema,
+    },
+    POST: {
+      body: CreateUserSchema,
+    },
+    PUT: {
+      params: z.object({ id: z.string().uuid() }),
+      body: CreateUserSchema.partial(),
+    },
+    DELETE: {
+      params: z.object({ id: z.string().uuid() }),
+    },
+  },
+  response: {
+    200: z.object({
+      data: z.array(UserSchema),
+      total: z.number(),
+    }),
+    201: z.object({
+      data: UserSchema,
+    }),
+    204: z.undefined(),
+    400: z.object({
+      error: z.string(),
+      details: z.array(z.string()).optional(),
+    }),
+    404: z.object({
+      error: z.string(),
+    }),
+  },
+});
+
+// === Type Inference Tests ===
+describe("Contract Type Inference", () => {
+  it("should infer contract types correctly", () => {
+    // Type-level test: InferContract
+    type ContractTypes = InferContract<typeof userContract>;
+
+    // These are compile-time checks - if they compile, types are correct
+    type _GetQuery = ContractTypes["request"]["GET"]["query"];
+    type _PostBody = ContractTypes["request"]["POST"]["body"];
+
+    // Runtime check
+    expect(userContract.description).toBe("User Management API");
+    expect(userContract.tags).toEqual(["users"]);
+  });
+
+  it("should infer query types for specific methods", () => {
+    // Type-level test: InferQuery
+    type GetQuery = InferQuery<typeof userContract, "GET">;
+
+    // Verify at runtime that schema exists
+    expect(userContract.request.GET?.query).toBeDefined();
+
+    // Test schema validation
+    const querySchema = userContract.request.GET?.query;
+    if (querySchema) {
+      const result = querySchema.safeParse({ page: "2", limit: "20" });
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.page).toBe(2);
+        expect(result.data.limit).toBe(20);
+      }
+    }
+  });
+
+  it("should infer body types for specific methods", () => {
+    // Type-level test: InferBody
+    type PostBody = InferBody<typeof userContract, "POST">;
+
+    // Verify at runtime that schema exists
+    expect(userContract.request.POST?.body).toBeDefined();
+
+    // Test schema validation
+    const bodySchema = userContract.request.POST?.body;
+    if (bodySchema) {
+      const validData = {
+        email: "test@example.com",
+        name: "Test User",
+      };
+      const result = bodySchema.safeParse(validData);
+      expect(result.success).toBe(true);
+    }
+  });
+
+  it("should infer response types for specific status codes", () => {
+    // Type-level test: InferResponse
+    type Success200 = InferResponse<typeof userContract, 200>;
+    type Created201 = InferResponse<typeof userContract, 201>;
+    type Error400 = InferResponse<typeof userContract, 400>;
+
+    // Verify at runtime that schemas exist
+    expect(userContract.response[200]).toBeDefined();
+    expect(userContract.response[201]).toBeDefined();
+    expect(userContract.response[400]).toBeDefined();
+  });
+});
+
+// === Handler Type Inference Tests ===
+describe("Handler Type Inference", () => {
+  it("should create typed handlers with correct context types", () => {
+    const handlers = Mandu.handler(userContract, {
+      GET: async (ctx) => {
+        // ctx.query should be typed as { page: number, limit: number }
+        const { page, limit } = ctx.query;
+        expect(typeof page).toBe("undefined"); // Not parsed yet at this level
+
+        // Return type should match response schema
+        return {
+          data: [],
+          total: 0,
+        };
+      },
+      POST: async (ctx) => {
+        // ctx.body should be typed as { email: string, name: string }
+        // Return type should match 201 response schema
+        return {
+          data: {
+            id: "123e4567-e89b-12d3-a456-426614174000",
+            email: "test@example.com",
+            name: "Test",
+            createdAt: new Date().toISOString(),
+          },
+        };
+      },
+    });
+
+    expect(handlers.GET).toBeDefined();
+    expect(handlers.POST).toBeDefined();
+    expect(typeof handlers.GET).toBe("function");
+    expect(typeof handlers.POST).toBe("function");
+  });
+
+  it("should allow partial handler implementation", () => {
+    // Only implement some methods
+    const partialHandlers = Mandu.handler(userContract, {
+      GET: (ctx) => ({
+        data: [],
+        total: 0,
+      }),
+      // POST, PUT, DELETE not implemented - should be allowed
+    });
+
+    expect(partialHandlers.GET).toBeDefined();
+    expect(partialHandlers.POST).toBeUndefined();
+  });
+});
+
+// === Route Definition Tests ===
+describe("Route Definition", () => {
+  it("should define route with contract and handler", () => {
+    const route = Mandu.route({
+      contract: userContract,
+      handler: {
+        GET: (ctx) => ({
+          data: [],
+          total: 0,
+        }),
+        POST: (ctx) => ({
+          data: {
+            id: "123e4567-e89b-12d3-a456-426614174000",
+            email: ctx.body.email,
+            name: ctx.body.name,
+            createdAt: new Date().toISOString(),
+          },
+        }),
+      },
+    });
+
+    expect(route.contract).toBe(userContract);
+    expect(route.handler.GET).toBeDefined();
+    expect(route.handler.POST).toBeDefined();
+  });
+
+  it("should preserve contract metadata in route", () => {
+    const route = Mandu.route({
+      contract: {
+        description: "Test Route",
+        tags: ["test"],
+        request: {
+          GET: { query: z.object({ id: z.string() }) },
+        },
+        response: {
+          200: z.object({ result: z.string() }),
+        },
+      },
+      handler: {
+        GET: (ctx) => ({ result: ctx.query.id }),
+      },
+    });
+
+    expect(route.contract.description).toBe("Test Route");
+    expect(route.contract.tags).toEqual(["test"]);
+  });
+});
+
+// === Integration with Validator Tests ===
+describe("Contract + Validator Integration", () => {
+  it("should validate request against contract schema", async () => {
+    const { ContractValidator } = await import("./validator");
+
+    const validator = new ContractValidator(userContract);
+
+    // Create a mock request
+    const request = new Request("http://localhost/users?page=1&limit=10", {
+      method: "GET",
+    });
+
+    const result = await validator.validateRequest(request, "GET");
+    expect(result.success).toBe(true);
+  });
+
+  it("should reject invalid request", async () => {
+    const { ContractValidator } = await import("./validator");
+
+    const validator = new ContractValidator(userContract);
+
+    // Create request with invalid body
+    const request = new Request("http://localhost/users", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "invalid-email" }), // Missing name, invalid email
+    });
+
+    const result = await validator.validateRequest(request, "POST");
+    expect(result.success).toBe(false);
+    expect(result.errors).toBeDefined();
+  });
+});
+
+// === Complex Type Scenarios ===
+describe("Complex Type Scenarios", () => {
+  it("should handle nested schemas", () => {
+    const nestedContract = Mandu.contract({
+      request: {
+        POST: {
+          body: z.object({
+            user: z.object({
+              profile: z.object({
+                bio: z.string(),
+                avatar: z.string().url().optional(),
+              }),
+            }),
+          }),
+        },
+      },
+      response: {
+        200: z.object({ success: z.boolean() }),
+      },
+    });
+
+    const handlers = Mandu.handler(nestedContract, {
+      POST: (ctx) => {
+        // Deep nested access should be typed
+        const bio = ctx.body.user.profile.bio;
+        return { success: true };
+      },
+    });
+
+    expect(handlers.POST).toBeDefined();
+  });
+
+  it("should handle union types in response", () => {
+    const unionContract = Mandu.contract({
+      request: {
+        GET: { query: z.object({ id: z.string() }) },
+      },
+      response: {
+        200: z.object({ found: z.literal(true), data: z.string() }),
+        404: z.object({ found: z.literal(false), message: z.string() }),
+      },
+    });
+
+    const handlers = Mandu.handler(unionContract, {
+      GET: (ctx) => {
+        // Can return either 200 or 404 response shape
+        if (ctx.query.id === "not-found") {
+          return { found: false as const, message: "Not found" };
+        }
+        return { found: true as const, data: "Found!" };
+      },
+    });
+
+    expect(handlers.GET).toBeDefined();
+  });
+
+  it("should handle optional fields correctly", () => {
+    const optionalContract = Mandu.contract({
+      request: {
+        POST: {
+          body: z.object({
+            required: z.string(),
+            optional: z.string().optional(),
+            withDefault: z.string().default("default"),
+          }),
+        },
+      },
+      response: {
+        200: z.object({ result: z.string() }),
+      },
+    });
+
+    const handlers = Mandu.handler(optionalContract, {
+      POST: (ctx) => {
+        const { required, optional, withDefault } = ctx.body;
+        return { result: required + (optional ?? "") + withDefault };
+      },
+    });
+
+    expect(handlers.POST).toBeDefined();
+  });
+});

package/src/contract/types.ts

@@ -132,3 +132,86 @@ export type ContractMethods<T extends ContractSchema> = Extract<
  * Helper type to get all defined status codes in a contract
  */
 export type ContractStatusCodes<T extends ContractSchema> = keyof T["response"];
+
+/**
+ * Helper type to check if a method exists in contract
+ */
+export type HasMethod<
+  T extends ContractSchema,
+  M extends string
+> = M extends keyof T["request"] ? true : false;
+
+/**
+ * Extract all required fields from a method schema
+ */
+export type RequiredFields<
+  T extends ContractSchema,
+  M extends keyof T["request"]
+> = T["request"][M] extends MethodRequestSchema
+  ? {
+      query: T["request"][M]["query"] extends z.ZodTypeAny ? true : false;
+      body: T["request"][M]["body"] extends z.ZodTypeAny ? true : false;
+      params: T["request"][M]["params"] extends z.ZodTypeAny ? true : false;
+      headers: T["request"][M]["headers"] extends z.ZodTypeAny ? true : false;
+    }
+  : never;
+
+/**
+ * Get the success response type (200 or 201)
+ */
+export type SuccessResponse<T extends ContractSchema> = T["response"][200] extends z.ZodTypeAny
+  ? z.infer<T["response"][200]>
+  : T["response"][201] extends z.ZodTypeAny
+    ? z.infer<T["response"][201]>
+    : never;
+
+/**
+ * Get the error response type (400, 404, 500, etc.)
+ */
+export type ErrorResponse<T extends ContractSchema> =
+  | (T["response"][400] extends z.ZodTypeAny ? z.infer<T["response"][400]> : never)
+  | (T["response"][401] extends z.ZodTypeAny ? z.infer<T["response"][401]> : never)
+  | (T["response"][403] extends z.ZodTypeAny ? z.infer<T["response"][403]> : never)
+  | (T["response"][404] extends z.ZodTypeAny ? z.infer<T["response"][404]> : never)
+  | (T["response"][500] extends z.ZodTypeAny ? z.infer<T["response"][500]> : never);
+
+/**
+ * Utility type for strict contract enforcement
+ * Contract에 정의된 메서드만 허용
+ */
+export type StrictContractMethods<T extends ContractSchema> = {
+  [M in ContractMethods<T>]: true;
+};
+
+/**
+ * Type-safe fetch options derived from contract
+ * 클라이언트에서 Contract 기반 fetch 호출에 사용
+ */
+export type ContractFetchOptions<
+  T extends ContractSchema,
+  M extends keyof T["request"]
+> = T["request"][M] extends MethodRequestSchema
+  ? {
+      query?: T["request"][M]["query"] extends z.ZodTypeAny
+        ? z.input<T["request"][M]["query"]>
+        : never;
+      body?: T["request"][M]["body"] extends z.ZodTypeAny
+        ? z.input<T["request"][M]["body"]>
+        : never;
+      params?: T["request"][M]["params"] extends z.ZodTypeAny
+        ? z.input<T["request"][M]["params"]>
+        : never;
+      headers?: T["request"][M]["headers"] extends z.ZodTypeAny
+        ? z.input<T["request"][M]["headers"]>
+        : never;
+    }
+  : never;
+
+/**
+ * Response type union for a contract
+ */
+export type ContractResponseUnion<T extends ContractSchema> = {
+  [K in keyof T["response"]]: T["response"][K] extends z.ZodTypeAny
+    ? { status: K; data: z.infer<T["response"][K]> }
+    : never;
+}[keyof T["response"]];

package/src/filling/filling.ts

@@ -293,7 +293,11 @@ export class ManduFilling<TLoaderData = unknown> {
   }
 }
 
-export const Mandu = {
+/**
+ * Mandu Filling factory functions
+ * Note: These are also available via the main `Mandu` namespace
+ */
+export const ManduFillingFactory = {
   filling<TLoaderData = unknown>(): ManduFilling<TLoaderData> {
     return new ManduFilling<TLoaderData>();
   },

package/src/filling/index.ts

@@ -4,7 +4,7 @@
 
 export { ManduContext, ValidationError, CookieManager } from "./context";
 export type { CookieOptions } from "./context";
-export { ManduFilling, Mandu, LoaderTimeoutError } from "./filling";
+export { ManduFilling, ManduFillingFactory, LoaderTimeoutError } from "./filling";
 export type { Handler, Guard, HttpMethod, Loader, LoaderOptions } from "./filling";
 
 // Auth Guards

package/src/index.ts

@@ -12,3 +12,78 @@ export * from "./contract";
 export * from "./openapi";
 export * from "./brain";
 export * from "./watcher";
+
+// Consolidated Mandu namespace
+import { ManduFilling, ManduContext, ManduFillingFactory } from "./filling";
+import { createContract, defineHandler, defineRoute, createClient, contractFetch } from "./contract";
+import type { ContractDefinition, ContractInstance, ContractSchema } from "./contract";
+import type { ContractHandlers, ClientOptions } from "./contract";
+
+/**
+ * Mandu - Unified Namespace
+ *
+ * 통합된 Mandu API 인터페이스
+ *
+ * @example
+ * ```typescript
+ * import { Mandu } from "@mandujs/core";
+ * import { z } from "zod";
+ *
+ * // Filling (Handler) API
+ * export default Mandu.filling()
+ *   .get(async (ctx) => ctx.json({ message: "Hello" }));
+ *
+ * // Contract API
+ * const contract = Mandu.contract({
+ *   request: { GET: { query: z.object({ id: z.string() }) } },
+ *   response: { 200: z.object({ data: z.string() }) },
+ * });
+ *
+ * // Handler API (with type inference)
+ * const handlers = Mandu.handler(contract, {
+ *   GET: (ctx) => ({ data: ctx.query.id }),
+ * });
+ *
+ * // Client API (type-safe fetch)
+ * const client = Mandu.client(contract, { baseUrl: "/api" });
+ * const result = await client.GET({ query: { id: "123" } });
+ * ```
+ */
+export const Mandu = {
+  // === Filling (Handler) API ===
+  /**
+   * Create a new filling (handler chain)
+   */
+  filling: ManduFillingFactory.filling,
+
+  /**
+   * Create a ManduContext from a Request
+   */
+  context: ManduFillingFactory.context,
+
+  // === Contract API ===
+  /**
+   * Define a typed API contract
+   */
+  contract: createContract,
+
+  /**
+   * Create typed handlers for a contract
+   */
+  handler: defineHandler,
+
+  /**
+   * Define a complete route (contract + handler)
+   */
+  route: defineRoute,
+
+  /**
+   * Create a type-safe API client
+   */
+  client: createClient,
+
+  /**
+   * Make a type-safe fetch call
+   */
+  fetch: contractFetch,
+} as const;