@veloxts/validation 0.6.82 → 0.6.84

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @veloxts/validation
 
+## 0.6.84
+
+### Patch Changes
+
+- - auth: add simplified guard() function with overloads + fluent builder
+- Updated dependencies
+  - @veloxts/core@0.6.84
+
+## 0.6.83
+
+### Patch Changes
+
+- docs(templates): add /veloxts skill to CLAUDE.md files and links to online documentation
+- Updated dependencies
+  - @veloxts/core@0.6.83
+
 ## 0.6.82
 
 ### Patch Changes

package/dist/index.d.ts

@@ -33,5 +33,6 @@ export type { BaseEntity, IdParam, TimestampFields } from './schemas/common.js';
 export { baseEntitySchema, booleanStringSchema, createIdSchema, datetimeSchema, emailSchema, idParamSchema, integerStringSchema, makePartial, nonEmptyStringSchema, numberStringSchema, omitFields, partialExcept, pickFields, timestampFieldsSchema, urlSchema, uuidSchema, } from './schemas/common.js';
 export type { CursorPaginatedResponse, CursorPaginationInput, CursorPaginationMeta, PaginatedResponse, PaginationInput, PaginationMeta, } from './schemas/pagination.js';
 export { calculateOffset, calculatePaginationMeta, createCursorPaginatedResponseSchema, createPaginatedResponse, createPaginatedResponseSchema, createPaginationSchema, cursorPaginationSchema, PAGINATION_DEFAULTS, paginationInputSchema, } from './schemas/pagination.js';
+export { pagination, queryArray, queryBoolean, queryEnum, queryInt, queryNumber, } from './schemas/query.js';
 export type { InferWithTimestamps, OmitTimestamps, SerializedDates, WithOptional, } from './schemas/serialization.js';
 export { dateToISOString, dateToISOStringNullable, dateToISOStringOptional, dateToIso, dateToIsoNullable, dateToIsoOptional, prismaDecimal, prismaDecimalNullable, prismaDecimalOptional, timestamps, timestampsWithSoftDelete, withTimestamps, } from './schemas/serialization.js';

package/dist/index.js

@@ -35,6 +35,10 @@ export { isSchema, isZodSchema, wrapSchema } from './types.js';
 export { assertSchema, createTypeGuard, createValidator, formatZodErrors, parse, parseAll, safeParse, zodErrorToValidationError, } from './middleware.js';
 export { baseEntitySchema, booleanStringSchema, createIdSchema, datetimeSchema, emailSchema, idParamSchema, integerStringSchema, makePartial, nonEmptyStringSchema, numberStringSchema, omitFields, partialExcept, pickFields, timestampFieldsSchema, urlSchema, uuidSchema, } from './schemas/common.js';
 export { calculateOffset, calculatePaginationMeta, createCursorPaginatedResponseSchema, createPaginatedResponse, createPaginatedResponseSchema, createPaginationSchema, cursorPaginationSchema, PAGINATION_DEFAULTS, paginationInputSchema, } from './schemas/pagination.js';
