@nhtio/validation 0.1.0-master-5ddd6b01

package/private/schemas.d.ts

@@ -0,0 +1,157 @@
+import type { AnySchema as JoiAnySchema, StringSchema as JoiStringSchema, BinarySchema as JoiBinarySchema, NumberSchema as JoiNumberSchema, BooleanSchema as JoiBooleanSchema, ObjectSchema as JoiObjectSchema, ArraySchema as JoiArraySchema, DateSchema as JoiDateSchema, Reference, BasicType, CustomHelpers } from 'joi';
+/**
+ * Base schema type for all validation schemas.
+ *
+ * This interface provides the foundation for all validation schemas with
+ * comprehensive validation methods and options.
+ *
+ * @public
+ */
+export interface AnySchema<TSchema = any> extends Omit<JoiAnySchema<TSchema>, 'default'> {
+    /**
+     * Sets a default value if the original value is `undefined`.
+     *
+     * @param value - The default value. Can be:
+     * - A literal value (string, number, object, etc.)
+     * - A reference to another schema value
+     * - A function that returns the default value with signature `(parent, helpers) => value`
+     *   - `parent` - A clone of the object containing the value being validated
+     *   - `helpers` - Validation helper functions for custom validation logic
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.string().default('hello world')
+     * const schemaWithFunction = joi.number().default((parent, helpers) => parent.someOtherField * 2)
+     * ```
+     */
+    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+}
+/**
+ * Schema type for string validation.
+ *
+ * @public
+ */
+export interface StringSchema<TSchema = string> extends Omit<JoiStringSchema<TSchema>, 'default'> {
+    /**
+     * Sets a default value if the original value is `undefined`.
+     *
+     * @param value - The default value. Can be:
+     * - A literal string value
+     * - A reference to another schema value
+     * - A function that returns the default value with signature `(parent, helpers) => value`
+     *   - `parent` - A clone of the object containing the value being validated
+     *   - `helpers` - Validation helper functions for custom validation logic
+     */
+    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+}
+/**
+ * Schema type for binary data validation.
+ *
+ * @public
+ */
+export interface BinarySchema<TSchema = Buffer> extends Omit<JoiBinarySchema<TSchema>, 'default'> {
+    /**
+     * Sets a default value if the original value is `undefined`.
+     *
+     * @param value - The default value. Can be:
+     * - A literal binary value (Buffer, Uint8Array, etc.)
+     * - A reference to another schema value
+     * - A function that returns the default value with signature `(parent, helpers) => value`
+     *   - `parent` - A clone of the object containing the value being validated
+     *   - `helpers` - Validation helper functions for custom validation logic
+     */
+    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+}
+/**
+ * Schema type for number validation.
+ *
+ * @public
+ */
+export interface NumberSchema<TSchema = number> extends Omit<JoiNumberSchema<TSchema>, 'default'> {
+    /**
+     * Sets a default value if the original value is `undefined`.
+     *
+     * @param value - The default value. Can be:
+     * - A literal number value
+     * - A reference to another schema value
+     * - A function that returns the default value with signature `(parent, helpers) => value`
+     *   - `parent` - A clone of the object containing the value being validated
+     *   - `helpers` - Validation helper functions for custom validation logic
+     */
+    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+}
+/**
+ * Schema type for boolean validation.
+ *
+ * @public
+ */
+export interface BooleanSchema<TSchema = boolean> extends Omit<JoiBooleanSchema<TSchema>, 'default'> {
+    /**
+     * Sets a default value if the original value is `undefined`.
+     *
+     * @param value - The default value. Can be:
+     * - A literal boolean value
+     * - A reference to another schema value
+     * - A function that returns the default value with signature `(parent, helpers) => value`
+     *   - `parent` - A clone of the object containing the value being validated
+     *   - `helpers` - Validation helper functions for custom validation logic
+     */
+    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+}
+/**
+ * Schema type for object validation.
+ *
+ * @public
+ */
+export interface ObjectSchema<TSchema = any> extends Omit<JoiObjectSchema<TSchema>, 'default'> {
+    /**
+     * Sets a default value if the original value is `undefined`.
+     *
+     * @param value - The default value. Can be:
+     * - A literal object value
+     * - A reference to another schema value
+     * - A function that returns the default value with signature `(parent, helpers) => value`
+     *   - `parent` - A clone of the object containing the value being validated
+     *   - `helpers` - Validation helper functions for custom validation logic
+     *
+     * When called without any value on an object schema type, a default value will be
+     * automatically generated based on the default values of the object keys.
+     */
+    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+}
+/**
+ * Schema type for array validation.
+ *
+ * @public
+ */
+export interface ArraySchema<TSchema = any[]> extends Omit<JoiArraySchema<TSchema>, 'default'> {
+    /**
+     * Sets a default value if the original value is `undefined`.
+     *
+     * @param value - The default value. Can be:
+     * - A literal array value
+     * - A reference to another schema value
+     * - A function that returns the default value with signature `(parent, helpers) => value`
+     *   - `parent` - A clone of the object containing the value being validated
+     *   - `helpers` - Validation helper functions for custom validation logic
+     */
+    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+}
+/**
+ * Schema type for date validation.
+ *
+ * @public
+ */
+export interface DateSchema<TSchema = Date> extends Omit<JoiDateSchema<TSchema>, 'default'> {
+    /**
+     * Sets a default value if the original value is `undefined`.
+     *
+     * @param value - The default value. Can be:
+     * - A literal date value
+     * - A reference to another schema value
+     * - A function that returns the default value with signature `(parent, helpers) => value`
+     *   - `parent` - A clone of the object containing the value being validated
+     *   - `helpers` - Validation helper functions for custom validation logic
+     */
+    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+}

