@kalutskii/foundation 0.4.3 → 0.4.5

package/dist/index.d.ts

@@ -30,20 +30,33 @@ type FetchResult<T> = {
     data: null;
 };
 
-/** Factory for creating successful API responses with serializable data. */
+/**
+ * Factory for creating successful API responses with serializable data.
+ * Example usage: `success({ status: 200, data: { message: 'Operation successful' } })`
+ */
 declare function success<T = unknown>({ status, data }: {
     status: SuccessStatusCode;
     data: T;
 }): APISuccess<T>;
-/** Factory for creating API error responses, including the error message. */
+/**
+ * Factory for creating API error responses, including the error message.
+ * Example usage: `failure({ status: 404, error: 'User not found' })`
+ */
 declare function failure({ status, error }: {
     status: ExceptionStatusCode;
     error: string;
 }): APIError;
 
-/** Resolves an APIContractResult fetcher into a FetchResult discriminated union. */
+/**
+ * Resolves an APIContractResult fetcher into a FetchResult discriminated union.
+ * Does not throw errors, instead returning them in the error property of the FetchResult.
+ * Example usage: const result = await fetchSafely(() => api.fetchUser(userId));
+ */
 declare function fetchSafely<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<FetchResult<APIContractData<TResult>>>;
-/** Resolves an APIContractResult fetcher, throwing an error if the result is an APIError. */
+/**
+ * Resolves an APIContractResult fetcher, throwing an error if the result is an APIError.
+ * Example usage: const data = await fetchAndThrow(() => api.fetchUser(userId));
+ */
 declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<APIContractData<TResult>>;
 
 /**
@@ -53,7 +66,7 @@ declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetch
 declare const onHandlerError: ErrorHandler;
 
 /**
- * Request logging middleware for Hono, providing detailed logs for each incoming request.
+ * Request logging middleware for Hono, providing deeply detailed logs for each incoming request.
  * Example log output: [12:12:12 (+4 UTC)] hono     | POST 200  123ms /api/v1/users (search=term)
  */
 declare const honoLoggingHandler: MiddlewareHandler;
@@ -61,15 +74,24 @@ declare const honoLoggingHandler: MiddlewareHandler;
 /**
  * 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.
- * Example: SerializeDates<{ createdAt: Date; nested: { updatedAt: Date }; tags: Date[] }> \
- * = { createdAt: string; nested: { updatedAt: string }; tags: string[] }
+ * Example usage: `SerializeDates<{ createdAt: Date; nested: { updatedAt: Date }; tags: Date[] }>` \
+ * = `{ createdAt: string; nested: { updatedAt: string }; tags: string[] }`
  */
 type SerializeDates<T> = T extends Date ? string : T extends (infer U)[] ? SerializeDates<U>[] : T extends readonly (infer U)[] ? readonly SerializeDates<U>[] : T extends object ? {
     [K in keyof T]: SerializeDates<T[K]>;
 } : T;
