@bgord/bun 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/bun",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "license": "MIT",
   "type": "module",
   "author": "Bartosz Gordon",

package/readme.md

@@ -66,7 +66,12 @@ src/
 ├── invariant-error-handler.service.ts
 ├── invariant.service.ts
 ├── jobs.service.ts
-├── logger.service.ts
+├── logger-format-error.service.ts
+├── logger-noop.adapter.ts
+├── logger-winston-local.adapter.ts
+├── logger-winston-production.adapter.ts
+├── logger-winston.adapter.ts
+├── logger.port.ts
 ├── mailer-noop.adapter.ts
 ├── mailer-smtp-with-logger.adapter.ts
 ├── mailer-smtp.adapter.ts

package/src/better-auth-logger.service.ts

@@ -1,19 +1,42 @@
 import type { LogLevel } from "better-auth";
-import { type Logger, LogLevelEnum } from "./logger.service";
+import { type LoggerPort, LogLevelEnum } from "./logger.port";
+import { formatError } from "./logger-format-error.service";
 
 export class BetterAuthLogger {
-  constructor(private readonly logger: Logger) {}
+  constructor(private readonly logger: LoggerPort) {}
 
   attach() {
     return {
       disabled: false,
       level: "debug",
-      log: (level: LogLevel | undefined, message: string, ...args: unknown[]) =>
-        this.logger[this.mapLevel(level)]({
-          message,
+      log: (lvl: LogLevel | undefined, message: string, ...args: unknown[]) => {
+        const level = this.mapLevel(lvl);
+
+        const base = {
+          component: "infra",
           operation: "better-auth",
+          message,
           metadata: { args },
-        }),
+        } as const;
+
+        switch (level) {
+          case LogLevelEnum.error: {
+            this.logger.error({
+              ...base,
+              error: formatError(args.find((a) => a instanceof Error) ?? new Error(message)),
+            });
+            break;
+          }
+          case LogLevelEnum.warn: {
+            this.logger.warn(base);
+            break;
+          }
+          default: {
+            this.logger.info(base);
+            break;
+          }
+        }
+      },
     } as const;
   }
 

package/src/command-logger.service.ts

@@ -1,7 +1,7 @@
-import type { Logger } from "./logger.service";
+import type { LoggerPort } from "./logger.port";
 
 export class CommandLogger {
-  constructor(private readonly logger: Logger) {}
+  constructor(private readonly logger: LoggerPort) {}
 
   private _handle(
     type: string,
@@ -15,6 +15,7 @@ export class CommandLogger {
 
     this.logger.info({
       message: `${commandName} emitted`,
+      component: "infra",
       operation: "command_emitted",
       metadata: commandData,
     });

package/src/decorators.service.ts

@@ -1,12 +1,12 @@
 import * as tools from "@bgord/tools";
-import type { Logger } from "./logger.service";
+import type { LoggerPort } from "./logger.port";
 
 export class DecoratorTimeoutError extends Error {}
 
 export class Decorators {
   private readonly rounding = new tools.RoundToDecimal(2);
 
-  constructor(private readonly logger: Logger) {}
+  constructor(private readonly logger: LoggerPort) {}
 
   duration() {
     const that = this;
@@ -27,6 +27,7 @@ export class Decorators {
 
         that.logger.info({
           message: `${label} duration`,
+          component: "infra",
           operation: "decorators_duration_ms",
           metadata: { durationMs: that.rounding.round(after - before) },
         });
@@ -53,6 +54,7 @@ export class Decorators {
 
         that.logger.info({
           message: `${label} inspector`,
+          component: "infra",
           operation: "decorators_inspector",
           metadata: { arguments: args, output: value },
         });

package/src/event-handler.service.ts

@@ -1,9 +1,10 @@
 import type { z } from "zod/v4";
 import type { GenericEventSchema } from "./event.types";
-import type { Logger } from "./logger.service";
+import type { LoggerPort } from "./logger.port";
+import { formatError } from "./logger-format-error.service";
 
 export class EventHandler {
-  constructor(private readonly logger: Logger) {}
+  constructor(private readonly logger: LoggerPort) {}
 
   handle<T extends { name: z.infer<GenericEventSchema["shape"]["name"]> }>(fn: (event: T) => Promise<void>) {
     return async (event: T) => {
@@ -12,8 +13,10 @@ export class EventHandler {
       } catch (error) {
         this.logger.error({
           message: `Unknown ${event.name} event handler error`,
+          component: "infra",
           operation: "unknown_event_handler_error",
-          metadata: this.logger.formatError(error),
+          error: formatError(error),
+          metadata: { name: event.name },
         });
       }
     };

package/src/event-logger.service.ts

@@ -1,7 +1,7 @@
-import type { Logger } from "./logger.service";
+import type { LoggerPort } from "./logger.port";
 
 export class EventLogger {
-  constructor(private readonly logger: Logger) {}
+  constructor(private readonly logger: LoggerPort) {}
 
   private _handle(
     type: string,
@@ -15,6 +15,7 @@ export class EventLogger {
 
     this.logger.info({
       message: `${eventName} emitted`,
+      component: "infra",
       operation: "event_emitted",
       metadata: eventData,
     });

package/src/http-logger.middleware.ts

@@ -4,7 +4,7 @@ import _ from "lodash";
 import { CacheHitEnum } from "./cache-resolver.service";
 import { CacheResponse } from "./cache-response.middleware";
 import type { CorrelationIdType } from "./correlation-id.vo";
-import type { Logger } from "./logger.service";
+import type { LoggerPort } from "./logger.port";
 
 export class HttpLogger {
   private static simplify(response: unknown) {
@@ -37,7 +37,7 @@ export class HttpLogger {
     "if-none-match",
   ];
 
-  static build = (logger: Logger) =>
+  static build = (logger: LoggerPort) =>
     createMiddleware(async (c, next) => {
       const correlationId = c.get("requestId") as CorrelationIdType;
       const info = getConnInfo(c);
@@ -64,6 +64,7 @@ export class HttpLogger {
       };
 
       logger.http({
+        component: "http",
         operation: "http_request_before",
         correlationId,
         message: "request",
@@ -96,12 +97,13 @@ export class HttpLogger {
       const durationMs = durationMsMatch?.[1] ? Number(durationMsMatch[1]) : undefined;
 
       logger.http({
+        component: "http",
         operation: "http_request_after",
         correlationId,
         message: "response",
         method,
         url,
-        responseCode: c.res.status,
+        status: c.res.status,
         durationMs,
         client,
         metadata: HttpLogger.simplify(httpRequestAfterMetadata),

package/src/index.ts

@@ -39,7 +39,12 @@ export * from "./image-exif.service";
 export * from "./invariant.service";
 export * from "./invariant-error-handler.service";
 export * from "./jobs.service";
-export * from "./logger.service";
+export * from "./logger.port";
+export * from "./logger-format-error.service";
+export * from "./logger-noop.adapter";
+export * from "./logger-winston.adapter";
+export * from "./logger-winston-local.adapter";
+export * from "./logger-winston-production.adapter";
 export * from "./mailer.port";
 export * from "./mailer-noop.adapter";
 export * from "./mailer-smtp.adapter";

package/src/jobs.service.ts

@@ -2,7 +2,8 @@ import * as tools from "@bgord/tools";
 import type { Cron } from "croner";
 import { CorrelationId } from "./correlation-id.vo";
 import { CorrelationStorage } from "./correlation-storage.service";
-import type { Logger } from "./logger.service";
+import type { LoggerPort } from "./logger.port";
+import { formatError } from "./logger-format-error.service";
 
 export type JobNameType = string;
 
@@ -41,7 +42,7 @@ export type JobProcessorType = {
 };
 
 export class JobHandler {
-  constructor(private readonly logger: Logger) {}
+  constructor(private readonly logger: LoggerPort) {}
 
   handle(jobProcessor: JobProcessorType) {
     const correlationId = CorrelationId.parse(crypto.randomUUID());
@@ -55,6 +56,7 @@ export class JobHandler {
       try {
         that.logger.info({
           message: `${jobProcessor.label} start`,
+          component: "infra",
           operation: "job_start",
           correlationId,
         });
@@ -63,6 +65,7 @@ export class JobHandler {
 
         that.logger.info({
           message: `${jobProcessor.label} success`,
+          component: "infra",
           operation: "job_success",
           correlationId,
           metadata: stopwatch.stop(),
@@ -70,12 +73,11 @@ export class JobHandler {
       } catch (error) {
         that.logger.error({
           message: `${jobProcessor.label} error`,
+          component: "infra",
           operation: "job_error",
           correlationId,
-          metadata: {
-            ...that.logger.formatError(error),
-            ...stopwatch.stop(),
-          },
+          error: formatError(error),
+          metadata: { ...stopwatch.stop() },
         });
       }
     };
@@ -85,11 +87,7 @@ export class JobHandler {
     // biome-ignore lint: lint/complexity/noUselessThisAlias
     const that = this;
 
-    return async () => {
-      that.logger.info({
-        message: `${cron.name} overrun`,
-        operation: "job_overrun",
-      });
-    };
+    return async () =>
+      that.logger.info({ message: `${cron.name} overrun`, component: "infra", operation: "job_overrun" });
   }
 }

package/src/logger-format-error.service.ts

@@ -0,0 +1,24 @@
+import type { ErrorInfo } from "./logger.port";
+
+export function formatError(err: unknown): ErrorInfo {
+  if (err instanceof Error) {
+    const code = (err as any)?.code;
+    const cause = (err as any)?.cause;
+    return {
+      name: err.name ?? "Error",
+      message: err.message ?? "Unknown error",
+      stack: err.stack, // always include if present
+      code: code != null ? String(code) : undefined,
+      cause:
+        cause instanceof Error
+          ? { name: cause.name, message: cause.message }
+          : typeof cause === "string"
+            ? { message: cause }
+            : undefined,
+    };
+  }
+  return {
+    name: "NonErrorThrown",
+    message: typeof err === "string" ? err : String(err),
+  };
+}

package/src/logger-noop.adapter.ts

@@ -0,0 +1,13 @@
+import type { LoggerPort } from "./logger.port";
+
+export class LoggerNoopAdapter implements LoggerPort {
+  warn: LoggerPort["warn"] = (_log) => {};
+  error: LoggerPort["error"] = (_log) => {};
+  info: LoggerPort["info"] = (_log) => {};
+  http: LoggerPort["http"] = (_log) => {};
+  verbose: LoggerPort["verbose"] = (_log) => {};
+  debug: LoggerPort["debug"] = (_log) => {};
+  silly: LoggerPort["silly"] = (_log) => {};
+
+  setSilent: LoggerPort["setSilent"] = (_silent) => {};
+}

package/src/logger-winston-local.adapter.ts

@@ -0,0 +1,17 @@
+import * as winston from "winston";
+import type { LogAppType, LoggerPort, LogLevelEnum } from "./logger.port";
+import { LoggerWinstonAdapter } from "./logger-winston.adapter";
+import { NodeEnvironmentEnum } from "./node-env.vo";
+
+export class LoggerWinstonLocalAdapter {
+  constructor(private readonly app: LogAppType) {}
+
+  create(level: LogLevelEnum): LoggerPort {
+    return new LoggerWinstonAdapter({
+      app: this.app,
+      environment: NodeEnvironmentEnum.local,
+      level,
+      formats: [winston.format.prettyPrint()],
+    });
+  }
+}

package/src/logger-winston-production.adapter.ts

@@ -0,0 +1,41 @@
+import { WinstonTransport as AxiomTransport } from "@axiomhq/winston";
+import * as tools from "@bgord/tools";
+import * as winston from "winston";
+import type { LogAppType, LoggerPort, LogLevelEnum } from "./logger.port";
+import { LoggerWinstonAdapter } from "./logger-winston.adapter";
+import { NodeEnvironmentEnum } from "./node-env.vo";
+
+type LoggerWinstonProductionAdapterConfigType = {
+  app: LogAppType;
+  AXIOM_API_TOKEN: string;
+};
+
+export class LoggerWinstonProductionAdapter {
+  readonly prodLogFile: string;
+
+  constructor(private readonly config: LoggerWinstonProductionAdapterConfigType) {
+    this.prodLogFile = this.createProdLogFile();
+  }
+
+  create(level: LogLevelEnum): LoggerPort {
+    const file = new winston.transports.File({
+      filename: `/var/log/${this.config.app}-${NodeEnvironmentEnum.production}.log`,
+      maxsize: tools.Size.toBytes({ unit: tools.SizeUnit.MB, value: 100 }),
+      maxFiles: 3,
+      tailable: true,
+    });
+
+    const axiom = new AxiomTransport({ token: this.config.AXIOM_API_TOKEN, dataset: this.config.app });
+
+    return new LoggerWinstonAdapter({
+      app: this.config.app,
+      environment: NodeEnvironmentEnum.production,
+      level,
+      transports: [file, axiom],
+    });
+  }
+
+  private createProdLogFile() {
+    return `/var/log/${this.config.app}-${NodeEnvironmentEnum.production}.log`;
+  }
+}

package/src/logger-winston.adapter.ts

@@ -0,0 +1,46 @@
+import * as winston from "winston";
+import { type LogAppType, type LoggerPort, LogLevelEnum } from "./logger.port";
+import type { NodeEnvironmentEnum } from "./node-env.vo";
+
+type WinstonLoggerOptions = {
+  app: LogAppType;
+  environment: NodeEnvironmentEnum;
+  level: LogLevelEnum;
+  formats?: winston.Logform.Format[];
+  transports?: winston.transport[];
+};
+
+export class LoggerWinstonAdapter implements LoggerPort {
+  private readonly logger: winston.Logger;
+
+  constructor(options: WinstonLoggerOptions) {
+    const format = winston.format.combine(
+      winston.format.errors({ stack: true }),
+      winston.format.timestamp(),
+      winston.format.json(),
+      ...(options.formats ?? []),
+    );
+
+    this.logger = winston.createLogger({
+      levels: winston.config.npm.levels,
+      level: options.level,
+      defaultMeta: { app: options.app, environment: options.environment },
+      handleExceptions: true,
+      handleRejections: true,
+      format,
+      transports: [new winston.transports.Console(), ...(options.transports ?? [])],
+    });
+  }
+
+  warn: LoggerPort["warn"] = (log) => this.logger.log({ level: LogLevelEnum.warn, ...log });
+  error: LoggerPort["error"] = (log) => this.logger.log({ level: LogLevelEnum.error, ...log });
+  info: LoggerPort["info"] = (log) => this.logger.log({ level: LogLevelEnum.info, ...log });
+  http: LoggerPort["http"] = (log) => this.logger.log({ level: LogLevelEnum.http, ...log });
+  verbose: LoggerPort["verbose"] = (log) => this.logger.log({ level: LogLevelEnum.verbose, ...log });
+  debug: LoggerPort["debug"] = (log) => this.logger.log({ level: LogLevelEnum.debug, ...log });
+  silly: LoggerPort["silly"] = (log) => this.logger.log({ level: LogLevelEnum.silly, ...log });
+
+  setSilent: LoggerPort["setSilent"] = (silent) => {
+    this.logger.silent = silent;
+  };
+}

package/src/logger.port.ts

@@ -0,0 +1,69 @@
+import type { CorrelationIdType } from "./correlation-id.vo";
+import type { NodeEnvironmentEnum } from "./node-env.vo";
+
+export type HttpClientInfo = { ip?: string; userAgent?: string };
+
+export type LogAppType = string;
+
+export type ErrorInfo = {
+  name?: string;
+  message?: string;
+  stack?: string;
+  code?: string;
+  cause?: { name?: string; message?: string };
+};
+
+export enum LogLevelEnum {
+  error = "error",
+  warn = "warn",
+  info = "info",
+  http = "http",
+  verbose = "verbose",
+  debug = "debug",
+  silly = "silly",
+}
+
+export type LogCoreType = {
+  /** ISO-8601 UTC string with milliseconds, e.g. 2025-08-23T18:42:31.123Z */
+  timestamp: string;
+  level: LogLevelEnum;
+  app: LogAppType;
+  environment: NodeEnvironmentEnum;
+  /** Bounded context / subsystem, e.g., "http" | "emotions" | "publishing" | "infra" */
+  component: string;
+  /** Machine-friendly operation name, e.g., "weekly_review_generate" */
+  operation: string;
+  /** Short human-readable sentence */
+  message: string;
+  correlationId?: CorrelationIdType;
+  metadata?: Record<string, any>;
+};
+
+export type LogHttpType = LogCoreType & {
+  level: LogLevelEnum.http;
+  component: "http";
+  method: string;
+  url: string;
+  status?: number;
+  durationMs?: number;
+  client: HttpClientInfo;
+  cacheHit?: boolean;
+};
+
+export type LogErrorType = LogCoreType & { level: LogLevelEnum.error; error: ErrorInfo };
+
+export type LogWarnType = LogCoreType & { level: LogLevelEnum.warn; error?: ErrorInfo };
+
+export type AdapterInjectedFields = "timestamp" | "level" | "app" | "environment";
+
+export interface LoggerPort {
+  error(entry: Omit<LogErrorType, AdapterInjectedFields>): void;
+  warn(entry: Omit<LogWarnType, AdapterInjectedFields>): void;
+  info(entry: Omit<LogCoreType, AdapterInjectedFields>): void;
+  http(entry: Omit<LogHttpType, AdapterInjectedFields>): void;
+  verbose(entry: Omit<LogCoreType, AdapterInjectedFields>): void;
+  debug(entry: Omit<LogCoreType, AdapterInjectedFields>): void;
+  silly(entry: Omit<LogCoreType, AdapterInjectedFields>): void;
+
+  setSilent(silent: boolean): void;
+}

package/src/mailer-noop.adapter.ts

@@ -1,14 +1,19 @@
 import type { SendMailOptions } from "nodemailer";
-import type { Logger } from "./logger.service";
+import type { LoggerPort } from "./logger.port";
 import type { MailerPort } from "./mailer.port";
 
 type MailerSendOptionsType = SendMailOptions;
 
 export class MailerNoopAdapter implements MailerPort {
-  constructor(private readonly logger: Logger) {}
+  constructor(private readonly logger: LoggerPort) {}
 
   async send(message: MailerSendOptionsType): Promise<unknown> {
-    return this.logger.info({ message: "[NOOP] Mailer adapter", operation: "write", metadata: message });
+    return this.logger.info({
+      message: "[NOOP] Mailer adapter",
+      component: "mailer",
+      operation: "write",
+      metadata: message,
+    });
   }
 
   async verify() {

package/src/mailer-smtp-with-logger.adapter.ts

@@ -1,5 +1,6 @@
 import type { SendMailOptions } from "nodemailer";
-import type { Logger } from "./logger.service";
+import type { LoggerPort } from "./logger.port";
+import { formatError } from "./logger-format-error.service";
 import type { MailerPort } from "./mailer.port";
 import type { MailerSmtpAdapter } from "./mailer-smtp.adapter";
 
@@ -7,7 +8,7 @@ type MailerSendOptionsType = SendMailOptions;
 
 type SmtpMailerWithLoggerConfigType = {
   smtpMailer: MailerSmtpAdapter;
-  logger: Logger;
+  logger: LoggerPort;
 };
 
 export class MailerSmtpWithLoggerAdapter implements MailerPort {
@@ -15,12 +16,18 @@ export class MailerSmtpWithLoggerAdapter implements MailerPort {
 
   async send(message: MailerSendOptionsType): Promise<unknown> {
     try {
-      this.config.logger.info({ message: "Mailer attempt", operation: "mailer", metadata: message });
+      this.config.logger.info({
+        message: "Mailer attempt",
+        component: "infra",
+        operation: "mailer",
+        metadata: message,
+      });
 
       const result = await this.config.smtpMailer.send(message);
 
       this.config.logger.info({
         message: "Mailer success",
+        component: "infra",
         operation: "mailer",
         metadata: { message, result },
       });
@@ -29,8 +36,9 @@ export class MailerSmtpWithLoggerAdapter implements MailerPort {
     } catch (error) {
       this.config.logger.error({
         message: "Mailer error",
+        component: "infra",
         operation: "mailer",
-        metadata: this.config.logger.formatError(error),
+        error: formatError(error),
       });
 
       throw error;

package/src/prerequisites/log-file.ts

@@ -1,8 +1,8 @@
-import type { Logger } from "../logger.service";
+import type { LoggerWinstonProductionAdapter } from "../logger-winston-production.adapter";
 import * as prereqs from "../prerequisites.service";
 
 type PrerequisiteLogFileConfigType = {
-  logger: Logger;
+  logger: LoggerWinstonProductionAdapter;
   label: prereqs.PrerequisiteLabelType;
   enabled?: boolean;
 };
@@ -18,8 +18,9 @@ export class PrerequisiteLogFile extends prereqs.AbstractPrerequisite<Prerequisi
     if (!this.enabled) return prereqs.PrerequisiteStatusEnum.undetermined;
 
     try {
-      const path = this.config.logger.getProductionLogFilePath();
+      const path = this.config.logger.prodLogFile;
 
+      // TODO: adjust checks
       const result = await Bun.file(path).exists();
 
       return result ? this.pass() : this.reject();

package/src/setup.service.ts

@@ -13,7 +13,7 @@ import { CorrelationStorage } from "./correlation-storage.service";
 import { ETagExtractor } from "./etag-extractor.middleware";
 import { HttpLogger } from "./http-logger.middleware";
 import type { I18nConfigType } from "./i18n.service";
-import type { Logger } from "./logger.service";
+import type { LoggerPort } from "./logger.port";
 import { TimeZoneOffset } from "./time-zone-offset.middleware";
 import { WeakETagExtractor } from "./weak-etag-extractor.middleware";
 
@@ -28,7 +28,7 @@ type CorsOptions = Parameters<typeof cors>[0];
 type SetupOverridesType = { cors?: CorsOptions };
 
 export class Setup {
-  static essentials(logger: Logger, i18n: I18nConfigType, overrides?: SetupOverridesType) {
+  static essentials(logger: LoggerPort, i18n: I18nConfigType, overrides?: SetupOverridesType) {
     const corsOptions = overrides?.cors ?? { origin: "*" };
 
     return [