@mandujs/core 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -13,6 +13,9 @@
     "./auth/reset": "./src/auth/reset.ts",
     "./auth/verification": "./src/auth/verification.ts",
     "./client": "./src/client/index.ts",
+    "./client/rpc": "./src/client/rpc.ts",
+    "./contract": "./src/contract/index.ts",
+    "./contract/rpc": "./src/contract/rpc.ts",
     "./content": "./src/content/index.ts",
     "./content/prebuild": "./src/content/prebuild.ts",
     "./content/collection": "./src/content/collection.ts",

package/src/client/index.ts

@@ -112,7 +112,17 @@ export { Link, NavLink, type LinkProps, type NavLinkProps } from "./Link";
 export { Form, type FormProps, type FormState } from "./Form";
 
 // RPC Client
-export { createClient, RpcError, type RpcMethods, type RpcRequestOptions, type RpcClientOptions } from "./rpc";
+export {
+  createClient,
+  RpcError,
+  type RpcMethods,
+  type RpcRequestOptions,
+  type RpcClientOptions,
+  // Phase 18.κ — typed RPC proxy
+  createRpcClient,
+  RpcCallError,
+  type CreateRpcClientOptions,
+} from "./rpc";
 
 // useFetch Composable
 export { useFetch, type UseFetchOptions, type UseFetchReturn } from "./use-fetch";

package/src/client/rpc.ts

