@bgord/bun 0.6.0 → 0.8.0

package/dist/url-wo-trailing-slash.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod/v4";
+export declare const UrlWithoutTrailingSlash: z.ZodURL;
+export type UrlWithoutTrailingSlashType = z.infer<typeof UrlWithoutTrailingSlash>;
+//# sourceMappingURL=url-wo-trailing-slash.d.ts.map

package/dist/url-wo-trailing-slash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-wo-trailing-slash.d.ts","sourceRoot":"","sources":["../src/url-wo-trailing-slash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,eAAO,MAAM,uBAAuB,UAMhC,CAAC;AAEL,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/url-wo-trailing-slash.js

@@ -0,0 +1,9 @@
+import { z } from "zod/v4";
+export const UrlWithoutTrailingSlash = z
+    .url()
+    .trim()
+    .min(1)
+    .refine((value) => !value.endsWith("/"), {
+    message: "url_cannot_end_with_trailing_slash",
+});
+//# sourceMappingURL=url-wo-trailing-slash.js.map

package/dist/url-wo-trailing-slash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-wo-trailing-slash.js","sourceRoot":"","sources":["../src/url-wo-trailing-slash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC;KACrC,GAAG,EAAE;KACL,IAAI,EAAE;KACN,GAAG,CAAC,CAAC,CAAC;KACN,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;IACvC,OAAO,EAAE,oCAAoC;CAC9C,CAAC,CAAC"}

package/dist/uuid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAI3B,eAAO,MAAM,IAAI,yBAA6C,CAAC;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC"}
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAI3B,eAAO,MAAM,IAAI,yBAA6C,CAAC;AAE/D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/bun",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "MIT",
   "type": "module",
   "author": "Bartosz Gordon",
@@ -22,6 +22,7 @@
     "@commitlint/config-conventional": "19.8.1",
     "@types/bun": "1.2.15",
     "@types/lodash": "4.17.17",
+    "@types/mime-types": "3.0.1",
     "@types/nodemailer": "6.4.17",
     "cspell": "9.0.2",
     "knip": "5.60.2",
@@ -31,12 +32,14 @@
     "typescript": "5.8.3"
   },
   "dependencies": {
-    "@bgord/tools": "0.6.0",
+    "@bgord/tools": "0.7.0",
     "check-disk-space": "3.4.0",
     "croner": "9.0.0",
+    "hcaptcha": "0.2.0",
     "hono": "4.7.11",
     "lodash": "4.17.21",
     "lucia": "3.2.2",
+    "mime-types": "3.0.1",
     "node-cache": "5.1.2",
     "nodemailer": "7.0.3",
     "sharp": "0.34.2",

package/src/basic-auth.ts

@@ -0,0 +1,26 @@
+import { z } from "zod/v4";
+
+export const BasicAuthUsername = z.string().min(1).max(128);
+
+export type BasicAuthUsernameType = z.infer<typeof BasicAuthUsername>;
+
+export const BasicAuthPassword = z.string().min(1).max(128);
+
+export type BasicAuthPasswordType = z.infer<typeof BasicAuthPassword>;
+
+type BasicAuthHeaderValueType = { authorization: string };
+
+export class BasicAuth {
+  static toHeaderValue(
+    username: BasicAuthUsernameType,
+    password: BasicAuthPasswordType,
+  ): BasicAuthHeaderValueType {
+    const credentials = btoa(`${username}:${password}`);
+
+    return { authorization: `Basic ${credentials}` };
+  }
+
+  static toHeader(username: BasicAuthUsernameType, password: BasicAuthPasswordType): Headers {
+    return new Headers(BasicAuth.toHeaderValue(username, password));
+  }
+}

package/src/correlation-id.ts

@@ -3,4 +3,5 @@ import { z } from "zod/v4";
 import { UUID } from "./uuid";
 
 export const CorrelationId = UUID;
+
 export type CorrelationIdType = z.infer<typeof CorrelationId>;

package/src/decorators.ts

@@ -0,0 +1,78 @@
+import * as tools from "@bgord/tools";
+
+import { Logger } from "./logger";
+
+export class DecoratorTimeoutError extends Error {}
+
+export class Decorators {
+  private readonly rounding = new tools.RoundToDecimal(2);
+
+  constructor(private readonly logger: Logger) {}
+
+  duration() {
+    const that = this;
+
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+      const className =
+        // @ts-expect-error
+        this?.constructor?.name || target?.name || target?.constructor?.name || "UnknownClass";
+
+      const original: (...args: unknown[]) => unknown = descriptor.value;
+
+      const label = `${className}.${propertyKey}`;
+
+      descriptor.value = function (...args: unknown[]) {
+        const before = performance.now();
+        const value = original.apply(this, args);
+        const after = performance.now();
+
+        that.logger.info({
+          message: `${label} duration`,
+          operation: "decorators_duration_ms",
+          metadata: { durationMs: that.rounding.round(after - before) },
+        });
+
+        return value;
+      };
+    };
+  }
+
+  inspector() {
+    const that = this;
+
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+      const className =
+        // @ts-expect-error
+        this?.constructor?.name || target?.name || target?.constructor?.name || "UnknownClass";
+
+      const original: (...args: unknown[]) => unknown = descriptor.value;
+
+      const label = `${className}.${propertyKey}`;
+
+      descriptor.value = async function (...args: unknown[]) {
+        const value = await original.apply(this, args);
+
+        that.logger.info({
+          message: `${label} inspector`,
+          operation: "decorators_inspector",
+          metadata: { arguments: args, output: value },
+        });
+
+        return value;
+      };
+    };
+  }
+
+  timeout(ms: number) {
+    return (_target: any, _key: string, descriptor: PropertyDescriptor) => {
+      const original: (...args: unknown[]) => unknown = descriptor.value;
+
+      descriptor.value = async function (...args: any[]) {
+        return await Promise.race([
+          original.apply(this, args),
+          new Promise((_, reject) => setTimeout(() => reject(new DecoratorTimeoutError()), ms)),
+        ]);
+      };
+    };
+  }
+}