+type QueryPrimitive = string | number | boolean | bigint | Date | null | undefined;
+/**
+ * Type utility that recursively transforms all fields to string, as well as handling arrays and objects.
+ * This is useful for serializing complex data structures into query parameters, which must be strings.
+ * Example usage: `AsQuery<{ id: number; name: string; tags: string[] }>` = `{ id: string; name: string; tags: string[] }`
+ */
+type AsQuery<T> = T extends QueryPrimitive ? string : T extends readonly (infer Item)[] ? AsQuery<Item>[] : T extends object ? {
+    [Key in keyof T]: AsQuery<T[Key]>;
+} : string;
 /**
  * Transforms a string to a number (when passing query parameters).
- * Example: asQueryNumber(z.number())('123') = 123
+ * Example usage: `asQueryNumber(z.number())('123') = 123`
  */
 declare const asQueryNumber: <T extends ZodNumber>(schema: T) => z.ZodPreprocess<T>;
 /**
@@ -79,8 +101,8 @@ declare const asQueryNumber: <T extends ZodNumber>(schema: T) => z.ZodPreprocess
 declare const asQueryBoolean: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<T>;
 
 /**
- * Wraps c.json with a typed success payload & possible APIError.
- * When no data is provided, responds with an empty object {}.
+ * Wraps c.json with a typed success payload / (or void data) & possible APIError response.
+ * When no data is provided, responds with an empty object {} (purely for type consistency).
  */
 declare function respond<T extends object = Record<string, never>, S extends SuccessStatusCode = SuccessStatusCode>(c: Context, options: {
     status: S;
@@ -89,19 +111,19 @@ declare function respond<T extends object = Record<string, never>, S extends Suc
 
 /**
  * Returns the current time in the specified timezone.
- * Example: getZonedTime({ tz: 'America/New_York' }) = new Date('2026-03-15T12:00:00Z')
+ * Example usage: `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)'
+ * Example usage: `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)'
+ * Example usage: `getFormattedTime({ tz: 'America/New_York' }) = '12:00:00 (-4 UTC)'`
  */
 declare const getFormattedTime: ({ tz }?: {
     tz?: string;
@@ -109,7 +131,7 @@ declare const getFormattedTime: ({ tz }?: {
 /**
  * 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)'
+ * Example usage: `getFormattedDate({ tz: 'America/New_York' }) = '03.15.2026 12:00:00 (-4 UTC)'`
  */
 declare const getFormattedDate: ({ tz, withTime, }?: {
     tz?: string;
@@ -117,7 +139,7 @@ declare const getFormattedDate: ({ tz, withTime, }?: {
 }) => 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)'
+ * Example usage: `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;
@@ -126,13 +148,31 @@ declare const formatTime: (time: Date, { locale, tz }?: {
 
 /**
  * Safely executes functions and handles errors without using try/catch in the calling code.
- * Example: safeExecute(() => fetchData(), (error) => console.error(error));
+ * Example usage: `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>;
+type MeasuredExecution<T> = {
+    /** The result of the executed function. */
+    result: T;
+    /** The time taken to execute the function, in milliseconds. */
+    executionTime: number;
+};
+/**
+ * Utility function to measure the execution time of an asynchronous function.
+ * @returns An object containing the result of the execution and the time taken in milliseconds.
+ *
+ * ```ts
+ * const { result, executionTime } = await measureExecutionTime(async () => {
+ *    return await fetchData();
+ * });
+ * console.log(`Execution time: ${executionTime}ms`);
+ * ```
+ */
+declare function measureExecutionTime<T>(execution: () => Promise<T>): Promise<MeasuredExecution<T>>;
 
 /**
  * Creates a random string of the specified length using characters from DEFAULT_CHARACTERS.
- * Example: generateRandomString(5) = 'aZ3fG' / generateRandomString() = 'G5kLm2P9sQ' (default 10 characters)
+ * Example usage: `generateRandomString(5) = 'aZ3fG' / generateRandomString() = 'G5kLm2P9sQ'`
  */
 declare function generateRandomString(length?: number): string;
 
@@ -143,7 +183,7 @@ declare function generateRandomString(length?: number): string;
 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.
+ * with optional service name and stack trace for errors (error level).
  */
 declare const log: {
     info: (message: string, service?: string) => void;
@@ -212,4 +252,4 @@ declare class ZodJWTService<TPayloadOrSchema> {
     verifyOrThrow(token: string, secret: string): Promise<Payload<TPayloadOrSchema>>;
 }
 
-export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type JWTServiceOptions, type JWTSignOptions, type Payload, type PayloadSchema, SUCCESS_STATUS_CODES, type SerializeDates, type SuccessStatusCode, type XOR, ZodJWTService, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, log, onHandlerError, respond, safeExecute, success };
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AsQuery, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type JWTServiceOptions, type JWTSignOptions, type MeasuredExecution, type Payload, type PayloadSchema, SUCCESS_STATUS_CODES, type SerializeDates, type SuccessStatusCode, type XOR, ZodJWTService, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, log, measureExecutionTime, onHandlerError, respond, safeExecute, success };

package/dist/index.js

@@ -140,6 +140,12 @@ async function safeExecute(fn, onError) {
     throw err;
   }
 }
+async function measureExecutionTime(execution) {
+  const startedAt = performance.now();
+  const result = await execution();
+  const executionTime = performance.now() - startedAt;
+  return { result, executionTime: Math.round(executionTime) };
+}
 
 // src/utilities/serialization.utilities.ts
 import { z } from "zod";
@@ -224,6 +230,7 @@ export {
   getZonedTime,
   honoLoggingHandler,
   log,
+  measureExecutionTime,
   onHandlerError,
   respond,
   safeExecute,

package/package.json

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