@@ -1,140 +1,293 @@
-/**
- * Mandu RPC Client
- * Contract 정의에서 타입 안전한 API 클라이언트 생성
- */
-
-// ========== Types ==========
-
-/** RPC 클라이언트 에러 */
-export class RpcError extends Error {
-  constructor(
-    public readonly status: number,
-    public readonly body: unknown
-  ) {
-    super(`API Error ${status}`);
-    this.name = "RpcError";
-  }
-}
-
-export interface RpcRequestOptions {
-  query?: Record<string, unknown>;
-  body?: unknown;
-  params?: Record<string, string>;
-  headers?: Record<string, string>;
-  signal?: AbortSignal;
-}
-
-export interface RpcClientOptions {
-  /** API base URL (기본: 현재 origin) */
-  baseUrl?: string;
-  /** 공통 헤더 */
-  headers?: Record<string, string>;
-  /** 커스텀 fetch (테스트용) */
-  fetch?: typeof globalThis.fetch;
-}
-
-// ========== Implementation ==========
-
-/**
- * Contract 기반 타입 안전 RPC 클라이언트 생성
- *
- * @example
- * ```typescript
- * import { createClient } from "@mandujs/core/client";
- * import type todoContract from "../spec/contracts/api-todos.contract";
- *
- * const api = createClient<typeof todoContract>("/api/todos");
- *
- * // 타입 추론 동작
- * const { todos } = await api.get({ query: { page: 2 } });
- * const { id } = await api.post({ body: { title: "New" } });
- * ```
- */
-export function createClient<TContract = unknown>(
-  path: string,
-  options?: RpcClientOptions
-): RpcMethods {
-  const baseFetch = options?.fetch ?? globalThis.fetch;
-  const baseUrl = options?.baseUrl ?? "";
-  const baseHeaders = options?.headers ?? {};
-
-  function makeRequest(method: string) {
-    return async (input?: RpcRequestOptions): Promise<unknown> => {
-      const url = new URL(`${baseUrl}${path}`, typeof window !== "undefined" ? window.location.origin : "http://localhost");
-
-      // URL 파라미터 치환
-      if (input?.params) {
-        let resolvedPath = url.pathname;
-        for (const [key, value] of Object.entries(input.params)) {
-          resolvedPath = resolvedPath.replace(`:${key}`, encodeURIComponent(value));
-        }
-        // 미해결 파라미터 검출
-        if (resolvedPath.includes(":")) {
-          throw new RpcError(0, `Unresolved path params in "${resolvedPath}". Check your params object.`);
-        }
-        url.pathname = resolvedPath;
-      }
-
-      // Query 파라미터
-      if (input?.query) {
-        for (const [key, value] of Object.entries(input.query)) {
-          if (value !== undefined && value !== null) {
-            url.searchParams.set(key, String(value));
-          }
-        }
-      }
-
-      const headers: Record<string, string> = {
-        ...baseHeaders,
-        ...input?.headers,
-        "Accept": "application/json",
-      };
-
-      const fetchOptions: RequestInit = {
-        method: method.toUpperCase(),
-        headers,
-        signal: input?.signal,
-      };
-
-      // Body (GET/HEAD 제외)
-      if (input?.body && method !== "GET" && method !== "HEAD") {
-        fetchOptions.body = JSON.stringify(input.body);
-        headers["Content-Type"] = "application/json";
-      }
-
-      const response = await baseFetch(url.toString(), fetchOptions);
-
-      if (!response.ok) {
-        let body: unknown;
-        try {
-          body = await response.json();
-        } catch {
-          body = await response.text().catch(() => null);
-        }
-        throw new RpcError(response.status, body);
-      }
-
-      const contentType = response.headers.get("content-type") ?? "";
-      if (contentType.includes("application/json")) {
-        return response.json();
-      }
-      return response.text();
-    };
-  }
-
-  return {
-    get: makeRequest("GET"),
-    post: makeRequest("POST"),
-    put: makeRequest("PUT"),
-    patch: makeRequest("PATCH"),
-    delete: makeRequest("DELETE"),
-  };
-}
-
-export interface RpcMethods {
-  get: (input?: RpcRequestOptions) => Promise<unknown>;
-  post: (input?: RpcRequestOptions) => Promise<unknown>;
-  put: (input?: RpcRequestOptions) => Promise<unknown>;
-  patch: (input?: RpcRequestOptions) => Promise<unknown>;
-  delete: (input?: RpcRequestOptions) => Promise<unknown>;
-}
+/**
+ * Mandu RPC Client
+ * Contract 정의에서 타입 안전한 API 클라이언트 생성
+ */
+
+// ========== Types ==========
+
+/** RPC 클라이언트 에러 */
+export class RpcError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: unknown
+  ) {
+    super(`API Error ${status}`);
+    this.name = "RpcError";
+  }
+}
+
+export interface RpcRequestOptions {
+  query?: Record<string, unknown>;
+  body?: unknown;
+  params?: Record<string, string>;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+export interface RpcClientOptions {
+  /** API base URL (기본: 현재 origin) */
+  baseUrl?: string;
+  /** 공통 헤더 */
+  headers?: Record<string, string>;
+  /** 커스텀 fetch (테스트용) */
+  fetch?: typeof globalThis.fetch;
+}
+
+// ========== Implementation ==========
+
+/**
+ * Contract 기반 타입 안전 RPC 클라이언트 생성
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@mandujs/core/client";
+ * import type todoContract from "../spec/contracts/api-todos.contract";
+ *
+ * const api = createClient<typeof todoContract>("/api/todos");
+ *
+ * // 타입 추론 동작
+ * const { todos } = await api.get({ query: { page: 2 } });
+ * const { id } = await api.post({ body: { title: "New" } });
+ * ```
+ */
+export function createClient<TContract = unknown>(
+  path: string,
+  options?: RpcClientOptions
+): RpcMethods {
+  const baseFetch = options?.fetch ?? globalThis.fetch;
+  const baseUrl = options?.baseUrl ?? "";
+  const baseHeaders = options?.headers ?? {};
+
+  function makeRequest(method: string) {
+    return async (input?: RpcRequestOptions): Promise<unknown> => {
+      const url = new URL(`${baseUrl}${path}`, typeof window !== "undefined" ? window.location.origin : "http://localhost");
+
+      // URL 파라미터 치환
+      if (input?.params) {
+        let resolvedPath = url.pathname;
+        for (const [key, value] of Object.entries(input.params)) {
+          resolvedPath = resolvedPath.replace(`:${key}`, encodeURIComponent(value));
+        }
+        // 미해결 파라미터 검출
+        if (resolvedPath.includes(":")) {
+          throw new RpcError(0, `Unresolved path params in "${resolvedPath}". Check your params object.`);
+        }
+        url.pathname = resolvedPath;
+      }
+
+      // Query 파라미터
+      if (input?.query) {
+        for (const [key, value] of Object.entries(input.query)) {
+          if (value !== undefined && value !== null) {
+            url.searchParams.set(key, String(value));
+          }
+        }
+      }
+
+      const headers: Record<string, string> = {
+        ...baseHeaders,
+        ...input?.headers,
+        "Accept": "application/json",
+      };
+
+      const fetchOptions: RequestInit = {
+        method: method.toUpperCase(),
+        headers,
+        signal: input?.signal,
+      };
+
+      // Body (GET/HEAD 제외)
+      if (input?.body && method !== "GET" && method !== "HEAD") {
+        fetchOptions.body = JSON.stringify(input.body);
+        headers["Content-Type"] = "application/json";
+      }
+
+      const response = await baseFetch(url.toString(), fetchOptions);
+
+      if (!response.ok) {
+        let body: unknown;
+        try {
+          body = await response.json();
+        } catch {
+          body = await response.text().catch(() => null);
+        }
+        throw new RpcError(response.status, body);
+      }
+
+      const contentType = response.headers.get("content-type") ?? "";
+      if (contentType.includes("application/json")) {
+        return response.json();
+      }
+      return response.text();
+    };
+  }
+
+  return {
+    get: makeRequest("GET"),
+    post: makeRequest("POST"),
+    put: makeRequest("PUT"),
+    patch: makeRequest("PATCH"),
+    delete: makeRequest("DELETE"),
+  };
+}
+
+export interface RpcMethods {
+  get: (input?: RpcRequestOptions) => Promise<unknown>;
+  post: (input?: RpcRequestOptions) => Promise<unknown>;
+  put: (input?: RpcRequestOptions) => Promise<unknown>;
+  patch: (input?: RpcRequestOptions) => Promise<unknown>;
+  delete: (input?: RpcRequestOptions) => Promise<unknown>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 18.κ — Typed RPC Client (tRPC-like)
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// `createRpcClient<typeof postsRpc>()` returns a Proxy whose properties
+// are the RPC procedure names (`list`, `get`, …). Each access produces
+// an async function whose input type is the procedure's Zod input
+// type and whose return type is the procedure's Zod output type.
+//
+// Wire protocol:
+//   POST <baseUrl>/<method>
+//   body: { "input": <value> }
+//   response: { "ok": true, "data": <value> }
+//            | { "ok": false, "error": { code, message, issues? } }
+//
+// Errors throw {@link RpcCallError} with the structured fields
+// preserved so UI code can surface field-level validation issues.
+
+import type { RpcClient, RpcDefinition, RpcProcedureRecord, RpcWireEnvelope, RpcWireError } from "../contract/rpc";
+
+/** Options passed to {@link createRpcClient}. */
+export interface CreateRpcClientOptions {
+  /**
+   * Absolute or site-relative base URL for the RPC endpoint —
+   * typically `/api/rpc/<name>`. The method name is appended.
+   */
+  baseUrl: string;
+  /** Extra headers sent with every call. */
+  headers?: Record<string, string>;
+  /** Custom fetch (e.g. test double or node-fetch polyfill). */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Optional per-call AbortSignal factory. Useful when the proxy is
+   * shared across React components that want independent cancellation.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Typed error thrown by {@link createRpcClient} calls on non-OK
+ * envelopes. Carries the wire-level {@link RpcWireError} + HTTP
+ * status so callers can distinguish validation vs. handler errors
+ * without string-matching on `message`.
+ */
+export class RpcCallError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly error: RpcWireError
+  ) {
+    super(`[Mandu RPC] ${error.code}: ${error.message}`);
+    this.name = "RpcCallError";
+  }
+
+  /** Machine-readable code (forwarded from the server). */
+  get code(): string {
+    return this.error.code;
+  }
+
+  /** Field-level issues, if any. */
+  get issues(): RpcWireError["issues"] {
+    return this.error.issues;
+  }
+}
+
+/**
+ * Create a typed RPC client from an `RpcDefinition` type import.
+ *
+ * The implementation uses a `Proxy` so no codegen step is required —
+ * TypeScript infers call signatures from the imported `typeof` at
+ * compile time, and at runtime every property access produces a
+ * fetch wrapper.
+ *
+ * @example
+ * ```ts
+ * import { createRpcClient } from "@mandujs/core/client";
+ * import type { postsRpc } from "../server/rpc/posts";
+ *
+ * const api = createRpcClient<typeof postsRpc>({ baseUrl: "/api/rpc/posts" });
+ * const posts = await api.list({ limit: 20 });   // fully typed
+ * const post  = await api.get({ id: "abc" });    // fully typed
+ * ```
+ *
+ * Type-check failures at the call site are real compile errors:
+ * `api.list({ limit: "not-a-number" })` is a TS2322.
+ */
+export function createRpcClient<TDef extends RpcDefinition<RpcProcedureRecord>>(
+  options: CreateRpcClientOptions
+): RpcClient<TDef> {
+  const baseFetch = options.fetch ?? globalThis.fetch;
+  const baseUrl = options.baseUrl.replace(/\/$/, "");
+  const baseHeaders = options.headers ?? {};
+
+  const call = async (method: string, input: unknown): Promise<unknown> => {
+    const url = `${baseUrl}/${method}`;
+    const payload = input === undefined ? { input: undefined } : { input };
+    const response = await baseFetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...baseHeaders,
+      },
+      body: JSON.stringify(payload),
+      signal: options.signal,
+    });
+
+    // Prefer JSON parse (every legitimate RPC response is JSON), but
+    // tolerate non-JSON failure paths (e.g. upstream proxy error).
+    let envelope: RpcWireEnvelope | null = null;
+    const text = await response.text();
+    try {
+      envelope = text.length > 0 ? (JSON.parse(text) as RpcWireEnvelope) : null;
+    } catch {
+      envelope = null;
+    }
+
+    if (envelope && envelope.ok === true) {
+      return envelope.data;
+    }
+
+    // Non-OK path — throw a structured error. Prefer server-emitted
+    // envelope; fall back to a synthesized one for transport errors.
+    let error: RpcWireError;
+    if (envelope && envelope.ok === false) {
+      error = envelope.error;
+    } else {
+      error = {
+        code: response.ok ? "BAD_RESPONSE" : `HTTP_${response.status}`,
+        message:
+          text.length > 0
+            ? text.slice(0, 500)
+            : `RPC call to ${url} failed with HTTP ${response.status}`,
+      };
+    }
+    throw new RpcCallError(response.status, error);
+  };
+
+  // A Proxy on a plain object: every property access returns a
+  // pre-curried call fn. Symbol keys (`Symbol.toStringTag`, etc.) fall
+  // through so `console.log(api)` does not throw.
+  const target = Object.create(null) as Record<string, unknown>;
+  return new Proxy(target, {
+    get(_t, prop) {
+      if (typeof prop !== "string") return undefined;
+      // Allow common non-method inspection hooks to no-op.
+      if (prop === "then") return undefined; // not thenable
+      if (prop === "toJSON") return undefined;
+      return (input?: unknown) => call(prop, input);
+    },
+  }) as RpcClient<TDef>;
+}
+