package/src/encryption.ts

@@ -0,0 +1,60 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import { pipeline } from "node:stream/promises";
+import * as util from "node:util";
+import { z } from "zod/v4";
+
+export const EncryptionIV = z
+  .string()
+  .min(1)
+  .transform((value) => Buffer.from(value.split(",").map(Number)));
+
+export type EncryptionIVType = z.infer<typeof EncryptionIV>;
+
+export const EncryptionSecret = z.string().length(64);
+
+export type EncryptionSecretType = z.infer<typeof EncryptionSecret>;
+
+export type EncryptionConfig = {
+  secret: EncryptionSecretType;
+  iv: EncryptionIVType;
+};
+
+export type EncryptionOperationConfig = {
+  input: fs.PathLike;
+  output: fs.PathLike;
+};
+
+const scrypt = util.promisify(crypto.scrypt);
+
+export class Encryption {
+  private readonly algorithm = "aes-192-cbc";
+
+  constructor(private readonly config: EncryptionConfig) {}
+
+  async createEncrypt() {
+    const key = (await scrypt(this.config.secret, "salt", 24)) as Buffer;
+
+    // @ts-ignore
+    return crypto.createCipheriv(this.algorithm, key, this.config.iv);
+  }
+
+  async createDecrypt() {
+    const key = (await scrypt(this.config.secret, "salt", 24)) as Buffer;
+
+    // @ts-ignore
+    return crypto.createDecipheriv(this.algorithm, key, this.config.iv);
+  }
+
+  async encrypt(config: EncryptionOperationConfig) {
+    const encrypt = await this.createEncrypt();
+
+    return pipeline(fs.createReadStream(config.input), encrypt, fs.createWriteStream(config.output));
+  }
+
+  async decrypt(config: EncryptionOperationConfig) {
+    const decrypt = await this.createDecrypt();
+
+    return pipeline(fs.createReadStream(config.input), decrypt, fs.createWriteStream(config.output));
+  }
+}

package/src/env-validator.ts

