@kalutskii/foundation 0.1.3 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
-# @esb-market-contracts/core
+# @kalutskii/foundation
 
-Shared HTTP contracts and helpers for consistent API communication across esb-market-space services.
+Collection of utilities, types, and helpers for building typed API contracts and responses in TypeScript projects. Designed for use in Bun/Node.js and Cloudflare Workers environments.
 
 ## What this package provides
 
@@ -13,13 +13,13 @@ Shared HTTP contracts and helpers for consistent API communication across esb-ma
 ## Installation
 
 ```bash
-bun add @esb-market-contracts/core
+bun add @kalutskii/foundation
 ```
 
 or
 
 ```bash
-npm i @esb-market-contracts/core
+npm i @kalutskii/foundation
 ```
 
 ## Core concepts
@@ -39,8 +39,8 @@ Status code groups are exported as constants and used by types:
 ### 1. Build typed contracts
 
 ```ts
-import { failure, success } from '@esb-market-contracts/core';
-import type { APIContractResult } from '@esb-market-contracts/core';
+import { failure, success } from '@kalutskii/foundation';
+import type { APIContractResult } from '@kalutskii/foundation';
 
 type User = { id: string; name: string };
 
@@ -53,8 +53,8 @@ const result: APIContractResult<User> = Math.random() > 0.5 ? ok : bad;
 ### 2. Resolve fetchers safely
 
 ```ts
-import { fetchAndThrow, fetchSafely } from '@esb-market-contracts/core';
-import type { APIContractResult } from '@esb-market-contracts/core';
+import { fetchAndThrow, fetchSafely } from '@kalutskii/foundation';
+import type { APIContractResult } from '@kalutskii/foundation';
 
 type User = { id: string; name: string };
 
