@jay-framework/logger 0.12.0

package/dist/index.d.mts

@@ -0,0 +1,130 @@
+/**
+ * Jay Framework Logger
+ *
+ * Centralized logging for all Jay packages. The default implementation
+ * uses console methods. CLIs replace this with level-aware implementations.
+ */
+type LogLevel = 'silent' | 'info' | 'verbose';
+/**
+ * Core logging interface used throughout Jay packages.
+ *
+ * Log method semantics:
+ * - `important()`: Always shown unless silent (startup messages, major events)
+ * - `info()`: Only shown in verbose mode (detailed operational info)
+ * - `warn()`: Shown unless silent (warnings that don't prevent operation)
+ * - `error()`: Always shown (errors that need attention)
+ */
+interface JayLogger {
+    /** Log important messages - shown in default mode (startup, major events) */
+    important: (msg: string) => void;
+    /** Log info messages - shown only in verbose mode */
+    info: (msg: string) => void;
+    /** Log warnings - shown unless silent */
+    warn: (msg: string) => void;
+    /** Log errors - always shown */
+    error: (msg: string) => void;
+}
+/**
+ * Request timing interface for dev server performance tracking.
+ */
+interface RequestTiming {
+    /** Record Vite SSR module compilation time */
+    recordViteSsr: (ms: number) => void;
+    /** Record parameter loading time (jay-html parsing, manifest) */
+    recordParams: (ms: number) => void;
+    /** Record slow render phase time */
+    recordSlowRender: (ms: number) => void;
+    /** Record fast render phase time */
+    recordFastRender: (ms: number) => void;
+    /** Record Vite client transform time */
+    recordViteClient: (ms: number) => void;
+    /** End the request and print final timing line */
+    end: () => void;
+}
+/**
+ * Extended logger with request timing support (for dev server).
+ */
+interface JayDevLogger extends JayLogger {
+    /** Start timing a new request. Returns timing recorder. */
+    startRequest: (method: string, path: string) => RequestTiming;
+}
+/**
+ * Get the current logger instance.
+ *
+ * @example
+ * ```typescript
+ * import { getLogger } from '@jay-framework/logger';
+ *
+ * const log = getLogger();
+ * log.info('[MyModule] Starting operation...');
+ * log.error('[MyModule] Operation failed!');
+ * ```
+ */
+declare function getLogger(): JayLogger;
+/**
+ * Replace the current logger with a custom implementation.
+ * Typically called by CLIs at startup to set log level.
+ *
+ * @example
+ * ```typescript
+ * import { setLogger, type JayLogger } from '@jay-framework/logger';
+ *
+ * const cliLogger: JayLogger = {
+ *   important: (msg) => console.log(msg),
+ *   info: verbose ? (msg) => console.log(msg) : () => {},
+ *   warn: quiet ? () => {} : (msg) => console.warn(msg),
+ *   error: (msg) => console.error(msg),
+ * };
+ *
+ * setLogger(cliLogger);
+ * ```
+ */
+declare function setLogger(logger: JayLogger): void;
+/**
+ * Reset to the default console-based logger.
+ * Useful for testing.
+ */
+declare function resetLogger(): void;
+/**
+ * Create a log-level-aware logger.
+ * Convenience factory for CLIs.
+ *
+ * @example
+ * ```typescript
+ * import { createLogger, setLogger } from '@jay-framework/logger';
+ *
+ * // From CLI flags
+ * const level = quiet ? 'silent' : verbose ? 'verbose' : 'info';
+ * setLogger(createLogger(level));
+ * ```
+ */
+declare function createLogger(level: LogLevel): JayLogger;
+/**
+ * Get the dev logger with timing support.
+ * Returns undefined if not set (non-dev-server context).
+ */
+declare function getDevLogger(): JayDevLogger | undefined;
+/**
+ * Set the dev logger with timing support.
+ * Called by dev server at startup.
+ */
+declare function setDevLogger(logger: JayDevLogger): void;
+/**
+ * Reset the dev logger.
+ */
+declare function resetDevLogger(): void;
+/**
+ * Create a dev logger with timing support.
+ * Displays request timing in a single updating line.
+ *
+ * @example
+ * ```typescript
+ * import { createDevLogger, setDevLogger } from '@jay-framework/logger';
+ *
+ * const level = quiet ? 'silent' : verbose ? 'verbose' : 'info';
+ * setDevLogger(createDevLogger(level));
+ * ```
+ */
+declare function createDevLogger(level: LogLevel): JayDevLogger;
+
+export { type JayDevLogger, type JayLogger, type LogLevel, type RequestTiming, createDevLogger, createLogger, getDevLogger, getLogger, resetDevLogger, resetLogger, setDevLogger, setLogger };