package/src/config/mandu.ts

@@ -3,6 +3,8 @@ import { readJsonFile } from "../utils/bun";
 import type { ManduAdapter } from "../runtime/adapter";
 import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
 import type { Middleware } from "../middleware/define";
+import type { RpcDefinition, RpcProcedureRecord } from "../contract/rpc";
+import type { CronDef } from "../scheduler";
 
 export type GuardRuleSeverity = "error" | "warn" | "warning" | "off";
 
@@ -373,6 +375,53 @@ export interface ManduConfig {
    * @see `docs/architect/middleware-composition.md`
    */
   middleware?: Middleware[];
+  /**
+   * Phase 18.κ — tRPC-like typed RPC endpoints.
+   *
+   * Keys become URL segments: `endpoints.posts` is served from
+   * `/api/rpc/posts/<method>`. Each value is a `defineRpc()` result —
+   * a tagged object carrying Zod input/output schemas and handler
+   * functions. The runtime dispatcher (`runtime/server.ts`) registers
+   * every declared endpoint at `startServer()` time and validates
+   * both request inputs and handler outputs against the schemas.
+   *
+   * Wire protocol: `POST /api/rpc/<name>/<method>` with JSON body
+   * `{ "input": <value> }`; returns `{ ok: true, data }` or
+   * `{ ok: false, error: { code, message, issues? } }`.
+   *
+   * Client: `createRpcClient<typeof postsRpc>({ baseUrl: "/api/rpc/posts" })`.
+   *
+   * @see `docs/architect/typed-rpc.md`
+   * @see `@mandujs/core/contract/rpc` for `defineRpc`.
+   * @see `@mandujs/core/client/rpc` for `createRpcClient`.
+   */
+  rpc?: {
+    endpoints?: Record<string, RpcDefinition<RpcProcedureRecord>>;
+  };
+  /**
+   * Phase 18.λ — declarative cron job scheduler.
+   *
+   * `scheduler.jobs` is an array of {@link CronDef} objects (from
+   * `@mandujs/core/scheduler`). At `startServer()` boot time the runtime
+   * filters the set by `runOn === "bun"` (or `runOn` omitted) and registers
+   * each surviving job with `Bun.cron`. At build time, when
+   * `--target=workers` is set, the CLI filters by `runOn === "workers"` (or
+   * omitted) and emits the schedule strings into the generated
+   * `wrangler.toml` `[triggers] crons = [...]` block.
+   *
+   * Schedule strings are validated synchronously at `defineCron` time, so
+   * malformed crontabs fail boot instead of silently never firing.
+   *
+   * `scheduler.disabled` is an escape hatch for environments where cron
+   * should not fire (e.g., a read-only replica). Default: `false`.
+   *
+   * @see `docs/architect/cron-scheduler.md`
+   * @see `@mandujs/core/scheduler` for `defineCron`.
+   */
+  scheduler?: {
+    jobs?: CronDef[];
+    disabled?: boolean;
+  };
 }
 
 export const CONFIG_FILES = [

package/src/config/validate.ts

@@ -6,6 +6,7 @@ import { readJsonFile } from "../utils/bun";
 import type { ManduAdapter } from "../runtime/adapter";
 import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
 import type { Middleware } from "../middleware/define";
+import type { CronDef } from "../scheduler";
 
 /**
  * DNA-003: Strict mode schema helper
@@ -335,6 +336,47 @@ const CacheConfigSchema = z
   })
   .strict();
 
+/**
+ * Phase 18.λ — declarative cron scheduler (strict).
+ *
+ * Each `jobs[i]` entry is structurally validated: `name` must be a non-empty
+ * string, `schedule` a string (deeper cron validation runs at `defineCron`
+ * time), and `handler` (or `run` alias) a function. Zod cannot introspect
+ * closures, so the handler field is a structural check.
+ *
+ * `disabled` short-circuits registration in environments where cron
+ * shouldn't fire (e.g., a read-only replica reading the same config file
+ * its primary uses).
+ */
+const CronDefSchema = z.custom<CronDef>(
+  (v) => {
+    if (typeof v !== "object" || v === null) return false;
+    const obj = v as Record<string, unknown>;
+    if (typeof obj.name !== "string" || obj.name.length === 0) return false;
+    if (typeof obj.schedule !== "string" || obj.schedule.length === 0) return false;
+    if (typeof obj.handler !== "function" && typeof obj.run !== "function") return false;
+    if (obj.timezone !== undefined && typeof obj.timezone !== "string") return false;
+    if (obj.runOn !== undefined) {
+      if (!Array.isArray(obj.runOn)) return false;
+      for (const r of obj.runOn) {
+        if (r !== "bun" && r !== "workers") return false;
+      }
+    }
+    return true;
+  },
+  {
+    message:
+      "Each cron job must be an object with `name` (string), `schedule` (string), and `handler` (function). Optional: `timezone` (string), `runOn` (array of 'bun'|'workers'), `skipInDev` (boolean), `timeoutMs` (number).",
+  }
+);
+
+const SchedulerConfigSchema = z
+  .object({
+    jobs: z.array(CronDefSchema).optional(),
+    disabled: z.boolean().optional(),
+  })
+  .strict();
+
 export const ManduConfigSchema = z
   .object({
     adapter: AdapterConfigSchema.optional(),
@@ -375,6 +417,12 @@ export const ManduConfigSchema = z
      * passthrough at runtime).
      */
     middleware: z.array(MiddlewareSchema).optional(),
+    /**
+     * Phase 18.λ — declarative cron scheduler. See {@link SchedulerConfigSchema}.
+     * Omit the block to disable scheduling entirely (zero-overhead
+     * passthrough).
+     */
+    scheduler: SchedulerConfigSchema.optional(),
   })
   .strict();
 

package/src/contract/index.ts

@@ -19,6 +19,24 @@ export * from "./client-safe";
 export * from "./protection";
 export * from "./route-helpers";
 
+// Phase 18.κ — tRPC-like typed RPC (see `./rpc.ts`).
+export {
+  defineRpc,
+  registerRpc,
+  getRpc,
+  clearRpcRegistry,
+  listRpcEndpoints,
+  matchRpcPath,
+  dispatchRpc,
+  type RpcContext,
+  type RpcProcedure,
+  type RpcProcedureRecord,
+  type RpcDefinition,
+  type RpcClient,
+  type RpcWireEnvelope,
+  type RpcWireError,
+} from "./rpc";
+
 import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
 import type { ContractHandlers, RouteDefinition } from "./handler";
 import { defineHandler, defineRoute } from "./handler";