@kalutskii/foundation 0.6.5 → 0.6.7

package/README.md

@@ -5,11 +5,14 @@ Designed for use in Bun/Node.js and Cloudflare Workers environments.
 
 ## What this package provides
 
-- Typed API response contracts.
-- Response factories for success and failure payloads.
-- Safe async resolvers for contract-based fetch functions.
-- A Hono helper for typed JSON success responses.
-- Utility types/helpers for query parsing and Date serialization.
+- Typed API response contracts with success/failure factories and safe resolvers.
+- Hono helpers: typed JSON responses, global error handler, request logging middleware.
+- Execution utilities: safe async execution and execution time measurement.
+- Datetime utilities: timezone-aware formatting helpers.
+- Logging utility: unified colored log interface.
+- Random string generation utility.
+- JWT service with optional Zod schema validation.
+- Zod helpers for query param coercion, pagination schemas, and type utilities.
 
 ## Installation
 
@@ -32,8 +35,8 @@ Contract shape:
 
 Status code groups are exported as constants and used by types:
 
-- `SUCCESS_STATUS_CODES`
-- `EXCEPTION_STATUS_CODES`
+- `SUCCESS_STATUS_CODES` — `[200, 201, 202, 307]`
+- `EXCEPTION_STATUS_CODES` — `[400, 401, 403, 404, 405, 409, 500]`
 
 ## Usage
 
@@ -87,34 +90,132 @@ const app = new Hono();
 app.get('/health', (c) => {
   return respond(c, {
     status: 200,
-    data: { ok: true, now: new Date() },
+    data: { ok: true },
   });
 });
 ```
 
-`respond` returns a typed JSON response contract and includes API error type in route output unions.
+`respond` wraps `c.json` with a typed success payload and includes `APIError` in the route's output union.
 
-### 4. Parse query params with helpers
+### 4. Wire up Hono error handler and logging middleware
 
 ```ts
-import { asQueryBoolean, asQueryNumber } from '@kalutskii/foundation';
+import { honoLoggingHandler, onHandlerError } from '@kalutskii/foundation';
+import { Hono } from 'hono';
+
+const app = new Hono();
+
+app.use('*', honoLoggingHandler);
+app.onError(onHandlerError);
+```
+
+`onHandlerError` catches all thrown errors, maps `HTTPException` (< 500) to their status codes, and returns a generic 500 with a unique error ID for unexpected errors.
+
+`honoLoggingHandler` logs each request with method, status, duration, path, and query params.
+Example: `[12:12:12 (+4 UTC)] hono         | POST 200    123ms /api/v1/users (search=term)`
+
+### 5. Execute functions safely and measure performance
+
+```ts
+import { measureExecutionTime, safeExecute } from '@kalutskii/foundation';
+
+const result = await safeExecute(
+  () => fetchData(),
+  (error) => console.error(error)
+);
+
+const { result: data, executionTime } = await measureExecutionTime(() => fetchData());
+console.log(`Done in ${executionTime}ms`);
+```
+
+### 6. Parse query params with `asQuery`
+
+```ts
+import { asQuery } from '@kalutskii/foundation';
+import { z } from 'zod';
+
+const schema = z.object({
+  page: asQuery(z.number().int().positive()),
+  isActive: asQuery(z.boolean()),
+});
+
+schema.parse({ page: '2', isActive: 'true' }); // { page: 2, isActive: true }
+```
+
+`asQuery` preprocesses string values from query parameters — coercing `'true'`/`'false'` to booleans and numeric strings to numbers — before passing them to the Zod schema for validation.
+
+### 7. Use pagination schema
+
+```ts
+import { refinePagination, zodPaginationSchema, zodPaginationShape } from '@kalutskii/foundation';
+import { z } from 'zod';
+
+// Use as a standalone schema
+const options = zodPaginationSchema.parse({ offset: '0', limit: '20' });
+// { offset: 0, limit: 20 }
+
+// Spread shape into a larger query schema
+const querySchema = z.object({
+  search: z.string().optional(),
+  ...zodPaginationShape,
+});
+
+// Strip undefined pagination values before passing to a query builder (e.g. Drizzle)
+await db.query.users.findMany({
+  ...refinePagination(options),
+});
+```
+
+### 8. Work with JWT using `ZodJWTService`
+
+```ts
+import { ZodJWTService } from '@kalutskii/foundation';
 import { z } from 'zod';
 
