@kalutskii/foundation 0.6.21 → 0.6.23

package/README.md

@@ -144,7 +144,7 @@ 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.
 
-### 8. Build flat query schemas from nested objects
+### 7. Build flat query schemas from nested objects
 
 ```typescript
 import { asQuerySchema } from '@kalutskii/foundation';
@@ -171,26 +171,32 @@ 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
+### 8. Build reusable search schemas
 
 ```typescript
-import { refinePagination, zodPaginationSchema, zodPaginationShape } from '@kalutskii/foundation';
+import { zodPaginationSchema, zodSearchSchema } from '@kalutskii/foundation';
 import { z } from 'zod';
 
-// Use as a standalone schema
-const options = zodPaginationSchema.parse({ offset: '0', limit: '20' });
-// { offset: 0, limit: 20 }
+const assetSchema = z.object({
+  status: z.enum(['active', 'archived']),
+  categoryId: z.number(),
+});
 
-// Spread shape into a larger query schema
-const querySchema = z.object({
-  search: z.string().optional(),
-  ...zodPaginationShape,
+const assetSearchSchema = zodSearchSchema({
+  filters: assetSchema.pick({ status: true, categoryId: true }),
 });
 
-// Strip undefined pagination values before passing to a query builder (e.g. Drizzle)
-await db.query.users.findMany({
-  ...refinePagination(options),
+type AssetSearch = z.infer<typeof assetSearchSchema>;
+
+assetSearchSchema.parse({
+  where: { status: 'active' },
+  query: 'asset name',
+  pagination: { offset: 0, limit: 20 },
 });
+
+// Pagination remains available as a standalone reusable schema.
+zodPaginationSchema.parse({ offset: '0', limit: '20' });
+// { offset: 0, limit: 20 }
 ```
 
 ### 9. Work with JWT using `ZodJWTService`
@@ -240,7 +246,8 @@ The package exports all public APIs from a single entrypoint:
 - **Hono**: `respond`, `onHandlerError`, `honoLoggingHandler`.
 - **Utilities**: `safeExecute`, `measureExecutionTime`, `generateRandomString`, `log`, `getColoredHTTPStatus`, datetime helpers.
 - **Zod JWT**: `ZodJWTService`.
-- **Zod Pagination**: `zodPaginationSchema`, `zodPaginationShape`, `refinePagination`, `ZodPaginationOptions`.
+- **Zod Search**: `zodSearchSchema`, `ZodSearchSchemaOptions`.
+- **Zod Pagination**: `zodPaginationSchema`, `zodPaginationShape`, `ZodPaginationOptions`.
 - **Zod Flatten**: `asQuerySchema`, `flattenZodShape`, `isZodObject`, `isZodOptional`, `unwrapOptional`, `FlattenZodShape`.
 - **Zod Validation**: `asQuery`, `AsQuery`, `AtLeastOne`.
 - **Type Utilities**: `Simplify`.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SQL, Simplify as Simplify$1 } from 'drizzle-orm';
+import { SQL } from 'drizzle-orm';
 import { ErrorHandler, MiddlewareHandler, Context, TypedResponse } from 'hono';
 import { Locale } from 'date-fns';
 import { SymmetricAlgorithm } from 'hono/utils/jwt/jwa';
@@ -58,29 +58,6 @@ type FetchResult<T> = {
     data: null;
 };
 
-type QueryPrimitive = string | number | boolean | bigint | Date;
-/**
- * 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 null | undefined ? 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.
- *
- * ```typescript
- * 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$1<Required<Pick<T, Keys>> & Partial<Omit<T, Keys>>> : never;
-
 /**
  * Wraps c.json with a typed success payload / (or void data) & possible APIError response.
  * When no data is provided, responds with an empty object {} (purely for type consistency).
@@ -88,7 +65,7 @@ type AtLeastOne<T, Keys extends keyof T = keyof T> = Keys extends keyof T ? Simp
 declare function respond<T extends object = Record<string, never>, S extends SuccessStatusCode = SuccessStatusCode>(c: Context, options: {
     status: S;
     data?: T;
-}): Response & TypedResponse<APISuccess<AsQuery<T>> | APIError, S, 'json'>;
+}): Response & TypedResponse<APISuccess<T> | APIError, S, 'json'>;
 
 /**
  * Factory for creating successful API responses with serializable data.
@@ -297,26 +274,114 @@ declare class ZodJWTService<TPayloadOrSchema> {
     verifyOrThrow(token: string, secret: string): Promise<Payload<TPayloadOrSchema>>;
 }
 
+/**
+ * Validates offset-based pagination shared by search request contracts.
+ * Missing fields inside the required object receive predictable defaults.
+ */
 declare const zodPaginationSchema: z.ZodObject<{
     offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
 /**
- * Reusable pagination fields for flat query schemas, allowing for
- * consistent validation of pagination parameters across different endpoints.
- *
- * Spread into another `z.object(...)` when composing a larger query schema,
- * or use `zodPaginationSchema.extend(...)` when building directly from the schema.
+ * Exposes pagination fields for composition into other object schemas.
+ * The shape stays derived from the schema to prevent contract divergence.
  */
 declare const zodPaginationShape: {
     offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 };
+
 /**
- * TypeScript type representing the pagination options validated by the `zodPaginationSchema`.
- * Read documentation for `zodPaginationSchema` for more details on the structure and usage of this type.
+ * TypeScript output produced after successful pagination validation.
+ * Defaulted fields are represented as required numeric properties.
  */
 type ZodPaginationOptions = z.infer<typeof zodPaginationSchema>;
+/**
+ * Configuration used to compose a reusable search request schema.
+ * Literal feature flags are preserved in the resulting static shape.
+ */
+type ZodSearchSchemaOptions<TShape extends z.ZodRawShape, TQueryEnabled extends boolean = true, TPaginationEnabled extends boolean = true> = {
+    /**
+     * Object schema whose fields become available inside the `where` object.
+     * Every resulting field is optional, but one value must be defined.
+     */
+    filters: z.ZodObject<TShape>;
+    /**
+     * Controls whether an optional non-empty `query` field is generated.
+     * The field is enabled when this option is omitted from the call.
+     */
+    queryEnabled?: TQueryEnabled;
+    /**
+     * Controls whether a required `pagination` object is generated.
+     * The field is enabled when this option is omitted from the call.
+     */
+    paginationEnabled?: TPaginationEnabled;
+};
+
+/**
+ * Optional text query shared by search request contracts.
+ * Provided values are trimmed and must contain visible text.
+ */
+declare const zodSearchQuerySchema: z.ZodOptional<z.ZodString>;
+/**
+ * Makes every supplied filter optional while requiring one defined value.
+ * The wrapper itself stays optional because searches may omit filtering.
+ */
+declare const createZodSearchWhereSchema: <TShape extends z.ZodRawShape>(filters: z.ZodObject<TShape>) => z.ZodOptional<z.ZodPipe<z.ZodObject<{ -readonly [k in keyof TShape]: z.ZodOptional<TShape[k]>; }, z.core.$strip>, z.ZodTransform<Awaited<AtLeastOne<z.core.$InferObjectOutput<{ -readonly [k in keyof TShape]: z.ZodOptional<TShape[k]>; }, {}>, keyof z.core.$InferObjectOutput<{ -readonly [k in keyof TShape]: z.ZodOptional<TShape[k]>; }, {}>>>, z.core.$InferObjectOutput<{ -readonly [k in keyof TShape]: z.ZodOptional<TShape[k]>; }, {}>>>>;
+/**
+ * Empty schema shape used when a search feature is explicitly disabled.
+ * Intersections remove disabled fields without widening enabled branches.
+ */
+type ZodDisabledSearchShape = Record<never, never>;
+/**
+ * Schema-level shape assembled from filter fields and literal feature flags.
+ * Keeping Zod schemas here makes runtime composition the contract source.
+ */
+type ZodSearchShape<TShape extends z.ZodRawShape, TQueryEnabled extends boolean, TPaginationEnabled extends boolean> = {
+    where: ReturnType<typeof createZodSearchWhereSchema<TShape>>;
+} & (TQueryEnabled extends false ? ZodDisabledSearchShape : {
+    query: typeof zodSearchQuerySchema;
+}) & (TPaginationEnabled extends false ? ZodDisabledSearchShape : {
+    pagination: typeof zodPaginationSchema;
+});
+/**
+ * Builds a strict schema for reusable search request contracts.
+ * The optional `where` object must contain one defined filter.
+ *
+ * Query is optional and non-empty; pagination is required by default.
+ * Literal feature flags update both runtime and inferred static shapes.
+ *
+ * @example
+ * const assetSearchSchema = zodSearchSchema({
+ *   filters: assetSchema.pick({ status: true }),
+ * });
+ *
+ * type AssetSearch = z.infer<typeof assetSearchSchema>;
+ */
+declare const zodSearchSchema: <const TShape extends z.ZodRawShape, const TQueryEnabled extends boolean = true, const TPaginationEnabled extends boolean = true>({ filters, queryEnabled, paginationEnabled, }: ZodSearchSchemaOptions<TShape, TQueryEnabled, TPaginationEnabled>) => z.ZodObject<ZodSearchShape<TShape, TQueryEnabled, TPaginationEnabled> extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strict>;
+
+type QueryPrimitive = string | number | boolean | bigint | Date;
+/**
+ * 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 null | undefined ? 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.
+ *
+ * ```typescript
+ * 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 a partial Zod object schema with:
@@ -356,4 +421,4 @@ declare const asQuery: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<T>
  */
 declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
 
-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, type ReplaceDotsWithUnderscores, SUCCESS_STATUS_CODES, type Simplify, type StringEnumRecord, type SuccessStatusCode, ZodJWTService, type ZodPaginationOptions, asQuery, createStringEnumRecord, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, isPlainObject, log, measureExecutionTime, onHandlerError, parseQueryValue, respond, safeExecute, sqlWhere, success, zodAtLeastOne, zodPaginationSchema, zodPaginationShape };
+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, type ReplaceDotsWithUnderscores, SUCCESS_STATUS_CODES, type Simplify, type StringEnumRecord, type SuccessStatusCode, ZodJWTService, type ZodPaginationOptions, type ZodSearchSchemaOptions, asQuery, createStringEnumRecord, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, isPlainObject, log, measureExecutionTime, onHandlerError, parseQueryValue, respond, safeExecute, sqlWhere, success, zodAtLeastOne, zodPaginationSchema, zodPaginationShape, zodSearchSchema };

package/dist/index.js

@@ -213,16 +213,25 @@ var ZodJWTService = class {
   }
 };
 
-// src/zod-pagination/zod-pagination.schemas.ts
+// src/zod-search/zod-search.pagination.schemas.ts
 import z from "zod";
 var zodPaginationSchema = z.object({
-  /** Integer representing the starting point for pagination. */
+  /**
+   * Zero-based number of records skipped before collecting a result page.
+   * String values are coerced to support validation of URL query input.
+   */
   offset: z.coerce.number().int().nonnegative().default(0),
-  /** Integer representing the maximum number of items to return. */
+  /**
+   * Positive maximum number of records returned in a single result page.
+   * String values are coerced to support validation of URL query input.
+   */
   limit: z.coerce.number().int().positive().default(10)
 });
 var zodPaginationShape = zodPaginationSchema.shape;
 
+// src/zod-search/zod-search.schemas.ts
+import z2 from "zod";
+
 // src/zod-validation/zod-validation.refiners.ts
 var DEFAULT_ERROR_MESSAGE = "Invalid input. At least one field must be provided.";
 var zodAtLeastOne = (schema) => schema.superRefine((val, ctx) => {
@@ -231,8 +240,20 @@ var zodAtLeastOne = (schema) => schema.superRefine((val, ctx) => {
     ctx.addIssue({ code: "custom", message: DEFAULT_ERROR_MESSAGE });
 }).transform((val) => val);
 
+// src/zod-search/zod-search.schemas.ts
+var zodSearchQuerySchema = z2.string().trim().min(1).optional();
+var createZodSearchWhereSchema = (filters) => zodAtLeastOne(filters.partial()).optional();
+var zodSearchSchema = ({ filters, queryEnabled, paginationEnabled }) => {
+  const shape = {
+    where: createZodSearchWhereSchema(filters),
+    ...queryEnabled !== false ? { query: zodSearchQuerySchema } : {},
+    ...paginationEnabled !== false ? { pagination: zodPaginationSchema } : {}
+  };
+  return z2.object(shape).strict();
+};
+
 // src/zod-validation/zod-validation.parsing.ts
-import z2 from "zod";
+import z3 from "zod";
 
 // src/zod-validation/zod-validation.utilities.ts
 var isPlainObject = (value) => {
@@ -259,7 +280,7 @@ var parseQueryValue = (value) => {
     return Number(normalized);
   return value;
 };
-var asQuery = (schema) => z2.preprocess(parseQueryValue, schema);
+var asQuery = (schema) => z3.preprocess(parseQueryValue, schema);
 export {
   EXCEPTION_STATUS_CODES,
   SUCCESS_STATUS_CODES,
@@ -288,5 +309,6 @@ export {
   success,
   zodAtLeastOne,
   zodPaginationSchema,
-  zodPaginationShape
+  zodPaginationShape,
+  zodSearchSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.6.21",
+  "version": "0.6.23",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
   "type": "module",
   "repository": {
@@ -14,6 +14,7 @@
     "build": "tsup",
     "lint": "eslint . --ext .ts --fix",
     "format": "prettier --write .",
+    "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "exports": {