@bgord/bun 0.1.0

package/dist/time.d.ts

@@ -0,0 +1,21 @@
+interface TimeResultInterface {
+    readonly days: number;
+    readonly hours: number;
+    readonly minutes: number;
+    readonly seconds: number;
+    readonly ms: number;
+    isAfter(another: TimeResultInterface): boolean;
+    isBefore(another: TimeResultInterface): boolean;
+}
+export declare class Time {
+    static Days(value: number): TimeResultInterface;
+    static Hours(value: number): TimeResultInterface;
+    static Minutes(value: number): TimeResultInterface;
+    static Seconds(value: number): TimeResultInterface;
+    static Ms(value: number): TimeResultInterface;
+    static Now(now?: number): {
+        Minus(time: TimeResultInterface): TimeResultInterface;
+        Add(time: TimeResultInterface): TimeResultInterface;
+    };
+}
+export {};

package/dist/timeout.d.ts

@@ -0,0 +1,9 @@
+import express from "express";
+import { TimestampType } from "./schema";
+type TimeoutConfigType = {
+    ms: TimestampType;
+};
+export declare class Timeout {
+    static build(config: TimeoutConfigType): (request: express.Request, response: express.Response, next: express.NextFunction) => void;
+}
+export {};

package/dist/ts-utils.d.ts

@@ -0,0 +1,3 @@
+export type Constructor<T> = new (...args: any[]) => T;
+export type Falsy<T> = T | null | undefined;
+export type Nullable<T> = T | null;

package/dist/uploaded-file-location.d.ts

@@ -0,0 +1,10 @@
+import * as Schema from "./schema";
+import { FileLocation, FileLocationConfigType } from "./file-location";
+import { Size } from "./size";
+export declare class UploadedFileLocation {
+    readonly size: Size;
+    readonly temporary: Schema.PathType;
+    readonly handle: FileLocation;
+    constructor(file: Schema.UploadedFileType, parent: FileLocationConfigType["parent"]);
+    transfer(): Promise<void>;
+}

package/dist/uptime.d.ts

@@ -0,0 +1,9 @@
+import { DateFormatters } from "./dates";
+import { TimestampType } from "./schema";
+export type UptimeResultType = {
+    seconds: TimestampType;
+    formatted: ReturnType<(typeof DateFormatters)["relative"]>;
+};
+export declare class Uptime {
+    static get(): UptimeResultType;
+}

package/dist/uuid.d.ts

@@ -0,0 +1,3 @@
+export declare class NewUUID {
+    static generate(): `${string}-${string}-${string}-${string}-${string}`;
+}

package/dist/visually-unambiguous-characters-generator.d.ts

@@ -0,0 +1,4 @@
+export declare class VisuallyUnambiguousCharactersGenerator {
+    static chars: string[];
+    static generate(length?: number): string;
+}

package/dist/z-score.d.ts

@@ -0,0 +1,8 @@
+import { RoundingStrategy } from "./rounding";
+export declare class ZScore {
+    private readonly rounding;
+    private readonly mean;
+    private readonly standardDeviation;
+    constructor(values: number[], rounding?: RoundingStrategy);
+    calculate(value: number): number;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "version": "0.1.0",
+  "license": "MIT",
+  "name": "@bgord/bun",
+  "type": "module",
+  "author": "Bartosz Gordon",
+  "source": "src/index.ts",
+  "exports": {
+    "require": "./dist/bgord-bun.cjs",
+    "default": "./dist/bgord-bun.modern.js"
+  },
+  "main": "./dist/bgord-bun.cjs",
+  "module": "./dist/bgord-bun.module.js",
+  "unpkg": "./dist/bgord-bun.umd.js",
+  "typings": "./dist/index.d.ts",
+  "scripts": {
+    "build": "microbundle",
+    "prepare": "husky",
+    "preinstall": "npx only-allow bun"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "1.9.3",
+    "@commitlint/cli": "19.5.0",
+    "@commitlint/config-conventional": "19.5.0",
+    "@types/bun": "1.1.11",
+    "@types/lodash": "4.17.10",
+    "cspell": "8.14.4",
+    "husky": "9.1.6",
+    "knip": "5.33.2",
+    "microbundle": "0.15.1",
+    "only-allow": "1.2.1",
+    "shellcheck": "3.0.0",
+    "supertest": "7.0.0",
+    "typescript": "5.6.3"
+  },
+  "dependencies": {
+    "@bgord/node": "0.82.0",
+    "hono": "4.6.4",
+    "lodash": "4.17.21"
+  },
+  "resolutions": {
+    "typescript": "4.7.4"
+  }
+}