+// ============================================================================
+// Query Parameter Helpers
+// ============================================================================
+export { pagination, queryArray, queryBoolean, queryEnum, queryInt, queryNumber, } from './schemas/query.js';
 export { 
 // Date serialization
 dateToISOString, dateToISOStringNullable, dateToISOStringOptional, 

package/dist/schemas/query.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Query Parameter Coercion Helpers
+ *
+ * Provides type-safe coercion utilities for query string parameters.
+ * Query parameters arrive as strings; these helpers provide automatic
+ * conversion to appropriate types with sensible defaults.
+ *
+ * @module schemas/query
+ */
+import { z } from 'zod';
+/**
+ * Creates a number schema that coerces from query string
+ *
+ * @param defaultValue - Default when undefined/empty (optional)
+ * @returns Zod schema that parses string to number
+ *
+ * @example Required number
+ * ```typescript
+ * .input(z.object({
+ *   userId: queryNumber(), // Required, no default
+ * }))
+ * ```
+ *
+ * @example With default value
+ * ```typescript
+ * .input(z.object({
+ *   page: queryNumber(1),   // Defaults to 1
+ *   limit: queryNumber(20), // Defaults to 20
+ * }))
+ * ```
+ */
+export declare function queryNumber(): z.ZodNumber;
+export declare function queryNumber(defaultValue: number): z.ZodDefault<z.ZodNumber>;
+/**
+ * Creates an integer schema that coerces from query string
+ *
+ * @param defaultValue - Default when undefined/empty (optional)
+ * @returns Zod schema that parses string to integer
+ *
+ * @example
+ * ```typescript
+ * .input(z.object({
+ *   page: queryInt(1),      // Defaults to 1
+ *   userId: queryInt(),     // Required integer
+ * }))
+ * ```
+ */
+export declare function queryInt(): z.ZodNumber;
+export declare function queryInt(defaultValue: number): z.ZodDefault<z.ZodNumber>;
+/**
+ * Creates a boolean schema that coerces from query string
+ *
+ * Accepts common truthy/falsy string values:
+ * - Truthy: 'true', '1', 'yes', 'on'
+ * - Falsy: 'false', '0', 'no', 'off'
+ *
+ * @param defaultValue - Default when undefined/empty (optional)
+ * @returns Zod schema that parses string to boolean
+ *
+ * @example
+ * ```typescript
+ * .input(z.object({
+ *   active: queryBoolean(true),   // Defaults to true
+ *   deleted: queryBoolean(false), // Defaults to false
+ *   verified: queryBoolean(),     // Optional, undefined if not provided
+ * }))
+ *
+ * // Accepts: ?active=true, ?active=1, ?active=yes, ?active=on
+ * // Accepts: ?deleted=false, ?deleted=0, ?deleted=no, ?deleted=off
+ * ```
+ */
+export declare function queryBoolean(): z.ZodOptional<z.ZodBoolean>;
+export declare function queryBoolean(defaultValue: boolean): z.ZodDefault<z.ZodBoolean>;
+/**
+ * Creates a string array schema that coerces from comma-separated query string
+ *
+ * @param options - Configuration options
+ * @returns Zod schema that parses comma-separated string to array
+ *
+ * @example Basic usage
+ * ```typescript
+ * .input(z.object({
+ *   tags: queryArray(),           // 'a,b,c' -> ['a', 'b', 'c']
+ *   ids: queryArray({ min: 1 }),  // At least one item required
+ *   categories: queryArray({ max: 5 }), // Max 5 items
+ * }))
+ *
+ * // GET /api/products?tags=electronics,sale,featured
+ * // Result: { tags: ['electronics', 'sale', 'featured'] }
+ * ```
+ *
+ * @example Edge cases
+ * ```typescript
+ * // Empty string results in empty array (whitespace-only items filtered)
+ * queryArray().parse('')          // []
+ * queryArray().parse('  ,  ')     // []
+ *
+ * // With min constraint, empty string will fail validation
+ * queryArray({ min: 1 }).parse('')  // throws: "Array must have at least 1 item(s)"
+ *
+ * // If you want "no parameter = no filter", combine with optional:
+ * .input(z.object({
+ *   tags: queryArray({ min: 1 }).optional(),  // undefined or non-empty array
+ * }))
+ * ```
+ *
+ * @remarks
+ * Empty strings and whitespace-only values are automatically filtered out.
+ * This means `?tags=` (empty) and `?tags=,,` (only separators) both result
+ * in an empty array `[]`. If you have a `min: 1` constraint, these will fail
+ * validation. Use `.optional()` if the parameter should be omittable.
+ */
+export declare function queryArray(options?: {
+    /** Minimum number of items required */
+    min?: number;
+    /** Maximum number of items allowed */
+    max?: number;
+    /** Separator character (default: ',') */
+    separator?: string;
+}): z.ZodType<string[], z.ZodTypeDef, string>;
+/**
+ * Creates an enum schema that validates against allowed values
+ *
+ * @param values - Array of allowed string values (use `as const` for type inference)
+ * @param defaultValue - Default value when undefined/empty (optional)
+ * @returns Zod schema that validates against enum values
+ *
+ * @example
+ * ```typescript
+ * .input(z.object({
+ *   sort: queryEnum(['asc', 'desc'] as const, 'asc'),
+ *   status: queryEnum(['active', 'pending', 'archived'] as const),
+ * }))
+ *
+ * // GET /api/users?sort=desc&status=active
+ * // Result: { sort: 'desc', status: 'active' }
+ * ```
+ */
+export declare function queryEnum<T extends readonly [string, ...string[]]>(values: T): z.ZodEnum<[T[number], ...T[number][]]>;
+export declare function queryEnum<T extends readonly [string, ...string[]]>(values: T, defaultValue: T[number]): z.ZodDefault<z.ZodEnum<[T[number], ...T[number][]]>>;
+/**
+ * Pre-built pagination schema for common use cases
+ *
+ * This is a shorthand for creating pagination input schemas.
+ * For more customization, use `createPaginationSchema` from pagination.js.
+ *
+ * @param options - Pagination configuration
+ * @returns Zod schema for pagination input
+ *
+ * @example Default offset-based pagination
+ * ```typescript
+ * .input(pagination())
+ * // { page: number, limit: number }
+ * ```
+ *
+ * @example With custom limits
+ * ```typescript
+ * .input(pagination({ defaultLimit: 10, maxLimit: 50 }))
+ * ```
+ *
+ * @example Extended with filters
+ * ```typescript
+ * .input(pagination().extend({
+ *   search: z.string().optional(),
+ *   status: queryEnum(['active', 'archived'] as const),
+ * }))
+ * ```
+ */
+export declare function pagination(options?: {
+    /** Default page number (default: 1) */
+    defaultPage?: number;
+    /** Default items per page (default: 20) */
+    defaultLimit?: number;
+    /** Maximum allowed items per page (default: 100) */
+    maxLimit?: number;
+}): z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    limit: number;
+}, {
+    page?: number | undefined;
+    limit?: number | undefined;
+}>;

