Initial commit

src/types.ts

@@ -0,0 +1,61 @@
+/** A severity threshold, ordered from most to least verbose. */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "silent";
+export type LoggerEnvironment = "development" | "staging" | "production";
+export type LogData = unknown | (() => unknown);
+
+/** A structured event after its level policy has allowed it to be emitted. */
+export interface LogEvent {
+    level: Exclude<LogLevel, "silent">;
+    namespace?: string;
+    arguments: readonly unknown[];
+    timestamp: Date;
+}
+
+/** A destination for enabled log events. */
+export interface LogSink {
+    emit(event: LogEvent): void;
+}
+
+export interface LoggerOptions {
+    environment: LoggerEnvironment;
+    namespace?: string | readonly string[];
+    /** Runtime used for the default destination policy. It is inferred when omitted. */
+    runtime?: "browser" | "node";
+    /** Hard override. It takes precedence over runtime environment defaults. */
+    level?: LogLevel;
+    /** Browser-only session override source; defaults to global sessionStorage when available. */
+    sessionStorage?: Pick<Storage, "getItem">;
+    /** Node/container environment source; defaults to process.env when available. */
+    env?: Record<string, string | undefined>;
+    /** Production error destination. Browser errors go only here; Node errors also go to stderr. */
+    sentry?: LogSink | false;
+    /** Complete destination override. When provided, `sentry` and default console behavior are not used. */
+    sinks?: readonly LogSink[];
+}
+
+export interface Logger {
+    readonly namespace?: string;
+    child(namespace: string): Logger;
+    trace(...arguments_: readonly unknown[]): void;
+    debug(...arguments_: readonly unknown[]): void;
+    log(...arguments_: readonly unknown[]): void;
+    info(...arguments_: readonly unknown[]): void;
+    warn(...arguments_: readonly unknown[]): void;
+    error(...arguments_: readonly unknown[]): void;
+    assert(condition: unknown, ...arguments_: readonly unknown[]): void;
+    group(...arguments_: readonly unknown[]): void;
+    groupCollapsed(...arguments_: readonly unknown[]): void;
+    groupEnd(): void;
+    dir(item?: unknown, options?: unknown): void;
+    dirxml(...arguments_: readonly unknown[]): void;
+    table(tabularData?: unknown, properties?: readonly string[]): void;
+    clear(): void;
+    count(label?: string): void;
+    countReset(label?: string): void;
+    time(label?: string): void;
+    timeLog(label?: string, ...arguments_: readonly unknown[]): void;
+    timeEnd(label?: string): void;
+    timeStamp(label?: string): void;
+    profile(label?: string): void;
+    profileEnd(label?: string): void;
+}