@kalutskii/foundation 0.6.8 → 0.6.10

package/README.md

@@ -12,7 +12,7 @@ Designed for use in Bun/Node.js and Cloudflare Workers environments.
 - 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.
+- Zod helpers for query param coercion, pagination schemas, nested schema flattening, and type utilities.
 
 ## Installation
 
@@ -144,7 +144,34 @@ 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
+### 8. Build flat query schemas from nested objects
+
+```ts
+import { asQuerySchema } from '@kalutskii/foundation';
+import { z } from 'zod';
+
+const schema = asQuerySchema(
+  z.object({
+    search: z.string().optional(),
+    sort: z
+      .object({
+        field: z.string(),
+        order: z.enum(['asc', 'desc']),
+      })
+      .optional(),
+  })
+);
+
+schema.parse({ search: 'foo', field: 'name', order: 'asc' });
+// { search: 'foo', field: 'name', order: 'asc' }
+
+// Rejects the original nested structure
+schema.parse({ sort: { field: 'name', order: 'asc' } }); // throws
+```
+
+`asQuerySchema` flattens nested `z.object(...)` fields to the top level, making it suitable for flat query parameter validation. Nested object fields are lifted, while optionality is preserved: required parents keep their fields required, optional parents make all promoted fields optional. The result is a strict schema (unknown keys are rejected).
+
+### 8. Use pagination schema
 
 ```ts
 import { refinePagination, zodPaginationSchema, zodPaginationShape } from '@kalutskii/foundation';
@@ -166,7 +193,7 @@ await db.query.users.findMany({
 });
 ```
 
-### 8. Work with JWT using `ZodJWTService`
+### 9. Work with JWT using `ZodJWTService`
 
 ```ts
 import { ZodJWTService } from '@kalutskii/foundation';
@@ -183,7 +210,7 @@ const payload = await jwt.verifyOrThrow(token, 'secret');
 const decoded = await jwt.decode(token);
 ```
 
-### 9. Datetime helpers
+### 10. Datetime helpers
 
 ```ts
 import { formatTime, getFormattedDate, getFormattedTime, getZonedTime } from '@kalutskii/foundation';
@@ -194,7 +221,7 @@ getFormattedDate({ tz: 'Europe/Moscow', withTime: false }); // '22.06.2026'
 formatTime(new Date(), { tz: 'Europe/Moscow' }); // '15:30:00, 22 июня 2026 (+3 UTC)'
 ```
 