package/src/api-key-shield.ts

@@ -0,0 +1,23 @@
+import * as bg from "@bgord/node";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+type ApiKeyShieldConfigType = { API_KEY: bg.Schema.ApiKeyType };
+
+export const AccessDeniedApiKeyError = new HTTPException(403, {
+  message: "access_denied_api_key",
+});
+
+export class ApiKeyShield {
+  static readonly HEADER_NAME = "bgord-api-key";
+
+  constructor(private readonly config: ApiKeyShieldConfigType) {}
+
+  verify = createMiddleware(async (c, next) => {
+    if (c.req.header(ApiKeyShield.HEADER_NAME) === this.config.API_KEY) {
+      return next();
+    }
+
+    throw AccessDeniedApiKeyError;
+  });
+}

package/src/api-version.ts

@@ -0,0 +1,19 @@
+import * as bg from "@bgord/node";
+import { createMiddleware } from "hono/factory";
+
+export class ApiVersion {
+  static HEADER_NAME = "api-version";
+
+  static DEFAULT_API_VERSION = "unknown";
+
+  static attach = createMiddleware(async (c, next) => {
+    const build = await bg.BuildInfoRepository.extract();
+
+    c.res.headers.set(
+      ApiVersion.HEADER_NAME,
+      build.BUILD_VERSION ?? ApiVersion.DEFAULT_API_VERSION
+    );
+
+    await next();
+  });
+}

package/src/context.ts

@@ -0,0 +1,20 @@
+import * as bg from "@bgord/node";
+import { createMiddleware } from "hono/factory";
+
+import { TimeZoneOffsetVariables } from "./time-zone-offset";
+
+export type ContextVariables = {
+  context: bg.ContextType;
+  requestId: string;
+} & TimeZoneOffsetVariables;
+
+export class Context {
+  static attach = createMiddleware(async (c, next) => {
+    c.set("context", {
+      requestId: c.get("requestId") as bg.Schema.CorrelationIdType,
+      timeZoneOffset: c.get("timeZoneOffset"),
+    });
+
+    await next();
+  });
+}

package/src/etag-extractor.ts

@@ -0,0 +1,41 @@
+import * as bg from "@bgord/node";
+import { createMiddleware } from "hono/factory";
+
+export type EtagVariables = {
+  ETag: bg.ETag | null;
+  WeakETag: bg.WeakETag | null;
+};
+
+export class ETagExtractor {
+  static attach = createMiddleware<{ Variables: EtagVariables }>(
+    async (c, next) => {
+      try {
+        const header = String(c.req.header(bg.ETag.IF_MATCH_HEADER_NAME));
+
+        if (!header || header === "undefined") c.set("ETag", null);
+        else c.set("ETag", bg.ETag.fromHeader(header));
+      } catch (error) {
+        c.set("ETag", null);
+      }
+
+      await next();
+    }
+  );
+}
+
+export class WeakETagExtractor {
+  static attach = createMiddleware<{ Variables: EtagVariables }>(
+    async (c, next) => {
+      try {
+        const header = String(c.req.header(bg.WeakETag.IF_MATCH_HEADER_NAME));
+
+        if (!header || header === "undefined") c.set("WeakETag", null);
+        else c.set("WeakETag", bg.ETag.fromHeader(header));
+      } catch (error) {
+        c.set("WeakETag", null);
+      }
+
+      await next();
+    }
+  );
+}