-const pageSchema = asQueryNumber(z.number().int().min(1));
-const enabledSchema = asQueryBoolean(z.boolean());
+const payloadSchema = z.object({ userId: z.string() });
+const jwt = new ZodJWTService(payloadSchema, { defaultExpirationSeconds: 3600 });
+
+const token = await jwt.sign({ userId: '42' }, 'secret');
+const payload = await jwt.verifyOrThrow(token, 'secret');
+// payload: { userId: '42', exp: ... }
+
+// decode without throwing (returns null on invalid token or schema mismatch)
+const decoded = await jwt.decode(token);
+```
+
+### 9. Datetime helpers
+
+```ts
+import { formatTime, getFormattedDate, getFormattedTime, getZonedTime } from '@kalutskii/foundation';
+
+getFormattedTime({ tz: 'Europe/Moscow' }); // '15:30:00 (+3 UTC)'
+getFormattedDate({ tz: 'Europe/Moscow' }); // '22.06.2026 15:30:00 (+3 UTC)'
+getFormattedDate({ tz: 'Europe/Moscow', withTime: false }); // '22.06.2026'
+formatTime(new Date(), { tz: 'Europe/Moscow' }); // '15:30:00, 22 июня 2026 (+3 UTC)'
+```
+
+### 10. Logging
+
+```ts
+import { log } from '@kalutskii/foundation';
 
