@bgord/bun 1.15.3 → 1.15.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/bun",
-  "version": "1.15.3",
+  "version": "1.15.5",
   "license": "MIT",
   "type": "module",
   "author": "Bartosz Gordon",
@@ -20,21 +20,21 @@
     "preinstall": "bunx only-allow bun"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.7",
+    "@biomejs/biome": "2.4.8",
     "@commitlint/cli": "20.5.0",
     "@commitlint/config-conventional": "20.5.0",
     "@standard-schema/spec": "1.1.0",
     "@stryker-mutator/core": "9.6.0",
-    "@types/bun": "1.3.10",
+    "@types/bun": "1.3.11",
     "@types/nodemailer": "7.0.11",
     "@types/yazl": "3.3.0",
-    "better-auth": "1.5.5",
+    "better-auth": "1.5.6",
     "cspell": "9.7.0",
-    "csv": "6.5.0",
-    "knip": "5.88.0",
+    "csv": "6.5.1",
+    "knip": "6.0.2",
     "lefthook": "2.1.4",
     "lockfile-lint": "5.0.0",
-    "nodemailer": "8.0.2",
+    "nodemailer": "8.0.3",
     "only-allow": "1.2.2",
     "resend": "6.9.4",
     "sharp": "0.34.5",
@@ -43,15 +43,15 @@
     "yazl": "3.3.1"
   },
   "dependencies": {
-    "@bgord/tools": "1.4.2",
+    "@bgord/tools": "1.4.4",
     "emittery": "2.0.0",
     "hono": "4.12.8",
     "node-cache": "5.1.2"
   },
   "peerDependencies": {
-    "better-auth": "1.5.5",
-    "csv": "6.5.0",
-    "nodemailer": "8.0.2",
+    "better-auth": "1.5.6",
+    "csv": "6.5.1",
+    "nodemailer": "8.0.3",
     "resend": "6.9.4",
     "sharp": "0.34.5",
     "yazl": "3.3.1"

package/readme.md

@@ -36,6 +36,17 @@ src/
 ├── ab-variant.vo.ts
 ├── ab-variants.vo.ts
 ├── ab.middleware.ts
+├── alert-channel-collecting.adapter.ts
+├── alert-channel-composite.adapter.ts
+├── alert-channel-mailer.adapter.ts
+├── alert-channel-noop.adapter.ts
+├── alert-channel-sms.adapter.ts
+├── alert-channel-with-logger.adapter.ts
+├── alert-channel-with-retry.adapter.ts
+├── alert-channel-with-timeout.adapter.ts
+├── alert-channel.builder.ts
+├── alert-channel.port.ts
+├── alert-message.vo.ts
 ├── antivirus-clamav.adapter.ts
 ├── antivirus-noop.adapter.ts
 ├── antivirus.port.ts
@@ -57,6 +68,7 @@ src/
 ├── cache-file.service.ts
 ├── cache-repository-node-cache.adapter.ts
 ├── cache-repository-noop.adapter.ts
+├── cache-repository-redis.adapter.ts
 ├── cache-repository.port.ts
 ├── cache-resolver-simple.strategy.ts
 ├── cache-resolver.strategy.ts
@@ -209,6 +221,9 @@ src/
 ├── image-formatter-noop.adapter.ts
 ├── image-formatter-sharp.adapter.ts
 ├── image-formatter.port.ts
+├── image-grayscale-noop.adapter.ts
+├── image-grayscale-sharp.adapter.ts
+├── image-grayscale.port.ts
 ├── image-info-noop.adapter.ts
 ├── image-info-sharp.adapter.ts
 ├── image-info.port.ts
@@ -237,11 +252,14 @@ src/
 ├── language-detector.middleware.ts
 ├── language-detector.strategy.ts
 ├── languages.vo.ts
+├── liveness-hono.handler.ts
+├── liveness.handler.ts
 ├── logger-collecting.adapter.ts
 ├── logger-noop.adapter.ts
 ├── logger-stats-provider-noop.adapter.ts
 ├── logger-stats-provider.port.ts
 ├── logger.port.ts
+├── mailer-collecting.adapter.ts
 ├── mailer-content-html.vo.ts
 ├── mailer-noop.adapter.ts
 ├── mailer-resend.adapter.ts
@@ -319,8 +337,6 @@ src/
 ├── pdf-generator-noop.adapter.ts
 ├── pdf-generator-with-logger.adapter.ts
 ├── pdf-generator.port.ts
-├── ping-hono.handler.ts
-├── ping.handler.ts
 ├── port.vo.ts
 ├── prerequisite-runner-startup.service.ts
 ├── prerequisite-verifier-binary.adapter.ts
@@ -340,6 +356,7 @@ src/
 ├── prerequisite-verifier-ram.adapter.ts
 ├── prerequisite-verifier-running-user.adapter.ts
 ├── prerequisite-verifier-self.adapter.ts
+├── prerequisite-verifier-sms.adapter.ts
 ├── prerequisite-verifier-space.adapter.ts
 ├── prerequisite-verifier-sqlite.adapter.ts
 ├── prerequisite-verifier-ssl-certificate-expiry.adapter.ts
@@ -353,6 +370,12 @@ src/
 ├── prerequisite-verifier.decorator.ts
 ├── prerequisite-verifier.port.ts
 ├── prerequisite.vo.ts
+├── randomness-crypto.strategy.ts
+├── randomness-math.strategy.ts
+├── randomness-noop.strategy.ts
+├── randomness.strategy.ts
+├── readiness-hono.handler.ts
+├── readiness.handler.ts
 ├── recaptcha-secret-key.vo.ts
 ├── recaptcha-site-key.vo.ts
 ├── redactor-composite.strategy.ts
@@ -369,7 +392,7 @@ src/
 ├── request-context-hono.adapter.ts
 ├── request-context.port.ts
 ├── retry-backoff-exponential.strategy.ts
-├── retry-backoff-fibonacci.strategy.ts
+├── retry-backoff-jitter.strategy.ts
 ├── retry-backoff-linear.strategy.ts
 ├── retry-backoff-noop.strategy.ts
 ├── retry-backoff.strategy.ts
@@ -413,6 +436,10 @@ src/
 ├── shield-hcaptcha-hono-local.strategy.ts
 ├── shield-hcaptcha-hono.strategy.ts
 ├── shield-hcaptcha.strategy.ts
+├── shield-ip-blacklist-hono.strategy.ts
+├── shield-ip-blacklist.strategy.ts
+├── shield-ip-whitelist-hono.strategy.ts
+├── shield-ip-whitelist.strategy.ts
 ├── shield-maintenance-hono.strategy.ts
 ├── shield-maintenance.strategy.ts
 ├── shield-rate-limit-hono.strategy.ts
@@ -430,6 +457,13 @@ src/
 ├── sleeper.port.ts
 ├── slower-hono.middleware.ts
 ├── slower.middleware.ts
+├── sms-collecting.adapter.ts
+├── sms-noop.adapter.ts
+├── sms-with-logger.adapter.ts
+├── sms-with-retry.adapter.ts
+├── sms-with-timeout.adapter.ts
+├── sms.builder.ts
+├── sms.port.ts
 ├── smtp-host.vo.ts
 ├── smtp-pass.vo.ts
 ├── smtp-port.vo.ts

package/src/alert-channel-collecting.adapter.ts

@@ -0,0 +1,14 @@
+import type { AlertChannelPort } from "./alert-channel.port";
+import type { AlertMessage } from "./alert-message.vo";
+
+export class AlertChannelCollectingAdapter implements AlertChannelPort {
+  readonly alerts: Array<AlertMessage> = [];
+
+  async send(alert: AlertMessage): Promise<void> {
+    this.alerts.push(alert);
+  }
+
+  async verify(): Promise<boolean> {
+    return true;
+  }
+}

package/src/alert-channel-composite.adapter.ts

@@ -0,0 +1,24 @@
+import type { AlertChannelPort } from "./alert-channel.port";
+import type { AlertMessage } from "./alert-message.vo";
+
+export const AlertChannelCompositeError = {
+  Min: "alert.channel.composite.channels.min",
+  Max: "alert.channel.composite.channels.max",
+};
+
+export class AlertChannelCompositeAdapter implements AlertChannelPort {
+  constructor(private readonly channels: ReadonlyArray<AlertChannelPort>) {
+    if (this.channels.length === 0) throw new Error(AlertChannelCompositeError.Min);
+    if (this.channels.length > 5) throw new Error(AlertChannelCompositeError.Max);
+  }
+
+  async send(alert: AlertMessage): Promise<void> {
+    await Promise.allSettled(this.channels.map((channel) => channel.send(alert)));
+  }
+
+  async verify(): Promise<boolean> {
+    const checks = await Promise.all(this.channels.map((channel) => channel.verify()));
+
+    return checks.every(Boolean);
+  }
+}

package/src/alert-channel-mailer.adapter.ts

@@ -0,0 +1,22 @@
+import type { AlertChannelPort } from "./alert-channel.port";
+import type { AlertMessage } from "./alert-message.vo";
+import type { MailerPort } from "./mailer.port";
+import type { MailerTemplate } from "./mailer-template.vo";
+
+export type AlertChannelMailerAdapterConfig = { template: (alert: AlertMessage) => MailerTemplate };
+export type AlertChannelMailerAdapterDependencies = { Mailer: MailerPort };
+
+export class AlertChannelMailerAdapter implements AlertChannelPort {
+  constructor(
+    private readonly config: AlertChannelMailerAdapterConfig,
+    private readonly deps: AlertChannelMailerAdapterDependencies,
+  ) {}
+
+  async send(alert: AlertMessage): Promise<void> {
+    await this.deps.Mailer.send(this.config.template(alert));
+  }
+
+  async verify(): Promise<boolean> {
+    return this.deps.Mailer.verify();
+  }
+}

package/src/alert-channel-noop.adapter.ts

@@ -0,0 +1,10 @@
+import type { AlertChannelPort } from "./alert-channel.port";
+import type { AlertMessage } from "./alert-message.vo";
+
+export class AlertChannelNoopAdapter implements AlertChannelPort {
+  async send(_alert: AlertMessage): Promise<void> {}
+
+  async verify(): Promise<boolean> {
+    return true;
+  }
+}

package/src/alert-channel-sms.adapter.ts

@@ -0,0 +1,22 @@
+import type * as tools from "@bgord/tools";
+import type { AlertChannelPort } from "./alert-channel.port";
+import type { AlertMessage } from "./alert-message.vo";
+import type { SmsPort } from "./sms.port";
+
+export type AlertChannelSmsAdapterConfig = { message: (alert: AlertMessage) => tools.SmsMessage };
+export type AlertChannelSmsAdapterDependencies = { Sms: SmsPort };
+
+export class AlertChannelSmsAdapter implements AlertChannelPort {
+  constructor(
+    private readonly config: AlertChannelSmsAdapterConfig,
+    private readonly deps: AlertChannelSmsAdapterDependencies,
+  ) {}
+
+  async send(alert: AlertMessage): Promise<void> {
+    await this.deps.Sms.send(this.config.message(alert));
+  }
+
+  async verify(): Promise<boolean> {
+    return this.deps.Sms.verify();
+  }
+}

package/src/alert-channel-with-logger.adapter.ts

@@ -0,0 +1,46 @@
+import type { AlertChannelPort } from "./alert-channel.port";
+import type { AlertMessage } from "./alert-message.vo";
+import type { ClockPort } from "./clock.port";
+import type { LoggerPort } from "./logger.port";
+import { Stopwatch } from "./stopwatch.service";
+
+export type AlertChannelWithLoggerAdapterDependencies = {
+  inner: AlertChannelPort;
+  Logger: LoggerPort;
+  Clock: ClockPort;
+};
+
+export class AlertChannelWithLoggerAdapter implements AlertChannelPort {
+  private readonly base = { component: "infra", operation: "alert_channel" };
+
+  constructor(private readonly deps: AlertChannelWithLoggerAdapterDependencies) {}
+
+  async send(alert: AlertMessage): Promise<void> {
+    const duration = new Stopwatch(this.deps);
+
+    try {
+      this.deps.Logger.info({ message: "Alert channel attempt", metadata: alert.toJSON(), ...this.base });
+
+      await this.deps.inner.send(alert);
+
+      this.deps.Logger.info({
+        message: "Alert channel success",
+        metadata: { alert: alert.toJSON(), duration: duration.stop() },
+        ...this.base,
+      });
+    } catch (error) {
+      this.deps.Logger.error({
+        message: "Alert channel error",
+        error,
+        metadata: duration.stop(),
+        ...this.base,
+      });
+
+      throw error;
+    }
+  }
+
+  async verify(): Promise<boolean> {
+    return this.deps.inner.verify();
+  }
+}

package/src/alert-channel-with-retry.adapter.ts

@@ -0,0 +1,22 @@
+import type { AlertChannelPort } from "./alert-channel.port";
+import type { AlertMessage } from "./alert-message.vo";
+import { Retry, type RetryConfig } from "./retry.service";
+import type { SleeperPort } from "./sleeper.port";
+
+export type AlertChannelWithRetryAdapterDependencies = { Sleeper: SleeperPort; inner: AlertChannelPort };
+export type AlertChannelWithRetryAdapterConfig = { retry: RetryConfig };
+
+export class AlertChannelWithRetryAdapter implements AlertChannelPort {
+  constructor(
+    private readonly config: AlertChannelWithRetryAdapterConfig,
+    private readonly deps: AlertChannelWithRetryAdapterDependencies,
+  ) {}
+
+  async send(alert: AlertMessage): Promise<void> {
+    await new Retry(this.deps).run(async () => this.deps.inner.send(alert), this.config.retry);
+  }
+
+  async verify(): Promise<boolean> {
+    return this.deps.inner.verify();
+  }
+}

package/src/alert-channel-with-timeout.adapter.ts

@@ -0,0 +1,25 @@
+import type * as tools from "@bgord/tools";
+import type { AlertChannelPort } from "./alert-channel.port";
+import type { AlertMessage } from "./alert-message.vo";
+import type { TimeoutRunnerPort } from "./timeout-runner.port";
+
+export type AlertChannelWithTimeoutAdapterDependencies = {
+  TimeoutRunner: TimeoutRunnerPort;
+  inner: AlertChannelPort;
+};
+export type AlertChannelWithTimeoutAdapterConfig = { timeout: tools.Duration };
+
+export class AlertChannelWithTimeoutAdapter implements AlertChannelPort {
+  constructor(
+    private readonly config: AlertChannelWithTimeoutAdapterConfig,
+    private readonly deps: AlertChannelWithTimeoutAdapterDependencies,
+  ) {}
+
+  async send(alert: AlertMessage): Promise<void> {
+    await this.deps.TimeoutRunner.run(this.deps.inner.send(alert), this.config.timeout);
+  }
+
+  async verify(): Promise<boolean> {
+    return this.deps.inner.verify();
+  }
+}

package/src/alert-channel.builder.ts

@@ -0,0 +1,48 @@
+import type { AlertChannelPort } from "./alert-channel.port";
+import {
+  AlertChannelWithLoggerAdapter,
+  type AlertChannelWithLoggerAdapterDependencies,
+} from "./alert-channel-with-logger.adapter";
+import {
+  AlertChannelWithRetryAdapter,
+  type AlertChannelWithRetryAdapterConfig,
+  type AlertChannelWithRetryAdapterDependencies,
+} from "./alert-channel-with-retry.adapter";
+import {
+  AlertChannelWithTimeoutAdapter,
+  type AlertChannelWithTimeoutAdapterConfig,
+  type AlertChannelWithTimeoutAdapterDependencies,
+} from "./alert-channel-with-timeout.adapter";
+
+export class AlertChannelBuilder {
+  constructor(private inner: AlertChannelPort) {}
+
+  static of(channel: AlertChannelPort): AlertChannelBuilder {
+    return new AlertChannelBuilder(channel);
+  }
+
+  withLogger(deps: Omit<AlertChannelWithLoggerAdapterDependencies, "inner">) {
+    this.inner = new AlertChannelWithLoggerAdapter({ ...deps, inner: this.inner });
+    return this;
+  }
+
+  withRetry(
+    config: AlertChannelWithRetryAdapterConfig,
+    deps: Omit<AlertChannelWithRetryAdapterDependencies, "inner">,
+  ) {
+    this.inner = new AlertChannelWithRetryAdapter(config, { ...deps, inner: this.inner });
+    return this;
+  }
+
+  withTimeout(
+    config: AlertChannelWithTimeoutAdapterConfig,
+    deps: Omit<AlertChannelWithTimeoutAdapterDependencies, "inner">,
+  ) {
+    this.inner = new AlertChannelWithTimeoutAdapter(config, { ...deps, inner: this.inner });
+    return this;
+  }
+
+  build(): AlertChannelPort {
+    return this.inner;
+  }
+}

package/src/alert-channel.port.ts

@@ -0,0 +1,7 @@
+import type { AlertMessage } from "./alert-message.vo";
+
+export interface AlertChannelPort {
+  send(alert: AlertMessage): Promise<void>;
+
+  verify(): Promise<boolean>;
+}

package/src/alert-message.vo.ts

@@ -0,0 +1,10 @@
+export class AlertMessage {
+  constructor(
+    readonly message: string,
+    readonly error?: unknown,
+  ) {}
+
+  toJSON() {
+    return { message: this.message, error: this.error };
+  }
+}

package/src/cache-repository-redis.adapter.ts

@@ -0,0 +1,31 @@
+import type { RedisClient } from "bun";
+import type { CacheRepositoryPort, CacheRepositoryTtlType } from "./cache-repository.port";
+import type { Hash } from "./hash.vo";
+
+export class CacheRepositoryRedisAdapter implements CacheRepositoryPort {
+  constructor(
+    private readonly client: RedisClient,
+    private readonly config: CacheRepositoryTtlType,
+  ) {}
+
+  async get<T>(subject: Hash): Promise<T | null> {
+    const value = await this.client.get(subject.get());
+    if (value === null) return null;
+    return JSON.parse(value) as T;
+  }
+
+  async set<T>(subject: Hash, value: T): Promise<void> {
+    await this.client.set(subject.get(), JSON.stringify(value));
+    if (this.config.type === "finite") {
+      await this.client.expire(subject.get(), this.config.ttl.seconds);
+    }
+  }
+
+  async delete(subject: Hash): Promise<void> {
+    await this.client.del(subject.get());
+  }
+
+  async flush(): Promise<void> {
+    await this.client.send("FLUSHALL", []);
+  }
+}

package/src/healthcheck-hono.handler.ts

@@ -23,9 +23,8 @@ export class HealthcheckHonoHandler implements HandlerHonoPort {
   handle() {
     return factory.createHandlers(async (c) => {
       const healthcheck = await this.handler.check();
-      const code = healthcheck.ok ? 200 : 424;
 
-      return c.json(healthcheck, code);
+      return c.json(healthcheck, healthcheck.code);
     });
   }
 }

package/src/healthcheck.handler.ts

@@ -19,6 +19,12 @@ import type { RedactorStrategy } from "./redactor.strategy";
 import { Stopwatch } from "./stopwatch.service";
 import { Uptime, type UptimeResultType } from "./uptime.service";
 
+export enum HealthcheckStatusEnum {
+  healthy = "healthy",
+  degraded = "degraded",
+  unhealthy = "unhealthy",
+}
+
 type Dependencies = {
   Clock: ClockPort;
   BuildInfoRepository: BuildInfoRepositoryStrategy;
@@ -33,8 +39,15 @@ export type HealthcheckConfig = {
 
 const self = new Prerequisite("self", new PrerequisiteVerifierSelfAdapter());
 
+export const HealthcheckStatusCode = {
+  [HealthcheckStatusEnum.healthy]: 200,
+  [HealthcheckStatusEnum.degraded]: 207,
+  [HealthcheckStatusEnum.unhealthy]: 424,
+} as const;
+
 export type HealthcheckResult = {
-  ok: boolean;
+  status: HealthcheckStatusEnum;
+  code: (typeof HealthcheckStatusCode)[keyof typeof HealthcheckStatusCode];
   deployment: {
     version: string;
     timestamp: tools.TimestampValueType;
@@ -99,7 +112,18 @@ export class HealthcheckHandler {
       }),
     );
 
-    const ok = details.every((result) => result.outcome.outcome !== PrerequisiteVerificationOutcome.failure);
+    const hasFailure = details.some(
+      (result) => result.outcome.outcome === PrerequisiteVerificationOutcome.failure,
+    );
+    const hasUndetermined = details.some(
+      (result) => result.outcome.outcome === PrerequisiteVerificationOutcome.undetermined,
+    );
+
+    const status = hasFailure
+      ? HealthcheckStatusEnum.unhealthy
+      : hasUndetermined
+        ? HealthcheckStatusEnum.degraded
+        : HealthcheckStatusEnum.healthy;
 
     const build = await this.deps.BuildInfoRepository.extract();
     const uptime = Uptime.get(this.deps.Clock);
@@ -107,7 +131,8 @@ export class HealthcheckHandler {
     const memory = MemoryConsumption.snapshot();
 
     return {
-      ok,
+      status,
+      code: HealthcheckStatusCode[status],
       details,
       deployment: {
         version: build.version.toString(),

package/src/image-grayscale-noop.adapter.ts

@@ -0,0 +1,8 @@
+import type * as tools from "@bgord/tools";
+import type { ImageGrayscalePort, ImageGrayscaleStrategy } from "./image-grayscale.port";
+
+export class ImageGrayscaleNoopAdapter implements ImageGrayscalePort {
+  async grayscale(recipe: ImageGrayscaleStrategy): Promise<tools.FilePathRelative | tools.FilePathAbsolute> {
+    return recipe.strategy === "output_path" ? recipe.output : recipe.input;
+  }
+}

package/src/image-grayscale-sharp.adapter.ts

@@ -0,0 +1,45 @@
+import type * as tools from "@bgord/tools";
+import type sharp from "sharp";
+import { DynamicImport } from "./dynamic-import.service";
+import type { FileRenamerPort } from "./file-renamer.port";
+import type { ImageGrayscalePort, ImageGrayscaleStrategy } from "./image-grayscale.port";
+
+export const ImageGrayscaleSharpAdapterError = {
+  MissingDependency: "image.grayscale.sharp.adapter.error.missing.dependency",
+};
+
+type Dependencies = { FileRenamer: FileRenamerPort };
+type Sharp = typeof sharp;
+
+export class ImageGrayscaleSharpAdapter implements ImageGrayscalePort {
+  private static readonly importer = DynamicImport.for<{ default: Sharp }>(
+    "sharp",
+    ImageGrayscaleSharpAdapterError.MissingDependency,
+  );
+
+  private constructor(
+    private readonly sharp: Sharp,
+    private readonly deps: Dependencies,
+  ) {}
+
+  static async build(deps: Dependencies): Promise<ImageGrayscaleSharpAdapter> {
+    const library = await ImageGrayscaleSharpAdapter.importer.resolve();
+
+    return new ImageGrayscaleSharpAdapter(library.default, deps);
+  }
+
+  async grayscale(recipe: ImageGrayscaleStrategy): Promise<tools.FilePathRelative | tools.FilePathAbsolute> {
+    const final = recipe.strategy === "output_path" ? recipe.output : recipe.input;
+
+    const filename = final.getFilename();
+    const temporary = final.withFilename(filename.withSuffix("-grayscale"));
+
+    const pipeline = this.sharp(recipe.input.get());
+    using _sharp_ = { [Symbol.dispose]: () => pipeline.destroy() };
+
+    await pipeline.rotate().grayscale().toFile(temporary.get());
+    await this.deps.FileRenamer.rename(temporary, final);
+
+    return final;
+  }
+}

package/src/image-grayscale.port.ts

@@ -0,0 +1,16 @@
+import type * as tools from "@bgord/tools";
+
+export type ImageGrayscaleOutputPathStrategy = {
+  strategy: "output_path";
+  input: tools.FilePathRelative | tools.FilePathAbsolute;
+  output: tools.FilePathRelative | tools.FilePathAbsolute;
+};
+export type ImageGrayscaleInPlaceStrategy = {
+  strategy: "in_place";
+  input: tools.FilePathRelative | tools.FilePathAbsolute;
+};
+export type ImageGrayscaleStrategy = ImageGrayscaleInPlaceStrategy | ImageGrayscaleOutputPathStrategy;
+
+export interface ImageGrayscalePort {
+  grayscale(recipe: ImageGrayscaleStrategy): Promise<tools.FilePathRelative | tools.FilePathAbsolute>;
+}