@veloxts/validation 0.2.0 → 0.3.0

package/dist/schemas/common.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Common schema utilities and pre-built schemas
+ *
+ * Provides commonly used validation patterns with proper type inference.
+ *
+ * @module schemas/common
+ */
+import { z } from 'zod';
+/**
+ * UUID v4 string schema
+ *
+ * @example
+ * ```typescript
+ * const id = uuidSchema.parse('123e4567-e89b-12d3-a456-426614174000');
+ * // id: string (validated UUID)
+ * ```
+ */
+export declare const uuidSchema: z.ZodString;
+/**
+ * Email address schema
+ */
+export declare const emailSchema: z.ZodString;
+/**
+ * Non-empty string schema
+ */
+export declare const nonEmptyStringSchema: z.ZodString;
+/**
+ * URL string schema
+ */
+export declare const urlSchema: z.ZodString;
+/**
+ * ISO 8601 datetime string schema
+ */
+export declare const datetimeSchema: z.ZodString;
+/**
+ * Generic ID parameter schema (UUID)
+ * Commonly used for route parameters like `/users/:id`
+ */
+export declare const idParamSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+/**
+ * Type for id parameter objects
+ */
+export type IdParam = z.infer<typeof idParamSchema>;
+/**
+ * Creates an ID schema that accepts either UUID or integer string
+ *
+ * @param type - Type of ID to accept ('uuid' | 'integer' | 'string')
+ * @returns Zod schema for the specified ID type
+ */
+export declare function createIdSchema<T extends 'uuid' | 'integer' | 'string'>(type: T): T extends 'uuid' ? typeof uuidSchema : T extends 'integer' ? z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber> : z.ZodString;
+/**
+ * Timestamp fields commonly added to database records
+ */
+export declare const timestampFieldsSchema: z.ZodObject<{
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+}, "strip", z.ZodTypeAny, {
+    createdAt: Date;
+    updatedAt: Date;
+}, {
+    createdAt: Date;
+    updatedAt: Date;
+}>;
+/**
+ * Type for timestamp fields
+ */
+export type TimestampFields = z.infer<typeof timestampFieldsSchema>;
+/**
+ * Base entity schema with ID and timestamps
+ */
+export declare const baseEntitySchema: z.ZodObject<{
+    id: z.ZodString;
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+}, {
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+}>;
+/**
+ * Type for base entity
+ */
+export type BaseEntity = z.infer<typeof baseEntitySchema>;
+/**
+ * Makes all fields in a schema optional
+ *
+ * @param schema - Zod object schema
+ * @returns Schema with all fields optional
+ *
+ * @example
+ * ```typescript
+ * const UpdateUserSchema = makePartial(UserSchema);
+ * // All fields are now optional
+ * ```
+ */
+export declare function makePartial<T extends z.ZodRawShape>(schema: z.ZodObject<T>): z.ZodObject<{
+    [K in keyof T]: z.ZodOptional<T[K]>;
+}>;
+/**
+ * Makes specific fields required in a partial schema
+ *
+ * @param schema - Zod object schema
+ * @param keys - Array of keys to make required
+ * @returns Schema with specified fields required, others optional
+ *
+ * @example
+ * ```typescript
+ * const UpdateUserSchema = partialExcept(UserSchema, ['id'] as const);
+ * // id is required, all other fields are optional
+ * ```
+ */
+export declare function partialExcept<T extends z.ZodRawShape, K extends keyof T & string>(schema: z.ZodObject<T>, keys: readonly K[]): z.ZodObject<{
+    [P in K]: T[P];
+} & {
+    [P in Exclude<keyof T, K>]: z.ZodOptional<T[P]>;
+}>;
+/**
+ * Omits specified fields from a schema
+ *
+ * @param schema - Zod object schema
+ * @param keys - Array of keys to omit
+ * @returns Schema without the specified fields
+ *
+ * @example
+ * ```typescript
+ * const UserWithoutPassword = omitFields(UserSchema, ['password'] as const);
+ * ```
+ */
+export declare function omitFields<T extends z.ZodRawShape, K extends keyof T & string>(schema: z.ZodObject<T>, keys: readonly K[]): z.ZodObject<Omit<T, K>>;
+/**
+ * Picks specified fields from a schema
+ *
+ * @param schema - Zod object schema
+ * @param keys - Array of keys to pick
+ * @returns Schema with only the specified fields
+ *
+ * @example
+ * ```typescript
+ * const UserIdAndName = pickFields(UserSchema, ['id', 'name'] as const);
+ * ```
+ */
+export declare function pickFields<T extends z.ZodRawShape, K extends keyof T & string>(schema: z.ZodObject<T>, keys: readonly K[]): z.ZodObject<Pick<T, K>>;
+/**
+ * String that coerces to boolean
+ * Accepts 'true', '1', 'yes' as true; 'false', '0', 'no' as false
+ */
+export declare const booleanStringSchema: z.ZodPipeline<z.ZodEffects<z.ZodString, boolean | undefined, string>, z.ZodBoolean>;
+/**
+ * String that coerces to number
+ * Useful for query parameters
+ */
+export declare const numberStringSchema: z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber>;
+/**
+ * String that coerces to integer
+ * Useful for pagination parameters
+ */
+export declare const integerStringSchema: z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber>;
+//# sourceMappingURL=common.d.ts.map