package/dist/index.mjs

@@ -0,0 +1,130 @@
+const defaultLogger = {
+  important: (msg) => console.log(msg),
+  info: (msg) => console.log(msg),
+  warn: (msg) => console.warn(msg),
+  error: (msg) => console.error(msg)
+};
+let currentLogger = defaultLogger;
+function getLogger() {
+  return currentLogger;
+}
+function setLogger(logger) {
+  currentLogger = logger;
+}
+function resetLogger() {
+  currentLogger = defaultLogger;
+}
+function createLogger(level) {
+  const isSilent = level === "silent";
+  const isVerbose = level === "verbose";
+  return {
+    important: isSilent ? () => {
+    } : (msg) => console.log(msg),
+    info: isVerbose ? (msg) => console.log(msg) : () => {
+    },
+    warn: isSilent ? () => {
+    } : (msg) => console.warn(msg),
+    error: (msg) => console.error(msg)
+  };
+}
+let currentDevLogger;
+function getDevLogger() {
+  return currentDevLogger;
+}
+function setDevLogger(logger) {
+  currentDevLogger = logger;
+  currentLogger = logger;
+}
+function resetDevLogger() {
+  currentDevLogger = void 0;
+}
+function createDevLogger(level) {
+  const baseLogger = createLogger(level);
+  const isSilent = level === "silent";
+  const isTTY = process.stdout.isTTY;
+  function formatTiming(state) {
+    const parts = [];
+    if (state.viteSsr > 0)
+      parts.push(`vite-ssr: ${state.viteSsr}ms`);
+    if (state.params > 0)
+      parts.push(`params: ${state.params}ms`);
+    if (state.slowRender > 0)
+      parts.push(`slow: ${state.slowRender}ms`);
+    if (state.fastRender > 0)
+      parts.push(`fast: ${state.fastRender}ms`);
+    if (state.viteClient > 0)
+      parts.push(`vite-client: ${state.viteClient}ms`);
+    const total = Date.now() - state.startTime;
+    const timingStr = parts.length > 0 ? `[${parts.join(" | ")}] ` : "";
+    return `${state.method} ${state.path} ${timingStr}${total}ms`;
+  }
+  function createTiming(method, path) {
+    const state = {
+      method,
+      path,
+      startTime: Date.now(),
+      viteSsr: 0,
+      params: 0,
+      slowRender: 0,
+      fastRender: 0,
+      viteClient: 0
+    };
+    let lastLineLength = 0;
+    function updateLine() {
+      if (isSilent)
+        return;
+      const line = formatTiming(state);
+      if (isTTY) {
+        const clearStr = "\r" + " ".repeat(lastLineLength) + "\r";
+        process.stdout.write(clearStr + line);
+        lastLineLength = line.length;
+      }
+    }
+    return {
+      recordViteSsr: (ms) => {
+        state.viteSsr += ms;
+        updateLine();
+      },
+      recordParams: (ms) => {
+        state.params += ms;
+        updateLine();
+      },
+      recordSlowRender: (ms) => {
+        state.slowRender += ms;
+        updateLine();
+      },
+      recordFastRender: (ms) => {
+        state.fastRender += ms;
+        updateLine();
+      },
+      recordViteClient: (ms) => {
+        state.viteClient += ms;
+        updateLine();
+      },
+      end: () => {
+        if (isSilent)
+          return;
+        const line = formatTiming(state);
+        if (isTTY) {
+          const clearStr = "\r" + " ".repeat(lastLineLength) + "\r";
+          process.stdout.write(clearStr);
+        }
+        console.log(line);
+      }
+    };
+  }
+  return {
+    ...baseLogger,
+    startRequest: createTiming
+  };
+}
+export {
+  createDevLogger,
+  createLogger,
+  getDevLogger,
+  getLogger,
+  resetDevLogger,
+  resetLogger,
+  setDevLogger,
+  setLogger
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@jay-framework/logger",
+  "version": "0.12.0",
+  "license": "Apache-2.0",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "^0.12.0",
+    "@types/node": "^20.11.5",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}