@bgord/bun 0.5.0 → 0.7.0

package/src/healthcheck.ts

@@ -1,28 +1,38 @@
-import * as bg from "@bgord/node";
+import * as tools from "@bgord/tools";
 import { createFactory } from "hono/factory";
 
+import { BuildInfoRepository } from "./build-info-repository";
+import { MemoryConsumption } from "./memory-consumption";
+import {
+  AbstractPrerequisite,
+  BasePrerequisiteConfig,
+  PrerequisiteLabelType,
+  PrerequisiteStatusEnum,
+} from "./prerequisites";
+import { Uptime, UptimeResultType } from "./uptime";
+
 const handler = createFactory();
 
 type HealthcheckResultType = {
-  ok: bg.PrerequisiteStatusEnum;
-  version: bg.Schema.BuildVersionType;
+  ok: PrerequisiteStatusEnum;
+  version: tools.BuildVersionType;
   details: {
-    label: bg.PrerequisiteLabelType;
-    status: bg.PrerequisiteStatusEnum;
+    label: PrerequisiteLabelType;
+    status: PrerequisiteStatusEnum;
   }[];
-  uptime: bg.UptimeResultType;
+  uptime: UptimeResultType;
   memory: {
-    bytes: bg.Size["bytes"];
-    formatted: ReturnType<bg.Size["format"]>;
+    bytes: tools.Size["bytes"];
+    formatted: ReturnType<tools.Size["format"]>;
   };
-} & bg.StopwatchResultType;
+} & tools.StopwatchResultType;
 
 export class Healthcheck {
-  static build = (prerequisites: bg.AbstractPrerequisite<bg.BasePrerequisiteConfig>[]) =>
+  static build = (prerequisites: AbstractPrerequisite<BasePrerequisiteConfig>[]) =>
     handler.createHandlers(async (c) => {
-      const stopwatch = new bg.Stopwatch();
+      const stopwatch = new tools.Stopwatch();
 
-      const build = await bg.BuildInfoRepository.extract();
+      const build = await BuildInfoRepository.extract();
 
       const details: HealthcheckResultType["details"][number][] = [];
 
@@ -31,20 +41,20 @@ export class Healthcheck {
         details.push({ label: prerequisite.label, status });
       }
 
-      const ok = details.every((result) => result.status !== bg.PrerequisiteStatusEnum.failure)
-        ? bg.PrerequisiteStatusEnum.success
-        : bg.PrerequisiteStatusEnum.failure;
+      const ok = details.every((result) => result.status !== PrerequisiteStatusEnum.failure)
+        ? PrerequisiteStatusEnum.success
+        : PrerequisiteStatusEnum.failure;
 
-      const code = ok === bg.PrerequisiteStatusEnum.success ? 200 : 424;
+      const code = ok === PrerequisiteStatusEnum.success ? 200 : 424;
 
       const result: HealthcheckResultType = {
         ok,
         details,
-        version: build.BUILD_VERSION ?? bg.Schema.BuildVersion.parse("unknown"),
-        uptime: bg.Uptime.get(),
+        version: build.BUILD_VERSION ?? tools.BuildVersion.parse("unknown"),
+        uptime: Uptime.get(),
         memory: {
-          bytes: bg.MemoryConsumption.get().toBytes(),
-          formatted: bg.MemoryConsumption.get().format(bg.SizeUnit.MB),
+          bytes: MemoryConsumption.get().toBytes(),
+          formatted: MemoryConsumption.get().format(tools.SizeUnit.MB),
         },
         ...stopwatch.stop(),
       };

package/src/http-logger.ts

@@ -1,8 +1,12 @@
-import * as bg from "@bgord/node";
 import { getConnInfo } from "hono/bun";
 import { createMiddleware } from "hono/factory";
 import _ from "lodash";
 
+import { CacheHitEnum } from "./cache-resolver";
+import { CacheResponse } from "./cache-response";
+import { CorrelationIdType } from "./correlation-id";
+import { Logger } from "./logger";
+
 export class HttpLogger {
   private static simplify(response: unknown) {
     const result = JSON.stringify(response, (_key, value) =>
@@ -34,9 +38,9 @@ export class HttpLogger {
     "if-none-match",
   ];
 
-  static build = (logger: bg.Logger) =>
+  static build = (logger: Logger) =>
     createMiddleware(async (c, next) => {
-      const correlationId = c.get("requestId") as bg.Schema.CorrelationIdType;
+      const correlationId = c.get("requestId") as CorrelationIdType;
       const info = getConnInfo(c);
       const url = c.req.url;
       const method = c.req.method;
@@ -71,9 +75,9 @@ export class HttpLogger {
 
       await next();
 
-      const cacheHitHeader = c.res.clone().headers.get(bg.CacheResponse.CACHE_HIT_HEADER);
+      const cacheHitHeader = c.res.clone().headers.get(CacheResponse.CACHE_HIT_HEADER);
 
-      const cacheHit = cacheHitHeader === bg.CacheHitEnum.hit ? bg.CacheHitEnum.hit : undefined;
+      const cacheHit = cacheHitHeader === CacheHitEnum.hit ? CacheHitEnum.hit : undefined;
 
       let response: any;
       try {

package/src/i18n.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
-import * as bgn from "@bgord/node";
-import { getCookie } from "hono/cookie";
-import { createMiddleware } from "hono/factory";
+import * as tools from "@bgord/tools";
+
+import { Path, PathType } from "./path";
 
 export type TranslationsKeyType = string;
 export type TranslationsValueType = string;
@@ -12,51 +12,19 @@ export type TranslationPlaceholderValueType = string | number;
 export type TranslationVariableType = Record<TranslationPlaceholderType, TranslationPlaceholderValueType>;
 
 export type I18nConfigType = {
-  translationsPath?: bgn.Schema.PathType;
-  defaultLanguage?: bgn.Schema.LanguageType;
-  supportedLanguages: Record<string, bgn.Schema.LanguageType>;
-};
-
-export type I18nVariablesType = {
-  language: bgn.Schema.LanguageType;
-  supportedLanguages: bgn.Schema.LanguageType[];
-  translationsPath: bgn.Schema.PathType;
+  translationsPath?: PathType;
+  defaultLanguage?: tools.LanguageType;
+  supportedLanguages: Record<string, tools.LanguageType>;
 };
 
 export class I18n {
-  static LANGUAGE_COOKIE_NAME = "accept-language";
-
-  // TODO: fix bgord/node types
-  static DEFAULT_TRANSLATIONS_PATH = bgn.Schema.Path.parse("infra/translations") as string;
-
-  static FALLBACK_LANGUAGE = "en";
-
-  static applyTo(config: I18nConfigType) {
-    return createMiddleware(async (c, next) => {
-      const translationsPath = config?.translationsPath ?? I18n.DEFAULT_TRANSLATIONS_PATH;
+  static DEFAULT_TRANSLATIONS_PATH = Path.parse("infra/translations");
 
-      const defaultLanguage = config?.defaultLanguage ?? I18n.FALLBACK_LANGUAGE;
-
-      const chosenLanguage = getCookie(c, I18n.LANGUAGE_COOKIE_NAME) ?? defaultLanguage;
-
-      const language = Object.keys(config.supportedLanguages).find((language) => language === chosenLanguage)
-        ? chosenLanguage
-        : I18n.FALLBACK_LANGUAGE;
-
-      c.set("supportedLanguages", Object.keys(config.supportedLanguages));
-      c.set("language", language);
-      c.set("translationsPath", translationsPath);
-
-      return next();
-    });
-  }
+  constructor(private translationsPath: PathType = I18n.DEFAULT_TRANSLATIONS_PATH) {}
 
-  static async getTranslations(
-    language: bgn.Schema.LanguageType,
-    translationsPath: bgn.Schema.PathType,
-  ): Promise<TranslationsType> {
+  async getTranslations(language: tools.LanguageType): Promise<TranslationsType> {
     try {
-      return Bun.file(I18n.getTranslationPathForLanguage(language, translationsPath)).json();
+      return Bun.file(this.getTranslationPathForLanguage(language)).json();
     } catch (error) {
       // biome-ignore lint: lint/suspicious/noConsoleLog
       console.log("I18n#getTranslations", error);
@@ -65,7 +33,7 @@ export class I18n {
     }
   }
 
-  static useTranslations(translations: TranslationsType) {
+  useTranslations(translations: TranslationsType) {
     return function translate(key: TranslationsKeyType, variables?: TranslationVariableType) {
       const translation = translations[key];
 
@@ -83,10 +51,7 @@ export class I18n {
     };
   }
 
-  static getTranslationPathForLanguage(
-    language: bgn.Schema.LanguageType,
-    translationsPath = I18n.DEFAULT_TRANSLATIONS_PATH,
-  ): bgn.Schema.PathType {
-    return bgn.Schema.Path.parse(path.join(translationsPath, `${language}.json`));
+  getTranslationPathForLanguage(language: tools.LanguageType): PathType {
+    return Path.parse(path.join(this.translationsPath, `${language}.json`));
   }
 }

package/src/index.ts

@@ -1,17 +1,38 @@
 export * from "./api-key-shield";
 export * from "./api-version";
 export * from "./auth-shield";
+export * from "./basic-auth";
+export * from "./build-info-repository";
+export * from "./cache-resolver";
+export * from "./cache-response";
+export * from "./cache-static-files";
 export * from "./context";
+export * from "./correlation-id";
+export * from "./download-file";
+export * from "./env-validator";
 export * from "./etag-extractor";
+export * from "./file-uploader";
 export * from "./graceful-shutdown";
 export * from "./healthcheck";
 export * from "./http-logger";
-export * from "./rate-limit-shield";
-export * from "./time-zone-offset";
-export * from "./cache-static-files";
-export * from "./cache-response";
-export * from "./download-file";
 export * from "./i18n";
-export * from "./file-uploader";
-export * from "./image-processor";
+export * from "./jobs";
+export * from "./logger";
+export * from "./mailer";
+export * from "./memory-consumption";
+export * from "./new-uuid";
+export * from "./node-env.vo";
+export * from "./passwords";
+export * from "./path";
+export * from "./port";
+export * from "./prerequisites";
+export * from "./prerequisites/index";
+export * from "./rate-limit-shield";
+export * from "./session-id";
 export * from "./setup";
+export * from "./time-zone-offset";
+export * from "./uptime";
+export * from "./username";
+export * from "./uuid";
+export * from "./weak-etag-extractor";
+export { default as sharp } from "sharp";

package/src/jobs.ts

@@ -0,0 +1,91 @@
+import * as tools from "@bgord/tools";
+import { Cron } from "croner";
+
+import { CorrelationId } from "./correlation-id";
+import { Logger } from "./logger";
+import { NewUUID } from "./new-uuid";
+
+export type JobNameType = string;
+export type MultipleJobsType = Record<JobNameType, Cron>;
+
+export enum UTC_DAY_OF_THE_WEEK {
+  Monday = 1,
+  Tuesday = 2,
+  Wednesday = 3,
+  Thursday = 4,
+  Friday = 5,
+  Saturday = 6,
+  Sunday = 0,
+}
+
+export class Jobs {
+  static SCHEDULES = { EVERY_MINUTE: "* * * * *", EVERY_HOUR: "0 * * * *" };
+
+  static stopAll(jobs: MultipleJobsType) {
+    Object.values(jobs).forEach((job) => job.stop());
+  }
+
+  static areAllRunning(jobs: MultipleJobsType): boolean {
+    return Object.values(jobs).every((job) => job.isRunning());
+  }
+}
+
+export type JobProcessorType = {
+  cron: string;
+  label: JobNameType;
+  process: () => Promise<void>;
+};
+
+export class JobHandler {
+  constructor(private readonly logger: Logger) {}
+
+  handle(jobProcessor: JobProcessorType) {
+    const correlationId = CorrelationId.parse(NewUUID.generate());
+
+    // biome-ignore lint: lint/complexity/noUselessThisAlias
+    const that = this;
+
+    return async () => {
+      const stopwatch = new tools.Stopwatch();
+
+      try {
+        that.logger.info({
+          message: `${jobProcessor.label} start`,
+          operation: "job_start",
+          correlationId,
+        });
+
+        await jobProcessor.process();
+
+        that.logger.info({
+          message: `${jobProcessor.label} success`,
+          operation: "job_success",
+          correlationId,
+          metadata: stopwatch.stop(),
+        });
+      } catch (error) {
+        that.logger.error({
+          message: `${jobProcessor.label} error`,
+          operation: "job_error",
+          correlationId,
+          metadata: {
+            ...that.logger.formatError(error),
+            ...stopwatch.stop(),
+          },
+        });
+      }
+    };
+  }
+
+  protect(cron: Cron) {
+    // biome-ignore lint: lint/complexity/noUselessThisAlias
+    const that = this;
+
+    return async () => {
+      that.logger.info({
+        message: `${cron.name} overrun`,
+        operation: "job_overrun",
+      });
+    };
+  }
+}

package/src/logger.ts

@@ -0,0 +1,156 @@
+import * as tools from "@bgord/tools";
+import * as winston from "winston";
+import { z } from "zod/v4";
+
+import { CorrelationIdType } from "./correlation-id";
+import { NodeEnvironmentEnum } from "./node-env.vo";
+import { PathType } from "./path";
+
+export enum LogLevelEnum {
+  /** @public */
+  silent = "silent",
+  error = "error",
+  warn = "warn",
+  info = "info",
+  http = "http",
+  verbose = "verbose",
+}
+export const LogLevel = z.enum(LogLevelEnum);
+
+type LogTimestampType = number;
+type LogAppType = string;
+type LogEnvironmentType = NodeEnvironmentEnum;
+type LogMessageType = string;
+type LogOperationType = string;
+type LogMetadataType = Record<string, any>;
+type LogCorrelationIdType = CorrelationIdType;
+
+const levels: Record<LogLevelEnum, number> = {
+  silent: 0,
+  error: 0,
+  warn: 1,
+  info: 2,
+  http: 3,
+  verbose: 4,
+};
+
+type LogFullType = {
+  timestamp: LogTimestampType;
+  app: LogAppType;
+  environment: LogEnvironmentType;
+  level: LogLevelEnum;
+  message: LogMessageType;
+  operation: LogOperationType;
+  method: string;
+  url: string;
+  client: { ip?: string; userAgent?: string };
+  correlationId?: LogCorrelationIdType;
+  responseCode?: number;
+  durationMs?: tools.TimestampType;
+  metadata?: LogMetadataType;
+};
+
+type LogErrorType = Omit<
+  LogFullType,
+  "app" | "client" | "environment" | "duration" | "level" | "method" | "responseCode" | "timestamp" | "url"
+>;
+
+type LogWarnType = Omit<
+  LogFullType,
+  "app" | "client" | "environment" | "duration" | "level" | "method" | "responseCode" | "timestamp" | "url"
+>;
+
+type LogInfoType = Omit<
+  LogFullType,
+  "app" | "client" | "environment" | "duration" | "level" | "method" | "responseCode" | "timestamp" | "url"
+>;
+
+type LogHttpType = Omit<LogFullType, "app" | "environment" | "timestamp" | "level">;
+
+type LoggerOptionsType = {
+  app: LogAppType;
+  environment: NodeEnvironmentEnum;
+  level?: LogLevelEnum;
+};
+
+export class Logger {
+  private readonly instance: winston.Logger;
+
+  private readonly app: LoggerOptionsType["app"];
+
+  private readonly environment: LoggerOptionsType["environment"];
+
+  private readonly level: LoggerOptionsType["level"] = LogLevelEnum.verbose;
+
+  constructor(options: LoggerOptionsType) {
+    this.app = options.app;
+    this.environment = options.environment;
+    this.level = options.level ?? LogLevelEnum.verbose;
+
+    const formats = [
+      winston.format.json(),
+
+      this.environment !== NodeEnvironmentEnum.production ? winston.format.prettyPrint() : undefined,
+    ].filter(Boolean);
+
+    this.instance = winston.createLogger({
+      level: this.level,
+      levels,
+      handleExceptions: true,
+      handleRejections: true,
+      format: winston.format.combine(...(formats as NonNullable<winston.LoggerOptions["format"]>[])),
+      transports: [new winston.transports.Console()],
+    });
+
+    if (this.environment === NodeEnvironmentEnum.production) {
+      this.instance.add(
+        new winston.transports.File({
+          filename: this.getProductionLogFilePath(),
+          maxsize: tools.Size.toBytes({ unit: tools.SizeUnit.MB, value: 100 }),
+        }),
+      );
+    }
+  }
+
+  private getBase() {
+    return {
+      app: this.app,
+      environment: this.environment,
+      timestamp: Date.now(),
+    };
+  }
+
+  info(log: LogInfoType) {
+    this.instance.info({ level: LogLevelEnum.info, ...this.getBase(), ...log });
+  }
+
+  error(log: LogErrorType) {
+    this.instance.error({
+      level: LogLevelEnum.error,
+      ...this.getBase(),
+      ...log,
+    });
+  }
+
+  warn(log: LogWarnType) {
+    this.instance.warn({ level: LogLevelEnum.warn, ...this.getBase(), ...log });
+  }
+
+  http(log: LogHttpType) {
+    this.instance.http({ level: LogLevelEnum.http, ...this.getBase(), ...log });
+  }
+
+  getProductionLogFilePath(): PathType {
+    return `/var/log/${this.app}-${this.environment}.log`;
+  }
+
+  formatError(_error: unknown) {
+    const error = _error as Error;
+
+    return {
+      message: error?.message,
+      name: error?.name,
+      stack: error?.stack,
+    };
+  }
+}

package/src/mailer.ts

@@ -0,0 +1,64 @@
+import nodemailer, { SendMailOptions } from "nodemailer";
+import { z } from "zod/v4";
+
+import { Path } from "./path";
+import { Port } from "./port";
+
+export const SmtpHost = z.string().trim().min(1);
+export type SmtpHostType = z.infer<typeof SmtpHost>;
+
+export const SmtpPort = Port;
+export type SmtpPortType = z.infer<typeof SmtpPort>;
+
+export const SmtpUser = z.string().trim().min(1);
+export type SmtpUserType = z.infer<typeof SmtpUser>;
+
+export const SmtpPass = z.string().trim().min(1);
+export type SmtpPassType = z.infer<typeof SmtpPass>;
+
+type MailerConfigType = {
+  SMTP_HOST: SmtpHostType;
+  SMTP_PORT: SmtpPortType;
+  SMTP_USER: SmtpUserType;
+  SMTP_PASS: SmtpPassType;
+};
+
+type MailerSendOptionsType = SendMailOptions;
+
+export const EmailSubject = z.string().min(1).max(128);
+export type EmailSubjectType = z.infer<typeof EmailSubject>;
+
+export const EmailContentHtml = z.string().min(1).max(10_000);
+export type EmailContentHtmlType = z.infer<typeof EmailContentHtml>;
+
+export const EmailFrom = z.email();
+export type EmailFromType = z.infer<typeof EmailFrom>;
+
+export const EmailTo = z.email();
+export type EmailToType = z.infer<typeof EmailTo>;
+
+export const EmailAttachment = z.object({ filename: Path, path: Path });
+export type EmailAttachmentType = z.infer<typeof EmailAttachment>;
+
+export class Mailer {
+  private readonly transport: nodemailer.Transporter;
+
+  constructor(config: MailerConfigType) {
+    this.transport = nodemailer.createTransport({
+      host: config.SMTP_HOST,
+      port: config.SMTP_PORT,
+      auth: {
+        user: config.SMTP_USER,
+        pass: config.SMTP_PASS,
+      },
+    });
+  }
+
+  async send(options: MailerSendOptionsType): Promise<unknown> {
+    return this.transport.sendMail(options);
+  }
+
+  async verify() {
+    return this.transport.verify();
+  }
+}

package/src/memory-consumption.ts

@@ -0,0 +1,9 @@
+import * as tools from "@bgord/tools";
+
+export class MemoryConsumption {
+  static get(): tools.Size {
+    const memoryConsumption = process.memoryUsage().rss;
+
+    return new tools.Size({ value: memoryConsumption, unit: tools.SizeUnit.b });
+  }
+}

package/src/new-uuid.ts

@@ -0,0 +1,5 @@
+export class NewUUID {
+  static generate() {
+    return crypto.randomUUID();
+  }
+}

package/src/node-env.vo.ts

@@ -0,0 +1,9 @@
+import { z } from "zod/v4";
+
+export enum NodeEnvironmentEnum {
+  local = "local",
+  test = "test",
+  staging = "staging",
+  production = "production",
+}
+export const NodeEnvironment = z.enum(NodeEnvironmentEnum);

package/src/passwords.ts

@@ -0,0 +1,55 @@
+import { z } from "zod/v4";
+
+export type PasswordType = string;
+type HashedPasswordType = string;
+
+export class Password {
+  private schema: z.ZodSchema = z.string().min(1).max(256);
+
+  private value: PasswordType;
+
+  constructor(value: PasswordType, schema?: z.ZodSchema) {
+    this.schema = schema ?? this.schema;
+    this.value = this.schema.parse(value) as PasswordType;
+  }
+
+  async hash(): Promise<HashedPassword> {
+    return HashedPassword.fromPassword(this);
+  }
+
+  read(): PasswordType {
+    return this.value;
+  }
+}
+
+export class HashedPassword {
+  private constructor(private value: HashedPasswordType) {}
+
+  static async fromPassword(password: Password) {
+    const hash = await Bun.password.hash(password.read());
+
+    return new HashedPassword(hash);
+  }
+
+  static async fromHash(value: HashedPasswordType) {
+    return new HashedPassword(value);
+  }
+
+  read(): HashedPasswordType {
+    return this.value;
+  }
+
+  async matches(password: Password): Promise<boolean> {
+    return Bun.password.verify(password.read(), this.read());
+  }
+
+  async matchesOrThrow(password: Password): Promise<true> {
+    const matches = await Bun.password.verify(password.read(), this.read());
+
+    if (!matches) {
+      throw new Error("HashedPassword does not match the provided password");
+    }
+
+    return true;
+  }
+}

package/src/path.ts

@@ -0,0 +1,4 @@
+import { z } from "zod/v4";
+
+export const Path = z.string().min(1);
+export type PathType = z.infer<typeof Path>;

package/src/port.ts

@@ -0,0 +1,4 @@
+import { z } from "zod/v4";
+
+export const Port = z.coerce.number().min(0).max(99999);
+export type PortType = z.infer<typeof Port>;