@kalutskii/foundation 0.5.0 → 0.5.2

package/dist/index.d.ts

@@ -1,8 +1,20 @@
 import { ErrorHandler, MiddlewareHandler, Context, TypedResponse } from 'hono';
-import z$1, { z, ZodNumber } from 'zod';
+import z 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,6 +42,25 @@ type FetchResult<T> = {
     data: null;
 };
 
+/**
+ * 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 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;
+
+/**
+ * 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;
+    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' } })`
@@ -60,54 +91,43 @@ declare function fetchSafely<TResult extends APIContractResult<unknown>>(fetcher
 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.
- * 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 usage: `asQueryNumber(z.number())('123') = 123`
+ * 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 asQueryNumber: <T extends ZodNumber>(schema: T) => z.ZodPreprocess<T>;
+declare const paginationSchema: z.ZodObject<{
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 /**
- * Transforms various string representations of boolean values into actual booleans.
- * See POSITIVE_VALUES and NEGATIVE_VALUES arrays below for supported inputs.
+ * 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.
  */
-declare const asQueryBoolean: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<T>;
+type PaginationOptions = z.infer<typeof paginationSchema>;
 
 /**
- * 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).
+ * 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 function respond<T extends object = Record<string, never>, S extends SuccessStatusCode = SuccessStatusCode>(c: Context, options: {
-    status: S;
-    data?: T;
-}): Response & TypedResponse<APISuccess<SerializeDates<T>> | APIError, S, 'json'>;
+declare const getPagination: (options?: PaginationOptions) => {
+    offset?: number | undefined;
+    limit?: number | undefined;
+};
 
 /**
  * Returns the current time in the specified timezone.
@@ -228,6 +248,45 @@ type XOR<T, U> = Simplify<T & {
  */
 type AtLeastOne<T, Keys extends keyof T = keyof T> = Keys extends keyof T ? Simplify<Required<Pick<T, Keys>> & Partial<Omit<T, Keys>>> : never;
 
+/**
+ * A Zod refinement function that ensures at least one of the specified keys in a Zod object schema is defined.
+ * This is useful for validating input where at least one of several optional fields must be provided.
+ *
+ * ```ts
+ * const mySchema = atLeastOneDefined(
+ *   z.object({
+ *     name: z.string().optional(),
+ *     email: z.string().email().optional(),
+ *     phone: z.string().optional(),
+ *   })
+ * );
+ *
+ * // Valid: { name: "Alice" }, { email: "alice@example.com" }, { phone: "123-456-7890" }
+ * // Invalid: {}, { name: undefined, email: undefined, phone: undefined }
+ * ```
+ */
+declare const atLeastOneDefined: <T extends z.ZodRawShape>(schema: z.ZodObject<T>) => z.ZodObject<T, z.core.$strip>;
+/**
+ * Transforms a string to a number (when passing query parameters).
+ * Example usage: `asQueryNumber(z.number())('123') = 123`
+ */
+declare const asQueryNumber: <T extends z.ZodNumber>(schema: T) => z.ZodPreprocess<T>;
+/**
+ * Transforms various string representations of boolean values into actual booleans.
+ * See POSITIVE_VALUES and NEGATIVE_VALUES arrays below for supported inputs.
+ */
+declare const asQueryBoolean: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<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;
+
 /** Options for configuring the JWT service. */
 type JWTServiceOptions = {
     /** The algorithm to use for signing and verifying JWTs. Defaults to 'HS256'. */
@@ -241,9 +300,9 @@ type JWTSignOptions = {
     expiresInSeconds?: number;
 };
 /** Utility types for inferring payload types from Zod schemas. */
-type Payload<T> = T extends z$1.ZodType ? z$1.infer<T> : T;
+type Payload<T> = T extends z.ZodType ? z.infer<T> : T;
 /** Utility type to extract the payload schema type from a Zod schema. */
-type PayloadSchema<T> = T extends z$1.ZodType ? T : never;
+type PayloadSchema<T> = T extends z.ZodType ? T : never;
 
 /**
  * A service class for handling JWT operations with optional Zod schema validation for the payload.
@@ -276,4 +335,4 @@ declare class ZodJWTService<TPayloadOrSchema> {
     verifyOrThrow(token: string, secret: string): Promise<Payload<TPayloadOrSchema>>;
 }
 
-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 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, 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, atLeastOneDefined, 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 {
@@ -147,13 +166,18 @@ async function measureExecutionTime(execution) {
   return { result, executionTime: Math.round(executionTime) };
 }
 
-// src/utilities/serialization.utilities.ts
-import { z } from "zod";
-var asQueryNumber = (schema) => z.preprocess((v) => typeof v === "string" ? Number(v) : v, schema);
+// src/validation/validation.refiners.ts
+import z2 from "zod";
+var AT_LEAST_ONE_DEFINED_ERROR = (keys) => `At least one of the specified keys must be defined: ${keys.join(", ")}`;
+var atLeastOneDefined = (schema) => {
+  const keys = Object.keys(schema.shape);
+  return schema.refine((value) => keys.some((key) => value[key] !== void 0 && value[key] !== null), { message: AT_LEAST_ONE_DEFINED_ERROR(keys) });
+};
+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") {
@@ -221,6 +245,7 @@ export {
   ZodJWTService,
   asQueryBoolean,
   asQueryNumber,
+  atLeastOneDefined,
   failure,
   fetchAndThrow,
   fetchSafely,
@@ -229,12 +254,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.5.0",
+  "version": "0.5.2",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
   "type": "module",
   "repository": {
@@ -40,6 +40,7 @@
     "esbuild-plugin-tsconfig-paths": "^1.0.2",
     "eslint": "^10.2.1",
     "eslint-config-prettier": "^10.1.8",
+    "jiti": "^2.7.0",
     "prettier": "^3.8.1",
     "tsup": "^8.5.1",
     "typescript-eslint": "^8.58.2"