@@ -0,0 +1,43 @@
+import { z } from "zod/v4";
+
+import { NodeEnvironment } from "../src/node-env.vo";
+
+type NodeEnvironmentEnumType = z.infer<typeof NodeEnvironment>;
+
+type AnyZodSchema = z.ZodSchema<any, any>;
+type QuitType = boolean;
+
+type EnvironmentValidatorConfig = {
+  type: unknown;
+  schema: AnyZodSchema;
+  quit?: QuitType;
+};
+
+export class EnvironmentValidator<SchemaType> {
+  type: NodeEnvironmentEnumType;
+  schema: z.Schema<SchemaType>;
+  quit: QuitType;
+
+  constructor(config: EnvironmentValidatorConfig) {
+    this.schema = config.schema;
+    this.quit = config?.quit ?? true;
+
+    const result = NodeEnvironment.safeParse(config.type);
+
+    if (result.success) {
+      this.type = result.data;
+    } else if (this.quit) {
+      // biome-ignore lint: lint/suspicious/noConsoleLog
+      console.log(`Invalid EnvironmentType: ${config.type}`);
+      process.exit(1);
+    } else {
+      throw new NodeEnvironmentError();
+    }
+  }
+
+  load(): SchemaType & { type: NodeEnvironmentEnumType } {
+    return { ...this.schema.parse(process.env), type: this.type };
+  }
+}
+
+class NodeEnvironmentError extends Error {}

package/src/event-handler.ts

@@ -0,0 +1,20 @@
+import { EventType } from "./event";
+import { Logger } from "./logger";
+
+export class EventHandler {
+  constructor(private readonly logger: Logger) {}
+
+  handle<T extends Pick<EventType, "name">>(fn: (event: T) => Promise<void>) {
+    return async (event: T) => {
+      try {
+        await fn(event);
+      } catch (error) {
+        this.logger.error({
+          message: `Unknown ${event.name} event handler error`,
+          operation: "unknown_event_handler_error",
+          metadata: this.logger.formatError(error),
+        });
+      }
+    };
+  }
+}

package/src/event-logger.ts

@@ -0,0 +1,24 @@
+import { Logger } from "./logger";
+
+export class EventLogger {
+  constructor(private readonly logger: Logger) {}
+
+  private _handle(
+    type: string,
+    _debugName: string,
+    eventName: string | undefined,
+    eventData: Record<string, any> | undefined,
+  ) {
+    if (type === "subscribe") return;
+
+    if (typeof eventName === "symbol") return;
+
+    this.logger.info({
+      message: `${eventName} emitted`,
+      operation: "event_emitted",
+      metadata: eventData,
+    });
+  }
+
+  handle = this._handle.bind(this);
+}

package/src/event.ts

@@ -0,0 +1,29 @@
+import { z } from "zod/v4";
+
+import { UUID } from "./uuid";
+
+export const Event = z.object({
+  id: UUID,
+  createdAt: z.date(),
+
+  stream: z.string().min(1),
+
+  name: z.string().min(1),
+  version: z.number().int().positive(),
+  payload: z
+    .record(z.string(), z.any())
+    .refine((value) => {
+      try {
+        JSON.parse(JSON.stringify(value));
+        return true;
+      } catch (error) {
+        return false;
+      }
+    })
+    .transform((value) => JSON.stringify(value)),
+});
+
+export const ParsedEvent = Event.merge(z.object({ payload: z.record(z.string(), z.any()) }));
+
+export type EventType = z.infer<typeof Event>;
+export type ParsedEventType = z.infer<typeof ParsedEvent>;

package/src/file-location.ts

@@ -0,0 +1,70 @@
+import * as path from "node:path";
+
+import { Path, PathType } from "./path";
+
+type FileLocationBasenameType = string;
+
+type FileLocationExtensionType = string;
+
+type FileLocationParentType = string;
+
+export type FileLocationConfigType = {
+  parent: FileLocationParentType;
+  basename: FileLocationBasenameType;
+  extension: FileLocationExtensionType;
+};
+
+export class FileLocation {
+  readonly parent: PathType; // /parent/dir
+
+  private basename: FileLocationBasenameType; // index
+
+  private extension: FileLocationExtensionType; // .html
+
+  constructor(config: FileLocationConfigType) {
+    this.parent = Path.parse(config.parent);
+    this.basename = config.basename;
+    this.extension = config.extension;
+  }
+
+  getBasename(): FileLocationBasenameType {
+    return this.basename; // index
+  }
+
+  getExtension(): FileLocationExtensionType {
+    return this.extension; // .html
+  }
+
+  getFilename(extension?: FileLocationExtensionType): PathType {
+    return Path.parse(`${this.basename}${extension ?? this.extension}`); // index.html
+  }
+
+  getPath(extension?: FileLocationExtensionType): PathType {
+    const filename = this.getFilename(extension);
+    return Path.parse(path.join(this.parent, filename)); // parent/index.html
+  }
+
+  getGzippedPath(): PathType {
+    return Path.parse(`${this.getPath()}.gz`); // parent/index.html.gz
+  }
+
+  summary() {
+    return {
+      parent: this.parent,
+      basename: this.getBasename(),
+      extension: this.getExtension(),
+      filename: this.getFilename(),
+      path: this.getPath(),
+      gzipped: this.getGzippedPath(),
+    };
+  }
+
+  setBasename(basename: FileLocationBasenameType): FileLocation {
+    this.basename = basename;
+    return this;
+  }
+
+  async delete(): Promise<void> {
+    return Bun.file(this.getPath()).unlink();
+  }
+}

