@damurka/jovian 0.1.0 → 0.1.2

package/lib/session/runtimes.js

@@ -0,0 +1,80 @@
+import { execFileSync } from 'node:child_process';
+const runCommand = (command, args) => {
+    try {
+        const output = execFileSync(command, args, {
+            encoding: 'utf8',
+            timeout: 10_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true
+        });
+        const lines = output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        return lines[lines.length - 1];
+    }
+    catch {
+        return undefined;
+    }
+};
+const defaultContext = () => ({ run: runCommand, env: process.env, platform: process.platform });
+/**
+ * Where R lives, when the caller did not say: $R_HOME, else what `R RHOME`
+ * prints (R's own answer, valid on every platform, if R is on PATH), else on
+ * Windows the install path R's installer records in the registry.
+ */
+export function discoverRHome(context = defaultContext()) {
+    if (context.env.R_HOME)
+        return context.env.R_HOME;
+    const fromR = context.run('R', ['RHOME']);
+    if (fromR)
+        return fromR;
+    if (context.platform === 'win32') {
+        for (const hive of ['HKLM', 'HKCU']) {
+            const line = context.run('reg', ['query', `${hive}\\SOFTWARE\\R-core\\R`, '/v', 'InstallPath']);
+            const match = line?.match(/InstallPath\s+REG_SZ\s+(.+)$/);
+            if (match?.[1])
+                return match[1].trim();
+        }
+    }
+    return undefined;
+}
+/**
+ * Which Python to embed, when the caller did not say: $PYTHONHOME, else the
+ * installation prefix of the first python on PATH. sys.base_prefix, not
+ * sys.prefix: inside a virtual environment the latter is the venv, which has
+ * no libpython to load.
+ */
+export function discoverPythonHome(context = defaultContext()) {
+    if (context.env.PYTHONHOME)
+        return context.env.PYTHONHOME;
+    const script = 'import sys; print(sys.base_prefix)';
+    const candidates = [
+        ['python3', ['-c', script]],
+        ['python', ['-c', script]]
+    ];
+    if (context.platform === 'win32')
+        candidates.push(['py', ['-3', '-c', script]]);
+    for (const [command, args] of candidates) {
+        const home = context.run(command, args);
+        if (home)
+            return home;
+    }
+    return undefined;
+}
+/**
+ * The options with rHome (R sessions) or pythonHome (Python sessions) filled
+ * in when the caller left them out and the runtime could be found. Anything
+ * the caller passed is kept as it is; if nothing is found the field stays
+ * unset, and the kernel reports what it could not find.
+ */
+export function withDiscoveredRuntime(options, context = defaultContext()) {
+    if (options.kernelType === 'python') {
+        if (options.pythonHome)
+            return options;
+        const pythonHome = discoverPythonHome(context);
+        return pythonHome ? { ...options, pythonHome } : options;
+    }
+    if (options.rHome)
+        return options;
+    const rHome = discoverRHome(context);
+    return rHome ? { ...options, rHome } : options;
+}
+//# sourceMappingURL=runtimes.js.map

package/lib/session/session-manager.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'events';
-import type { CommInfoReplyContent, CompleteReplyContent, EngineOptions, ExecutionHistoryEntry, ExecutionOptions, ExecutionResult, InspectReplyContent, IsCompleteReplyContent, KernelHistoryEntry, KernelHistoryOptions, KernelInfoReplyContent, SessionStatusInfo, ShinyAppHandle, ShinyAppOptions } from '../types/index.js';
+import type { CommInfoReplyContent, CompleteReplyContent, EngineOptions, ExecutionHistoryEntry, ExecutionOptions, ExecutionResult, InspectReplyContent, IsCompleteReplyContent, KernelHistoryEntry, KernelHistoryOptions, KernelInfoReplyContent, LoggerFunction, LogThreshold, SessionManagerOptions, SessionStatusInfo, ShinyAppHandle, ShinyAppOptions } from '../types/index.js';
 import type { ExecutionState } from '../types/messages.js';
 import { SupervisorClient, type SessionConnectionInfo } from './supervisor-client.js';
 import { Comm } from './comm.js';
