bguard 0.3.0 → 0.4.0

package/README.md

@@ -4,7 +4,82 @@
 
 ![Coveralls branch](https://img.shields.io/coverallsCoverage/github/NBlasko/bguard) ![npm](https://img.shields.io/npm/dt/bguard) ![Known Vulnerabilities](https://snyk.io/test/github/NBlasko/bguard/badge.svg)
 
-### Features
+Table of contents
+
+ * [Features](#h3_features)
+ * [Installation](#h3_installation)
+ * [Usage](#h3_usage)
+    * [Defining a Schema](#h4_usage_defining_a_schema)
+    * [Inferring TypeScript Types](#h4_usage_inferring_typescript_types)
+    * [Generating TypeScript Types with `codeGen`](#h4_usage_generating_typescript_types_with_codeGen)
+    * [Generating Named TypeScript Types with `codeGenWithName`](#h4_usage_generating_typescript_types_with_codeGenWithName)
+    * [Summary:](#h4_usage_summary)
+ * [Validating Data](#h3_validating_data)
+    * [`parse` Method](#h4_validating_data_parse)
+    * [`parseOrFail` Method](#h4_validating_data_parseOrFail)
+ * [Chaining Methods](#h3_chaining_methods)
+    * [nullable()](#h4_chaining_nullable)
+    * [optional()](#h4_chaining_optional)
+    * [id(value: string)](#h4_chaining_id)
+    * [description(value: string)](#h4_chaining_description)
+ * [Literals](#h3_literals)
+ * [Custom (Library Built-in) Assertions](#h3_custom_builtin_assertions)
+ * [Create Custom Assertions](#h3_create_custom_assertions)
+ * [Translation](#translation)
+    * [Using Translations](#h4_using_translation)
+    * [Common and Custom Translations](#common_and_custom_translations)
+
+ * [Built-in Custom Assert Documentation](#builtin_custom_assert_documentation) 
+
+     * [string](#assertdir_string)
+          * [atLeastOneDigit](#assert_atLeastOneDigit_string)
+          * [atLeastOneLowerChar](#assert_atLeastOneLowerChar_string)
+          * [atLeastOneSpecialChar](#assert_atLeastOneSpecialChar_string)
+          * [atLeastOneUpperChar](#assert_atLeastOneUpperChar_string)
+          * [contains](#assert_contains_string)
+          * [email](#assert_email_string)
+          * [endsWith](#assert_endsWith_string)
+          * [isValidDate](#assert_isValidDate_string)
+          * [isValidDateTime](#assert_isValidDateTime_string)
+          * [isValidTime](#assert_isValidTime_string)
+          * [lowerCase](#assert_lowerCase_string)
+          * [maxLength](#assert_maxLength_string)
+          * [minLength](#assert_minLength_string)
+          * [regExp](#assert_regExp_string)
+          * [startsWith](#assert_startsWith_string)
+          * [upperCase](#assert_upperCase_string)
+          * [uuid](#assert_uuid_string)
+          * [uuidV1](#assert_uuidV1_string)
+          * [uuidV2](#assert_uuidV2_string)
+          * [uuidV3](#assert_uuidV3_string)
+          * [uuidV4](#assert_uuidV4_string)
+          * [uuidV5](#assert_uuidV5_string)
+          * [validUrl](#assert_validUrl_string)
+     * [number](#assertdir_number)
+          * [max](#assert_max_number)
+          * [maxExcluded](#assert_maxExcluded_number)
+          * [min](#assert_min_number)
+          * [minExcluded](#assert_minExcluded_number)
+          * [negative](#assert_negative_number)
+          * [positive](#assert_positive_number)
+     * [array](#assertdir_array)
+          * [maxArrayLength](#assert_maxArrayLength_array)
+          * [minArrayLength](#assert_minArrayLength_array)
+     * [bigint](#assertdir_bigint)
+          * [bigintMax](#assert_bigintMax_bigint)
+          * [bigintMaxExcluded](#assert_bigintMaxExcluded_bigint)
+          * [bigintMin](#assert_bigintMin_bigint)
+          * [bigintMinExcluded](#assert_bigintMinExcluded_bigint)
+     * [date](#assertdir_date)
+          * [dateMax](#assert_dateMax_date)
+          * [dateMin](#assert_dateMin_date)
+     * [mix](#assertdir_mix)
+          * [equalTo](#assert_equalTo_mix)
+          * [oneOfValues](#assert_oneOfValues_mix)
+     * [object](#assertdir_object)
+          * [maxKeys](#assert_maxKeys_object)
+
+### <a id="h3_features"> Features </a>
 
 - **Type Inference**: Automatically infer TypeScript types from your validation schemas.
 - **Custom Assertions**: Add custom validation logic for your schemas.
@@ -14,17 +89,17 @@
 - **Small Bundle Size**: Each assertion is in its own file, minimizing your final bundle size.
 - **Lightweight**: No dependencies and optimized for performance.
 
-### Installation
+### <a id="h3_installation"> Installation </a>
 
 ```bash
 npm install bguard
 ```
 
-### Usage
+### <a id="h3_usage"> Usage </a>
 
 Here’s a basic example of how to use `bguard` to define and validate a schema.
 
-#### Defining a Schema
+#### <a id="h4_usage_defining_a_schema"> Defining a Schema </a>
 
 Let's define a schema for a Student object:
 
@@ -57,7 +132,7 @@ const studentSchema = object({
 
 ```
 
-#### Inferring TypeScript Types
+#### <a id="h4_usage_inferring_typescript_types"> Inferring TypeScript Types </a>
 
 Using the InferType utility, you can infer the TypeScript type of the schema:
 
@@ -83,7 +158,7 @@ type StudentSchema = {
 
 ```
 
-#### Generating TypeScript Types with `codeGen`
+#### <a id="h4_usage_generating_typescript_types_with_codeGen"> Generating TypeScript Types with `codeGen` </a>
 
 If you prefer to generate TypeScript types as a string, you can use the `codeGen` function:
 
@@ -118,7 +193,7 @@ This would output a string:
 
 > **Notice:** The returned string does not include a type name or the `=` symbol. You would need to add these manually if you want a complete type definition.
 
-#### Generating Named TypeScript Types with `codeGenWithName`
+#### <a id="h4_usage_generating_typescript_types_with_codeGenWithName"> Generating Named TypeScript Types with `codeGenWithName` </a>
 
 For convenience, if you want to generate a complete type definition including a name, use the `codeGenWithName` function:
 
@@ -150,14 +225,13 @@ type StudentSchema = {
   verified?: boolean | undefined;
 }
 ```
-
-#### Summary:
+#### <a id="h4_usage_summary"> Summary: </a>
 
 `codeGen(schema: CommonSchema): string` - Generates a string of the TypeScript type based on the schema. You need to manually add a type name and assignment if needed.
 
 `codeGenWithName(typeName: string, schema: CommonSchema): string` - Generates a complete TypeScript type definition string, including the type keyword and type name.
 
-### Validating Data
+### <a id="h3_validating_data"> Validating Data </a>
 
 This library provides two methods to parse data against schemas: `parse` and `parseOrFail`. These methods help in validating the data and obtaining structured errors if any issues are found during validation.
 
@@ -193,7 +267,7 @@ const invalidStudentData = {
 };
 ```
 
-#### `parse` Method
+#### <a id="h4_validating_data_parse"> `parse` Method </a>
 
 The `parse` method validates the data and returns a tuple containing errors and the parsed value. This method allows you to choose whether to collect all errors or stop at the first error using an options flag.
 
@@ -216,7 +290,7 @@ Options:
 - `lng`: Specifies the language for error messages. Default is `'default'`.
 - `getAllErrors`: If `true`, collects all validation errors. If `false` or `undefined`, stops at the first error. Turning off `getAllErrors` provides a runtime optimization, as it stops validation at the first error, avoiding unnecessary checks for the remaining received value.
 
-#### `parseOrFail` Method
+#### <a id="h4_validating_data_parseOrFail"> `parseOrFail` Method </a>
 
 The `parseOrFail` method validates the data and throws an error on the first validation failure. It is useful when you want to halt processing immediately upon encountering an error.
 
@@ -244,8 +318,6 @@ Options:
 
 - `lng`: Specifies the language for error messages. Default is `'default'`.
 
-####
-
 Explanation
 
 - **`parse` Method**: This method returns a tuple where the first element is an array of validation errors (if any), and the second element is the successfully parsed value (or `undefined` if errors exist). It allows collecting all errors by setting the `getAllErrors` flag.
@@ -254,11 +326,31 @@ Explanation
 
 - **Options**: Both methods accept options for language settings and error collection, enhancing flexibility in handling validation processes.
 
-### Chaining Methods
+### <a id="h3_chaining_methods"> Chaining Methods </a>
+
+#### <a id="h4_chaining_nullable"> nullable() </a>
+
+Allows the value to be `null`.
+
+Example:
+
+```typeScript
+const nullableSchema = string().nullable().optional();
+// This schema allows string or null values.
+```
+
+#### <a id="h4_chaining_optional"> optional() </a>
+Allows the value to be `undefined`.
+
+_Example_:
+
+```typeScript
+const optionalSchema = string().nullable().optional();
+// This schema allows string or undefined values.
+```
 
-- `nullable()`: Allows the value to be `null`.
-- `optional()`: Allows the value to be `undefined`.
-- `default(value: unknown)`: Sets a default value if the received value is `undefined`.
+#### <a id="h4_chaining_default"> default(value: InferType<this>)</a>
+Sets a default value if the received value is `undefined`. The default value must match the inferred type of the schema, ensuring compatibility.
 
 
 > **Notice:** You cannot chain `default()` and `optional()` together, as they are contradictory. The `optional()` method allows the value to be `undefined`, while the `default()` method assigns a value if `undefined`. Attempting to chain both will throw a `BuildSchemaError` with the message: `"Cannot call method 'default' after method 'optional'"`.
@@ -266,8 +358,7 @@ Explanation
 
 > **Notice:** Additionally, `default()` must be the last method in the chain because it validates during schema build time that the default value is compatible with the rest of the schema. For example, if the schema is `number()`, the default value cannot be a `string`.
 
-
-Example:
+_Example_:
 
 ```typeScript
 const schemaWithDefault = string().nullable().default('defaultString'); 
@@ -276,20 +367,76 @@ const schemaWithDefault = string().nullable().default('defaultString');
 const optionalSchema = string().nullable().optional();
 // This schema allows both null and undefined values, but it does not provide a default value.
 ```
+#### <a id="h4_chaining_id"> id(value: string) </a> 
+
+Assigns a unique identifier to the schema, useful for tracking or mapping validation errors. The `id` can be accessed via `err.meta?.id` in case of a validation error.
+
+#### <a id="h4_chaining_description"> description(value: string) </a> 
+
+Provides a description for the schema, which can be used to give more context about the validation error. The `description` can be accessed via `err.meta?.description` in case of a validation error.
+
+_Example_:
+
+```typeScript
+const addressSchema = string()
+  .id('address')
+  .description('Users address');
+// This schema validates that string and assigns an ID and description for better error handling.
+
+try {
+  parseOrFail(addressSchema, undefined);
+} catch (e) {
+  const err = e as ValidationError;
+  console.log(err.message);  // Output: 'The required value is missing'
+  console.log(err.pathToError);  // Output: ''
+  console.log(err.meta?.id);  // Output:  'address'
+  console.log(err.meta?.description);  // Output: 'Users address'
+}
+```
+#### <a id="h4_chaining_transformbeforevalidation"> transformBeforeValidation\<In\>(cb: TransformCallback<In, InferType\<Schema>\>) </a>
+
+This method allows you to apply a transformation to the input value before any validation occurs. The transformation is applied before the schema's other methods (like `nullable`, `custom`, etc.). The callback function can receive an input of type `unknown` by default, but you can specify the type if you know it, such as `string`. The return value of the callback must be of the same type as the inferred type of the schema, ensuring that the overall type does not change.
+
+<b>Order of Execution</b>: 
+First, transformations specified using transformBeforeValidation are applied.
+Then, the schema checks for null or undefined based on methods like `nullable` or `optional`.
+Finally, the `custom` validations and type checks are performed.
+
+This method is particularly useful for normalizing or preparing data before validation, such as trimming whitespace, converting empty strings to null, or handling other preprocessing needs.
+
+> **Notice:** Like default, `transformBeforeValidation` should be placed at the end of the chain. This ensures that the transformation is correctly applied after all other type checks are resolved, preserving the expected type.
 
-- String Literals:
+_Example_:
+
+```typescript
+const stringOrNullSchema = string()
+  .nullable()
+  .custom(minLength(3))
+  .transformBeforeValidation((val) => val + '') // First, transform value to a string
+  .transformBeforeValidation((val: string) => (val === '' ? null : val)); // Second, convert empty strings to null
+
+// Parsing 'test' will pass as 'test' is a valid string longer than 3 characters.
+parseOrFail(stringOrNullSchema, 'test');
+
+// Parsing '' will be transformed to null and will pass due to .nullable().
+parseOrFail(stringOrNullSchema, '');
+```
+
+### <a id="h3_literals"> Literals </a>
+
+- <b>String Literals</b>:
   `string().equalTo('myStringValue')` will infer <b>'myStringValue'</b> as the type.
   `string().oneOfValues(['foo', 'bar'])` will infer <b>'foo' | 'bar'</b> as the type.
 
-- Number Literals:
+- <b>Number Literals</b>:
   `number().equalTo(42)` will infer <b>42</b> as the type.
   `number().oneOfValues([3, 5])` will infer <b>3 | 5</b> as the type.
 
-- Boolean Literals:
+- <b>Boolean Literals</b>:
   `boolean().onlyTrue()` will infer <b>true</b> as the type.
   `boolean().onlyFalse()` will infer <b>false</b> as the type.
 
-### Custom (Library Built-in) Assertions
+### <a id="h3_custom_builtin_assertions"> Custom (Library Built-in) Assertions </a>
 
 The `custom` method allows you to extend the validation schema with additional asserts. These asserts can either be user-defined or selected from the comprehensive set provided by the library. This flexibility ensures that you can tailor validations to meet specific requirements beyond the standard methods available.
 All built-in asserts are documented in the [Built-in Custom Assert Documentation](#builtin_custom_assert_documentation) section.
@@ -305,7 +452,7 @@ const ageSchema = number().custom(min(18), max(120));
 
 Library built-in assertions are imported from specific paths for better tree-shaking and smaller bundle sizes.
 
-### Create Custom Assertions
+### <a id="h3_create_custom_assertions"> Create Custom Assertions </a>
 
 Bguard allows developers to create custom validation functions that can be integrated seamlessly with the library's existing functionality. Below is a detailed example demonstrating how to create a custom validation function, `minLength`, and how to properly document and map error messages for translations.
 
@@ -349,7 +496,7 @@ Explanation
   3. The `minLengthErrorMessage` serves as the default message. If you want to provide translations, you can do so by mapping the error key in the translationMap.
      For single-language applications, you can override the default message by directly passing your custom message to `guardException`.
 
-### Translation {#translation}
+### <a id="translation"> Translation </a>
 
 Bguard provides default translations for error messages, but you can customize them as needed. Each potential error has an `errorKey` and `errorMessage`.
 
@@ -389,7 +536,7 @@ With this setup, in the translation namespace 'SR', if the received value is 4,
 
 > **Notice:** Do not overwrite the 'default' namespace. If a translation is missing, it will fall back to the 'default' translation.
 
-#### Using Translations
+#### <a id="h4_using_translation"> Using Translations </a>
 
 To apply the new translation, both `parse` and `parseOrFail` functions accept a lng property in the options object provided as the third parameter:
 
@@ -399,7 +546,7 @@ parseOrFail(testSchema, { foo: 4 }, { lng: 'SR' });
 parse(testSchema, { foo: 4 }, { lng: 'SR' });
 ```
 
-#### Common and Custom Translations {#common_and_custom_translations}
+#### <a id="common_and_custom_translations"> Common and Custom Translations </a>
 
 We have two sets of translations: common errors and specific assertions.
 
@@ -462,56 +609,9 @@ console.log(maxLength.message); // Output: 'The received value length is greater
 
 <b>3.</b> IDE Support:
 Each key and message will be visible in text editors that support JSDoc IntelliSense.
+### <a id="builtin_custom_assert_documentation"> Built-in Custom Assert Documentation </a> 
 
-### Built-in Custom Assert Documentation {#builtin_custom_assert_documentation} 
-
- * [string](#assertdir_string)
-    * [atLeastOneDigit](#assert_atLeastOneDigit_string)
-    * [atLeastOneLowerChar](#assert_atLeastOneLowerChar_string)
-    * [atLeastOneSpecialChar](#assert_atLeastOneSpecialChar_string)
-    * [atLeastOneUpperChar](#assert_atLeastOneUpperChar_string)
-    * [contains](#assert_contains_string)
-    * [email](#assert_email_string)
-    * [endsWith](#assert_endsWith_string)
-    * [isValidDate](#assert_isValidDate_string)
-    * [isValidDateTime](#assert_isValidDateTime_string)
-    * [isValidTime](#assert_isValidTime_string)
-    * [lowerCase](#assert_lowerCase_string)
-    * [maxLength](#assert_maxLength_string)
-    * [minLength](#assert_minLength_string)
-    * [regExp](#assert_regExp_string)
-    * [startsWith](#assert_startsWith_string)
-    * [upperCase](#assert_upperCase_string)
-    * [uuid](#assert_uuid_string)
-    * [uuidV1](#assert_uuidV1_string)
-    * [uuidV2](#assert_uuidV2_string)
-    * [uuidV3](#assert_uuidV3_string)
-    * [uuidV4](#assert_uuidV4_string)
-    * [uuidV5](#assert_uuidV5_string)
-    * [validUrl](#assert_validUrl_string)
- * [number](#assertdir_number)
-    * [max](#assert_max_number)
-    * [maxExcluded](#assert_maxExcluded_number)
-    * [min](#assert_min_number)
-    * [minExcluded](#assert_minExcluded_number)
-    * [negative](#assert_negative_number)
-    * [positive](#assert_positive_number)
- * [array](#assertdir_array)
-    * [maxArrayLength](#assert_maxArrayLength_array)
-    * [minArrayLength](#assert_minArrayLength_array)
- * [bigint](#assertdir_bigint)
-    * [bigintMax](#assert_bigintMax_bigint)
-    * [bigintMaxExcluded](#assert_bigintMaxExcluded_bigint)
-    * [bigintMin](#assert_bigintMin_bigint)
-    * [bigintMinExcluded](#assert_bigintMinExcluded_bigint)
- * [date](#assertdir_date)
-    * [dateMax](#assert_dateMax_date)
-    * [dateMin](#assert_dateMin_date)
- * [mix](#assertdir_mix)
-    * [equalTo](#assert_equalTo_mix)
-    * [oneOfValues](#assert_oneOfValues_mix)
-
-#### string {#assertdir_string}
+#### <a id="assertdir_string"> string </a>
    
  <b>Prerequisites</b>
    
@@ -528,7 +628,7 @@ import { string } from 'bguard/string';
 ```
    
         
-##### atLeastOneDigit (string) {#assert_atLeastOneDigit_string}
+##### <a id="assert_atLeastOneDigit_string"> atLeastOneDigit </a>
         
 ```typescript
 import { atLeastOneDigit } from 'bguard/string/atLeastOneDigit';
@@ -545,7 +645,7 @@ import { atLeastOneDigit } from 'bguard/string/atLeastOneDigit';
 * _See_ Error Translation Key = 's:atLeastOneDigit'
         
         
-##### atLeastOneLowerChar (string) {#assert_atLeastOneLowerChar_string}
+##### <a id="assert_atLeastOneLowerChar_string"> atLeastOneLowerChar </a>
         
 ```typescript
 import { atLeastOneLowerChar } from 'bguard/string/atLeastOneLowerChar';
@@ -562,7 +662,7 @@ import { atLeastOneLowerChar } from 'bguard/string/atLeastOneLowerChar';
 * _See_ Error Translation Key = 's:atLeastOneLowerChar'
         
         
-##### atLeastOneSpecialChar (string) {#assert_atLeastOneSpecialChar_string}
+##### <a id="assert_atLeastOneSpecialChar_string"> atLeastOneSpecialChar </a>
         
 ```typescript
 import { atLeastOneSpecialChar } from 'bguard/string/atLeastOneSpecialChar';
@@ -584,7 +684,7 @@ import { atLeastOneSpecialChar } from 'bguard/string/atLeastOneSpecialChar';
 * _See_ Error Translation Key = 's:atLeastOneSpecialChar'
         
         
-##### atLeastOneUpperChar (string) {#assert_atLeastOneUpperChar_string}
+##### <a id="assert_atLeastOneUpperChar_string"> atLeastOneUpperChar </a>
         
 ```typescript
 import { atLeastOneUpperChar } from 'bguard/string/atLeastOneUpperChar';
@@ -601,7 +701,7 @@ import { atLeastOneUpperChar } from 'bguard/string/atLeastOneUpperChar';
 * _See_ Error Translation Key = 's:atLeastOneUpperChar'
         
         
-##### contains (string) {#assert_contains_string}
+##### <a id="assert_contains_string"> contains </a>
         
 ```typescript
 import { contains } from 'bguard/string/contains';
@@ -619,7 +719,7 @@ import { contains } from 'bguard/string/contains';
 * _See_ Error Translation Key = 's:contains'
         
         
-##### email (string) {#assert_email_string}
+##### <a id="assert_email_string"> email </a>
         
 ```typescript
 import { email } from 'bguard/string/email';
@@ -636,7 +736,7 @@ import { email } from 'bguard/string/email';
 * _See_ - Error Translation Key = 's:email'
         
         
-##### endsWith (string) {#assert_endsWith_string}
+##### <a id="assert_endsWith_string"> endsWith </a>
         
 ```typescript
 import { endsWith } from 'bguard/string/endsWith';
@@ -654,7 +754,7 @@ import { endsWith } from 'bguard/string/endsWith';
 * _See_ Error Translation Key = 's:endsWith'
         
         
-##### isValidDate (string) {#assert_isValidDate_string}
+##### <a id="assert_isValidDate_string"> isValidDate </a>
         
 ```typescript
 import { isValidDate } from 'bguard/string/isValidDate';
@@ -672,7 +772,7 @@ import { isValidDate } from 'bguard/string/isValidDate';
 * _See_ Error Translation Key = 's:isValidDate'
         
         
-##### isValidDateTime (string) {#assert_isValidDateTime_string}
+##### <a id="assert_isValidDateTime_string"> isValidDateTime </a>
         
 ```typescript
 import { isValidDateTime } from 'bguard/string/isValidDateTime';
@@ -700,7 +800,7 @@ import { isValidDateTime } from 'bguard/string/isValidDateTime';
 * _See_ Error Translation Key = 's:isValidDateTime'
         
         
-##### isValidTime (string) {#assert_isValidTime_string}
+##### <a id="assert_isValidTime_string"> isValidTime </a>
         
 ```typescript
 import { isValidTime } from 'bguard/string/isValidTime';
@@ -723,7 +823,7 @@ import { isValidTime } from 'bguard/string/isValidTime';
 * _See_ Error Translation Key = 's:isValidTime'
         
         
-##### lowerCase (string) {#assert_lowerCase_string}
+##### <a id="assert_lowerCase_string"> lowerCase </a>
         
 ```typescript
 import { lowerCase } from 'bguard/string/lowerCase';
@@ -740,7 +840,7 @@ import { lowerCase } from 'bguard/string/lowerCase';
 * _See_ Error Translation Key = 's:lowerCase'
         
         
-##### maxLength (string) {#assert_maxLength_string}
+##### <a id="assert_maxLength_string"> maxLength </a>
         
 ```typescript
 import { maxLength } from 'bguard/string/maxLength';
@@ -758,7 +858,7 @@ import { maxLength } from 'bguard/string/maxLength';
 * _See_ Error Translation Key = 's:maxLength'
         
         
-##### minLength (string) {#assert_minLength_string}
+##### <a id="assert_minLength_string"> minLength </a>
         
 ```typescript
 import { minLength } from 'bguard/string/minLength';
@@ -776,7 +876,7 @@ import { minLength } from 'bguard/string/minLength';
 * _See_ Error Translation Key = 's:minLength'
         
         
-##### regExp (string) {#assert_regExp_string}
+##### <a id="assert_regExp_string"> regExp </a>
         
 ```typescript
 import { regExp } from 'bguard/string/regExp';
@@ -794,7 +894,7 @@ import { regExp } from 'bguard/string/regExp';
 * _See_ Error Translation Key = 's:regExp'
         
         
-##### startsWith (string) {#assert_startsWith_string}
+##### <a id="assert_startsWith_string"> startsWith </a>
         
 ```typescript
 import { startsWith } from 'bguard/string/startsWith';
@@ -812,7 +912,7 @@ import { startsWith } from 'bguard/string/startsWith';
 * _See_ Error Translation Key = 's:startsWith'
         
         
-##### upperCase (string) {#assert_upperCase_string}
+##### <a id="assert_upperCase_string"> upperCase </a>
         
 ```typescript
 import { upperCase } from 'bguard/string/upperCase';
@@ -830,7 +930,7 @@ import { upperCase } from 'bguard/string/upperCase';
 * _See_ Error Translation Key = 's:upperCase'
         
         
-##### uuid (string) {#assert_uuid_string}
+##### <a id="assert_uuid_string"> uuid </a>
         
 ```typescript
 import { uuid } from 'bguard/string/uuid';
@@ -847,7 +947,7 @@ import { uuid } from 'bguard/string/uuid';
 * _See_ Error Translation Key = 's:uuid'
         
         
-##### uuidV1 (string) {#assert_uuidV1_string}
+##### <a id="assert_uuidV1_string"> uuidV1 </a>
         
 ```typescript
 import { uuidV1 } from 'bguard/string/uuidV1';
@@ -865,7 +965,7 @@ import { uuidV1 } from 'bguard/string/uuidV1';
 * _See_ Error Translation Key = 's:uuidV1'
         
         
-##### uuidV2 (string) {#assert_uuidV2_string}
+##### <a id="assert_uuidV2_string"> uuidV2 </a>
         
 ```typescript
 import { uuidV2 } from 'bguard/string/uuidV2';
@@ -883,7 +983,7 @@ import { uuidV2 } from 'bguard/string/uuidV2';
 * _See_ Error Translation Key = 's:uuidV2'
         
         
-##### uuidV3 (string) {#assert_uuidV3_string}
+##### <a id="assert_uuidV3_string"> uuidV3 </a>
         
 ```typescript
 import { uuidV3 } from 'bguard/string/uuidV3';
@@ -901,7 +1001,7 @@ import { uuidV3 } from 'bguard/string/uuidV3';
 * _See_ Error Translation Key = 's:uuidV3'
         
         
-##### uuidV4 (string) {#assert_uuidV4_string}
+##### <a id="assert_uuidV4_string"> uuidV4 </a>
         
 ```typescript
 import { uuidV4 } from 'bguard/string/uuidV4';
@@ -921,7 +1021,7 @@ import { uuidV4 } from 'bguard/string/uuidV4';
 * _See_ Error Translation Key = 's:uuidV4'
         
         
-##### uuidV5 (string) {#assert_uuidV5_string}
+##### <a id="assert_uuidV5_string"> uuidV5 </a>
         
 ```typescript
 import { uuidV5 } from 'bguard/string/uuidV5';
@@ -939,7 +1039,7 @@ import { uuidV5 } from 'bguard/string/uuidV5';
 * _See_ Error Translation Key = 's:uuidV5'
         
         
-##### validUrl (string) {#assert_validUrl_string}
+##### <a id="assert_validUrl_string"> validUrl </a>
         
 ```typescript
 import { validUrl } from 'bguard/string/validUrl';
@@ -958,7 +1058,7 @@ import { validUrl } from 'bguard/string/validUrl';
 ```
 * _See_ Error Translation Key = 's:url'
         
-#### number {#assertdir_number}
+#### <a id="assertdir_number"> number </a>
    
  <b>Prerequisites</b>
    
@@ -975,7 +1075,7 @@ import { number } from 'bguard/number';
 ```
    
         
-##### max (number) {#assert_max_number}
+##### <a id="assert_max_number"> max </a>
         
 ```typescript
 import { max } from 'bguard/number/max';
@@ -994,7 +1094,7 @@ import { max } from 'bguard/number/max';
 * _See_ Error Translation Key = 'n:max'
         
         
-##### maxExcluded (number) {#assert_maxExcluded_number}
+##### <a id="assert_maxExcluded_number"> maxExcluded </a>
         
 ```typescript
 import { maxExcluded } from 'bguard/number/maxExcluded';
@@ -1013,7 +1113,7 @@ import { maxExcluded } from 'bguard/number/maxExcluded';
 * _See_ Error Translation Key = 'n:maxExcluded'
         
         
-##### min (number) {#assert_min_number}
+##### <a id="assert_min_number"> min </a>
         
 ```typescript
 import { min } from 'bguard/number/min';
@@ -1032,7 +1132,7 @@ import { min } from 'bguard/number/min';
 * _See_ Error Translation Key = 'n:min'
         
         
-##### minExcluded (number) {#assert_minExcluded_number}
+##### <a id="assert_minExcluded_number"> minExcluded </a>
         
 ```typescript
 import { minExcluded } from 'bguard/number/minExcluded';
@@ -1051,7 +1151,7 @@ import { minExcluded } from 'bguard/number/minExcluded';
 * _See_ Error Translation Key = 'n:minExcluded'
         
         
-##### negative (number) {#assert_negative_number}
+##### <a id="assert_negative_number"> negative </a>
         
 ```typescript
 import { negative } from 'bguard/number/negative';
@@ -1069,7 +1169,7 @@ import { negative } from 'bguard/number/negative';
 * _See_ - Error Translation Key = 'n:negative'
         
         
-##### positive (number) {#assert_positive_number}
+##### <a id="assert_positive_number"> positive </a>
         
 ```typescript
 import { positive } from 'bguard/number/positive';
@@ -1086,7 +1186,7 @@ import { positive } from 'bguard/number/positive';
 ```
 * _See_ Error Translation Key = 'n:positive'
         
-#### array {#assertdir_array}
+#### <a id="assertdir_array"> array </a>
    
  <b>Prerequisites</b>
    
@@ -1105,7 +1205,7 @@ import { array } from 'bguard/array';
 ```
    
         
-##### maxArrayLength (array) {#assert_maxArrayLength_array}
+##### <a id="assert_maxArrayLength_array"> maxArrayLength </a>
         
 ```typescript
 import { maxArrayLength } from 'bguard/array/maxArrayLength';
@@ -1124,7 +1224,7 @@ import { maxArrayLength } from 'bguard/array/maxArrayLength';
 * _See_ Error Translation Key = 'a:maxArrayLength'
         
         
-##### minArrayLength (array) {#assert_minArrayLength_array}
+##### <a id="assert_minArrayLength_array"> minArrayLength </a>
         
 ```typescript
 import { minArrayLength } from 'bguard/array/minArrayLength';
@@ -1142,7 +1242,7 @@ import { minArrayLength } from 'bguard/array/minArrayLength';
 ```
 * _See_ Error Translation Key = 'a:minArrayLength'
         
-#### bigint {#assertdir_bigint}
+#### <a id="assertdir_bigint"> bigint </a>
    
  <b>Prerequisites</b>
    
@@ -1160,7 +1260,7 @@ import { bigint } from 'bguard/bigint';
 ```
    
         
-##### bigintMax (bigint) {#assert_bigintMax_bigint}
+##### <a id="assert_bigintMax_bigint"> bigintMax </a>
         
 ```typescript
 import { bigintMax } from 'bguard/bigint/bigintMax';
@@ -1179,7 +1279,7 @@ import { bigintMax } from 'bguard/bigint/bigintMax';
 * _See_ Error Translation Key = 'bi:max'
         
         
-##### bigintMaxExcluded (bigint) {#assert_bigintMaxExcluded_bigint}
+##### <a id="assert_bigintMaxExcluded_bigint"> bigintMaxExcluded </a>
         
 ```typescript
 import { bigintMaxExcluded } from 'bguard/bigint/bigintMaxExcluded';
@@ -1198,7 +1298,7 @@ import { bigintMaxExcluded } from 'bguard/bigint/bigintMaxExcluded';
 * _See_ Error Translation Key = 'bi:maxExcluded'
         
         
-##### bigintMin (bigint) {#assert_bigintMin_bigint}
+##### <a id="assert_bigintMin_bigint"> bigintMin </a>
         
 ```typescript
 import { bigintMin } from 'bguard/bigint/bigintMin';
@@ -1217,7 +1317,7 @@ import { bigintMin } from 'bguard/bigint/bigintMin';
 * _See_ Error Translation Key = 'bi:min'
         
         
-##### bigintMinExcluded (bigint) {#assert_bigintMinExcluded_bigint}
+##### <a id="assert_bigintMinExcluded_bigint"> bigintMinExcluded </a>
         
 ```typescript
 import { bigintMinExcluded } from 'bguard/bigint/bigintMinExcluded';
@@ -1235,7 +1335,7 @@ import { bigintMinExcluded } from 'bguard/bigint/bigintMinExcluded';
 ```
 * _See_ Error Translation Key = 'bi:minExcluded'
         
-#### date {#assertdir_date}
+#### <a id="assertdir_date"> date </a>
    
  <b>Prerequisites</b>
    
@@ -1252,7 +1352,7 @@ import { date } from 'bguard/date';
 ```
    
         
-##### dateMax (date) {#assert_dateMax_date}
+##### <a id="assert_dateMax_date"> dateMax </a>
         
 ```typescript
 import { dateMax } from 'bguard/date/dateMax';
@@ -1271,7 +1371,7 @@ import { dateMax } from 'bguard/date/dateMax';
 * _See_ Error Translation Key = 'dt:max'
         
         
-##### dateMin (date) {#assert_dateMin_date}
+##### <a id="assert_dateMin_date"> dateMin </a>
         
 ```typescript
 import { dateMin } from 'bguard/date/dateMin';
@@ -1289,7 +1389,7 @@ import { dateMin } from 'bguard/date/dateMin';
 ```
 * _See_ Error Translation Key = 'dt:min'
         
-#### mix {#assertdir_mix}
+#### <a id="assertdir_mix"> mix </a>
    
  <b>Prerequisites</b>
    
@@ -1310,7 +1410,7 @@ import { oneOfTypes } from 'bguard/mix';
 ```
    
         
-##### equalTo (mix) {#assert_equalTo_mix}
+##### <a id="assert_equalTo_mix"> equalTo </a>
         
 ```typescript
 import { equalTo } from 'bguard/mix/equalTo';
@@ -1329,7 +1429,7 @@ import { equalTo } from 'bguard/mix/equalTo';
 * _See_ Error Translation Key = 'm:equalTo'
         
         
-##### oneOfValues (mix) {#assert_oneOfValues_mix}
+##### <a id="assert_oneOfValues_mix"> oneOfValues </a>
         
 ```typescript
 import { oneOfValues } from 'bguard/mix/oneOfValues';
@@ -1348,5 +1448,53 @@ import { oneOfValues } from 'bguard/mix/oneOfValues';
 ```
 * _See_ Error Translation Key = 'm:oneOfValues'
         
+#### <a id="assertdir_object"> object </a>
+   
+ <b>Prerequisites</b>
+   
+```typescript
+import { object } from 'bguard/object';
+```
+   
+* _Description_ Creates a new schema for validating objects where each property must match the specified schema.
+ 
+* _Param_ {T} shapeSchema - The schema that each property of the object must match.
+* _Example_
+```typescript
+ const schema = object({
+   name: string(),
+   age: number()
+ });
+ parseOrFail(schema, { name: 'John', age: 30 }); // Validates successfully
+ parseOrFail(schema, { name: 'John', age: '30' }); // Throws a validation error
+```
+   
+        
+##### <a id="assert_maxKeys_object"> maxKeys </a>
+        
+```typescript
+import { maxKeys } from 'bguard/object/maxKeys';
+```
+        
+* _Description_ Ensures that the object has no more than the specified number of keys.
+* _Param_ {number} expected - The maximum number of keys allowed in the object.
+* _Throws_ {ValidationError} if the number of the received keys is greater than the expected value.
+* _Example_
+```typescript
+ const schema = object({
+   name: string(),
+   email: string(),
+ })
+   .allowUnrecognized()
+   .custom(maxKeys(2));
+
+ // This will pass
+ parseOrFail(schema, { name: 'John', email: 'john@example.com' });
+
+ // This will throw an error because there are 3 keys
+ parseOrFail(schema, { name: 'John', email: 'john@example.com', address: '123 Main St' });
+```
+* _See_ Error Translation Key = 'o:maxKeys'
+        
 ### Contributing
-Contributions are welcome! Please open an issue or submit a pull request for any bugs or feature requests.
+Contributions are welcome! Please open an issue or submit a pull request for any bugs or feature requests.