-pageSchema.parse('2'); // 2
-enabledSchema.parse('yes'); // true
-enabledSchema.parse('off'); // false
+log.info('Server started', 'app');
+log.warn('Deprecated call', 'auth');
+log.error('Something failed', 'db', error.stack);
+// [15:30:00 (+3 UTC)] app          | Server started
 ```
 
 ## Exports
 
 The package exports all public APIs from a single entrypoint:
 
-- HTTP constants, schemas, factories, and resolvers.
-- Hono `respond` helper.
-- Serialization/query utilities, including `SerializeDates`.
+- **HTTP**: `success`, `failure`, `fetchSafely`, `fetchAndThrow`, constants, schemas.
+- **Hono**: `respond`, `onHandlerError`, `honoLoggingHandler`.
+- **Utilities**: `safeExecute`, `measureExecutionTime`, `generateRandomString`, `log`, `getColoredHTTPStatus`, datetime helpers.
+- **Zod JWT**: `ZodJWTService`.
+- **Zod Pagination**: `zodPaginationSchema`, `zodPaginationShape`, `refinePagination`, `ZodPaginationOptions`.
+- **Zod Validation**: `asQuery`, `AsQuery`, `AtLeastOne`.
+- **Type Utilities**: `Simplify`.
 
 ## Development
 

package/dist/index.d.ts

@@ -1,7 +1,24 @@
+import { SQL } from 'drizzle-orm';
 import { ErrorHandler, MiddlewareHandler, Context, TypedResponse } from 'hono';
-import z from 'zod';
 import { Locale } from 'date-fns';
 import { SymmetricAlgorithm } from 'hono/utils/jwt/jwa';
+import z from 'zod';
+
+/**
+ * Builds a Drizzle SQL `where` condition from a plain object.
+ *
+ * Maps each `where` entry to `eq(table[key], value)` and combines them with `and`.
+ * Assumes that `where` was already validated and contains only existing table fields.
+ *
+ * ```ts
+ * await db
+ *   .update(usersTable)
+ *   .set(values)
+ *   .where(sqlWhere(usersTable, { id: 1 }))
+ *   .returning();
+ * ```
+ */
+declare function sqlWhere(table: unknown, where: Record<string, unknown>): SQL | undefined;
 
 /**
  * Global error handler for Hono framework. Catches all exceptions thrown in route handlers and middlewares.
@@ -33,7 +50,10 @@ type APIError = {
 type APIContractResult<TData = void> = APISuccess<TData> | APIError;
 type APIContractData<TResult extends APIContractResult<unknown>> = TResult extends APISuccess<infer TData> ? TData : never;
 type APIContractError<TResult extends APIContractResult<unknown>> = Extract<TResult, APIError>;
-/** Discriminated union result of a fetch operation. If `error` is set, `data` is null and vice versa. */
+/**
+ * Discriminated union result of a fetch operation.
+ * If `error` is set, `data` is null and vice versa.
+ */
 type FetchResult<T> = {
     error: null;
     data: T;
@@ -42,15 +62,36 @@ type FetchResult<T> = {
     data: null;
 };
 
+/**
+ * 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];
+} & {};
+
 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;
+/**
+ * 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;
 
 /**
  * Wraps c.json with a typed success payload / (or void data) & possible APIError response.
@@ -80,86 +121,65 @@ declare function failure({ status, error }: {
 
 /**
  * Resolves an APIContractResult fetcher into a FetchResult discriminated union.
- * Does not throw errors, instead returning them in the error property of the FetchResult.
+ * Does not throw errors, instead returning them as 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, 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.ZodObject<{
-    offset: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
-    limit: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
-}, z.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.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.
+ * Returns the current date and time shifted to the specified timezone.
  *
- * ```ts
- * await db.query.someTable.findMany({
- *   ...refinePagination(options),
- * });
- * ```
- */
-declare const refinePagination: (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')`
+ * This is useful when the application needs to display "now" from another
+ * region's point of view instead of relying on the server's local timezone.
  */
 declare const getZonedTime: ({ tz }?: {
     tz?: string;
 }) => Date;
 /**
- * Returns the timezone offset in the format (+4 UTC) / (-5 UTC).
- * Example usage: `getUTCOffset(new Date('2026-03-15T12:00:00Z'), 'America/New_York') = '(-4 UTC)'`
+ * Returns the UTC offset for the specified timezone at the given date.
+ *
+ * The offset is formatted for display next to dates and times, for example
+ * `(+4 UTC)`, `(0 UTC)`, or `(-5 UTC)`. The date is required because timezone
+ * offsets may change depending on daylight saving time or historical rules.
  */
 declare const getUTCOffset: (date: Date, tz: string) => string;
 /**
- * Returns the current time in the specified timezone, formatted as HH:mm:ss (+X UTC).
- * Example usage: `getFormattedTime({ tz: 'America/New_York' }) = '12:00:00 (-4 UTC)'`
+ * Returns the current time formatted in the specified timezone.
+ *
+ * The result includes both the local time and its UTC offset, making it suitable
+ * for UI labels, logs, bot messages, and other places where the user should see
+ * not only the time itself, but also the timezone context behind that value.
+ *
+ * Format: `HH:mm:ss (+X 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 usage: `getFormattedDate({ tz: 'America/New_York' }) = '03.15.2026 12:00:00 (-4 UTC)'`
+ * Returns the current date formatted in the specified timezone.
+ *
+ * By default, the result includes date, time, and UTC offset. This is useful for
+ * complete timestamps displayed in UI, bot messages, reports, or diagnostics.
+ *
+ * Format with time: `dd.MM.yyyy HH:mm:ss (+X UTC)`.
+ * Format without time: `dd.MM.yyyy`.
  */
 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 usage: `formatTime(new Date('2026-03-15T12:00:00Z'), { tz: 'America/New_York' }) = '12:00:00, March 15, 2026 (-4 UTC)'`