package/src/gzip.ts

@@ -0,0 +1,23 @@
+import { PathLike, createReadStream, createWriteStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import { createGunzip, createGzip } from "node:zlib";
+
+type GzipCompressConfigType = { input: PathLike; output: PathLike };
+
+export class Gzip {
+  static createCompress() {
+    return createGzip();
+  }
+
+  static createDecompress() {
+    return createGunzip();
+  }
+
+  static async compress(config: GzipCompressConfigType) {
+    return pipeline(createReadStream(config.input), createGzip(), createWriteStream(config.output));
+  }
+
+  static async uncompress(config: GzipCompressConfigType) {
+    return pipeline(createReadStream(config.input), createGunzip(), createWriteStream(config.output));
+  }
+}

package/src/hcaptcha-shield.ts

@@ -0,0 +1,57 @@
+import hcaptcha from "hcaptcha";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod/v4";
+
+export const HCaptchaSecretKey = z.string().trim().length(42);
+
+export type HCaptchaSecretKeyType = z.infer<typeof HCaptchaSecretKey>;
+
+export const HCaptchaSiteKey = z.string().trim().length(36);
+export type HCaptchaSiteKeyType = z.infer<typeof HCaptchaSiteKey>;
+
+export const HCaptchaResponseToken = z.string().trim();
+export type HCaptchaResponseTokenType = z.infer<typeof HCaptchaResponseToken>;
+
+type HCaptchaVerifierModeType = "local" | "production";
+
+export const AccessDeniedHcaptchaError = new HTTPException(403, {
+  message: "access_denied_recaptcha",
+});
+
+export type HCaptchaVerifierConfigType = {
+  secretKey: HCaptchaSecretKeyType;
+  mode: HCaptchaVerifierModeType;
+};
+
+export class HcaptchaShield {
+  private readonly secretKey: HCaptchaSecretKeyType;
+  private readonly mode: HCaptchaVerifierModeType;
+
+  private readonly LOCAL_HCAPTCHA_RESPONSE_PLACEHOLDER = "10000000-aaaa-bbbb-cccc-000000000001";
+
+  constructor(config: HCaptchaVerifierConfigType) {
+    this.mode = config.mode;
+    this.secretKey = config.secretKey;
+  }
+
+  build = createMiddleware(async (c, next) => {
+    try {
+      const form = await c.req.formData();
+
+      const hcaptchaTokenFormData = form.get("h-captcha-response")?.toString() as HCaptchaResponseTokenType;
+
+      const result = await hcaptcha.verify(
+        this.secretKey,
+        this.mode === "production" ? hcaptchaTokenFormData : this.LOCAL_HCAPTCHA_RESPONSE_PLACEHOLDER,
+      );
+
+      if (!result?.success) {
+        throw AccessDeniedHcaptchaError;
+      }
+      return next();
+    } catch (error) {
+      throw AccessDeniedHcaptchaError;
+    }
+  });
+}

package/src/healthcheck.ts

@@ -3,22 +3,17 @@ import { createFactory } from "hono/factory";
 
 import { BuildInfoRepository } from "./build-info-repository";
 import { MemoryConsumption } from "./memory-consumption";
-import {
-  AbstractPrerequisite,
-  BasePrerequisiteConfig,
-  PrerequisiteLabelType,
-  PrerequisiteStatusEnum,
-} from "./prerequisites";
+import * as prereqs from "./prerequisites";
 import { Uptime, UptimeResultType } from "./uptime";
 
 const handler = createFactory();
 
 type HealthcheckResultType = {
-  ok: PrerequisiteStatusEnum;
+  ok: prereqs.PrerequisiteStatusEnum;
   version: tools.BuildVersionType;
   details: {
-    label: PrerequisiteLabelType;
-    status: PrerequisiteStatusEnum;
+    label: prereqs.PrerequisiteLabelType;
+    status: prereqs.PrerequisiteStatusEnum;
   }[];
   uptime: UptimeResultType;
   memory: {
@@ -28,7 +23,7 @@ type HealthcheckResultType = {
 } & tools.StopwatchResultType;
 
 export class Healthcheck {
-  static build = (prerequisites: AbstractPrerequisite<BasePrerequisiteConfig>[]) =>
+  static build = (prerequisites: prereqs.AbstractPrerequisite<prereqs.BasePrerequisiteConfig>[]) =>
     handler.createHandlers(async (c) => {
       const stopwatch = new tools.Stopwatch();
 
@@ -41,11 +36,11 @@ export class Healthcheck {
         details.push({ label: prerequisite.label, status });
       }
 
-      const ok = details.every((result) => result.status !== PrerequisiteStatusEnum.failure)
-        ? PrerequisiteStatusEnum.success
-        : PrerequisiteStatusEnum.failure;
+      const ok = details.every((result) => result.status !== prereqs.PrerequisiteStatusEnum.failure)
+        ? prereqs.PrerequisiteStatusEnum.success
+        : prereqs.PrerequisiteStatusEnum.failure;
 
-      const code = ok === PrerequisiteStatusEnum.success ? 200 : 424;
+      const code = ok === prereqs.PrerequisiteStatusEnum.success ? 200 : 424;
 
       const result: HealthcheckResultType = {
         ok,

package/src/i18n.ts

@@ -4,11 +4,15 @@ import * as tools from "@bgord/tools";
 import { Path, PathType } from "./path";
 
 export type TranslationsKeyType = string;
+
 export type TranslationsValueType = string;
+
 export type TranslationsType = Record<TranslationsKeyType, TranslationsValueType>;
 
 export type TranslationPlaceholderType = string;
+
 export type TranslationPlaceholderValueType = string | number;
+
 export type TranslationVariableType = Record<TranslationPlaceholderType, TranslationPlaceholderValueType>;
 
 export type I18nConfigType = {

package/src/image-compressor.ts

@@ -0,0 +1,26 @@
+import sharp from "sharp";
+import { z } from "zod/v4";
+
+import { PathType } from "../src/path";
+
+export const ImageCompressionQuality = z.number().int().min(1).max(100).default(85);
+
+type ImageCompressionQualityType = z.infer<typeof ImageCompressionQuality>;
+
+export type ImageCompressorConfigType = {
+  input: PathType;
+  output: PathType;
+  quality?: ImageCompressionQualityType;
+};
+
+export class ImageCompressor {
+  static async compress(config: ImageCompressorConfigType): Promise<sharp.OutputInfo> {
+    const quality = config.quality ?? 85;
+
+    const image = sharp(config.input);
+    const metadata = await image.metadata();
+    const format = metadata.format as keyof sharp.FormatEnum;
+
+    return image.toFormat(format, { quality }).toFile(config.output);
+  }
+}

package/src/image-exif.ts

@@ -0,0 +1,38 @@
+import path from "node:path";
+import * as tools from "@bgord/tools";
+import mime from "mime-types";
+import sharp from "sharp";
+
+import { PathType } from "./path";
+
+export type ImageExifOutputType = {
+  width: tools.WidthType;
+  height: tools.HeightType;
+  name: path.ParsedPath["base"];
+  mimeType: tools.MimeRawType;
+};
+
+export type ImageExifClearConfigType = {
+  input: PathType;
+  output: PathType;
+};
+
+export class ImageEXIF {
+  static async read(input: PathType): Promise<ImageExifOutputType> {
+    const image = sharp(input);
+    const metadata = await image.metadata();
+
+    const name = path.parse(input).base;
+
+    return {
+      width: tools.Width.parse(metadata.width),
+      height: tools.Height.parse(metadata.height),
+      name,
+      mimeType: String(mime.contentType(String(metadata.format))),
+    };
+  }
+
+  static async clear(config: ImageExifClearConfigType): Promise<sharp.OutputInfo> {
+    return sharp(config.input).rotate().toFile(config.output);
+  }
+}