@@ -27,7 +27,10 @@ export declare class Session extends EventEmitter {
     private readonly executionHistory;
     private readonly executionHistoryByMsgId;
     private readonly historyStreamChars;
-    constructor(info: SessionConnectionInfo, options: EngineOptions, supervisor: SupervisorClient);
+    constructor(info: SessionConnectionInfo, options: EngineOptions, supervisor: SupervisorClient, logging?: {
+        level?: LogThreshold | undefined;
+        logger?: LoggerFunction | undefined;
+    });
     /**
      * (Re)establishes the WebSocket to this.info's session and resolves
      * once it's ready. Used both by the constructor and by restart() --
@@ -122,7 +125,7 @@ export declare class Session extends EventEmitter {
      * execute() timed out) first.
      */
     interrupt(options?: {
-        timeout?: number;
+        timeout?: number | undefined;
     }): Promise<boolean>;
     /**
      * The latest iopub `status` the kernel reported ('busy' while it is
@@ -145,7 +148,7 @@ export declare class Session extends EventEmitter {
      * shutdown_request (stop()/restart()) -- the supervisor rejects those.
      */
     request<T = any>(msgType: string, content?: Record<string, unknown>, options?: {
-        timeout?: number;
+        timeout?: number | undefined;
     }): Promise<T>;
     private trackExecutionState;
     private routeComm;
@@ -209,11 +212,20 @@ export declare class Session extends EventEmitter {
     kill(): void;
 }
 export declare class SessionManager {
+    private readonly logLevel;
+    private readonly customLogger;
+    private readonly logger;
     private readonly supervisor;
     private readonly sessions;
     private exitHandlerRegistered;
+    /**
+     * Quiet by default: only one-time setup notices, warnings and errors are
+     * printed. See SessionManagerOptions for `logLevel`, `logger` and
+     * `kernelOutput` (and the JOVIAN_LOG_LEVEL / JOVIAN_KERNEL_OUTPUT variables).
+     */
+    constructor(options?: SessionManagerOptions);
     /** Creates a new R session in its own OS process and waits for it to be ready. */
-    createSession(options?: EngineOptions): Promise<Session>;
+    createSession(requested?: EngineOptions): Promise<Session>;
     /** Gracefully stops every session managed by this instance. */
     stopAll(): Promise<void>;
     /**

package/lib/session/session-manager.js

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
-import { Logger } from '../utils/logger.js';
+import { Logger, defaultLogLevel } from '../utils/logger.js';
 import { MessageRouter } from '../messaging/message-router.js';
 import { ExecutionQueue } from '../execution/execution-queue.js';
 import { MiddlewareChain } from '../middleware/middleware-chain.js';
@@ -12,6 +12,9 @@ import { ErrorHandler } from '../handlers/error-handler.js';
 import { DisplayHandler } from '../handlers/display-handler.js';
 import { findFreePort, waitForPort } from '../utils/network.js';
 import { SupervisorClient } from './supervisor-client.js';
+import { withDiscoveredRuntime } from './runtimes.js';
+import { ensureRPackages } from './r-setup.js';
+import { bundledHeraSource } from './native-paths.js';
 import { Comm } from './comm.js';
 const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
 // How long stop() waits for the kernel's shutdown_reply after the
@@ -86,12 +89,12 @@ export class Session extends EventEmitter {
     executionHistory = [];
     executionHistoryByMsgId = new Map();
     historyStreamChars = new WeakMap();
-    constructor(info, options, supervisor) {
+    constructor(info, options, supervisor, logging = {}) {
         super();
         this.info = info;
         this.currentOptions = options;
         this.supervisor = supervisor;
-        this.logger = new Logger(options.logger);
+        this.logger = new Logger(options.logger ?? logging.logger, logging.level);
         this.on('message', (message) => {
             this.recordExecutionHistory(message);
             this.settleRequest(message);
@@ -213,7 +216,7 @@ export class Session extends EventEmitter {
         // The supervisor replaces a session's options wholesale, so send the
         // merge -- a restart that only switches rHome must keep the
         // workingDirectory, rLibs, ... the session was created with.
-        const mergedOptions = options ? { ...this.currentOptions, ...options } : undefined;
+        const mergedOptions = options ? withDiscoveredRuntime({ ...this.currentOptions, ...options }) : undefined;
         // Reassigned synchronously, before awaiting anything below, so a
         // concurrent execute()/createShiny() call that reads this.readyPromise
         // while the restart is still in flight waits for the new connection
@@ -222,6 +225,8 @@ export class Session extends EventEmitter {
         const shutdownReply = this.watchFor('shutdown_reply');
         this.readyPromise = (async () => {
             try {
+                if (mergedOptions)
+                    await ensureRPackages(mergedOptions, this.logger);
                 await this.supervisor.restartSession(this.info, mergedOptions);
                 if (mergedOptions) {
                     this.currentOptions = mergedOptions;
@@ -776,13 +781,34 @@ export class Session extends EventEmitter {
     }
 }
 export class SessionManager {
-    supervisor = new SupervisorClient(new Logger());
+    logLevel;
+    customLogger;
+    logger;
+    supervisor;
     sessions = new Set();
     exitHandlerRegistered = false;
+    /**
+     * Quiet by default: only one-time setup notices, warnings and errors are
+     * printed. See SessionManagerOptions for `logLevel`, `logger` and
+     * `kernelOutput` (and the JOVIAN_LOG_LEVEL / JOVIAN_KERNEL_OUTPUT variables).
+     */
+    constructor(options = {}) {
+        this.logLevel = options.logLevel ?? defaultLogLevel();
+        this.customLogger = options.logger;
+        this.logger = new Logger(this.customLogger, this.logLevel);
+        const verbose = this.logLevel === 'trace' || this.logLevel === 'debug';
+        const forwardKernelOutput = options.kernelOutput ?? (Boolean(process.env.JOVIAN_KERNEL_OUTPUT) || verbose);
+        this.supervisor = new SupervisorClient(this.logger, { forwardKernelOutput });
+    }
     /** Creates a new R session in its own OS process and waits for it to be ready. */
-    async createSession(options = {}) {
+    async createSession(requested = {}) {
+        // Finds R / Python when rHome / pythonHome were not given (see runtimes.ts).
+        // An installed package brings its own copy of hera (none in a source checkout).
+        const options = withDiscoveredRuntime(requested.heraSrcPath ? requested : { ...requested, heraSrcPath: bundledHeraSource() });
+        // First R session only: installs hera and what it needs (see r-setup.ts).
+        await ensureRPackages(options, this.logger);
         const info = await this.supervisor.createSession(options);
-        const session = new Session(info, options, this.supervisor);
+        const session = new Session(info, options, this.supervisor, { level: this.logLevel, logger: this.customLogger });
         this.sessions.add(session);
         this.registerExitHandler();
         try {
@@ -798,7 +824,7 @@ export class SessionManager {
     async stopAll() {
         await Promise.all([...this.sessions].map((session) => session.stop()));
         this.sessions.clear();
-        this.supervisor.kill();
+        this.supervisor.kill(true);
     }
     /**
      * Forcibly terminates every session. Prefer stopAll(), but a session

package/lib/session/supervisor-client.d.ts

@@ -10,7 +10,14 @@ export declare class SupervisorClient {
     private child;
     private readyPromise;
     private readonly logger;
-    constructor(logger: Logger);
+    private readonly forwardKernelOutput;
+    private readonly recentOutput;
+    constructor(logger: Logger, options?: {
+        forwardKernelOutput?: boolean;
+    });
+    private rememberOutput;
+    /** The message plus what the kernels said just before, when that was not already printed. */
+    private withKernelOutput;
     private ensureStarted;
     private spawnSupervisor;
     createSession(options: EngineOptions): Promise<SessionConnectionInfo>;
@@ -30,7 +37,11 @@ export declare class SupervisorClient {
      * close this session and create a new one just to pick a different R.
      */
     restartSession(info: SessionConnectionInfo, options?: Partial<EngineOptions>): Promise<void>;
-    /** Skips graceful per-session shutdown -- only for cleanup on the way out. */
-    kill(): void;
+    /**
+     * Skips graceful per-session shutdown -- only for cleanup on the way out.
+     * `expected` is the normal end of stopAll(), after every session was
+     * stopped: not worth a warning.
+     */
+    kill(expected?: boolean): void;
 }
 //# sourceMappingURL=supervisor-client.d.ts.map

package/lib/session/supervisor-client.js

@@ -33,8 +33,29 @@ export class SupervisorClient {
     child;
     readyPromise;
     logger;
-    constructor(logger) {
+    forwardKernelOutput;
+    // The supervisor's stderr is where every kernel's start-up output ends up
+    // ([elara] ..., [carpo] ...). It is kept, not printed, unless asked for,
+    // and attached to the error when a kernel fails to start.
+    recentOutput = [];
+    constructor(logger, options = {}) {
         this.logger = logger;
+        this.forwardKernelOutput = options.forwardKernelOutput ?? false;
+    }
+    rememberOutput(line) {
+        if (!line.trim())
+            return;
+        this.recentOutput.push(line);
+        if (this.recentOutput.length > 200)
+            this.recentOutput.shift();
+    }
+    /** The message plus what the kernels said just before, when that was not already printed. */
+    withKernelOutput(message) {
+        if (this.forwardKernelOutput || this.recentOutput.length === 0)
+            return message;
+        const notable = this.recentOutput.filter((line) => /error|fatal|warning|failed|cannot|not found|no such/i.test(line));
+        const lines = (notable.length > 0 ? notable : this.recentOutput).slice(-8);
+        return `${message}\nKernel output:\n  ${lines.join('\n  ')}`;
     }
     ensureStarted() {
         if (!this.readyPromise) {
@@ -48,7 +69,11 @@ export class SupervisorClient {
             this.logger.debug(`Spawning supervisor process from: ${exePath}`);
             const child = spawn(exePath, [], { stdio: ['ignore', 'pipe', 'pipe'] });
             this.child = child;
-            child.stderr?.on('data', (chunk) => process.stderr.write(chunk));
+            createInterface({ input: child.stderr }).on('line', (line) => {
+                this.rememberOutput(line);
+                if (this.forwardKernelOutput)
+                    process.stderr.write(`${line}\n`);
+            });
             const rl = createInterface({ input: child.stdout });
             const onLine = (line) => {
                 let message;
@@ -87,7 +112,7 @@ export class SupervisorClient {
         });
         const body = await res.json();
         if (!res.ok || !body.sessionId) {
-            throw new Error(body.error ?? `Supervisor failed to create session (HTTP ${res.status})`);
+            throw new Error(this.withKernelOutput(body.error ?? `Supervisor failed to create session (HTTP ${res.status})`));
         }
         return { sessionId: body.sessionId, httpBase, wsBase: `ws://127.0.0.1:${wsPort}` };
     }
@@ -126,10 +151,18 @@ export class SupervisorClient {
             throw new Error(body.error ?? `Supervisor failed to restart session ${info.sessionId} (HTTP ${res.status})`);
         }
     }
-    /** Skips graceful per-session shutdown -- only for cleanup on the way out. */
-    kill() {
+    /**
+     * Skips graceful per-session shutdown -- only for cleanup on the way out.
+     * `expected` is the normal end of stopAll(), after every session was
+     * stopped: not worth a warning.
+     */
+    kill(expected = false) {
         if (this.child && !this.child.killed) {
-            this.logger.warn(`Force-killing supervisor process (pid ${this.child.pid})`);
+            const message = `Force-killing supervisor process (pid ${this.child.pid})`;
+            if (expected)
+                this.logger.debug(message);
+            else
+                this.logger.warn(message);
             this.child.kill();
         }
     }

package/lib/types/engine.d.ts

@@ -1,5 +1,29 @@
 import type { JupyterMessage } from './messages.js';
-export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+/**
+ * 'notice' is for the few things a user should be told even when the library
+ * is otherwise quiet (e.g. the one-time install of the R packages, which takes
+ * a while); it sits between 'info' and 'warn'.
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'notice' | 'warn' | 'error';
+/** What the built-in console logger prints: this level and above; 'silent' prints nothing. */
+export type LogThreshold = LogLevel | 'silent';
+export interface SessionManagerOptions {
+    /**
+     * How much the library prints to the console (default 'notice': one-time
+     * setup messages, warnings and errors; env JOVIAN_LOG_LEVEL sets the
+     * default). Ignored for messages sent to `logger`, which receives all of them.
+     */
+    logLevel?: LogThreshold | undefined;
+    /** Receives every log message instead of the console. */
+    logger?: LoggerFunction | undefined;
+    /**
+     * Print the kernels' own start-up output (the `[elara]` / `[carpo]` lines)
+     * to stderr as it happens. Off by default -- it is included in the error
+     * when a kernel fails to start -- and on when logLevel is 'debug' or
+     * 'trace' or env JOVIAN_KERNEL_OUTPUT is set.
+     */
+    kernelOutput?: boolean | undefined;
+}
 export type LoggerFunction = (level: LogLevel, message: string, data?: any) => void;
 export interface EngineOptions {
     /**
@@ -9,12 +33,13 @@ export interface EngineOptions {
      * supervisor actually uses (native/src/themisto/session_registry.cpp's
      * SessionOptions::kernelType) and which kernel executable it spawns.
      */
-    kernelType?: 'r' | 'python';
-    rHome?: string;
-    rPath?: string;
-    rLibs?: string;
+    kernelType?: 'r' | 'python' | undefined;
+    /** R installation (`R RHOME`). Found from $R_HOME, `R RHOME` or the Windows registry when omitted. */
+    rHome?: string | undefined;
+    rPath?: string | undefined;
+    rLibs?: string | undefined;
     /** Directory containing the pandoc binary, for bundled R installs that don't ship it on PATH. */
-    pandocPath?: string;
+    pandocPath?: string | undefined;
     /**
      * Source directory of the 'hera' R package (packages/hera in this repo).
      * When set, Elara installs it via remotes::install_local() if it is
@@ -23,13 +48,13 @@ export interface EngineOptions {
      * already installed in the library -- install or update it with
      * `npm run hera:install`.
      */
-    heraSrcPath?: string;
-    /** Only used when kernelType is 'python' -- Carpo's equivalent of rHome. */
-    pythonHome?: string;
+    heraSrcPath?: string | undefined;
+    /** Only used when kernelType is 'python' -- Carpo's equivalent of rHome. Found from $PYTHONHOME or `python3`/`python` on PATH when omitted. */
+    pythonHome?: string | undefined;
     /** Only used when kernelType is 'python' -- Carpo's equivalent of rPath. */
-    pythonPath?: string;
+    pythonPath?: string | undefined;
     /** Only used when kernelType is 'python' -- not yet consulted by Carpo itself (see carpo::EnvironmentConfig). */
-    venvPath?: string;
+    venvPath?: string | undefined;
     /**
      * Directory the kernel process starts in -- what `getwd()` (R) /
      * `os.getcwd()` (Python) report and what relative paths resolve against.
@@ -37,44 +62,44 @@ export interface EngineOptions {
      * (i.e. the calling process's), which is rarely what you want for a
      * notebook/project: set it to the project or document folder.
      */
-    workingDirectory?: string;
-    queueSize?: number;
-    enableLogging?: boolean;
-    enableMetrics?: boolean;
-    logger?: LoggerFunction;
+    workingDirectory?: string | undefined;
+    queueSize?: number | undefined;
+    enableLogging?: boolean | undefined;
+    enableMetrics?: boolean | undefined;
+    logger?: LoggerFunction | undefined;
 }
 export type EngineState = 'idle' | 'starting' | 'running' | 'stopping' | 'stopped' | 'error';
 export interface ExecutionOptions {
-    silent?: boolean;
-    storeHistory?: boolean;
-    allowStdin?: boolean;
+    silent?: boolean | undefined;
+    storeHistory?: boolean | undefined;
+    allowStdin?: boolean | undefined;
     /**
      * When this execution fails, abort every execute() still waiting behind
      * it in the queue instead of running them (Jupyter's stop_on_error) --
      * their results come back with `aborted: true` and nothing having run.
      * Also forwarded to the kernel in the execute_request itself.
      */
-    stopOnError?: boolean;
+    stopOnError?: boolean | undefined;
     /**
      * Expressions to evaluate in the kernel right after the code runs, as
      * {name: expression} (Jupyter's user_expressions). Only evaluated when
      * the code succeeded; each result -- or its own error -- comes back in
      * `ExecutionResult.userExpressions` under the same name.
      */
-    userExpressions?: Record<string, string>;
+    userExpressions?: Record<string, string> | undefined;
     /**
      * Milliseconds to wait for the execution to finish before giving up
      * (default 30000; 0 = no timeout, for calls meant to run indefinitely
      * such as a Shiny app).
      */
-    timeout?: number;
+    timeout?: number | undefined;
     /**
      * When the timeout fires, also send the kernel an interrupt (default
      * true) so it stops the code instead of carrying on with work no one is
      * waiting for -- which would otherwise block everything queued behind it.
      * Set false to leave the kernel running after a timeout.
      */
-    interruptOnTimeout?: boolean;
+    interruptOnTimeout?: boolean | undefined;
 }
 /** One evaluated user expression: its rich value, or the error evaluating it raised. */
 export type UserExpressionResult = {
@@ -131,19 +156,19 @@ export interface ExecutionHistoryEntry {
  */
 export interface KernelHistoryOptions {
     /** Defaults to 'tail' -- the n most recent executions. */
-    histAccessType?: 'tail' | 'range' | 'search';
+    histAccessType?: 'tail' | 'range' | 'search' | undefined;
     /** Include each entry's output alongside its input. Defaults to false -- the kernel doesn't actually record output today either way, so this currently only ever comes back empty. */
-    output?: boolean;
-    raw?: boolean;
+    output?: boolean | undefined;
+    raw?: boolean | undefined;
     /** Max entries to return ('tail'/'search'). Defaults to 100. */
-    n?: number;
+    n?: number | undefined;
     /** 'range' only. */
-    session?: number;
-    start?: number;
-    stop?: number;
+    session?: number | undefined;
+    start?: number | undefined;
+    stop?: number | undefined;
     /** 'search' only -- a glob pattern (*, ?). */
-    pattern?: string;
-    unique?: boolean;
+    pattern?: string | undefined;
+    unique?: boolean | undefined;
 }
 /**
  * One entry from a real history_reply: [session, line_number, input], or
@@ -179,13 +204,13 @@ export interface ShinyAppOptions {
     /** Directory containing the Shiny app (server.R/ui.R or app.R). */
     appDir: string;
     /** Defaults to an OS-assigned free port. */
-    port?: number;
+    port?: number | undefined;
     /** Defaults to '127.0.0.1'. */
-    host?: string;
+    host?: string | undefined;
     /** Defaults to false -- the caller decides how/where to display the app. */
-    launchBrowser?: boolean;
+    launchBrowser?: boolean | undefined;
     /** Max time to wait for the app to start accepting connections, in ms. Defaults to 10000. */
-    readyTimeout?: number;
+    readyTimeout?: number | undefined;
     /**
      * Environment variables to set (via Sys.setenv()) in the R session
      * before launching the app -- e.g. rmncah's app.R reads
@@ -195,7 +220,7 @@ export interface ShinyAppOptions {
      * that reads them after runApp() starts, since Sys.setenv() itself runs
      * synchronously right before it in the same execute() call.
      */
-    env?: Record<string, string>;
+    env?: Record<string, string> | undefined;
 }
 export interface ShinyAppHandle {
     host: string;

package/lib/utils/logger.d.ts

@@ -1,11 +1,22 @@
-import type { LoggerFunction } from '../types/index.js';
+import type { LogLevel, LoggerFunction, LogThreshold } from '../types/index.js';
 export declare function timestamp(): string;
+/** True when a message at `level` passes `threshold`. */
+export declare function passes(threshold: LogThreshold, level: LogLevel): boolean;
+/** The console threshold when none is given: $JOVIAN_LOG_LEVEL if it names one, else 'notice'. */
+export declare function defaultLogLevel(env?: Record<string, string | undefined>): LogThreshold;
 export declare class Logger {
-    private customLogger?;
-    constructor(customLogger?: LoggerFunction);
+    private readonly customLogger;
+    private readonly threshold;
+    /**
+     * A custom logger receives every message (it does its own filtering, as it
+     * always has); `threshold` only limits what is printed to the console.
+     */
+    constructor(customLogger?: LoggerFunction, threshold?: LogThreshold);
+    private emit;
     trace(message: string, data?: any): void;
     debug(message: string, data?: any): void;
     info(message: string, data?: any): void;
+    notice(message: string, data?: any): void;
     warn(message: string, data?: any): void;
     error(message: string, error?: any): void;
 }

package/lib/utils/logger.js

@@ -9,50 +9,58 @@ export function timestamp() {
     return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ` +
         `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}.${pad(now.getMilliseconds(), 3)}`;
 }
+const ORDER = { trace: 0, debug: 1, info: 2, notice: 3, warn: 4, error: 5, silent: 6 };
+/** True when a message at `level` passes `threshold`. */
+export function passes(threshold, level) {
+    return ORDER[level] >= ORDER[threshold];
+}
+/** The console threshold when none is given: $JOVIAN_LOG_LEVEL if it names one, else 'notice'. */
+export function defaultLogLevel(env = process.env) {
+    const wanted = env.JOVIAN_LOG_LEVEL?.trim().toLowerCase();
+    return wanted && wanted in ORDER ? wanted : 'notice';
+}
 export class Logger {
     customLogger;
-    constructor(customLogger) {
+    threshold;
+    /**
+     * A custom logger receives every message (it does its own filtering, as it
+     * always has); `threshold` only limits what is printed to the console.
+     */
+    constructor(customLogger, threshold = defaultLogLevel()) {
         this.customLogger = customLogger;
+        this.threshold = threshold;
     }
-    trace(message, data) {
+    emit(level, message, data) {
         if (this.customLogger) {
-            this.customLogger('trace', message, data);
-        }
-        else {
-            console.log(`${timestamp()} [trace] ${message}`, data ? data : '');
+            this.customLogger(level, message, data);
+            return;
         }
+        if (!passes(this.threshold, level))
+            return;
+        const print = level === 'warn' ? console.warn : level === 'error' ? console.error : console.log;
+        const line = `${timestamp()} [${level}] ${message}`;
+        if (data)
+            print(line, data);
+        else
+            print(line);
+    }
+    trace(message, data) {
+        this.emit('trace', message, data);
     }
     debug(message, data) {
-        if (this.customLogger) {
-            this.customLogger('debug', message, data);
-        }
-        else {
-            console.log(`${timestamp()} [debug] ${message}`, data ? data : '');
-        }
+        this.emit('debug', message, data);
     }
     info(message, data) {
-        if (this.customLogger) {
-            this.customLogger('info', message, data);
-        }
-        else {
-            console.log(`${timestamp()} [info] ${message}`, data ? data : '');
-        }
+        this.emit('info', message, data);
+    }
+    notice(message, data) {
+        this.emit('notice', message, data);
     }
     warn(message, data) {
-        if (this.customLogger) {
-            this.customLogger('warn', message, data);
-        }
-        else {
-            console.warn(`${timestamp()} [warn] ${message}`, data ? data : '');
-        }
+        this.emit('warn', message, data);
     }
     error(message, error) {
-        if (this.customLogger) {
-            this.customLogger('error', message, error);
-        }
-        else {
-            console.error(`${timestamp()} [error] ${message}`, error ? error : '');
-        }
+        this.emit('error', message, error);
     }
 }
 //# sourceMappingURL=logger.js.map