chore: update docs and error mesasge

Author: pavadeli

etc/types.api.md

@@ -142,9 +142,9 @@ export const int: Type<Branded<number, 'int'>, NumberTypeConfig>;
 
 // @public (undocumented)
 export interface InterfaceMergeOptions {
-    ignoreParsers?: true;
-    ignoreValidations?: true;
     name?: string;
+    omitParsers?: true;
+    omitValidations?: true;
 }
 
 // @public
@@ -410,7 +410,7 @@ export type PropertiesOfTypeTuple<Tuple> = Tuple extends [{
 
 // @public
 export type PropertyInfo<T extends Type<unknown> = Type<unknown>> = {
-    partial: boolean;
+    optional: boolean;
     type: T;
 };
 

markdown/types.interfacemergeoptions.ignorevalidations.md

@@ -12,8 +12,8 @@ interface InterfaceMergeOptions
 
 ## Properties
 
-| Property                                                                 | Modifiers | Type   | Description                                                                                                 |
-| ------------------------------------------------------------------------ | --------- | ------ | ----------------------------------------------------------------------------------------------------------- |
-| [ignoreParsers?](./types.interfacemergeoptions.ignoreparsers.md)         |           | true   | _(Optional)_ Suppress the error about existing custom parsers on one of the types that is being merged.     |
-| [ignoreValidations?](./types.interfacemergeoptions.ignorevalidations.md) |           | true   | _(Optional)_ Suppress the error about existing custom validations on one of the types that is being merged. |
-| [name?](./types.interfacemergeoptions.name.md)                           |           | string | _(Optional)_ The optional name for the type, uses a default TypeScript-like name if no name is given.       |
+| Property                                                             | Modifiers | Type   | Description                                                                                              |
+| -------------------------------------------------------------------- | --------- | ------ | -------------------------------------------------------------------------------------------------------- |
+| [name?](./types.interfacemergeoptions.name.md)                       |           | string | _(Optional)_ The optional name for the type, uses a default TypeScript-like name if no name is given.    |
+| [omitParsers?](./types.interfacemergeoptions.omitparsers.md)         |           | true   | _(Optional)_ Suppress the error about existing custom parsers on one of the types that is being merged.  |
+| [omitValidations?](./types.interfacemergeoptions.omitvalidations.md) |           | true   | _(Optional)_ When set, do not apply the custom validations from the base types onto the new merged type. |

markdown/types.interfacemergeoptions.md

@@ -1,15 +1,15 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [@skunkteam/types](./types.md) &gt; [InterfaceMergeOptions](./types.interfacemergeoptions.md) &gt; [ignoreParsers](./types.interfacemergeoptions.ignoreparsers.md)
+[Home](./index.md) &gt; [@skunkteam/types](./types.md) &gt; [InterfaceMergeOptions](./types.interfacemergeoptions.md) &gt; [omitParsers](./types.interfacemergeoptions.omitparsers.md)
 
-## InterfaceMergeOptions.ignoreParsers property
+## InterfaceMergeOptions.omitParsers property
 
 Suppress the error about existing custom parsers on one of the types that is being merged.
 
 **Signature:**
 
 ```typescript
-ignoreParsers?: true;
+omitParsers?: true;
 ```
 
 ## Remarks

markdown/types.interfacemergeoptions.ignoreparsers.md renamed to markdown/types.interfacemergeoptions.omitparsers.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@skunkteam/types](./types.md) &gt; [InterfaceMergeOptions](./types.interfacemergeoptions.md) &gt; [omitValidations](./types.interfacemergeoptions.omitvalidations.md)
+
+## InterfaceMergeOptions.omitValidations property
+
+When set, do not apply the custom validations from the base types onto the new merged type.
+
+**Signature:**
+
+```typescript
+omitValidations?: true;
+```
+
+## Remarks
+
+By default, custom validations (i.e. validations that are added to a type using [withValidation](./types.basetypeimpl.withvalidation.md) or [withConstraint](./types.basetypeimpl.withconstraint.md)<!-- -->) are reused when merging multiple interface types using [withOptional](./types.interfacetype.withoptional.md)<!-- -->, [withRequired](./types.interfacetype.withrequired.md) and [mergeWith](./types.interfacetype.mergewith.md)<!-- -->. Use this option to omit all custom validations in the resulting merged type.
+
+Note that reuse of custom validations only works when no properties overlap between the types that are being merged. As long as the properties don't overlap we can be sure that the merged type is assignable to each of the original types (`A & B` is assignable to both `A` and `B`<!-- -->). Therefore, the validations are still safe to run, even though the type has been extended with additional properties.
+
+When overlap is detected in the property-names of the types and any custom validation is encountered by Skunk Team types, an Error will be thrown. Use this option to ignore the custom validations and continue with the merge.

markdown/types.interfacemergeoptions.omitvalidations.md

@@ -10,7 +10,7 @@ Information about a single property of an object-like type including its optiona
 
 ```typescript
 type PropertyInfo<T extends Type<unknown> = Type<unknown>> = {
-    partial: boolean;
+    optional: boolean;
     type: T;
 };
 ```

markdown/types.propertyinfo.md

@@ -168,7 +168,7 @@ describe(object, () => {
             const TypeA = object('TypeA', { prop: string }).withValidation(v => v.prop === 'the value');
             expect(() => TypeA.withRequired({ prop: number })).toThrowErrorMatchingInlineSnapshot(
                 '"Error in TypeA.withRequired(): Merge operation not allowed because one of the types has custom validations applied ' +
-                    'and the following property is defined on both sides: <prop>, use `omitValidations` to suppress this error or ' +
+                    'and the following property is defined on both sides: <prop>, use `omitValidations` to prevent this error or ' +
                     'remove the conflicting property."',
             );
 

src/types/interface.test.ts

@@ -245,7 +245,7 @@ export class InterfaceType<Props extends Properties, ResultType>
                 throw new Error(
                     `Error in ${this.name}.${method}(): Merge operation not allowed because one of the types has custom ` +
                         `validations applied and the following ${propertiesAre} defined on both sides: ${conflicts}, ` +
-                        'use `omitValidations` to suppress this error or remove the conflicting property.',
+                        'use `omitValidations` to prevent this error or remove the conflicting property.',
                 );
             }
         }