+ * Formats the provided date and time in the specified timezone.
+ *
+ * Unlike helpers that always use the current moment, this function accepts an
+ * explicit Date value and formats that exact point in time for another timezone.
+ *
+ * Format: `HH:mm:ss, d MMMM yyyy (+X UTC)`.
  */
 declare const formatTime: (time: Date, { locale, tz }?: {
     locale?: Locale;
@@ -211,55 +231,6 @@ 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];
-} & {};
-
-/**
- * Transforms a string to a number (when passing query parameters).
- * Example usage: `asQueryNumber(z.number())('123') = 123`
- */
-declare const asQueryNumber: <T extends z.ZodTypeAny>(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>;
-
-/**
- * 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> = Simplify<T & {
-    [K in keyof U]?: never;
-}> | 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 = {
     /** The algorithm to use for signing and verifying JWTs. Defaults to 'HS256'. */
@@ -272,9 +243,13 @@ type JWTSignOptions = {
     /** The number of seconds until the JWT expires. */
     expiresInSeconds?: number;
 };
-/** Utility types for inferring payload types from Zod schemas. */
+/**
+ * Utility types for inferring payload types from Zod schemas.
+ */
 type Payload<T> = T extends z.ZodType ? z.infer<T> : T;
-/** Utility type to extract the payload schema type from a Zod schema. */
+/**
+ * Utility type to extract the payload schema type from a Zod schema.
+ * */
 type PayloadSchema<T> = T extends z.ZodType ? T : never;
 
 /**
@@ -308,4 +283,59 @@ 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 PaginationOptions, type Payload, type PayloadSchema, SUCCESS_STATUS_CODES, type Simplify, type SuccessStatusCode, type XOR, ZodJWTService, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, log, measureExecutionTime, onHandlerError, paginationSchema, refinePagination, respond, safeExecute, success };
+declare const zodPaginationSchema: z.ZodObject<{
+    offset: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
+    limit: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
+}, z.core.$strip>;
+/**
+ * Reusable pagination fields for flat query schemas, allowing for
+ * consistent validation of pagination parameters across different endpoints.
+ *
+ * Spread into another `z.object(...)` when composing a larger query schema,
+ * or use `zodPaginationSchema.extend(...)` when building directly from the schema.
+ */
+declare const zodPaginationShape: {
+    offset: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
+    limit: z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>;
+};
+/**
+ * TypeScript type representing the pagination options validated by the `zodPaginationSchema`.
+ * Read documentation for `zodPaginationSchema` for more details on the structure and usage of this type.
+ */
+type ZodPaginationOptions = z.infer<typeof zodPaginationSchema>;
+
+/**
+ * Extracts defined pagination options from a query object.
+ *
+ * This keeps query builder calls clean by omitting undefined values while
+ * preserving valid pagination values like `0`, useful when spreading pagination
+ * options into APIs that expect only explicitly provided fields (e.g., Drizzle).
+ *
+ * ```ts
+ * await db.query.someTable.findMany({
+ *   ...refinePagination(options),
+ * });
+ * ```
+ */
+declare const refinePagination: (options?: ZodPaginationOptions) => ZodPaginationOptions;
+
+/**
+ * Query parameters always arrive as strings, even when they semantically represent numbers
+ * or booleans, so we preprocess them to convert to the appropriate types before validation.
+ *
+ * ```ts
+ * const schema = z.object({
+ *   page: z.number().int().positive(),
+ *   isActive: z.boolean(),
+ * });
+ *
+ * const queryParams = { page: '2', isActive: 'true' };
+ * const result = schema.parse(queryParams); // { page: 2, isActive: true }
+ * ```
+ *
+ * @param schema - The Zod schema to validate the query parameters against.
+ * @returns A new Zod schema that preprocesses query parameter values before validation.
+ */
+declare const asQuery: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<T>;
+
+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 Simplify, type SuccessStatusCode, ZodJWTService, type ZodPaginationOptions, asQuery, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, log, measureExecutionTime, onHandlerError, refinePagination, respond, safeExecute, sqlWhere, success, zodPaginationSchema, zodPaginationShape };

package/dist/index.js

@@ -1,3 +1,9 @@
+// src/drizzle/drizzle.refiners.ts
+import { and, eq } from "drizzle-orm";
+function sqlWhere(table, where) {
+  return and(...Object.entries(where).map(([key, value]) => eq(table[key], value)));
+}
+
 // src/hono/hono.execution.ts
 import { HTTPException } from "hono/http-exception";
 import { red as red2 } from "kleur/colors";
