@mandujs/core 0.54.32 → 0.55.0-beta.1

package/src/runtime/trace.ts

@@ -1,144 +1,144 @@
-/**
- * Mandu Trace 🧭
- * Lifecycle 단계별 추적 (옵션)
- */
-
-import type { ManduContext } from "../filling/context";
-
-export type TraceEvent =
-  | "request"
-  | "parse"
-  | "transform"
-  | "beforeHandle"
-  | "handle"
-  | "afterHandle"
-  | "mapResponse"
-  | "afterResponse"
-  | "error";
-
-export type TracePhase = "begin" | "end" | "error";
-
-export interface TraceEntry {
-  event: TraceEvent;
-  phase: TracePhase;
-  time: number;
-  name?: string;
-  error?: string;
-}
-
-export interface TraceCollector {
-  records: TraceEntry[];
-}
-
-export interface TraceReportEntry {
-  event: TraceEvent;
-  name?: string;
-  start: number;
-  end: number;
-  duration: number;
-}
-
-export interface TraceReport {
-  entries: TraceReportEntry[];
-  errors: TraceEntry[];
-}
-
-export const TRACE_KEY = "__mandu_trace";
-
-const now = (): number => {
-  if (typeof performance !== "undefined" && typeof performance.now === "function") {
-    return performance.now();
-  }
-  return Date.now();
-};
-
-export function enableTrace(ctx: ManduContext): TraceCollector {
-  const existing = ctx.get<TraceCollector>(TRACE_KEY);
-  if (existing) return existing;
-  const collector: TraceCollector = { records: [] };
-  ctx.set(TRACE_KEY, collector);
-  return collector;
-}
-
-export function getTrace(ctx: ManduContext): TraceCollector | undefined {
-  return ctx.get<TraceCollector>(TRACE_KEY);
-}
-
-/**
- * Build a normalized trace report with durations
- */
-export function buildTraceReport(collector: TraceCollector): TraceReport {
-  const entries: TraceReportEntry[] = [];
-  const errors: TraceEntry[] = [];
-  const stacks = new Map<string, TraceEntry[]>();
-
-  for (const record of collector.records) {
-    if (record.phase === "error") {
-      errors.push(record);
-      continue;
-    }
-
-    const key = `${record.event}:${record.name ?? ""}`;
-    if (record.phase === "begin") {
-      const stack = stacks.get(key) ?? [];
-      stack.push(record);
-      stacks.set(key, stack);
-      continue;
-    }
-
-    if (record.phase === "end") {
-      const stack = stacks.get(key);
-      const begin = stack?.pop();
-      if (!begin) continue;
-      entries.push({
-        event: record.event,
-        name: record.name,
-        start: begin.time,
-        end: record.time,
-        duration: record.time - begin.time,
-      });
-    }
-  }
-
-  return { entries, errors };
-}
-
-/**
- * Convert trace report to JSON string
- */
-export function formatTraceReport(report: TraceReport): string {
-  return JSON.stringify(report, null, 2);
-}
-
-export interface Tracer {
-  enabled: boolean;
-  begin: (event: TraceEvent, name?: string) => () => void;
-  error: (event: TraceEvent, err: unknown, name?: string) => void;
-}
-
-const NOOP_TRACER: Tracer = {
-  enabled: false,
-  begin: () => () => {},
-  error: () => {},
-};
-
-export function createTracer(ctx: ManduContext, enabled?: boolean): Tracer {
-  const shouldEnable = Boolean(enabled) || ctx.has(TRACE_KEY);
-  if (!shouldEnable) return NOOP_TRACER;
-
-  const collector = enableTrace(ctx);
-
-  return {
-    enabled: true,
-    begin: (event, name) => {
-      collector.records.push({ event, phase: "begin", time: now(), name });
-      return () => {
-        collector.records.push({ event, phase: "end", time: now(), name });
-      };
-    },
-    error: (event, err, name) => {
-      const message = err instanceof Error ? err.message : String(err);
-      collector.records.push({ event, phase: "error", time: now(), name, error: message });
-    },
-  };
-}
+/**
+ * Mandu Trace 🧭
+ * Lifecycle 단계별 추적 (옵션)
+ */
+
+import type { ManduContext } from "../filling/context";
+
+export type TraceEvent =
+  | "request"
+  | "parse"
+  | "transform"
+  | "beforeHandle"
+  | "handle"
+  | "afterHandle"
+  | "mapResponse"
+  | "afterResponse"
+  | "error";
+
+export type TracePhase = "begin" | "end" | "error";
+
+export interface TraceEntry {
+  event: TraceEvent;
+  phase: TracePhase;
+  time: number;
+  name?: string;
+  error?: string;
+}
+
+export interface TraceCollector {
+  records: TraceEntry[];
+}
+
+export interface TraceReportEntry {
+  event: TraceEvent;
+  name?: string;
+  start: number;
+  end: number;
+  duration: number;
+}
+
+export interface TraceReport {
+  entries: TraceReportEntry[];
+  errors: TraceEntry[];
+}
+
+export const TRACE_KEY = "__mandu_trace";
+
+const now = (): number => {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+};
+
+export function enableTrace(ctx: ManduContext): TraceCollector {
+  const existing = ctx.get<TraceCollector>(TRACE_KEY);
+  if (existing) return existing;
+  const collector: TraceCollector = { records: [] };
+  ctx.set(TRACE_KEY, collector);
+  return collector;
+}
+
+export function getTrace(ctx: ManduContext): TraceCollector | undefined {
+  return ctx.get<TraceCollector>(TRACE_KEY);
+}
+
+/**
+ * Build a normalized trace report with durations
+ */
+export function buildTraceReport(collector: TraceCollector): TraceReport {
+  const entries: TraceReportEntry[] = [];
+  const errors: TraceEntry[] = [];
+  const stacks = new Map<string, TraceEntry[]>();
+
+  for (const record of collector.records) {
+    if (record.phase === "error") {
+      errors.push(record);
+      continue;
+    }
+
+    const key = `${record.event}:${record.name ?? ""}`;
+    if (record.phase === "begin") {
+      const stack = stacks.get(key) ?? [];
+      stack.push(record);
+      stacks.set(key, stack);
+      continue;
+    }
+
+    if (record.phase === "end") {
+      const stack = stacks.get(key);
+      const begin = stack?.pop();
+      if (!begin) continue;
+      entries.push({
+        event: record.event,
+        name: record.name,
+        start: begin.time,
+        end: record.time,
+        duration: record.time - begin.time,
+      });
+    }
+  }
+
+  return { entries, errors };
+}
+
+/**
+ * Convert trace report to JSON string
+ */
+export function formatTraceReport(report: TraceReport): string {
+  return JSON.stringify(report, null, 2);
+}
+
+export interface Tracer {
+  enabled: boolean;
+  begin: (event: TraceEvent, name?: string) => () => void;
+  error: (event: TraceEvent, err: unknown, name?: string) => void;
+}
+
+const NOOP_TRACER: Tracer = {
+  enabled: false,
+  begin: () => () => {},
+  error: () => {},
+};
+
+export function createTracer(ctx: ManduContext, enabled?: boolean): Tracer {
+  const shouldEnable = Boolean(enabled) || ctx.has(TRACE_KEY);
+  if (!shouldEnable) return NOOP_TRACER;
+
+  const collector = enableTrace(ctx);
+
+  return {
+    enabled: true,
+    begin: (event, name) => {
+      collector.records.push({ event, phase: "begin", time: now(), name });
+      return () => {
+        collector.records.push({ event, phase: "end", time: now(), name });
+      };
+    },
+    error: (event, err, name) => {
+      const message = err instanceof Error ? err.message : String(err);
+      collector.records.push({ event, phase: "error", time: now(), name, error: message });
+    },
+  };
+}