package/src/graceful-shutdown.ts

@@ -0,0 +1,44 @@
+import * as bg from "@bgord/node";
+
+type ServerType = ReturnType<typeof Bun.serve>;
+
+export class GracefulShutdown {
+  private static async shutdown(
+    server: ServerType,
+    callback: () => any = bg.noop
+  ) {
+    server.stop();
+    await callback();
+    // biome-ignore lint: lint/suspicious/noConsoleLog
+    console.log("HTTP server closed");
+  }
+
+  static applyTo(server: ServerType, callback: () => any = bg.noop) {
+    process.on("SIGTERM", async () => {
+      // biome-ignore lint: lint/suspicious/noConsoleLog
+      console.log("SIGTERM signal received: closing HTTP server");
+      await GracefulShutdown.shutdown(server, callback);
+      process.exit(0);
+    });
+
+    process.on("SIGINT", async () => {
+      // biome-ignore lint: lint/suspicious/noConsoleLog
+      console.log("SIGINT signal received: closing HTTP server");
+      await GracefulShutdown.shutdown(server, callback);
+      process.exit(0);
+    });
+
+    process.on("unhandledRejection", async (event) => {
+      // biome-ignore lint: lint/suspicious/noConsoleLog
+      console.log(
+        "UnhandledPromiseRejectionWarning received: closing HTTP server"
+      );
+
+      // biome-ignore lint: lint/suspicious/noConsoleLog
+      console.log(JSON.stringify(event));
+
+      await GracefulShutdown.shutdown(server, callback);
+      process.exit(1);
+    });
+  }
+}

package/src/healthcheck.ts

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

package/src/http-logger.ts

