@kalutskii/foundation 0.4.4 → 0.5.0

package/dist/index.d.ts

@@ -80,6 +80,15 @@ declare const honoLoggingHandler: MiddlewareHandler;
 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`
@@ -182,21 +191,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 = {
@@ -232,15 +262,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, 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 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 };

package/dist/index.js

@@ -189,6 +189,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 +202,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) {

package/package.json

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