@kalutskii/foundation 0.5.1 → 0.6.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';
 
@@ -42,15 +42,6 @@ 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;
 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.
@@ -60,16 +51,6 @@ type QueryPrimitive = string | number | boolean | bigint | Date | null | undefin
 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.
@@ -78,7 +59,7 @@ declare const asQueryBoolean: <T extends z.ZodTypeAny>(schema: T) => z.ZodPrepro
 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'>;
+}): Response & TypedResponse<APISuccess<AsQuery<T>> | APIError, S, 'json'>;
 
 /**
  * Factory for creating successful API responses with serializable data.
@@ -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.
@@ -139,11 +120,11 @@ type PaginationOptions = z$1.infer<typeof paginationSchema>;
  *
  * ```ts
  * await db.query.someTable.findMany({
- *   ...getPagination(options),
+ *   ...refinePagination(options),
  * });
  * ```
  */
-declare const getPagination: (options?: PaginationOptions) => {
+declare const refinePagination: (options?: PaginationOptions) => {
     offset?: number | undefined;
     limit?: number | undefined;
 };
@@ -237,6 +218,7 @@ declare const log: {
 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.
@@ -267,6 +249,29 @@ 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;
 
+/**
+ * Refines a Zod object schema to ensure that at least one of its keys is defined.
+ * This is useful for validating objects where at least one property must be present.
+ *
+ * ```ts
+ * const mySchema = z.object({
+ *   a: z.string()
+ *   b: z.number()
+ * }).refine(atLeastOneDefined);
+ * ```
+ */
+declare const atLeastOneDefined: <T extends z.ZodRawShape>(schema: z.ZodObject<T>) => z.ZodType<AtLeastOne<z.infer<z.ZodObject<T>>>>;
+/**
+ * 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>;
+
 /** Options for configuring the JWT service. */
 type JWTServiceOptions = {
     /** The algorithm to use for signing and verifying JWTs. Defaults to 'HS256'. */
@@ -280,9 +285,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 +320,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 Simplify, type SuccessStatusCode, type XOR, ZodJWTService, asQueryBoolean, asQueryNumber, atLeastOneDefined, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, log, measureExecutionTime, onHandlerError, paginationSchema, refinePagination, respond, safeExecute, success };

package/dist/index.js

@@ -137,8 +137,8 @@ var paginationSchema = z.object({
   limit: z.number().int().positive().optional()
 });
 
-// src/pagination/pagination.utilities.ts
-var getPagination = (options) => {
+// src/pagination/pagination.refiners.ts
+var refinePagination = (options) => {
   const pagination = {};
   if (options?.offset !== void 0) {
     pagination.offset = options.offset;
@@ -166,8 +166,19 @@ 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";
+
+// src/validation/validation.messages.ts
+var AT_LEAST_ONE_DEFINED_ERROR = (keys) => `At least one of the specified keys must be defined: ${keys.join(", ")}`;
+
+// src/validation/validation.refiners.ts
+var atLeastOneDefined = (schema) => {
+  const keys = Object.keys(schema.shape);
+  return schema.partial().refine((value) => keys.some((key) => 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 +251,7 @@ export {
   ZodJWTService,
   asQueryBoolean,
   asQueryNumber,
+  atLeastOneDefined,
   failure,
   fetchAndThrow,
   fetchSafely,
@@ -248,7 +260,6 @@ export {
   getColoredHTTPStatus,
   getFormattedDate,
   getFormattedTime,
-  getPagination,
   getUTCOffset,
   getZonedTime,
   honoLoggingHandler,
@@ -256,6 +267,7 @@ export {
   measureExecutionTime,
   onHandlerError,
   paginationSchema,
+  refinePagination,
   respond,
   safeExecute,
   success

package/package.json

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