@mionjs/type-formats

@mionjs/type-formats provides runtype functionality such as validation and serialization based on TypeScript types. Unlike libraries like Zod or AJV-formats, which use JavaScript to declare schemas, @mionjs/type-formats directly leverages TypeScript types and extracts information at compile time to generate validation and serialization functions.

You can find examples of how to use these formats in the various spec files under the string directory.

⚡ Fast:
The validation and serialization functions generated by @mionjs/type-formats are JIT (Just-In-Time) compiled, ensuring they are highly optimized for performance. This makes them suitable for use in high-throughput applications where efficiency is critical.

Available Formats

Below is a list of available formats parsed from the spec files:

String Formats

• Base String Format

  • StringFormat: The base format for all string-related validations and transformations. It provides a set of customizable parameters that can be reused to create any custom string format. Below are the available parameters:

    • Validators:

      • maxLength: Maximum length of the string.
      • minLength: Minimum length of the string.
      • length: Exact length of the string.
      • allowedChars: A string containing characters allowed in the string.
      • disallowedChars: A string containing characters not allowed in the string.
      • allowedValues: An array of allowed string values.
      • disallowedValues: An array of disallowed string values.
      • pattern: A regular expression pattern with an optional message and sample values.

    • Transformers:

      • lowercase: Converts the string to lowercase.
      • uppercase: Converts the string to uppercase.
      • capitalize: Capitalizes the first letter of the string.
      • trim: Removes whitespace from both ends of the string.
      • replace: Replaces the first occurrence of a substring with another value.
      • replaceAll: Replaces all occurrences of a substring with another value.

• UUID Formats

  • UUID_V4: Validates UUID version 4.
  • UUID_V7: Validates UUID version 7.

• Time Formats

  • TimeString: Supports formats like ISO, HH:mm:ss[.mmm]TZ, HH:mm:ss, HH:mm, mm:ss, HH, mm, ss.

• Date Formats

  • DateString: Supports formats like ISO, YYYY-MM-DD, DD-MM-YYYY, MM-DD-YYYY, MM-DD, DD-MM, YYYY-MM.

• DateTime Formats

  • DateTimeString: Combines date and time formats in a customizable way. Most common format is ISO, i.e., YYYY-MM-DDTHH:mm:ssTZ.

• String Validation Formats

  • AlphaString: Validates strings containing only alphabetic characters.
  • AlphaNumericString: Validates strings containing only alphanumeric characters.
  • NumericString: Validates strings containing only numeric characters.
  • LowerString: Validates strings in lowercase.
  • UpperString: Validates strings in uppercase.
  • CapitalString: Validates strings with the first letter capitalized.

• Domain Formats

  • Domain: Validates domain names with customizable parameters for subdomains, TLDs, and length.

• Email Formats

  • Email: Validates email addresses with customizable parameters for local parts and domains.

• IP Formats

  • IP: Validates IP addresses (IPv4, IPv6, or both) with options for localhost and port inclusion.

• URL Formats

  • URL: Validates URLs with customizable parameters for protocols, length, and allowed/disallowed characters.

Example Usage

Using DateTimeString Format with isType

The DateTimeString format allows you to validate date-time strings with customizable date and time formats. Below is an example of how to use it with the isType function:

import {isTypeFn} from '@mionjs/run-types';
import {DateTimeString} from '@mionjs/type-formats';

// Customizing DateTimeString to include only year, month, and time (HH:mm:ss)
type CustomDateTimeString = DateTimeString<{date: {format: 'YYYY-MM'}; time: {format: 'HH:mm:ss'}; splitChar: '/'}>;

const isIsoDateTime = await isTypeFn<DateTimeString>();

// Example usage for default ISO DateTimeString
console.log(await isIsoDateTime('2024-01-01T12:30:45Z')); // true
console.log(await isIsoDateTime('2024-01-01T12:30:45')); // true
console.log(await isIsoDateTime('2024-01-01 12:30:45')); // false (missing 'T' separator)
console.log(await isIsoDateTime('2024-13-01T12:30:45Z')); // false (invalid month 13)

const isCustomDateTime = await isTypeFn<CustomDateTimeString>();

// Example usage for custom DateTimeString
console.log(isCustomDateTime('2024-01/12:30:45')); // true
console.log(isCustomDateTime('2024-01T12:30:45')); // false (wrong split char T instead of the custom /)
console.log(isCustomDateTime('2024-01-01/12:30:45')); // false (day is not allowed)
console.log(isCustomDateTime('2024-13/12:30:45')); // false (invalid month 13)

This example demonstrates how to validate both default ISO date-time strings and a custom date-time string format.

Check Out The Website And Documentation 📚

MIT LICENSE