@kalutskii/foundation 0.6.7 → 0.6.9

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

@@ -11,14 +11,10 @@ import z from 'zod';
  * 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();
+ * await db.update(usersTable).set(values).where(sqlWhere(usersTable, { id: 1 })).returning();
  * ```
  */
-declare function sqlWhere(table: unknown, where: Record<string, unknown>): SQL | undefined;
+declare function sqlWhere(table: unknown, where: Record<string, unknown>): SQL;
 
 /**
  * Global error handler for Hono framework. Catches all exceptions thrown in route handlers and middlewares.
@@ -72,8 +68,8 @@ type Simplify<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.
+ * 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]>;
@@ -319,6 +315,76 @@ 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;
+
 /**
  * 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.
@@ -338,4 +404,4 @@ 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 };
+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, isZodObject, isZodOptional, log, measureExecutionTime, onHandlerError, refinePagination, respond, safeExecute, sqlWhere, success, unwrapOptional, zodPaginationSchema, zodPaginationShape };

package/dist/index.js

@@ -1,7 +1,13 @@
 // src/drizzle/drizzle.refiners.ts
 import { and, eq } from "drizzle-orm";
+var AT_LEAST_ONE_DEFINED_CONDITION_ERROR = "sqlWhere requires at least one defined condition.";
 function sqlWhere(table, where) {
-  return and(...Object.entries(where).map(([key, value]) => eq(table[key], value)));
+  const columns = table;
+  const conditions = Object.entries(where).filter(([, value]) => value !== void 0).map(([key, value]) => eq(columns[key], value));
+  if (conditions.length === 0) {
+    throw new Error(AT_LEAST_ONE_DEFINED_CONDITION_ERROR);
+  }
+  return and(...conditions);
 }
 
 // src/hono/hono.execution.ts
@@ -239,14 +245,50 @@ 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();
+};
 export {
   EXCEPTION_STATUS_CODES,
   SUCCESS_STATUS_CODES,
   ZodJWTService,
   asQuery,
+  asQuerySchema,
   failure,
   fetchAndThrow,
   fetchSafely,
+  flattenZodShape,
   formatTime,
   generateRandomString,
   getColoredHTTPStatus,
@@ -255,6 +297,8 @@ export {
   getUTCOffset,
   getZonedTime,
   honoLoggingHandler,
+  isZodObject,
+  isZodOptional,
   log,
   measureExecutionTime,
   onHandlerError,
@@ -263,6 +307,7 @@ export {
   safeExecute,
   sqlWhere,
   success,
+  unwrapOptional,
   zodPaginationSchema,
   zodPaginationShape
 };

package/package.json

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