@@ -78,7 +78,7 @@ try {
 ### 3. Use typed Hono JSON responses
 
 ```ts
-import { respond } from '@esb-market-contracts/core';
+import { respond } from '@kalutskii/foundation';
 import { Hono } from 'hono';
 
 const app = new Hono();
@@ -96,7 +96,7 @@ app.get('/health', (c) => {
 ### 4. Parse query params with helpers
 
 ```ts
-import { asQueryBoolean, asQueryNumber } from '@esb-market-contracts/core';
+import { asQueryBoolean, asQueryNumber } from '@kalutskii/foundation';
 import { z } from 'zod';
 
 const pageSchema = asQueryNumber(z.number().int().min(1));

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { Context, TypedResponse } from 'hono';
+import { ErrorHandler, Context, TypedResponse } from 'hono';
 import { z, ZodNumber } from 'zod';
+import { Locale } from 'date-fns';
 
 declare const SUCCESS_STATUS_CODES: readonly [200, 201, 202, 307];
 declare const EXCEPTION_STATUS_CODES: readonly [400, 401, 403, 404, 405, 409, 500];
@@ -44,6 +45,12 @@ declare function fetchSafely<TResult extends APIContractResult<unknown>>(fetcher
 /** Resolves an APIContractResult fetcher, throwing an error if the result is an APIError. */
 declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<APIContractData<TResult>>;
 
+/**
+ * Global error handler for Hono framework. Catches all exceptions thrown in route handlers and middlewares.
+ * Distinguishes between expected HTTPExceptions (mapped to their status codes) and unexpected errors (500).
+ */
+declare const onHandlerError: ErrorHandler;
+
 /**
  * Type utility that recursively transforms all Date fields to string, as well as handling arrays and objects.
  * This is necessary for proper typing when working with RPC, as JSON does not support the Date type directly.
@@ -73,4 +80,68 @@ declare function respond<T extends object = Record<string, never>, S extends Suc
     data?: T;
 }): Response & TypedResponse<APISuccess<SerializeDates<T>> | APIError, S, 'json'>;
 
-export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, SUCCESS_STATUS_CODES, type SerializeDates, type SuccessStatusCode, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, respond, success };
+/**
+ * Returns the current time in the specified timezone.
+ * Example: getZonedTime({ tz: 'America/New_York' }) = new Date('2026-03-15T12:00:00Z')
+ */
+declare const getZonedTime: ({ tz }?: {
+    tz?: string;
+}) => Date;
+/**
+ * Returns the timezone offset in the format (+4 UTC) / (-5 UTC).
+ * Example: getUTCOffset(new Date('2026-03-15T12:00:00Z'), 'America/New_York') = '(-4 UTC)'
+ */
+declare const getUTCOffset: (date: Date, tz: string) => string;
+/**
+ * Returns the current time in the specified timezone, formatted as HH:mm:ss (+X UTC).
+ * Example: getFormattedTime({ tz: 'America/New_York' }) = '12:00:00 (-4 UTC)'
+ */
+declare const getFormattedTime: ({ tz }?: {
+    tz?: string;
+}) => string;
+/**
+ * Returns the current date in the specified timezone, formatted as dd.MM.yyyy.
+ * By default, it also includes time (HH:mm:ss) and timezone offset.
+ * Example: getFormattedDate({ tz: 'America/New_York' }) = '03.15.2026 12:00:00 (-4 UTC)'
+ */
+declare const getFormattedDate: ({ tz, withTime, }?: {
+    tz?: string;
+    withTime?: boolean;
+}) => string;
+/**
+ * Formats the given time in the specified timezone, using the provided locale for date formatting.
+ * Example: formatTime(new Date('2026-03-15T12:00:00Z'), { tz: 'America/New_York' }) = '12:00:00, March 15, 2026 (-4 UTC)'
+ */
+declare const formatTime: (time: Date, { locale, tz }?: {
+    locale?: Locale;
+    tz?: string;
+}) => string;
+
+/**
+ * Safely executes functions and handles errors without using try/catch in the calling code.
+ * Example: safeExecute(() => fetchData(), (error) => console.error(error));
+ */
+declare function safeExecute<T, E = never>(fn: () => Promise<T> | T, onError?: (error?: unknown) => E | Promise<E>): Promise<T | E>;
+
+/**
+ * Creates a random string of the specified length using characters from DEFAULT_CHARACTERS.
+ * Example: generateRandomString(5) = 'aZ3fG' / generateRandomString() = 'G5kLm2P9sQ' (default 10 characters)
+ */
+declare function generateRandomString(length?: number): string;
+
+/**
+ * HTTP status colors for better visual parsing in logs:
+ * 2xx - green, 4xx - yellow, 5xx - red, others - default color.
+ */
+declare function getColoredHTTPStatus(status: number): (text: string) => string;
+/**
+ * Unified logging interface for different levels (info, warn, error)
+ * with optional service name and stack trace for errors.
+ */
+declare const log: {
+    info: (message: string, service?: string) => void;
+    warn: (message: string, service?: string) => void;
+    error: (message: string, service?: string, stack?: string) => void;
+};
+
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, SUCCESS_STATUS_CODES, type SerializeDates, type SuccessStatusCode, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, log, onHandlerError, respond, safeExecute, success };

package/dist/index.js

@@ -24,12 +24,108 @@ async function fetchAndThrow(fetcher) {
   return response.data;
 }
 
+// src/hono/hono.execution.ts
+import { HTTPException } from "hono/http-exception";
+import { red as red2 } from "kleur";
+
+// src/utilities/generation.utilities.ts
+var DEFAULT_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+function generateRandomString(length = 10) {
+  const randomValues = crypto.getRandomValues(new Uint32Array(length));
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += DEFAULT_CHARACTERS[randomValues[i] % DEFAULT_CHARACTERS.length];
+  }
+  return result;
+}
+
+// src/utilities/logging.utilities.ts
+import { blue, dim, green, red, white, yellow } from "kleur/colors";
+
+// src/utilities/datetime.utilities.ts
+import { format } from "date-fns";
+import { getTimezoneOffset, toZonedTime } from "date-fns-tz";
+import { ru } from "date-fns/locale";
+var getZonedTime = ({ tz = "Europe/London" } = {}) => {
+  return toZonedTime(/* @__PURE__ */ new Date(), tz);
+};
+var getUTCOffset = (date, tz) => {
+  const offset = getTimezoneOffset(tz, date) / (60 * 60 * 1e3);
+  return `(${offset >= 0 ? "+" : ""}${offset} UTC)`;
+};
+var getFormattedTime = ({ tz = "Europe/London" } = {}) => {
+  const zonedTime = getZonedTime({ tz });
+  return `${format(zonedTime, "HH:mm:ss")} ${getUTCOffset(zonedTime, tz)}`;
+};
+var getFormattedDate = ({ tz = "Europe/London", withTime = true } = {}) => {
+  const zonedTime = getZonedTime({ tz });
+  const pattern = withTime ? "dd.MM.yyyy HH:mm:ss" : "dd.MM.yyyy";
+  const formatted = format(zonedTime, pattern);
+  return `${formatted}${withTime ? ` ${getUTCOffset(zonedTime, tz)}` : ""}`;
+};
+var formatTime = (time, { locale = ru, tz = "Europe/London" } = {}) => {
+  const zonedTime = toZonedTime(time, tz);
+  return `${format(zonedTime, "HH:mm:ss, d MMMM yyyy", { locale })} ${getUTCOffset(zonedTime, tz)}`;
+};
+
+// src/utilities/logging.utilities.ts
+function getColoredHTTPStatus(status) {
+  const colorMap = [
+    { range: [200, 299], colorFn: green },
+    { range: [400, 499], colorFn: yellow },
+    { range: [500, 599], colorFn: red }
+  ];
+  const statusColor = colorMap.find(({ range: [min, max] }) => status >= (min || 0) && status <= (max || 600));
+  return statusColor ? statusColor.colorFn : (text) => text;
+}
+function writeLog(message, level, service = "log", stack) {
+  const logColorMap = { info: blue, warn: yellow, error: red };
+  const timestamp = dim(getFormattedTime());
+  const serviceName = logColorMap[level](service).padEnd(18);
+  const formattedMessage = white(message);
+  console.log(`[${timestamp}] ${serviceName} | ${formattedMessage}`);
+  if (stack)
+    console.log(`[${timestamp}] ${red("\u21B3 trace").padEnd(18)} | ${dim(stack)}`);
+}
+var log = {
+  info: (message, service) => writeLog(message, "info", service),
+  warn: (message, service) => writeLog(message, "warn", service),
+  error: (message, service, stack) => writeLog(message, "error", service, stack)
+};
+
+// src/hono/hono.execution.ts
+function proceedUnhandledError(error) {
+  const errorId = generateRandomString(6);
+  const errorMessage = error instanceof Error ? error.message + error.stack : JSON.stringify(error);
+  log.error(`Unhandled error: ${red2(errorMessage)}`, errorId);
+  return failure({ status: 500, error: `Internal server error | ${errorId}` });
+}
+var onHandlerError = (error, c) => {
+  let response;
+  if (error instanceof HTTPException && error.status < 500) {
+    response = failure({ status: error.status, error: error.message });
+  } else
+    response = proceedUnhandledError(error);
+  return c.json(response, response.status);
+};
+
 // src/hono/hono.respond.ts
 function respond(c, options) {
   return c.json(success({ status: options.status, data: options.data ?? {} }), options.status);
 }
 
-// src/utilities/serialize.utilities.ts
+// src/utilities/execution.utilities.ts
+async function safeExecute(fn, onError) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (onError)
+      return await onError(err);
+    throw err;
+  }
+}
+
+// src/utilities/serialization.utilities.ts
 import { z } from "zod";
 var asQueryNumber = (schema) => z.preprocess((v) => typeof v === "string" ? Number(v) : v, schema);
 var asQueryBoolean = (schema) => {
@@ -56,6 +152,16 @@ export {
   failure,
   fetchAndThrow,
   fetchSafely,
+  formatTime,
+  generateRandomString,
+  getColoredHTTPStatus,
+  getFormattedDate,
+  getFormattedTime,
+  getUTCOffset,
+  getZonedTime,
+  log,
+  onHandlerError,
   respond,
+  safeExecute,
   success
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
   "type": "module",
   "repository": {