@kalutskii/foundation 0.4.5 → 0.5.1

package/dist/index.d.ts

@@ -3,6 +3,18 @@ import z$1, { z, ZodNumber } from 'zod';
 import { Locale } from 'date-fns';
 import { SymmetricAlgorithm } from 'hono/utils/jwt/jwa';
 
+/**
+ * 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;
+
+/**
+ * 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;
+
 declare const SUCCESS_STATUS_CODES: readonly [200, 201, 202, 307];
 declare const EXCEPTION_STATUS_CODES: readonly [400, 401, 403, 404, 405, 409, 500];
 
@@ -30,47 +42,6 @@ type FetchResult<T> = {
     data: null;
 };
 
-/**
- * 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.
- * 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.
- * 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.
- * Example usage: const data = await fetchAndThrow(() => api.fetchUser(userId));
- */
-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;
-
-/**
- * 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;
-
 /**
  * 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.
@@ -109,6 +80,74 @@ declare function respond<T extends object = Record<string, never>, S extends Suc
     data?: T;
 }): Response & TypedResponse<APISuccess<SerializeDates<T>> | APIError, S, 'json'>;
 
+/**
+ * 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.
+ * 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.
+ * 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.
+ * Example usage: const data = await fetchAndThrow(() => api.fetchUser(userId));
+ */
+declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<APIContractData<TResult>>;
+
+/**
+ * A Zod schema for validating pagination options, specifically the `offset` and `limit` parameters.
+ * - `offset`: An optional non-negative integer representing the starting point for pagination.
+ * - `limit`: An optional positive integer representing the maximum number of items to return.
+ *
+ * This schema can be used to inject in other Zod schemas for validating pagination options:
+ *
+ * ```ts
+ * const mySchema = paginationSchema.extend({
+ *   // other fields here
+ * });
+ * ```
+ */
+declare const paginationSchema: z$1.ZodObject<{
+    offset: z$1.ZodOptional<z$1.ZodNumber>;
+    limit: z$1.ZodOptional<z$1.ZodNumber>;
+}, z$1.core.$strip>;
+/**
+ * A TypeScript type representing the pagination options validated by the `paginationSchema`.
+ * Read documentation for `paginationSchema` for more details on the structure and usage of this type.
+ */
+type PaginationOptions = z$1.infer<typeof paginationSchema>;
+
+/**
+ * A utility function that extracts pagination options from the provided input.
+ * It returns an object containing the `offset` and `limit` properties if they are defined.
+ * If the input is undefined or does not contain these properties, it returns an empty object.
+ *
+ * ```ts
+ * await db.query.someTable.findMany({
+ *   ...getPagination(options),
+ * });
+ * ```
+ */
+declare const getPagination: (options?: PaginationOptions) => {
+    offset?: number | undefined;
+    limit?: number | undefined;
+};
+
 /**
  * Returns the current time in the specified timezone.
  * Example usage: `getZonedTime({ tz: 'America/New_York' }) = new Date('2026-03-15T12:00:00Z')`
@@ -191,21 +230,42 @@ declare const log: {
     error: (message: string, service?: string, stack?: string) => void;
 };
 
+/**
+ * Utility type that simplifies a given type T by flattening its structure.
+ * This is particularly useful for improving the readability of complex types.
+ */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
 /**
  * A utility type that represents a value that can be of type T or null.
  * Commonly used for optional fields in data models or function return types.
  *
- * ```
+ * ```ts
  * export type ObjectSelect = XOR<
  *   Pick<Object, 'id'>,
  *   Pick<Object, 'anotherUniqueField'>
  * >;
  */
-type XOR<T, U> = (T & {
+type XOR<T, U> = Simplify<T & {
     [K in keyof U]?: never;
-}) | (U & {
+}> | Simplify<U & {
     [K in keyof T]?: never;
-});
+}>;
+/**
+ * Utility type that ensures at least one property from the specified
+ * keys of a given type T is required, while the rest remain optional.
+ *
+ * This is useful for scenarios where you want to enforce that at least one
+ * of several optional (nullable) properties must be provided in an object.
+ *
+ * ```ts
+ * type Example = AtLeastOne<{ a?: string; b?: number; c?: boolean }>;
+ * // Valid: { a: "hello" }, { b: 42 }, { c: true }, { a: "hello", b: 42 }
+ * // Invalid: {}, { a: undefined, b: undefined, c: undefined }
+ * ```
+ */
+type AtLeastOne<T, Keys extends keyof T = keyof T> = Keys extends keyof T ? Simplify<Required<Pick<T, Keys>> & Partial<Omit<T, Keys>>> : never;
 
 /** Options for configuring the JWT service. */
 type JWTServiceOptions = {
@@ -241,15 +301,18 @@ declare class ZodJWTService<TPayloadOrSchema> {
     /**
      * Decodes a JWT token, and if a Zod schema is provided, validates the payload against it.
      * Returns the decoded payload if valid, or null if invalid or if the token cannot be decoded.
+     *
      * Example usage: `const payload = await JWTServiceInstance.decode(token);`
      */
     decode(token: string): Promise<Payload<TPayloadOrSchema> | null>;
     /**
      * Verifies and decodes a JWT token using the provided secret and configured algorithm,
-     * then validates the payload against the Zod schema if one is provided. Throws an error if verification fails or if the payload is invalid.
+     * then validates the payload against the Zod schema if one is provided.
+     *
+     * Throws an error if verification fails or if the payload is invalid according to the schema.
      * Example usage: `const payload = await JWTServiceInstance.verifyOrThrow(token, 'my-secret');`
      */
     verifyOrThrow(token: string, secret: string): Promise<Payload<TPayloadOrSchema>>;
 }
 
-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 };
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AsQuery, type AtLeastOne, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type JWTServiceOptions, type JWTSignOptions, type MeasuredExecution, type PaginationOptions, type Payload, type PayloadSchema, SUCCESS_STATUS_CODES, type SerializeDates, type Simplify, type SuccessStatusCode, type XOR, ZodJWTService, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getPagination, getUTCOffset, getZonedTime, honoLoggingHandler, log, measureExecutionTime, onHandlerError, paginationSchema, respond, safeExecute, success };