package/dist/schemas/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/schemas/common.ts"],"names":[],"mappings":"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"}

package/dist/schemas/common.js

@@ -0,0 +1,211 @@
+/**
+ * Common schema utilities and pre-built schemas
+ *
+ * Provides commonly used validation patterns with proper type inference.
+ *
+ * @module schemas/common
+ */
+import { z } from 'zod';
+// ============================================================================
+// Common String Schemas
+// ============================================================================
+/**
+ * UUID v4 string schema
+ *
+ * @example
+ * ```typescript
+ * const id = uuidSchema.parse('123e4567-e89b-12d3-a456-426614174000');
+ * // id: string (validated UUID)
+ * ```
+ */
+export const uuidSchema = z.string().uuid();
+/**
+ * Email address schema
+ */
+export const emailSchema = z.string().email();
+/**
+ * Non-empty string schema
+ */
+export const nonEmptyStringSchema = z.string().min(1);
+/**
+ * URL string schema
+ */
+export const urlSchema = z.string().url();
+/**
+ * ISO 8601 datetime string schema
+ */
+export const datetimeSchema = z.string().datetime();
+// ============================================================================
+// Common ID Schemas
+// ============================================================================
+/**
+ * Generic ID parameter schema (UUID)
+ * Commonly used for route parameters like `/users/:id`
+ */
+export const idParamSchema = z.object({
+    id: uuidSchema,
+});
+/**
+ * Creates an ID schema that accepts either UUID or integer string
+ *
+ * @param type - Type of ID to accept ('uuid' | 'integer' | 'string')
+ * @returns Zod schema for the specified ID type
+ */
+export function createIdSchema(type) {
+    switch (type) {
+        case 'uuid':
+            return uuidSchema;
+        case 'integer':
+            return z
+                .string()
+                .transform((val) => parseInt(val, 10))
+                .pipe(z.number().int().positive());
+        default:
+            return z.string().min(1);
+    }
+}
+// ============================================================================
+// Common Object Schemas
+// ============================================================================
+/**
+ * Timestamp fields commonly added to database records
+ */
+export const timestampFieldsSchema = z.object({
+    createdAt: z.coerce.date(),
+    updatedAt: z.coerce.date(),
+});
+/**
+ * Base entity schema with ID and timestamps
+ */
+export const baseEntitySchema = z.object({
+    id: uuidSchema,
+    createdAt: z.coerce.date(),
+    updatedAt: z.coerce.date(),
+});
+// ============================================================================
+// Schema Composition Utilities
+// ============================================================================
+/**
+ * Makes all fields in a schema optional
+ *
+ * @param schema - Zod object schema
+ * @returns Schema with all fields optional
+ *
+ * @example
+ * ```typescript
+ * const UpdateUserSchema = makePartial(UserSchema);
+ * // All fields are now optional
+ * ```
+ */
+export function makePartial(schema) {
+    return schema.partial();
+}
+/**
+ * Makes specific fields required in a partial schema
+ *
+ * @param schema - Zod object schema
+ * @param keys - Array of keys to make required
+ * @returns Schema with specified fields required, others optional
+ *
+ * @example
+ * ```typescript
+ * const UpdateUserSchema = partialExcept(UserSchema, ['id'] as const);
+ * // id is required, all other fields are optional
+ * ```
+ */
+export function partialExcept(schema, keys) {
+    const shape = schema.shape;
+    const requiredKeys = new Set(keys);
+    const newShape = {};
+    for (const key in shape) {
+        if (requiredKeys.has(key)) {
+            newShape[key] = shape[key];
+        }
+        else {
+            newShape[key] = shape[key].optional();
+        }
+    }
+    return z.object(newShape);
+}
+/**
+ * Omits specified fields from a schema
+ *
+ * @param schema - Zod object schema
+ * @param keys - Array of keys to omit
+ * @returns Schema without the specified fields
+ *
+ * @example
+ * ```typescript
+ * const UserWithoutPassword = omitFields(UserSchema, ['password'] as const);
+ * ```
+ */
+export function omitFields(schema, keys) {
+    // Build the omit mask manually to avoid Zod's strict typing
+    const shape = schema.shape;
+    const keysToOmit = new Set(keys);
+    const newShape = {};
+    for (const key in shape) {
+        if (!keysToOmit.has(key)) {
+            newShape[key] = shape[key];
+        }
+    }
+    return z.object(newShape);
+}
+/**
+ * Picks specified fields from a schema
+ *
+ * @param schema - Zod object schema
+ * @param keys - Array of keys to pick
+ * @returns Schema with only the specified fields
+ *
+ * @example
+ * ```typescript
+ * const UserIdAndName = pickFields(UserSchema, ['id', 'name'] as const);
+ * ```
+ */
+export function pickFields(schema, keys) {
+    // Build the pick mask manually to avoid Zod's strict typing
+    const shape = schema.shape;
+    const newShape = {};
+    for (const key of keys) {
+        if (key in shape) {
+            newShape[key] = shape[key];
+        }
+    }
+    return z.object(newShape);
+}
+// ============================================================================
+// Coercion Utilities
+// ============================================================================
+/**
+ * String that coerces to boolean
+ * Accepts 'true', '1', 'yes' as true; 'false', '0', 'no' as false
+ */
+export const booleanStringSchema = z
+    .string()
+    .transform((val) => {
+    const lower = val.toLowerCase();
+    if (['true', '1', 'yes'].includes(lower))
+        return true;
+    if (['false', '0', 'no'].includes(lower))
+        return false;
+    return undefined;
+})
+    .pipe(z.boolean());
+/**
+ * String that coerces to number
+ * Useful for query parameters
+ */
+export const numberStringSchema = z
+    .string()
+    .transform((val) => Number(val))
+    .pipe(z.number());
+/**
+ * String that coerces to integer
+ * Useful for pagination parameters
+ */
+export const integerStringSchema = z
+    .string()
+    .transform((val) => parseInt(val, 10))
+    .pipe(z.number().int());
+//# sourceMappingURL=common.js.map