package/dist/schemas/query.js

@@ -0,0 +1,150 @@
+/**
+ * Query Parameter Coercion Helpers
+ *
+ * Provides type-safe coercion utilities for query string parameters.
+ * Query parameters arrive as strings; these helpers provide automatic
+ * conversion to appropriate types with sensible defaults.
+ *
+ * @module schemas/query
+ */
+import { z } from 'zod';
+export function queryNumber(defaultValue) {
+    const base = z.coerce.number();
+    return defaultValue !== undefined ? base.default(defaultValue) : base;
+}
+export function queryInt(defaultValue) {
+    const base = z.coerce.number().int();
+    return defaultValue !== undefined ? base.default(defaultValue) : base;
+}
+export function queryBoolean(defaultValue) {
+    // Use preprocess to handle string-to-boolean conversion with query string conventions.
+    //
+    // NOTE: Type casting is required here because z.preprocess() wraps the inner schema
+    // in ZodEffects, but our public API promises ZodDefault<ZodBoolean> / ZodOptional<ZodBoolean>
+    // for better consumer type inference. The runtime behavior is correct; we cast to
+    // maintain the cleaner public type signature.
+    const booleanSchema = z.preprocess((val) => {
+        if (typeof val === 'boolean')
+            return val;
+        if (typeof val === 'string') {
+            return ['true', '1', 'yes', 'on'].includes(val.toLowerCase());
+        }
+        return undefined;
+    }, z.boolean());
+    if (defaultValue !== undefined) {
+        return booleanSchema.default(defaultValue);
+    }
+    return booleanSchema.optional();
+}
+// ============================================================================
+// String Array Helper
+// ============================================================================
+/**
+ * Creates a string array schema that coerces from comma-separated query string
+ *
+ * @param options - Configuration options
+ * @returns Zod schema that parses comma-separated string to array
+ *
+ * @example Basic usage
+ * ```typescript
+ * .input(z.object({
+ *   tags: queryArray(),           // 'a,b,c' -> ['a', 'b', 'c']
+ *   ids: queryArray({ min: 1 }),  // At least one item required
+ *   categories: queryArray({ max: 5 }), // Max 5 items
+ * }))
+ *
+ * // GET /api/products?tags=electronics,sale,featured
+ * // Result: { tags: ['electronics', 'sale', 'featured'] }
+ * ```
+ *
+ * @example Edge cases
+ * ```typescript
+ * // Empty string results in empty array (whitespace-only items filtered)
+ * queryArray().parse('')          // []
+ * queryArray().parse('  ,  ')     // []
+ *
+ * // With min constraint, empty string will fail validation
+ * queryArray({ min: 1 }).parse('')  // throws: "Array must have at least 1 item(s)"
+ *
+ * // If you want "no parameter = no filter", combine with optional:
+ * .input(z.object({
+ *   tags: queryArray({ min: 1 }).optional(),  // undefined or non-empty array
+ * }))
+ * ```
+ *
+ * @remarks
+ * Empty strings and whitespace-only values are automatically filtered out.
+ * This means `?tags=` (empty) and `?tags=,,` (only separators) both result
+ * in an empty array `[]`. If you have a `min: 1` constraint, these will fail
+ * validation. Use `.optional()` if the parameter should be omittable.
+ */
+export function queryArray(options = {}) {
+    const { min, max, separator = ',' } = options;
+    // Split by separator, trim whitespace, and filter out empty strings.
+    // Note: Empty input ('') results in [], which may fail min constraint.
+    const baseSchema = z.string().transform((val) => val
+        .split(separator)
+        .map((s) => s.trim())
+        .filter(Boolean));
+    // Apply min/max constraints via refinement if needed
+    if (min !== undefined || max !== undefined) {
+        return baseSchema.refine((arr) => {
+            if (min !== undefined && arr.length < min)
+                return false;
+            if (max !== undefined && arr.length > max)
+                return false;
+            return true;
+        }, {
+            message: min !== undefined && max !== undefined
+                ? `Array must have ${min}-${max} items`
+                : min !== undefined
+                    ? `Array must have at least ${min} item(s)`
+                    : `Array must have at most ${max} item(s)`,
+        });
+    }
+    return baseSchema;
+}
+export function queryEnum(values, defaultValue) {
+    // Cast to mutable tuple type that Zod expects
+    const mutableValues = [...values];
+    const base = z.enum(mutableValues);
+    return defaultValue !== undefined ? base.default(defaultValue) : base;
+}
+// ============================================================================
+// Pagination Shorthand
+// ============================================================================
+/**
+ * Pre-built pagination schema for common use cases
+ *
+ * This is a shorthand for creating pagination input schemas.
+ * For more customization, use `createPaginationSchema` from pagination.js.
+ *
+ * @param options - Pagination configuration
+ * @returns Zod schema for pagination input
+ *
+ * @example Default offset-based pagination
+ * ```typescript
+ * .input(pagination())
+ * // { page: number, limit: number }
+ * ```
+ *
+ * @example With custom limits
+ * ```typescript
+ * .input(pagination({ defaultLimit: 10, maxLimit: 50 }))
+ * ```
+ *
+ * @example Extended with filters
+ * ```typescript
+ * .input(pagination().extend({
+ *   search: z.string().optional(),
+ *   status: queryEnum(['active', 'archived'] as const),
+ * }))
+ * ```
+ */
+export function pagination(options = {}) {
+    const { defaultPage = 1, defaultLimit = 20, maxLimit = 100 } = options;
+    return z.object({
+        page: z.coerce.number().int().positive().default(defaultPage),
+        limit: z.coerce.number().int().positive().max(maxLimit).default(defaultLimit),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/validation",
-  "version": "0.6.82",
+  "version": "0.6.84",
   "description": "Zod integration and validation middleware for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "zod": "3.25.76",
-    "@veloxts/core": "0.6.82"
+    "@veloxts/core": "0.6.84"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.16",