package/src/scheduler/__tests__/scheduler.test.ts

@@ -24,6 +24,7 @@ import {
 interface FakeSchedule {
   schedule: string;
   handler: () => void | Promise<void>;
+  options?: { tz?: string };
   stop: ReturnType<typeof mock>;
 }
 
@@ -33,9 +34,9 @@ function makeFakeScheduler(): {
   tick(index: number): Promise<void>;
 } {
   const schedules: FakeSchedule[] = [];
-  const scheduleFn: CronScheduleFn = (schedule, handler) => {
+  const scheduleFn: CronScheduleFn = (schedule, handler, options) => {
     const stop = mock(() => {});
-    schedules.push({ schedule, handler, stop });
+    schedules.push({ schedule, handler, options, stop });
     return { stop };
   };
   return {
@@ -71,7 +72,7 @@ afterEach(() => {
   }
 });
 
-describe("@mandujs/core/scheduler — defineCron (public surface)", () => {
+describe("@mandujs/core/compat/scheduler — defineCron (public surface)", () => {
   it("returns a handle with start, stop, and status methods", () => {
     const reg = defineCron({});
     expect(typeof reg.start).toBe("function");
@@ -89,7 +90,7 @@ describe("@mandujs/core/scheduler — defineCron (public surface)", () => {
   });
 });
 
-describe("@mandujs/core/scheduler — scheduling", () => {
+describe("@mandujs/core/compat/scheduler — scheduling", () => {
   it("registers each job via the injected scheduleFn with its crontab expression", () => {
     const { scheduleFn, schedules } = makeFakeScheduler();
 
@@ -163,7 +164,7 @@ describe("@mandujs/core/scheduler — scheduling", () => {
   });
 });
 
-describe("@mandujs/core/scheduler — error isolation", () => {
+describe("@mandujs/core/compat/scheduler — error isolation", () => {
   it("increments errorCount when the handler throws and continues on next tick", async () => {
     const { scheduleFn, tick } = makeFakeScheduler();
     // Silence the expected console.error so test output stays clean.
@@ -206,7 +207,7 @@ describe("@mandujs/core/scheduler — error isolation", () => {
   });
 });
 
-describe("@mandujs/core/scheduler — overlap prevention", () => {
+describe("@mandujs/core/compat/scheduler — overlap prevention", () => {
   it("skips a tick when the previous invocation is still pending", async () => {
     const { scheduleFn, tick } = makeFakeScheduler();
 
@@ -252,7 +253,7 @@ describe("@mandujs/core/scheduler — overlap prevention", () => {
   });
 });
 
-describe("@mandujs/core/scheduler — dev-mode skip", () => {
+describe("@mandujs/core/compat/scheduler — dev-mode skip", () => {
   it("does not schedule jobs with skipInDev=true when NODE_ENV !== 'production'", () => {
     process.env.NODE_ENV = "development";
     const { scheduleFn, schedules } = makeFakeScheduler();
@@ -295,7 +296,7 @@ describe("@mandujs/core/scheduler — dev-mode skip", () => {
   });
 });
 
-describe("@mandujs/core/scheduler — timeout", () => {
+describe("@mandujs/core/compat/scheduler — timeout", () => {
   it("marks the tick as completed after timeoutMs and clears inFlight so the next tick can fire", async () => {
     const { scheduleFn, tick } = makeFakeScheduler();
     // Silence the expected console.warn.
@@ -340,7 +341,7 @@ describe("@mandujs/core/scheduler — timeout", () => {
   });
 });
 
-describe("@mandujs/core/scheduler — shutdown", () => {
+describe("@mandujs/core/compat/scheduler — shutdown", () => {
   it("stop() waits for in-flight handlers to complete before resolving", async () => {
     const { scheduleFn, tick } = makeFakeScheduler();
 
@@ -443,7 +444,7 @@ describe("@mandujs/core/scheduler — shutdown", () => {
   });
 });
 
-describe("@mandujs/core/scheduler — status shape", () => {
+describe("@mandujs/core/compat/scheduler — status shape", () => {
   it("returns a fully populated CronJobStatus for every registered job", () => {
     const { scheduleFn } = makeFakeScheduler();
     const jobs: Record<string, CronJobConfig> = {
@@ -489,7 +490,7 @@ describe("@mandujs/core/scheduler — status shape", () => {
   });
 });
 
-describe("@mandujs/core/scheduler — public defineCron probe", () => {
+describe("@mandujs/core/compat/scheduler — public defineCron probe", () => {
   it("throws a clear error when Bun.cron is unavailable and start() is invoked", () => {
     // Bun 1.3.10 (the test environment here) does not expose Bun.cron. The
     // module should surface a readable error that names the required version.

package/src/scheduler/index.ts

@@ -31,7 +31,7 @@
  *
  * @example
  * ```ts
- * import { defineCron } from "@mandujs/core/scheduler";
+ * import { defineCron } from "@mandujs/core/compat/scheduler/index";
  *
  * const jobs = defineCron({
  *   "clean:sessions": {
@@ -110,7 +110,8 @@ export interface CronJobConfig {
    * against this zone. **Not supported on Cloudflare Workers** — Workers cron
    * triggers always fire in UTC; emit a warning but still emit the crontab.
    *
-   * Default: host system timezone (Bun.cron's default).
+   * Default: `"UTC"`. Mandu passes the zone explicitly so Bun 1.4's local-time
+   * default does not change existing schedules or diverge from Workers cron.
    */
   timezone?: string;
   /**
@@ -198,6 +199,7 @@ interface CronJobHandle {
 export type CronScheduleFn = (
   schedule: string,
   handler: () => void | Promise<void>,
+  options?: { tz?: string },
 ) => CronJobHandle | void;
 
 interface BunCronGlobal {
@@ -212,7 +214,7 @@ function getBunCron(): CronScheduleFn {
   const g = globalThis as unknown as { Bun?: BunCronGlobal };
   if (!g.Bun || typeof g.Bun.cron !== "function") {
     throw new Error(
-      "[@mandujs/core/scheduler] Bun.cron is unavailable — this module requires the Bun runtime (>= 1.3.12).",
+      "[@mandujs/core/scheduler] Bun.cron is unavailable — this module requires the Bun runtime (>= 1.4.0).",
     );
   }
   return g.Bun.cron;
@@ -255,7 +257,9 @@ export function defineCron(
   // Probe lazily so `defineCron({})` with no entries can still be called in
   // environments without `Bun.cron`. When the user actually goes to `start()`,
   // the probe runs — matching `getBunPassword()` behaviour.
-  return _defineCronWith(jobs, (schedule, handler) => getBunCron()(schedule, handler));
+  return _defineCronWith(jobs, (schedule, handler, options) =>
+    getBunCron()(schedule, handler, options),
+  );
 }
 
 /**
@@ -499,7 +503,9 @@ export function _defineCronWith(
     for (const state of states.values()) {
       if (state.skipped) continue;
       const tick = makeTickHandler(state);
-      const handle = scheduleFn(state.config.schedule, tick);
+      const handle = scheduleFn(state.config.schedule, tick, {
+        tz: state.config.timezone ?? "UTC",
+      });
       state.handle = handle ?? null;
     }
   }