@kalutskii/foundation 0.6.23 → 0.6.24

package/README.md

@@ -199,7 +199,34 @@ zodPaginationSchema.parse({ offset: '0', limit: '20' });
 // { offset: 0, limit: 20 }
 ```
 
-### 9. Work with JWT using `ZodJWTService`
+### 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),
+});
+
+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>;
+```
+
+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';
@@ -216,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';
@@ -227,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';
@@ -245,6 +272,7 @@ 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 Search**: `zodSearchSchema`, `ZodSearchSchemaOptions`.
 - **Zod Pagination**: `zodPaginationSchema`, `zodPaginationShape`, `ZodPaginationOptions`.

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 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'. */
@@ -297,15 +343,10 @@ declare const zodPaginationShape: {
  */
 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.
+ * Feature flags shared by both supported search schema composition modes.
+ * Literal values are preserved in the resulting runtime and static shapes.
  */
-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>;
+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.
@@ -317,6 +358,30 @@ type ZodSearchSchemaOptions<TShape extends z.ZodRawShape, TQueryEnabled extends
      */
     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.
@@ -325,20 +390,27 @@ type ZodSearchSchemaOptions<TShape extends z.ZodRawShape, TQueryEnabled extends
 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.
+ * Top-level optionality is added later for both composition modes equally.
  */
-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]>; }, {}>>>>;
+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>;
 /**
- * Schema-level shape assembled from filter fields and literal feature flags.
+ * 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, TQueryEnabled extends boolean, TPaginationEnabled extends boolean> = {
-    where: ReturnType<typeof createZodSearchWhereSchema<TShape>>;
+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 : {
@@ -351,14 +423,19 @@ type ZodSearchShape<TShape extends z.ZodRawShape, TQueryEnabled extends boolean,
  * 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 }),
  * });
  *
- * type AssetSearch = z.infer<typeof assetSearchSchema>;
+ * const refinedAssetSearchSchema = zodSearchSchema({
+ *   whereSchema: zodAtLeastOne(assetSchema.pick({ status: true }).partial()),
+ * });
  */
-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>;
+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;
 /**
@@ -421,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, 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 };
+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 {
@@ -214,46 +227,47 @@ var ZodJWTService = class {
 };
 
 // src/zod-search/zod-search.pagination.schemas.ts
-import z from "zod";
-var zodPaginationSchema = z.object({
+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: z.coerce.number().int().nonnegative().default(0),
+  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: z.coerce.number().int().positive().default(10)
+  limit: z2.coerce.number().int().positive().default(10)
 });
 var zodPaginationShape = zodPaginationSchema.shape;
 
 // src/zod-search/zod-search.schemas.ts
-import z2 from "zod";
+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 = z2.string().trim().min(1).optional();
-var createZodSearchWhereSchema = (filters) => zodAtLeastOne(filters.partial()).optional();
-var zodSearchSchema = ({ filters, queryEnabled, paginationEnabled }) => {
+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: createZodSearchWhereSchema(filters),
-    ...queryEnabled !== false ? { query: zodSearchQuerySchema } : {},
-    ...paginationEnabled !== false ? { pagination: zodPaginationSchema } : {}
+    where: whereSchema.optional(),
+    ...options.queryEnabled !== false ? { query: zodSearchQuerySchema } : {},
+    ...options.paginationEnabled !== false ? { pagination: zodPaginationSchema } : {}
   };
-  return z2.object(shape).strict();
+  return z3.object(shape).strict();
 };
 
 // src/zod-validation/zod-validation.parsing.ts
-import z3 from "zod";
+import z4 from "zod";
 
 // src/zod-validation/zod-validation.utilities.ts
 var isPlainObject = (value) => {
@@ -280,7 +294,7 @@ var parseQueryValue = (value) => {
     return Number(normalized);
   return value;
 };
-var asQuery = (schema) => z3.preprocess(parseQueryValue, schema);
+var asQuery = (schema) => z4.preprocess(parseQueryValue, schema);
 export {
   EXCEPTION_STATUS_CODES,
   SUCCESS_STATUS_CODES,
@@ -308,6 +322,7 @@ export {
   sqlWhere,
   success,
   zodAtLeastOne,
+  zodBulkSelectionSchema,
   zodPaginationSchema,
   zodPaginationShape,
   zodSearchSchema

package/package.json

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