package/private/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * # Table of tokens
+ *
+ * (The example values below come from this time `2014-08-06T13:07:04.054`
+ * considered as a local time in America/New_York).
+ *
+ * Note that many tokens supported by the formatter are **not** supported by the parser.
+ *
+ * | Standalone token | Format token | Description                                                       | Example                     |
+ * | ---------------- | ------------ | ----------------------------------------------------------------- | --------------------------- |
+ * | S                |              | millisecond, no padding                                           | `54`                        |
+ * | SSS              |              | millisecond, padded to 3                                          | `054`                       |
+ * | u                |              | fractional seconds, (5 is a half second, 54 is slightly more)     | `54`                        |
+ * | uu               |              | fractional seconds, (one or two digits)                           | `05`                        |
+ * | uuu              |              | fractional seconds, (only one digit)                              | `5`                         |
+ * | s                |              | second, no padding                                                | `4`                         |
+ * | ss               |              | second, padded to 2 padding                                       | `04`                        |
+ * | m                |              | minute, no padding                                                | `7`                         |
+ * | mm               |              | minute, padded to 2                                               | `07`                        |
+ * | h                |              | hour in 12-hour time, no padding                                  | `1`                         |
+ * | hh               |              | hour in 12-hour time, padded to 2                                 | `01`                        |
+ * | H                |              | hour in 24-hour time, no padding                                  | `13`                        |
+ * | HH               |              | hour in 24-hour time, padded to 2                                 | `13`                        |
+ * | Z                |              | narrow offset                                                     | `+5`                        |
+ * | ZZ               |              | short offset                                                      | `+05:00`                    |
+ * | ZZZ              |              | techie offset                                                     | `+0500`                     |
+ * | z                |              | IANA zone                                                         | `America/New_York`          |
+ * | a                |              | meridiem                                                          | `AM`                        |
+ * | d                |              | day of the month, no padding                                      | `6`                         |
+ * | dd               |              | day of the month, padded to 2                                     | `06`                        |
+ * | E                | c            | day of the week, as number from 1-7 (Monday is 1, Sunday is 7)    | `3`                         |
+ * | EEE              | ccc          | day of the week, as an abbreviate localized string                | `Wed`                       |
+ * | EEEE             | cccc         | day of the week, as an unabbreviated localized string             | `Wednesday`                 |
+ * | M                | L            | month as an unpadded number                                       | `8`                         |
+ * | MM               | LL           | month as an padded number                                         | `08`                        |
+ * | MMM              | LLL          | month as an abbreviated localized string                          | `Aug`                       |
+ * | MMMM             | LLLL         | month as an unabbreviated localized string                        | `August`                    |
+ * | y                |              | year, 1-6 digits, very literally                                  | `2014`                      |
+ * | yy               |              | two-digit year, interpreted as > 1960 by default (also accepts 4) | `14`                        |
+ * | yyyy             |              | four-digit year                                                   | `2014`                      |
+ * | yyyyy            |              | four- to six-digit years                                          | `10340`                     |
+ * | yyyyyy           |              | six-digit years                                                   | `010340`                    |
+ * | G                |              | abbreviated localized era                                         | `AD`                        |
+ * | GG               |              | unabbreviated localized era                                       | `Anno Domini`               |
+ * | GGGGG            |              | one-letter localized era                                          | `A`                         |
+ * | kk               |              | ISO week year, unpadded                                           | `17`                        |
+ * | kkkk             |              | ISO week year, padded to 4                                        | `2014`                      |
+ * | W                |              | ISO week number, unpadded                                         | `32`                        |
+ * | WW               |              | ISO week number, padded to 2                                      | `32`                        |
+ * | o                |              | ordinal (day of year), unpadded                                   | `218`                       |
+ * | ooo              |              | ordinal (day of year), padded to 3                                | `218`                       |
+ * | q                |              | quarter, no padding                                               | `3`                         |
+ * | D                |              | localized numeric date                                            | `9/6/2014`                  |
+ * | DD               |              | localized date with abbreviated month                             | `Aug 6, 2014`               |
+ * | DDD              |              | localized date with full month                                    | `August 6, 2014`            |
+ * | DDDD             |              | localized date with full month and weekday                        | `Wednesday, August 6, 2014` |
+ * | t                |              | localized time                                                    | `1:07 AM`                   |
+ * | tt               |              | localized time with seconds                                       | `1:07:04 PM`                |
+ * | T                |              | localized 24-hour time                                            | `13:07`                     |
+ * | TT               |              | localized 24-hour time with seconds                               | `13:07:04`                  |
+ * | f                |              | short localized date and time                                     | `8/6/2014, 1:07 PM`         |
+ * | ff               |              | less short localized date and time                                | `Aug 6, 2014, 1:07 PM`      |
+ * | F                |              | short localized date and time with seconds                        | `8/6/2014, 1:07:04 PM`      |
+ * | FF               |              | less short localized date and time with seconds                   | `Aug 6, 2014, 1:07:04 PM`   |
+ * | '                |              | literal start/end, characters between are not tokenized           | `'T'`                       |
+ *
+ * Sourced from [here](https://moment.github.io/luxon/#/parsing?id=table-of-tokens).
+ */
+export type Tokens = string;

package/private/utils.d.ts

@@ -0,0 +1,106 @@
+import type { AnySchema } from './schemas';
+/**
+ * Encodes a validation schema into a compressed, base64-encoded string for transport between environments.
+ *
+ * This function serializes a validation schema description along with version information,
+ * compresses it using zlib, and encodes it as a base64 string. This enables efficient
+ * transfer of validation schemas between frontend and backend environments while
+ * maintaining version compatibility.
+ *
+ * The encoded string includes:
+ * - Current library version for compatibility checking
+ * - Complete schema description from `schema.describe()`
+ * - Zlib compression for minimal payload size
+ * - Base64 encoding for web-safe transport
+ *
+ * @param schema - The validation schema to encode
+ * @returns A compressed, base64-encoded string representing the schema
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import Joi from 'joi'
+ * import { encode } from './utils'
+ *
+ * const schema = Joi.object({
+ *   name: Joi.string().required(),
+ *   age: Joi.number().min(0)
+ * })
+ *
+ * const encoded = encode(schema)
+ * // Returns: "eJyrVkosLcmIz8nPS1WyUvJIzcnJT..."
+ * ```
+ *
+ * @example Cross-Environment Transfer
+ * ```typescript
+ * // Backend
+ * const validationSchema = Joi.object({
+ *   email: Joi.string().email().required()
+ * })
+ * const encodedSchema = encode(validationSchema)
+ *
+ * // Send to frontend via API
+ * response.json({ schema: encodedSchema })
+ *
+ * // Frontend can then decode and use the same validation
+ * ```
+ *
+ * @see {@link decode} For decoding schemas from encoded strings
+ */
+export declare const encode: (schema: AnySchema) => string;
+/**
+ * Decodes a base64-encoded schema string back into a usable validation schema.
+ *
+ * This function reverses the encoding process, decompressing and parsing the
+ * encoded schema while performing version compatibility checks. It ensures
+ * that schemas encoded with newer versions of the library are rejected to
+ * prevent runtime errors from incompatible schema formats.
+ *
+ * The function handles:
+ * - Base64 decoding and zlib decompression
+ * - Version compatibility validation using semantic versioning
+ * - Backward compatibility with legacy encoding formats
+ * - Input validation and error handling
+ * - Schema reconstruction using Joi's build method
+ *
+ * @param base64 - The base64-encoded schema string
+ * @returns A reconstructed validation schema ready for validation
+ * @throws {TypeError} When the encoded string is not a valid schema
+ * @throws {TypeError} When the schema version is invalid or incompatible
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { decode } from './utils'
+ *
+ * const encodedSchema = "eJyrVkosLcmIz8nPS1WyUvJIzcnJT..."
+ * const schema = decode(encodedSchema)
+ *
+ * // Use the decoded schema for validation
+ * const result = schema.validate({ name: "John", age: 30 })
+ * ```
+ *
+ * @example Error Handling
+ * ```typescript
+ * try {
+ *   const schema = decode(untrustedEncodedString)
+ *   // Use schema safely
+ * } catch (error) {
+ *   if (error instanceof TypeError) {
+ *     console.error('Invalid or incompatible schema:', error.message)
+ *   }
+ * }
+ * ```
+ *
+ * @example Version Compatibility
+ * ```typescript
+ * // Schema encoded with v2.1.0, current version is v2.0.0
+ * const futureSchema = "..." // Contains version 2.1.0
+ * decode(futureSchema) // Throws: Schema version 2.1.0 is not compatible
+ *
+ * // Schema encoded with v1.9.0, current version is v2.0.0
+ * const oldSchema = "..." // Contains version 1.9.0
+ * const schema = decode(oldSchema) // Works - backward compatible
+ * ```
+ *
+ * @see {@link encode} For encoding schemas into transportable strings
+ */
+export declare const decode: (base64: string) => AnySchema;