@@ -0,0 +1,123 @@
+import * as bg from "@bgord/node";
+import { createMiddleware } from "hono/factory";
+import { getConnInfo } from "hono/bun";
+import _ from "lodash";
+
+export class HttpLogger {
+  private static simplify(response: unknown) {
+    const result = JSON.stringify(response, (_key, value) =>
+      Array.isArray(value) ? { type: "Array", length: value.length } : value
+    );
+
+    return JSON.parse(result);
+  }
+
+  private static uninformativeHeaders = [
+    "accept",
+    "accept-encoding",
+    "cache-control",
+    "connection",
+    "content-length",
+    "content-type",
+    "cookie",
+    "dnt",
+    "host",
+    "origin",
+    "pragma",
+    "sec-fetch-dest",
+    "sec-fetch-mode",
+    "sec-fetch-site",
+    "sec-fetch-user",
+    "sec-gpc",
+    "upgrade-insecure-requests",
+    "user-agent",
+    "if-none-match",
+  ];
+
+  static build = (logger: bg.Logger) =>
+    createMiddleware(async (c, next) => {
+      const correlationId = c.get("requestId") as bg.Schema.CorrelationIdType;
+      const info = getConnInfo(c);
+      const url = c.req.url;
+      const method = c.req.method;
+
+      const client = {
+        ip:
+          c.req.header("x-real-ip") ||
+          c.req.header("x-forwarded-for") ||
+          info.remote.address,
+        userAgent: c.req.header("user-agent"),
+      };
+
+      let body: any;
+
+      try {
+        body = await c.req.json();
+      } catch (error) {}
+
+      const httpRequestBeforeMetadata = {
+        params: c.req.param(),
+        headers: _.omit(
+          c.req.raw.headers.toJSON(),
+          HttpLogger.uninformativeHeaders
+        ),
+        body,
+        query: c.req.queries(),
+      };
+
+      logger.http({
+        operation: "http_request_before",
+        correlationId,
+        message: "request",
+        method,
+        url,
+        client,
+        metadata: _.pickBy(
+          httpRequestBeforeMetadata,
+          (value) => !_.isEmpty(value)
+        ),
+      });
+
+      await next();
+
+      const cacheHitHeader = c.res.headers.get(
+        bg.CacheResponse.CACHE_HIT_HEADER
+      );
+
+      const cacheHit =
+        cacheHitHeader === bg.CacheHitEnum.hit
+          ? bg.CacheHitEnum.hit
+          : undefined;
+
+      let response: any;
+      try {
+        response = await c.res.clone().json();
+      } catch (error) {}
+
+      const httpRequestAfterMetadata = {
+        response,
+        cacheHit,
+      };
+
+      const serverTimingMs = c.res.headers.get("Server-Timing");
+
+      const durationMsMatch =
+        serverTimingMs?.match(/dur=([0-9]*\.?[0-9]+)/) ?? undefined;
+
+      const durationMs = durationMsMatch?.[1]
+        ? Number(durationMsMatch[1])
+        : undefined;
+
+      logger.http({
+        operation: "http_request_after",
+        correlationId,
+        message: "response",
+        method,
+        url,
+        responseCode: c.res.status,
+        durationMs,
+        client,
+        metadata: HttpLogger.simplify(httpRequestAfterMetadata),
+      });
+    });
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./graceful-shutdown";
+export * from "./api-version";
+export * from "./time-zone-offset";
+export * from "./context";
+export * from "./etag-extractor";
+export * from "./http-logger";
+export * from "./api-key-shield";
+export * from "./rate-limit-shield";
+export * from "./healthcheck";

package/src/rate-limit-shield.ts

@@ -0,0 +1,24 @@
+import * as bg from "@bgord/node";
+import { HTTPException } from "hono/http-exception";
+import { createMiddleware } from "hono/factory";
+
+type RateLimitShieldOptionsType = { ms: bg.Schema.TimestampType };
+
+export const TooManyRequestsError = new HTTPException(429, {
+  message: "app.too_many_requests",
+});
+
+export const rateLimitShield = (options: RateLimitShieldOptionsType) => {
+  const rateLimiter = new bg.RateLimiter(options);
+
+  return createMiddleware(async (_c, next) => {
+    const currentTimestampMs = Date.now();
+    const check = rateLimiter.verify(currentTimestampMs);
+
+    if (!check.allowed) {
+      throw TooManyRequestsError;
+    }
+
+    return next();
+  });
+};

package/src/time-zone-offset.ts

@@ -0,0 +1,44 @@
+import * as bg from "@bgord/node";
+import { createMiddleware } from "hono/factory";
+
+export type TimeZoneOffsetVariables = {
+  timeZoneOffset: {
+    minutes: bg.Schema.TimeZoneOffsetValueType;
+    seconds: bg.Schema.TimeZoneOffsetValueType;
+    miliseconds: bg.Schema.TimeZoneOffsetValueType;
+  };
+};
+
+export class TimeZoneOffset {
+  static TIME_ZONE_OFFSET_HEADER_NAME = "time-zone-offset";
+
+  static attach = createMiddleware(async (c, next) => {
+    const timeZoneOffsetMinutes = bg.Schema.TimeZoneOffsetHeaderValue.parse(
+      c.req.header(TimeZoneOffset.TIME_ZONE_OFFSET_HEADER_NAME)
+    );
+
+    const timeZoneOffset = {
+      minutes: timeZoneOffsetMinutes,
+      seconds: bg.Time.Minutes(timeZoneOffsetMinutes).seconds,
+      miliseconds: bg.Time.Minutes(timeZoneOffsetMinutes).ms,
+    };
+
+    c.set("timeZoneOffset", timeZoneOffset);
+
+    await next();
+  });
+
+  static adjustTimestamp(
+    timestamp: bg.Schema.TimestampType,
+    timeZoneOffsetMs: bg.Schema.TimeZoneOffsetValueType
+  ): bg.Schema.TimestampType {
+    return timestamp - timeZoneOffsetMs;
+  }
+
+  static adjustDate(
+    timestamp: bg.Schema.TimestampType,
+    timeZoneOffsetMs: bg.Schema.TimeZoneOffsetValueType
+  ): Date {
+    return new Date(timestamp - timeZoneOffsetMs);
+  }
+}