package/dist/schemas/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/schemas/common.ts"],"names":[],"mappings":"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"}

package/dist/schemas/pagination.d.ts

@@ -0,0 +1,287 @@
+/**
+ * Pagination schema utilities
+ *
+ * Provides standardized pagination input/output schemas for list endpoints.
+ *
+ * @module schemas/pagination
+ */
+import { z } from 'zod';
+/**
+ * Default pagination configuration
+ */
+export declare const PAGINATION_DEFAULTS: {
+    /** Default page number */
+    readonly page: 1;
+    /** Default items per page */
+    readonly limit: 20;
+    /** Maximum allowed items per page */
+    readonly maxLimit: 100;
+};
+/**
+ * Creates a pagination input schema with configurable defaults
+ *
+ * @param options - Pagination configuration options
+ * @returns Zod schema for pagination input
+ *
+ * @example
+ * ```typescript
+ * // Use defaults
+ * const PaginationSchema = createPaginationSchema();
+ *
+ * // Custom configuration
+ * const CustomPaginationSchema = createPaginationSchema({
+ *   defaultLimit: 10,
+ *   maxLimit: 50,
+ * });
+ * ```
+ */
+export declare function createPaginationSchema(options?: {
+    defaultPage?: number;
+    defaultLimit?: number;
+    maxLimit?: number;
+}): z.ZodObject<{
+    /** Current page number (1-indexed) */
+    page: z.ZodDefault<z.ZodNumber>;
+    /** Number of items per page */
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    limit: number;
+}, {
+    page?: number | undefined;
+    limit?: number | undefined;
+}>;
+/**
+ * Default pagination input schema
+ *
+ * Accepts page (default 1) and limit (default 20, max 100)
+ */
+export declare const paginationInputSchema: z.ZodObject<{
+    /** Current page number (1-indexed) */
+    page: z.ZodDefault<z.ZodNumber>;
+    /** Number of items per page */
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    limit: number;
+}, {
+    page?: number | undefined;
+    limit?: number | undefined;
+}>;
+/**
+ * Type for pagination input
+ */
+export type PaginationInput = z.infer<typeof paginationInputSchema>;
+/**
+ * Pagination with cursor-based navigation
+ *
+ * For more efficient pagination of large datasets
+ */
+export declare const cursorPaginationSchema: z.ZodObject<{
+    /** Cursor for the current position */
+    cursor: z.ZodOptional<z.ZodString>;
+    /** Number of items to fetch */
+    limit: z.ZodDefault<z.ZodNumber>;
+    /** Direction to fetch (forward/backward from cursor) */
+    direction: z.ZodDefault<z.ZodEnum<["forward", "backward"]>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    direction: "forward" | "backward";
+    cursor?: string | undefined;
+}, {
+    limit?: number | undefined;
+    cursor?: string | undefined;
+    direction?: "forward" | "backward" | undefined;
+}>;
+/**
+ * Type for cursor-based pagination input
+ */
+export type CursorPaginationInput = z.infer<typeof cursorPaginationSchema>;
+/**
+ * Creates a paginated response schema for a given item schema
+ *
+ * @param itemSchema - Zod schema for individual items
+ * @returns Zod schema for paginated response
+ *
+ * @example
+ * ```typescript
+ * const UserSchema = z.object({ id: z.string(), name: z.string() });
+ * const PaginatedUsersSchema = createPaginatedResponseSchema(UserSchema);
+ *
+ * type PaginatedUsers = z.infer<typeof PaginatedUsersSchema>;
+ * // { data: User[]; meta: { page, limit, total, totalPages, hasMore } }
+ * ```
+ */
+export declare function createPaginatedResponseSchema<T extends z.ZodTypeAny>(itemSchema: T): z.ZodObject<{
+    /** Array of items for the current page */
+    data: z.ZodArray<T, "many">;
+    /** Pagination metadata */
+    meta: z.ZodObject<{
+        /** Current page number */
+        page: z.ZodNumber;
+        /** Items per page */
+        limit: z.ZodNumber;
+        /** Total number of items across all pages */
+        total: z.ZodNumber;
+        /** Total number of pages */
+        totalPages: z.ZodNumber;
+        /** Whether there are more pages after this one */
+        hasMore: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+        hasMore: boolean;
+    }, {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+        hasMore: boolean;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    data: T["_output"][];
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+        hasMore: boolean;
+    };
+}, {
+    data: T["_input"][];
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+        hasMore: boolean;
+    };
+}>;
+/**
+ * Type helper to infer paginated response type from item schema
+ */
+export type PaginatedResponse<T> = {
+    data: T[];
+    meta: PaginationMeta;
+};
+/**
+ * Pagination metadata type
+ */
+export interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+/**
+ * Creates a cursor-based paginated response schema
+ *
+ * @param itemSchema - Zod schema for individual items
+ * @returns Zod schema for cursor-paginated response
+ */
+export declare function createCursorPaginatedResponseSchema<T extends z.ZodTypeAny>(itemSchema: T): z.ZodObject<{
+    /** Array of items */
+    data: z.ZodArray<T, "many">;
+    /** Cursor pagination metadata */
+    meta: z.ZodObject<{
+        /** Cursor for the next page (null if no more) */
+        nextCursor: z.ZodNullable<z.ZodString>;
+        /** Cursor for the previous page (null if at start) */
+        prevCursor: z.ZodNullable<z.ZodString>;
+        /** Whether there are more items after this page */
+        hasMore: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        hasMore: boolean;
+        nextCursor: string | null;
+        prevCursor: string | null;
+    }, {
+        hasMore: boolean;
+        nextCursor: string | null;
+        prevCursor: string | null;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    data: T["_output"][];
+    meta: {
+        hasMore: boolean;
+        nextCursor: string | null;
+        prevCursor: string | null;
+    };
+}, {
+    data: T["_input"][];
+    meta: {
+        hasMore: boolean;
+        nextCursor: string | null;
+        prevCursor: string | null;
+    };
+}>;
+/**
+ * Type for cursor-paginated response
+ */
+export type CursorPaginatedResponse<T> = {
+    data: T[];
+    meta: CursorPaginationMeta;
+};
+/**
+ * Cursor pagination metadata type
+ */
+export interface CursorPaginationMeta {
+    nextCursor: string | null;
+    prevCursor: string | null;
+    hasMore: boolean;
+}
+/**
+ * Calculates pagination metadata from total count
+ *
+ * @param options - Pagination calculation options
+ * @returns Pagination metadata
+ *
+ * @example
+ * ```typescript
+ * const meta = calculatePaginationMeta({
+ *   page: 2,
+ *   limit: 20,
+ *   total: 55,
+ * });
+ * // { page: 2, limit: 20, total: 55, totalPages: 3, hasMore: true }
+ * ```
+ */
+export declare function calculatePaginationMeta(options: {
+    page: number;
+    limit: number;
+    total: number;
+}): PaginationMeta;
+/**
+ * Calculates offset for database queries
+ *
+ * @param page - Current page number (1-indexed)
+ * @param limit - Items per page
+ * @returns Offset for database skip
+ *
+ * @example
+ * ```typescript
+ * const offset = calculateOffset(3, 20);
+ * // offset = 40 (skip first 40 items for page 3)
+ * ```
+ */
+export declare function calculateOffset(page: number, limit: number): number;
+/**
+ * Creates a paginated response from items and total count
+ *
+ * @param items - Array of items for current page
+ * @param pagination - Pagination input parameters
+ * @param total - Total count of items
+ * @returns Paginated response object
+ *
+ * @example
+ * ```typescript
+ * const users = await db.user.findMany({ skip: 20, take: 20 });
+ * const total = await db.user.count();
+ *
+ * return createPaginatedResponse(users, { page: 2, limit: 20 }, total);
+ * ```
+ */
+export declare function createPaginatedResponse<T>(items: T[], pagination: PaginationInput, total: number): PaginatedResponse<T>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/schemas/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/schemas/pagination.ts"],"names":[],"mappings":"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"}