@nhtio/validation 0.1.0-master-fe5983b7 → 0.1.0-master-b4207fd6

package/private/types.d.ts

@@ -1,69 +0,0 @@
-/**
- * # 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

@@ -1,186 +0,0 @@
-import type { Schema } from './schemas';
-/**
- * Options for encoding and decoding validation schemas.
- *
- * These options control what gets serialized when encoding schemas and how
- * they're reconstructed during decoding. The defaults prioritize security
- * and are designed for the most common use case: sharing validation rules
- * between frontend and backend environments.
- */
-export type EncoderOptions = {
-    /**
-     * Include database connections and database validation rules in the encoded schema.
-     *
-     * When `false` (default):
-     * - Database connections (`.knex()`, `.db()`) are stripped from the encoded schema
-     * - Database validation rules (`.uniqueInDb()`, `.existsInDb()`) are converted to no-ops
-     * - Filter functions in database rules are replaced with empty functions
-     * - This prevents credential leakage and reduces payload size
-     *
-     * When `true`:
-     * - Database connection configurations are serialized (if they're plain objects)
-     * - Database validation rules and their filter functions are preserved
-     * - **Security warning**: Only use this in trusted backend-to-backend communication
-     * - Encoded schemas will require re-attaching database connections after decoding
-     *
-     * **Why this defaults to `false`:**
-     * 1. **Security**: Prevents accidental exposure of database credentials in client-side code
-     * 2. **Use case alignment**: Frontend validation typically doesn't need database rules
-     * 3. **Credential safety**: Database connections often contain sensitive connection strings
-     * 4. **Function security**: Custom filter functions may contain business logic or credentials
-     *
-     * @default false
-     *
-     * @example Frontend/Backend Schema Sharing (default)
-     * ```typescript
-     * // Backend
-     * const schema = joi.object({
-     *   email: joi.string().email().uniqueInDb('users', 'email')
-     * }).knex(db)
-     *
-     * const encoded = encode(schema) // withDatabase defaults to false
-     * // Database rules are stripped, safe to send to frontend
-     *
-     * // Frontend receives and decodes
-     * const frontendSchema = decode(encoded)
-     * // Only gets email format validation, no database checks
-     * ```
-     *
-     * @example Backend-to-Backend Schema Transfer
-     * ```typescript
-     * // Service A
-     * const schema = joi.object({
-     *   username: joi.string().uniqueInDb('users', 'username', {
-     *     filter: async (query) => query.where('tenant_id', tenantId)
-     *   })
-     * }).knex({ client: 'pg', connection: { host: 'localhost', ... } })
-     *
-     * const encoded = encode(schema, { withDatabase: true })
-     * // Sends to trusted Service B
-     *
-     * // Service B
-     * const decoded = decode(encoded, { withDatabase: true })
-     * const rehydrated = decoded.knex(serviceB_db_connection)
-     * // Now has full database validation capabilities
-     * ```
-     */
-    withDatabase?: boolean;
-};
-/**
- * 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: Schema, options?: EncoderOptions) => 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
- * @param options - Decoding options
- * @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
- * ```
- *
- * @security
- * **IMPORTANT: Only decode schemas from trusted sources.**
- *
- * Decoded schemas may contain serialized functions that are evaluated using the
- * Function constructor. Never decode schemas from:
- * - User input or user-controlled data
- * - Untrusted third-party APIs
- * - Any source you do not control
- *
- * If the schema source is not under your direct control, validate its integrity
- * using cryptographic signatures or checksums before decoding.
- *
- * @see {@link encode} For encoding schemas into transportable strings
- */
-export declare const decode: (base64: string, options?: EncoderOptions) => Schema;