package/dist/index.js

@@ -1,6 +1,6 @@
-// src/http/http.constants.ts
-var SUCCESS_STATUS_CODES = [200, 201, 202, 307];
-var EXCEPTION_STATUS_CODES = [400, 401, 403, 404, 405, 409, 500];
+// src/hono/hono.execution.ts
+import { HTTPException } from "hono/http-exception";
+import { red as red2 } from "kleur/colors";
 
 // src/http/http.factory.ts
 function success({ status, data }) {
@@ -10,24 +10,6 @@ function failure({ status, error }) {
   return { kind: "error", status, error };
 }
 
-// src/http/http.resolvers.ts
-async function fetchSafely(fetcher) {
-  const response = await fetcher();
-  if (response.kind === "error")
-    return { error: response.error, data: null };
-  return { error: null, data: response.data };
-}
-async function fetchAndThrow(fetcher) {
-  const response = await fetcher();
-  if (response.kind === "error")
-    throw new Error(response.error);
-  return response.data;
-}
-
-// src/hono/hono.execution.ts
-import { HTTPException } from "hono/http-exception";
-import { red as red2 } from "kleur/colors";
-
 // src/utilities/generation.utilities.ts
 var DEFAULT_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
 function generateRandomString(length = 10) {
@@ -130,6 +112,43 @@ function respond(c, options) {
   return c.json(success({ status: options.status, data: options.data ?? {} }), options.status);
 }
 
+// src/http/http.constants.ts
+var SUCCESS_STATUS_CODES = [200, 201, 202, 307];
+var EXCEPTION_STATUS_CODES = [400, 401, 403, 404, 405, 409, 500];
+
+// src/http/http.resolvers.ts
+async function fetchSafely(fetcher) {
+  const response = await fetcher();
+  if (response.kind === "error")
+    return { error: response.error, data: null };
+  return { error: null, data: response.data };
+}
+async function fetchAndThrow(fetcher) {
+  const response = await fetcher();
+  if (response.kind === "error")
+    throw new Error(response.error);
+  return response.data;
+}
+
+// src/pagination/pagination.schemas.ts
+import z from "zod";
+var paginationSchema = z.object({
+  offset: z.number().int().nonnegative().optional(),
+  limit: z.number().int().positive().optional()
+});
+
+// src/pagination/pagination.utilities.ts
+var getPagination = (options) => {
+  const pagination = {};
+  if (options?.offset !== void 0) {
+    pagination.offset = options.offset;
+  }
+  if (options?.limit !== void 0) {
+    pagination.limit = options.limit;
+  }
+  return pagination;
+};
+
 // src/utilities/execution.utilities.ts
 async function safeExecute(fn, onError) {
   try {
@@ -148,12 +167,12 @@ async function measureExecutionTime(execution) {
 }
 
 // src/utilities/serialization.utilities.ts
-import { z } from "zod";
-var asQueryNumber = (schema) => z.preprocess((v) => typeof v === "string" ? Number(v) : v, schema);
+import { z as z2 } from "zod";
+var asQueryNumber = (schema) => z2.preprocess((v) => typeof v === "string" ? Number(v) : v, schema);
 var asQueryBoolean = (schema) => {
   const POSITIVE_VALUES = ["1", "true", "yes", "y", "on"];
   const NEGATIVE_VALUES = ["0", "false", "no", "n", "off"];
-  return z.preprocess((value) => {
+  return z2.preprocess((value) => {
     if (typeof value === "boolean")
       return value;
     if (typeof value === "string") {
@@ -189,6 +208,7 @@ var ZodJWTService = class {
   /**
    * Decodes a JWT token, and if a Zod schema is provided, validates the payload against it.
    * Returns the decoded payload if valid, or null if invalid or if the token cannot be decoded.
+   *
    * Example usage: `const payload = await JWTServiceInstance.decode(token);`
    */
   async decode(token) {
@@ -201,7 +221,9 @@ var ZodJWTService = class {
   }
   /**
    * Verifies and decodes a JWT token using the provided secret and configured algorithm,
-   * then validates the payload against the Zod schema if one is provided. Throws an error if verification fails or if the payload is invalid.
+   * then validates the payload against the Zod schema if one is provided.
+   *
+   * Throws an error if verification fails or if the payload is invalid according to the schema.
    * Example usage: `const payload = await JWTServiceInstance.verifyOrThrow(token, 'my-secret');`
    */
   async verifyOrThrow(token, secret) {
@@ -226,12 +248,14 @@ export {
   getColoredHTTPStatus,
   getFormattedDate,
   getFormattedTime,
+  getPagination,
   getUTCOffset,
   getZonedTime,
   honoLoggingHandler,
   log,
   measureExecutionTime,
   onHandlerError,
+  paginationSchema,
   respond,
   safeExecute,
   success

package/package.json

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