@kalutskii/foundation 0.5.1 → 0.5.2

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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';
 
@@ -51,25 +51,6 @@ type FetchResult<T> = {
 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`
- */
-declare const asQueryNumber: <T extends 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>;
 
 /**
  * Wraps c.json with a typed success payload / (or void data) & possible APIError response.
@@ -122,15 +103,15 @@ declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetch
  * });
  * ```
  */
-declare const paginationSchema: z$1.ZodObject<{
-    offset: z$1.ZodOptional<z$1.ZodNumber>;
-    limit: z$1.ZodOptional<z$1.ZodNumber>;
-}, z$1.core.$strip>;
+declare const paginationSchema: z.ZodObject<{
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<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$1.infer<typeof paginationSchema>;
+type PaginationOptions = z.infer<typeof paginationSchema>;
 
 /**
  * A utility function that extracts pagination options from the provided input.
@@ -267,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'. */
@@ -280,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.
@@ -315,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 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 };
+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

@@ -166,8 +166,13 @@ async function measureExecutionTime(execution) {
   return { result, executionTime: Math.round(executionTime) };
 }
 
-// src/utilities/serialization.utilities.ts
-import { z as z2 } from "zod";
+// 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"];
@@ -240,6 +245,7 @@ export {
   ZodJWTService,
   asQueryBoolean,
   asQueryNumber,
+  atLeastOneDefined,
   failure,
   fetchAndThrow,
   fetchSafely,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.5.1",
+  "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"