@@ -130,53 +136,6 @@ async function fetchAndThrow(fetcher) {
   return response.data;
 }
 
-// src/pagination/pagination.schemas.ts
-import z2 from "zod";
-
-// src/validation/validation.refiners.ts
-import z from "zod";
-var asQueryNumber = (schema) => z.preprocess((value) => {
-  if (typeof value !== "string")
-    return value;
-  if (value.trim() === "")
-    return value;
-  return Number(value);
-}, schema);
-var asQueryBoolean = (schema) => {
-  const POSITIVE_VALUES = ["1", "true", "yes", "y", "on"];
-  const NEGATIVE_VALUES = ["0", "false", "no", "n", "off"];
-  return z.preprocess((value) => {
-    if (typeof value === "boolean")
-      return value;
-    if (typeof value === "string") {
-      const normalized = value.trim().toLowerCase();
-      if (POSITIVE_VALUES.includes(normalized))
-        return true;
-      if (NEGATIVE_VALUES.includes(normalized))
-        return false;
-    }
-    return value;
-  }, schema);
-};
-
-// src/pagination/pagination.schemas.ts
-var paginationSchema = z2.object({
-  offset: asQueryNumber(z2.number().int().nonnegative()).optional(),
-  limit: asQueryNumber(z2.number().int().positive()).optional()
-});
-
-// src/pagination/pagination.refiners.ts
-var refinePagination = (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 {
@@ -242,12 +201,49 @@ var ZodJWTService = class {
     return this.payloadSchema.parseAsync(payload);
   }
 };
+
+// src/zod-pagination/zod-pagination.refiners.ts
+var refinePagination = (options) => ({
+  ...options?.offset !== void 0 ? { offset: options.offset } : {},
+  ...options?.limit !== void 0 ? { limit: options.limit } : {}
+});
+
+// src/zod-pagination/zod-pagination.schemas.ts
+import z2 from "zod";
+
+// src/zod-validation/zod-validation.refiners.ts
+import z from "zod";
+var parseQueryValue = (value) => {
+  if (Array.isArray(value))
+    return value.map(parseQueryValue);
+  if (typeof value !== "string")
+    return value;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "")
+    return value;
+  if (normalized === "true")
+    return true;
+  if (normalized === "false")
+    return false;
+  if (/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(normalized))
+    return Number(normalized);
+  return value;
+};
+var asQuery = (schema) => z.preprocess(parseQueryValue, schema);
+
+// src/zod-pagination/zod-pagination.schemas.ts
+var zodPaginationSchema = z2.object({
+  /** Integer representing the starting point for pagination. */
+  offset: asQuery(z2.number().int().nonnegative()).optional(),
+  /** Integer representing the maximum number of items to return. */
+  limit: asQuery(z2.number().int().positive()).optional()
+});
+var zodPaginationShape = zodPaginationSchema.shape;
 export {
   EXCEPTION_STATUS_CODES,
   SUCCESS_STATUS_CODES,
   ZodJWTService,
-  asQueryBoolean,
-  asQueryNumber,
+  asQuery,
   failure,
   fetchAndThrow,
   fetchSafely,
@@ -262,9 +258,11 @@ export {
   log,
   measureExecutionTime,
   onHandlerError,
-  paginationSchema,
   refinePagination,
   respond,
   safeExecute,
-  success
+  sqlWhere,
+  success,
+  zodPaginationSchema,
+  zodPaginationShape
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
   "type": "module",
   "repository": {
@@ -12,7 +12,8 @@
   },
   "scripts": {
     "build": "tsup",
-    "lint": "eslint .",
+    "lint": "eslint . --ext .ts",
+    "format": "prettier --write .",
     "typecheck": "tsc --noEmit"
   },
   "exports": {
@@ -28,6 +29,7 @@
     "@hono/zod-validator": "^0.8.0",
     "date-fns": "^4.1.0",
     "date-fns-tz": "^3.2.0",
+    "drizzle-orm": "^1.0.0-beta.22",
     "hono": "^4.12.18",
     "kleur": "^4.1.5",
     "typescript": "^5",