-### 10. Logging
+### 11. Logging
 
 ```ts
 import { log } from '@kalutskii/foundation';
@@ -214,6 +241,7 @@ The package exports all public APIs from a single entrypoint:
 - **Utilities**: `safeExecute`, `measureExecutionTime`, `generateRandomString`, `log`, `getColoredHTTPStatus`, datetime helpers.
 - **Zod JWT**: `ZodJWTService`.
 - **Zod Pagination**: `zodPaginationSchema`, `zodPaginationShape`, `refinePagination`, `ZodPaginationOptions`.
+- **Zod Flatten**: `asQuerySchema`, `flattenZodShape`, `isZodObject`, `isZodOptional`, `unwrapOptional`, `FlattenZodShape`.
 - **Zod Validation**: `asQuery`, `AsQuery`, `AtLeastOne`.
 - **Type Utilities**: `Simplify`.
 

package/dist/index.d.ts

@@ -58,36 +58,14 @@ 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.
+ * Recursively transforms all fields of T to `string`, matching how query parameters are serialized.
+ * Handles nested objects, arrays, and primitive values (including null and undefined as optional).
  */
 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.
@@ -227,6 +205,28 @@ 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];
+} & {};
+/**
+ * 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'. */
@@ -315,6 +315,77 @@ type ZodPaginationOptions = z.infer<typeof zodPaginationSchema>;
  */
 declare const refinePagination: (options?: ZodPaginationOptions) => ZodPaginationOptions;
 
+type ZodShape = Record<string, z.ZodTypeAny>;
+type AnyZodObject = z.ZodObject<ZodShape>;
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer I) => void ? I : never;
+type UnwrapOptional<T extends z.ZodTypeAny> = T extends z.ZodOptional<infer Inner> ? Inner : T;
+type IsOptional<T extends z.ZodTypeAny> = T extends z.ZodOptional<z.ZodTypeAny> ? true : false;
+type Optionalize<TSchema extends z.ZodTypeAny, TShouldOptionalize extends boolean> = TShouldOptionalize extends true ? z.ZodOptional<TSchema> : TSchema;
+type FlattenObjectField<TSchema extends z.ZodTypeAny> = UnwrapOptional<TSchema> extends z.ZodObject<infer InnerShape extends ZodShape> ? {
+    [K in keyof InnerShape]: Optionalize<InnerShape[K], IsOptional<TSchema>>;
+} : never;
+type FlattenNestedObjectFields<TShape extends ZodShape> = {
+    [K in keyof TShape]: FlattenObjectField<TShape[K]>;
+}[keyof TShape];
+/**
+ * The resulting shape after all nested `z.ZodObject` fields have been lifted to the top level.
+ * Primitive fields are kept as-is; nested object fields are replaced with their inner keys.
+ * If the parent field was optional, all promoted inner fields become optional as well.
+ */
+type FlattenZodShape<TShape extends ZodShape> = {
+    [K in keyof TShape as UnwrapOptional<TShape[K]> extends AnyZodObject ? never : K]: TShape[K];
+} & UnionToIntersection<FlattenNestedObjectFields<TShape>>;
+
+/**
+ * Recursively lifts all nested `z.ZodObject` fields to the top level of the shape.
+ * Primitive fields are preserved as-is. If the parent field was optional, all promoted
+ * inner keys become optional to avoid requiring fields that were previously nested under an optional object.
+ *
+ * ```ts
+ * const flat = flattenZodShape({
+ *   name: z.string(),
+ *   address: z.object({ city: z.string(), zip: z.string() }).optional(),
+ * });
+ * // { name: z.string(), city: z.string().optional(), zip: z.string().optional() }
+ * ```
+ */
+declare const flattenZodShape: <TShape extends ZodShape>(shape: TShape) => FlattenZodShape<TShape>;
+/**
+ * Builds a strict flat query schema from a nested `z.ZodObject`.
+ * All nested object fields are lifted to the top level while preserving optionality,
+ * making the result suitable for validating flat query parameter objects.
+ *
+ * ```ts
+ * const schema = asQuerySchema(
+ *   z.object({
+ *     search: z.string().optional(),
+ *     sort: z.object({ field: z.string(), order: z.enum(['asc', 'desc']) }).optional(),
+ *   })
+ * );
+ *
+ * schema.parse({ search: 'foo', field: 'name', order: 'asc' });
+ * // { search: 'foo', field: 'name', order: 'asc' }
+ * ```
+ */
+declare const asQuerySchema: <TShape extends ZodShape>(schema: z.ZodObject<TShape>) => z.ZodObject<FlattenZodShape<TShape> extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strict>;
+
+/**
+ * Checks if the provided schema is an instance of `z.ZodObject`.
+ * @returns `true` if the schema is a `z.ZodObject`, `false` otherwise.
+ */
+declare const isZodObject: (schema: z.ZodTypeAny) => schema is AnyZodObject;
+/**
+ * Checks if the provided schema is an instance of `z.ZodOptional`.
+ * @returns `true` if the schema is a `z.ZodOptional`, `false` otherwise.
+ */
+declare const isZodOptional: (schema: z.ZodTypeAny) => schema is z.ZodOptional<z.ZodTypeAny>;
+/**
+ * Unwraps a `z.ZodOptional` schema to retrieve its inner schema.
+ * If the provided schema is not optional, it is returned unchanged.
+ */
+declare const unwrapOptional: (schema: z.ZodTypeAny) => z.ZodTypeAny;
+
+declare const parseQueryValue: (value: unknown) => unknown;
 /**
  * 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.
@@ -334,4 +405,10 @@ declare const refinePagination: (options?: ZodPaginationOptions) => ZodPaginatio
  */
 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 };
+/**
+ * Checks if the given value is a plain object (i.e., an object
+ * that is not null, not an array, and has a prototype of Object).
+ */
+declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AnyZodObject, type AsQuery, type AtLeastOne, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type FlattenZodShape, type JWTServiceOptions, type JWTSignOptions, type MeasuredExecution, type Payload, type PayloadSchema, SUCCESS_STATUS_CODES, type Simplify, type SuccessStatusCode, ZodJWTService, type ZodPaginationOptions, type ZodShape, asQuery, asQuerySchema, failure, fetchAndThrow, fetchSafely, flattenZodShape, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, isPlainObject, isZodObject, isZodOptional, log, measureExecutionTime, onHandlerError, parseQueryValue, refinePagination, respond, safeExecute, sqlWhere, success, unwrapOptional, zodPaginationSchema, zodPaginationShape };

package/dist/index.js

@@ -245,14 +245,55 @@ var zodPaginationSchema = z2.object({
   limit: asQuery(z2.number().int().positive()).optional()
 });
 var zodPaginationShape = zodPaginationSchema.shape;
+
+// src/zod-flatten/zod-flatten.schemas.ts
+import z4 from "zod";
+
+// src/zod-flatten/zod-flatten.utilities.ts
+import z3 from "zod";
+var isZodObject = (schema) => {
+  return schema instanceof z3.ZodObject;
+};
+var isZodOptional = (schema) => {
+  return schema instanceof z3.ZodOptional;
+};
+var unwrapOptional = (schema) => {
+  return isZodOptional(schema) ? schema.unwrap() : schema;
+};
+
+// src/zod-flatten/zod-flatten.schemas.ts
+var flattenZodShape = (shape) => {
+  const flat = {};
+  for (const [key, schema] of Object.entries(shape)) {
+    const unwrappedSchema = unwrapOptional(schema);
+    if (isZodObject(unwrappedSchema) === false) {
+      flat[key] = schema;
+      continue;
+    }
+    for (const [innerKey, innerSchema] of Object.entries(unwrappedSchema.shape)) {
+      flat[innerKey] = isZodOptional(schema) ? innerSchema.optional() : innerSchema;
+    }
+  }
+  return flat;
+};
+var asQuerySchema = (schema) => {
+  return z4.object(flattenZodShape(schema.shape)).strict();
+};
+
+// src/zod-validation/zod-validation.utilities.ts
+var isPlainObject = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
 export {
   EXCEPTION_STATUS_CODES,
   SUCCESS_STATUS_CODES,
   ZodJWTService,
   asQuery,
+  asQuerySchema,
   failure,
   fetchAndThrow,
   fetchSafely,
+  flattenZodShape,
   formatTime,
   generateRandomString,
   getColoredHTTPStatus,
@@ -261,14 +302,19 @@ export {
   getUTCOffset,
   getZonedTime,
   honoLoggingHandler,
+  isPlainObject,
+  isZodObject,
+  isZodOptional,
   log,
   measureExecutionTime,
   onHandlerError,
+  parseQueryValue,
   refinePagination,
   respond,
   safeExecute,
   sqlWhere,
   success,
+  unwrapOptional,
   zodPaginationSchema,
   zodPaginationShape
 };

package/package.json

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