@kalutskii/foundation 0.6.22 → 0.6.24

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,29 +171,62 @@ 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' });
+const assetSchema = z.object({
+  status: z.enum(['active', 'archived']),
+  categoryId: z.number(),
+});
+
+const assetSearchSchema = zodSearchSchema({
+  filters: assetSchema.pick({ status: true, categoryId: true }),
+});
+
+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 }
+```
 
-// Spread shape into a larger query schema
-const querySchema = z.object({
-  search: z.string().optional(),
-  ...zodPaginationShape,
+### 9. Share bulk selection between frontend and backend
+
+```typescript
+import { zodBulkSelectionSchema, zodSearchSchema } from '@kalutskii/foundation';
+import { z } from 'zod';
+
+const assetBulkSelectionSchema = zodBulkSelectionSchema({
+  identifierSchema: z.string().min(1),
 });
 
-// Strip undefined pagination values before passing to a query builder (e.g. Drizzle)
-await db.query.users.findMany({
-  ...refinePagination(options),
+const assetBulkFilterSchema = zodSearchSchema({
+  filters: assetSchema.pick({ status: true, categoryId: true }),
+  paginationEnabled: false,
 });
+
+const assetBulkRequestSchema = z
+  .object({
+    selection: assetBulkSelectionSchema,
+    filter: assetBulkFilterSchema,
+  })
+  .strict();
+
+type AssetBulkRequest = z.infer<typeof assetBulkRequestSchema>;
 ```
 
-### 9. Work with JWT using `ZodJWTService`
+In `include` mode, the backend targets only `identifiers`. In `exclude` mode, it resolves all entities matching the same filter snapshot and removes `excludedIdentifiers` from that operation.
+
+### 10. Work with JWT using `ZodJWTService`
 
 ```typescript
 import { ZodJWTService } from '@kalutskii/foundation';
@@ -210,7 +243,7 @@ const payload = await jwt.verifyOrThrow(token, 'secret');
 const decoded = await jwt.decode(token);
 ```
 
-### 10. Datetime helpers
+### 11. Datetime helpers
 
 ```typescript
 import { formatTime, getFormattedDate, getFormattedTime, getZonedTime } from '@kalutskii/foundation';
@@ -221,7 +254,7 @@ getFormattedDate({ tz: 'Europe/Moscow', withTime: false }); // '22.06.2026'
 formatTime(new Date(), { tz: 'Europe/Moscow' }); // '15:30:00, 22 июня 2026 (+3 UTC)'
 ```
 
-### 11. Logging
+### 12. Logging
 
 ```typescript
 import { log } from '@kalutskii/foundation';
@@ -239,8 +272,10 @@ The package exports all public APIs from a single entrypoint:
 - **HTTP**: `success`, `failure`, `fetchSafely`, `fetchAndThrow`, constants, schemas.
 - **Hono**: `respond`, `onHandlerError`, `honoLoggingHandler`.
 - **Utilities**: `safeExecute`, `measureExecutionTime`, `generateRandomString`, `log`, `getColoredHTTPStatus`, datetime helpers.
+- **Zod Bulk**: `zodBulkSelectionSchema`, `ZodBulkSelection`, `ZodBulkIncludeSelection`, `ZodBulkExcludeSelection`.
 - **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,8 +1,8 @@
-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';
 import z, { ZodObject, ZodRawShape, z as z$1 } from 'zod';
+import { SymmetricAlgorithm } from 'hono/utils/jwt/jwa';
 
 /**
  * Builds a Drizzle SQL `where` condition from a plain object.
@@ -222,6 +222,52 @@ type Simplify<T> = {
     [K in keyof T]: T[K];
 } & {};
 
+/**
+ * Builds a strict selection contract for bulk operations across paginated data.
+ * The identifier schema is shared by explicit and all-matching selection modes.
+ *
+ * `include` targets only identifiers listed by the client. `exclude` targets every
+ * item matching the accompanying search snapshot except excluded identifiers.
+ *
+ * @example
+ * const assetBulkSelectionSchema = zodBulkSelectionSchema({
+ *   identifierSchema: z.string().min(1),
+ * });
+ */
+declare const zodBulkSelectionSchema: <const TIdentifierSchema extends z.ZodType<string | number>>({ identifierSchema, }: {
+    /**
+     * Schema used to validate every included or excluded entity identifier.
+     * Its transforms and exact inferred output are preserved in both branches.
+     */
+    identifierSchema: TIdentifierSchema;
+}) => z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"include">;
+    identifiers: z.ZodArray<TIdentifierSchema>;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"exclude">;
+    excludedIdentifiers: z.ZodArray<TIdentifierSchema>;
+}, z.core.$strict>], "mode">;
+
+/**
+ * Shared bulk-selection payload produced by `zodBulkSelectionSchema`.
+ * String identifiers are used by default for frontend table integrations.
+ */
+type ZodBulkSelection<TIdentifier extends string | number = string> = z.infer<ReturnType<typeof zodBulkSelectionSchema<z.ZodType<TIdentifier>>>>;
+/**
+ * Explicit bulk selection containing only identifiers chosen by the client.
+ * This branch does not require resolving an all-matching search snapshot.
+ */
+type ZodBulkIncludeSelection<TIdentifier extends string | number = string> = Extract<ZodBulkSelection<TIdentifier>, {
+    mode: 'include';
+}>;
+/**
+ * All-matching bulk selection containing identifiers excluded by the client.
+ * Backend handlers must resolve targets from the same search snapshot.
+ */
+type ZodBulkExcludeSelection<TIdentifier extends string | number = string> = Extract<ZodBulkSelection<TIdentifier>, {
+    mode: 'exclude';
+}>;
+
 /** Options for configuring the JWT service. */
 type JWTServiceOptions = {
     /** The algorithm to use for signing and verifying JWTs. Defaults to 'HS256'. */
@@ -274,26 +320,122 @@ 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>;
+/**
+ * Feature flags shared by both supported search schema composition modes.
+ * Literal values are preserved in the resulting runtime and static shapes.
+ */
+type ZodSearchFeatureOptions<TQueryEnabled extends boolean, TPaginationEnabled extends boolean> = {
+    /**
+     * 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;
+};
+/**
+ * Configuration used to compose a reusable search request schema.
+ * Exactly one source must be provided for the resulting `where` field.
+ *
+ * `filters` is the concise mode that applies partial and non-empty rules.
+ * `whereSchema` accepts a fully prepared schema with custom Zod effects.
+ */
+type ZodSearchSchemaOptions<TShape extends z.ZodRawShape = never, TWhereSchema extends z.ZodType<Record<string, unknown>> = never, TQueryEnabled extends boolean = true, TPaginationEnabled extends boolean = true> = ZodSearchFeatureOptions<TQueryEnabled, TPaginationEnabled> & ({
+    /**
+     * Object schema whose fields become optional filters inside `where`.
+     * The factory requires one defined value whenever `where` is present.
+     */
+    filters: z.ZodObject<TShape>;
+    /** Prevents combining automatic filters with a prepared schema. */
+    whereSchema?: never;
+} | {
+    /** Prevents combining a prepared schema with automatic filters. */
+    filters?: never;
+    /**
+     * Prepared schema used directly to validate the `where` object.
+     * Its refinements, transforms, and inferred output are preserved.
+     */
+    whereSchema: TWhereSchema;
+});
+
+/**
+ * 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.
+ * Top-level optionality is added later for both composition modes equally.
+ */
+declare const createZodSearchWhereSchema: <TShape extends z.ZodRawShape>(filters: z.ZodObject<TShape>) => 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>;
+/**
+ * Resolves the schema used by `where` from the selected composition mode.
+ * Prepared schemas remain untouched, including their effects and output.
+ */
+type ZodSearchWhereSchema<TShape extends z.ZodRawShape, TWhereSchema extends z.ZodType<Record<string, unknown>>> = [
+    TWhereSchema
+] extends [never] ? ReturnType<typeof createZodSearchWhereSchema<TShape>> : TWhereSchema;
+/**
+ * Schema-level shape assembled from the selected source and feature flags.
+ * Keeping Zod schemas here makes runtime composition the contract source.
+ */
+type ZodSearchShape<TShape extends z.ZodRawShape, TWhereSchema extends z.ZodType<Record<string, unknown>>, TQueryEnabled extends boolean, TPaginationEnabled extends boolean> = {
+    where: z.ZodOptional<ZodSearchWhereSchema<TShape, TWhereSchema>>;
+} & (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.
+ *
+ * Pass `filters` for automatic partial and non-empty validation, or use
+ * `whereSchema` to preserve a prepared schema with custom Zod effects.
+ *
+ * @example
+ * const assetSearchSchema = zodSearchSchema({
+ *   filters: assetSchema.pick({ status: true }),
+ * });
+ *
+ * const refinedAssetSearchSchema = zodSearchSchema({
+ *   whereSchema: zodAtLeastOne(assetSchema.pick({ status: true }).partial()),
+ * });
+ */
+declare const zodSearchSchema: <const TShape extends z.ZodRawShape = never, const TWhereSchema extends z.ZodType<Record<string, unknown>> = never, const TQueryEnabled extends boolean = true, const TPaginationEnabled extends boolean = true>(options: ZodSearchSchemaOptions<TShape, TWhereSchema, TQueryEnabled, TPaginationEnabled>) => z.ZodObject<ZodSearchShape<TShape, TWhereSchema, TQueryEnabled, TPaginationEnabled> extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strict>;
 
 type QueryPrimitive = string | number | boolean | bigint | Date;
 /**
@@ -316,7 +458,7 @@ type AsQuery<T> = T extends null | undefined ? T : T extends QueryPrimitive ? st
  * // 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;
+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 +498,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, type ZodBulkExcludeSelection, type ZodBulkIncludeSelection, type ZodBulkSelection, 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, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchSchema };

package/dist/index.js

@@ -164,6 +164,19 @@ async function measureExecutionTime(execution) {
   return { result, executionTime: Math.round(executionTime) };
 }
 
+// src/zod-bulk/zod-bulk.schemas.ts
+import z from "zod";
+var DEFAULT_ERROR_MESSAGE = "Selection identifiers must be provided.";
+var zodBulkSelectionSchema = ({ identifierSchema }) => {
+  const identifiersSchema = z.array(identifierSchema).refine((identifiers) => new Set(identifiers).size === identifiers.length, {
+    message: DEFAULT_ERROR_MESSAGE
+  });
+  return z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("include"), identifiers: identifiersSchema }).strict(),
+    z.object({ mode: z.literal("exclude"), excludedIdentifiers: identifiersSchema }).strict()
+  ]);
+};
+
 // src/zod-jwt/zod-jwt.schemas.ts
 import { decode as decodeJWT, sign as signJWT, verify as verifyJWT } from "hono/jwt";
 var ZodJWTService = class {
@@ -213,26 +226,48 @@ var ZodJWTService = class {
   }
 };
 
-// src/zod-pagination/zod-pagination.schemas.ts
-import z from "zod";
-var zodPaginationSchema = z.object({
-  /** Integer representing the starting point for pagination. */
-  offset: z.coerce.number().int().nonnegative().default(0),
-  /** Integer representing the maximum number of items to return. */
-  limit: z.coerce.number().int().positive().default(10)
+// src/zod-search/zod-search.pagination.schemas.ts
+import z2 from "zod";
+var zodPaginationSchema = z2.object({
+  /**
+   * Zero-based number of records skipped before collecting a result page.
+   * String values are coerced to support validation of URL query input.
+   */
+  offset: z2.coerce.number().int().nonnegative().default(0),
+  /**
+   * Positive maximum number of records returned in a single result page.
+   * String values are coerced to support validation of URL query input.
+   */
+  limit: z2.coerce.number().int().positive().default(10)
 });
 var zodPaginationShape = zodPaginationSchema.shape;
 
+// src/zod-search/zod-search.schemas.ts
+import z3 from "zod";
+
 // src/zod-validation/zod-validation.refiners.ts
-var DEFAULT_ERROR_MESSAGE = "Invalid input. At least one field must be provided.";
+var DEFAULT_ERROR_MESSAGE2 = "Invalid input. At least one field must be provided.";
 var zodAtLeastOne = (schema) => schema.superRefine((val, ctx) => {
   const hasValue = Object.values(val).some((v) => v !== void 0);
   if (!hasValue)
-    ctx.addIssue({ code: "custom", message: DEFAULT_ERROR_MESSAGE });
+    ctx.addIssue({ code: "custom", message: DEFAULT_ERROR_MESSAGE2 });
 }).transform((val) => val);
 
+// src/zod-search/zod-search.schemas.ts
+var zodSearchQuerySchema = z3.string().trim().min(1).optional();
+var createZodSearchWhereSchema = (filters) => zodAtLeastOne(filters.partial());
+var zodSearchSchema = (options) => {
+  const whereSchema = options.filters !== void 0 ? createZodSearchWhereSchema(options.filters) : options.whereSchema;
+  const shape = {
+    where: whereSchema.optional(),
+    ...options.queryEnabled !== false ? { query: zodSearchQuerySchema } : {},
+    ...options.paginationEnabled !== false ? { pagination: zodPaginationSchema } : {}
+  };
+  return z3.object(shape).strict();
+};
+
 // src/zod-validation/zod-validation.parsing.ts
-import z2 from "zod";
+import z4 from "zod";
 
 // src/zod-validation/zod-validation.utilities.ts
 var isPlainObject = (value) => {
@@ -259,7 +294,7 @@ var parseQueryValue = (value) => {
     return Number(normalized);
   return value;
 };
-var asQuery = (schema) => z2.preprocess(parseQueryValue, schema);
+var asQuery = (schema) => z4.preprocess(parseQueryValue, schema);
 export {
   EXCEPTION_STATUS_CODES,
   SUCCESS_STATUS_CODES,
@@ -287,6 +322,8 @@ export {
   sqlWhere,
   success,
   zodAtLeastOne,
+  zodBulkSelectionSchema,
   zodPaginationSchema,
-  zodPaginationShape
+  zodPaginationShape,
+  zodSearchSchema
 };

package/package.json

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