@nhtio/validation 0.1.0-master-d7a77552 → 0.1.0-master-649f9ed8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhtio/validation",
-  "version": "0.1.0-master-d7a77552",
+  "version": "0.1.0-master-649f9ed8",
   "description": "A powerful schema description language and data validator",
   "keywords": [],
   "author": "Jak Giveon <jak@nht.io>",
@@ -25,9 +25,6 @@
       "sqlite3"
     ]
   },
-  "peerDependencies": {
-    "@adonisjs/lucid": "^21.8.0"
-  },
   "packageManager": "pnpm@10.8.0+sha512.0e82714d1b5b43c74610193cb20734897c1d00de89d0e18420aebc5977fa13d780a9cb05734624e81ebd81cc876cd464794850641c48b9544326b5622ca29971",
   "type": "module",
   "dependencies": {}

package/private/core/root.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Modern ES6 + TypeScript reimplementation of Joi's root factory.
+ *
+ * Based on: https://github.com/hapijs/joi/blob/master/lib/index.js
+ *
+ * This module recreates Joi's internal root factory to enable deeper
+ * customization through schema type modifiers and shortcuts modifiers.
+ */
+import type { Root } from 'joi';
+import type { Schema } from '../index';
+export type SchemaTypeDefinition = Schema;
+export type SchemaTypeDefinititionMiddlewareFn = (ctx: SchemaTypeDefinition, root: Root, args: any[]) => SchemaTypeDefinition;
+export type ShortcutsMiddlewareFn = (ctx: string[]) => string[];
+export interface RootFactoryOptions {
+    schemaTypeModifiers?: SchemaTypeDefinititionMiddlewareFn[];
+    shortcutsModifiers?: ShortcutsMiddlewareFn[];
+}
+export declare class RootFactory {
+    static readonly types: {
+        alternatives: any;
+        any: any;
+        array: any;
+        boolean: any;
+        date: any;
+        function: any;
+        link: any;
+        number: any;
+        object: any;
+        string: any;
+        symbol: any;
+        binary: any;
+    };
+    static readonly aliases: {
+        alt: string;
+        bool: string;
+        func: string;
+    };
+    static assertValue(value: any, schema: any, annotate: boolean, args: any[]): any;
+    static generate(root: any, schema: any, args: any[]): any;
+    static expandExtension(extension: any, joi: any): any[];
+    static getMethods(): {
+        ValidationError: any;
+        version: any;
+        cache: any;
+        assert(value: any, schema: any, ...args: any[]): void;
+        attempt(value: any, schema: any, ...args: any[]): any;
+        build(this: Root, desc: any): any;
+        checkPreferences(prefs: any): void;
+        compile(this: Root, schema: any, options: any): any;
+        defaults(this: Root, modifier: any): Root;
+        expression(...args: any[]): any;
+        extend(this: Root, ...extensions: any[]): Root;
+        isError: any;
+        isExpression: any;
+        isRef: any;
+        isSchema: any;
+        in(...args: any[]): any;
+        override: any;
+        ref(...args: any[]): any;
+        types(this: any): any;
+    };
+    static create(options?: RootFactoryOptions): Root;
+}

package/private/index.d.ts

@@ -1,13 +1,14 @@
-import type * as Joi from 'joi';
 import type { DateTime } from 'luxon';
 import type { PhoneSchema } from './schemas/phone';
 import type { BigIntSchema } from './schemas/bigint';
 import type { DatetimeSchema } from './schemas/datetime';
 import type { CountryOrUnknown } from '@nhtio/phone-object';
-import type { Root, Reference, SchemaMap, SchemaLike } from 'joi';
 import type { I18nCallback, SetI18nCallback } from './patches/i18n';
-import type { KnexSchema, KnexSchemaConnection, KnexSchemaSearchRuleOptions } from './schemas/knex';
+import type { ValidationOptions, Root, Reference as JoiReference, SchemaMap, SchemaLike, WhenSchemaOptions, WhenOptions, State, ReferenceOptions } from 'joi';
 import type { AnySchema, StringSchema, BinarySchema, NumberSchema, BooleanSchema, ObjectSchema, ArraySchema, DateSchema, AlternativesSchema, FunctionSchema, LinkSchema, SymbolSchema, Schema } from './schemas';
+export type Reference = JoiReference & {
+    resolve: (value: any, state: State, prefs: ValidationOptions, local?: any, options?: ReferenceOptions) => any;
+};
 /**
  * Extended Joi root interface that includes custom schema types for
  * additional validation scenarios.
@@ -27,7 +28,7 @@ import type { AnySchema, StringSchema, BinarySchema, NumberSchema, BooleanSchema
  *
  * @public
  */
-export interface ValidationRoot extends Omit<Root, 'allow' | 'alt' | 'alternatives' | 'any' | 'array' | 'binary' | 'bool' | 'boolean' | 'date' | 'disallow' | 'equal' | 'exist' | 'forbidden' | 'func' | 'function' | 'invalid' | 'link' | 'not' | 'number' | 'object' | 'optional' | 'preferences' | 'prefs' | 'required' | 'string' | 'symbol' | 'types' | 'valid' | 'when'> {
+export interface ValidationRoot extends Omit<Root, 'allow' | 'alt' | 'alternatives' | 'any' | 'array' | 'binary' | 'bool' | 'boolean' | 'date' | 'disallow' | 'equal' | 'exist' | 'forbidden' | 'func' | 'function' | 'invalid' | 'link' | 'not' | 'number' | 'object' | 'optional' | 'preferences' | 'prefs' | 'required' | 'string' | 'symbol' | 'types' | 'valid' | 'when' | 'ref'> {
     /**
      * Generates a schema object that matches any data type.
      */
@@ -110,11 +111,6 @@ export interface ValidationRoot extends Omit<Root, 'allow' | 'alt' | 'alternativ
      * @param country - Optional country code or reference for phone validation
      */
     phone<TSchema = string>(country?: CountryOrUnknown | Reference | null): PhoneSchema<TSchema>;
-    /**
-     * Generates a schema object that matches a database record using a Knex.js connection or Adonis Lucid Database connection for validation.
-     * @param connection - The database connection or QueryClientContract to use for validation
-     */
-    knex<TSchema = any>(connection: KnexSchemaConnection): KnexSchema<TSchema>;
     /**
      * Returns an object where each key is a plain joi schema type.
      * Useful for creating type shortcuts using deconstruction.
@@ -136,7 +132,6 @@ export interface ValidationRoot extends Omit<Root, 'allow' | 'alt' | 'alternativ
         bigint: BigIntSchema;
         datetime: DatetimeSchema;
         phone: PhoneSchema;
-        knex: KnexSchema;
     };
     /**
      * Whitelists a value
@@ -172,16 +167,20 @@ export interface ValidationRoot extends Omit<Root, 'allow' | 'alt' | 'alternativ
     /**
      * Overrides the global validate() options for the current key and any sub-key.
      */
-    preferences(options: Joi.ValidationOptions): Schema;
+    preferences(options: ValidationOptions): Schema;
     /**
      * Overrides the global validate() options for the current key and any sub-key.
      */
-    prefs(options: Joi.ValidationOptions): Schema;
+    prefs(options: ValidationOptions): Schema;
     /**
      * Converts the type into an alternatives type where the conditions are merged into the type definition where:
      */
-    when(ref: string | Reference, options: Joi.WhenOptions | Joi.WhenOptions[]): AlternativesSchema;
-    when(ref: Schema, options: Joi.WhenSchemaOptions): AlternativesSchema;
+    when(ref: string | Reference, options: WhenOptions | WhenOptions[]): AlternativesSchema;
+    when(ref: Schema, options: WhenSchemaOptions): AlternativesSchema;
+    /**
+     * Creates a reference to another schema key.
+     */
+    ref(key: string, options?: ReferenceOptions): Reference;
     /**
      * Sets a global internationalization callback that applies to all validator instances.
      *
@@ -239,27 +238,8 @@ export interface ValidationRoot extends Omit<Root, 'allow' | 'alt' | 'alternativ
     $clearI18n: () => ValidationRoot;
     $i18n: I18nCallback;
 }
-/**
- * Extended Joi instance with custom schema types.
- *
- * This instance includes all standard Joi functionality plus additional
- * schema types for additional validation scenarios.
- *
- * @example
- * ```typescript
- * import { validator } from '@nhtio/validation'
- *
- * // Standard Joi usage
- * const userSchema = validator.object({
- *   name: validator.string().required(),
- *   age: validator.number().min(0),
- *   balance: validator.bigint().positive() // Custom BigInt type
- * })
- * ```
- *
- * @public
- */
 export declare const validator: ValidationRoot;
-export type { BigIntSchema, DatetimeSchema, PhoneSchema, KnexSchema, SetI18nCallback, I18nCallback, KnexSchemaConnection, KnexSchemaSearchRuleOptions, };
+export type { BigIntSchema, DatetimeSchema, PhoneSchema, SetI18nCallback, I18nCallback };
 export type * from './schemas';
 export { encode, decode } from './utils';
+export type { Knex } from 'knex';

package/private/patches/i18n.d.ts

@@ -1,7 +1,4 @@
 import type { Root } from 'joi';
-export declare const knownMessages: {
-    [k: string]: string;
-};
 /**
  * Callback function type for internationalization translation.
  *

package/private/patches/index.d.ts

@@ -1,4 +1,3 @@
 import type { Root } from 'joi';
 import type { ValidationRoot } from '../index';
-export declare const root: any;
-export declare const patch: (patchable: Root) => ValidationRoot;
+export declare const patch: (root: Root) => ValidationRoot;

package/private/patches/knex.d.ts

@@ -1,2 +1,16 @@
-import type { SchemaTypeDefinititionMiddlewareFn } from '../root';
+import type { Knex } from 'knex';
+import type { SchemaTypeDefinititionMiddlewareFn } from '../core/root';
+import type { KnexSchemaConnection } from '../schemas';
+export declare const knexMessages: {
+    'knex.unique': string;
+    'knex.exists': string;
+    'knex.missingConnection': string;
+    'knex.invalidTable': string;
+    'knex.invalidColumn': string;
+    'knex.internal': string;
+};
+export declare const resolveQueryBuilder: (connection: KnexSchemaConnection, table: string) => {
+    client: Knex;
+    query: Knex.QueryBuilder;
+};
 export declare const knex: SchemaTypeDefinititionMiddlewareFn;

package/private/schemas.d.ts

@@ -1,10 +1,40 @@
+import type { Knex } from 'knex';
+import type { Reference } from '..';
 import type { DateTime } from 'luxon';
 import type { PhoneSchema } from './schemas/phone';
 import type { BigIntSchema } from './schemas/bigint';
 import type { DatetimeSchema } from './schemas/datetime';
-import type { KnexSchema, KnexSchemaConnection } from './schemas/knex';
-import type { default as Joi, AnySchema as JoiAnySchema, Reference, BasicType, CustomHelpers } from 'joi';
+import type { QueryClientContract } from '@adonisjs/lucid/types/database';
+import type { DatabaseQueryBuilderContract } from '@adonisjs/lucid/types/querybuilder';
+import type { default as Joi, AnySchema as JoiAnySchema, BasicType, CustomHelpers, ExternalHelpers } from 'joi';
+export type { Knex, QueryClientContract, DatabaseQueryBuilderContract };
+export type KnexTransaction = Knex.Transaction;
+export type KnexQueryBuilder = Knex.QueryBuilder;
+export type QueryClient = Knex | KnexTransaction | QueryClientContract;
+export type QueryBuilder = KnexQueryBuilder | DatabaseQueryBuilderContract;
+export interface KnexConnectionConfigurations {
+    client: NonNullable<Knex.Config['client']>;
+    connection: NonNullable<Knex.Config['connection']>;
+    [key: string | number | symbol]: any;
+}
+export type KnexSchemaConnection = QueryClient | KnexConnectionConfigurations;
 export type DefaultableValue = Reference | BasicType | DateTime | bigint | ((parent: any, helpers: CustomHelpers) => Reference | BasicType | DateTime | bigint);
+/**
+ * Options for database-backed validation helpers such as `uniqueInDb` and `existsInDb`.
+ */
+export interface DbValidationOptions {
+    /**
+     * Perform case-insensitive comparisons when querying the database.
+     * Defaults to `false`.
+     */
+    caseInsensitive?: boolean;
+    /**
+     * Optional function that receives the Knex query builder (or equivalent) so
+     * the caller can append additional WHERE clauses (or joins). Can be async.
+     * Example: `async (query, value, column, helpers) => query.where('tenant_id', tenantId)`
+     */
+    filter?: (queryBuilder: QueryBuilder, value: any, column: string, helpers: Omit<ExternalHelpers, 'warn' | 'error' | 'message'>) => void | Promise<void>;
+}
 /**
  * Base schema type for all validation schemas.
  *
@@ -101,6 +131,70 @@ export interface AnySchema<TSchema = any> extends Omit<JoiAnySchema<TSchema>, '$
     warning(code: string, context: Joi.Context): this;
     when(ref: string | Reference, options: Joi.WhenOptions | Joi.WhenOptions[]): this;
     when(ref: Schema, options: Joi.WhenSchemaOptions): this;
+    $_knex: KnexSchemaConnection | undefined;
+    /**
+     * Sets the database connection for database validation rules.
+     * This must be called before using `.uniqueInDb()` or `.existsInDb()`.
+     *
+     * @param connection - A Knex instance, transaction, or connection configuration
+     *
+     * @example
+     * ```typescript
+     * import knex from 'knex'
+     * const db = knex({ client: 'pg', connection: {...} })
+     * const schema = joi.string().knex(db).uniqueInDb('users', 'email')
+     * ```
+     */
+    knex(connection: KnexSchemaConnection): this;
+    /**
+     * Alias for `.knex()`. Sets the database connection for database validation rules.
+     *
+     * @param connection - A Knex instance, transaction, or connection configuration
+     */
+    db(connection: KnexSchemaConnection): this;
+    /**
+     * Validates that the value is unique in the specified database table and column.
+     * Requires `.knex()` or `.db()` to be called first to set the database connection.
+     *
+     * @param table - The database table name (can be a Joi reference)
+     * @param column - The column name to check (can be a Joi reference)
+     * @param options - Optional configuration:
+     *   - `caseInsensitive`: Perform case-insensitive comparison (default: false)
+     *   - `filter`: Async function to add additional WHERE clauses to the query
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.object({
+     *   email: joi.string().email().knex(db).uniqueInDb('users', 'email'),
+     *   username: joi.string().knex(db).uniqueInDb('users', 'username', {
+     *     caseInsensitive: true,
+     *     filter: async (query) => query.where('tenant_id', tenantId)
+     *   })
+     * })
+     * ```
+     */
+    uniqueInDb(table: string | Reference, column: string | Reference, options?: DbValidationOptions): this;
+    /**
+     * Validates that the value exists in the specified database table and column.
+     * Requires `.knex()` or `.db()` to be called first to set the database connection.
+     *
+     * @param table - The database table name (can be a Joi reference)
+     * @param column - The column name to check (can be a Joi reference)
+     * @param options - Optional configuration:
+     *   - `caseInsensitive`: Perform case-insensitive comparison (default: false)
+     *   - `filter`: Async function to add additional WHERE clauses to the query
+     *
+     * @example
+     * ```typescript
+     * const schema = joi.object({
+     *   country_id: joi.number().knex(db).existsInDb('countries', 'id'),
+     *   category: joi.string().knex(db).existsInDb('categories', 'name', {
+     *     caseInsensitive: true
+     *   })
+     * })
+     * ```
+     */
+    existsInDb(table: string | Reference, column: string | Reference, options?: DbValidationOptions): this;
     /**
      * Sets a default value if the original value is `undefined`.
      *
@@ -119,10 +213,6 @@ export interface AnySchema<TSchema = any> extends Omit<JoiAnySchema<TSchema>, '$
      */
     default(value?: DefaultableValue): this;
     cast(to: 'map' | 'number' | 'set' | 'string' | 'object'): this;
-    /**
-     * Add the Knex.js extension methods to a string schema.
-     */
-    knex(connection: KnexSchemaConnection): KnexSchema<TSchema>;
 }
 /**
  * Schema type for string validation.

package/private/utils.d.ts

@@ -1,4 +1,71 @@
 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.
  *
@@ -46,7 +113,7 @@ import type { Schema } from './schemas';
  *
  * @see {@link decode} For decoding schemas from encoded strings
  */
-export declare const encode: (schema: Schema) => string;
+export declare const encode: (schema: Schema, options?: EncoderOptions) => string;
 /**
  * Decodes a base64-encoded schema string back into a usable validation schema.
  *
@@ -63,6 +130,7 @@ export declare const encode: (schema: Schema) => string;
  * - 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
@@ -101,6 +169,18 @@ export declare const encode: (schema: Schema) => string;
  * 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) => Schema;
+export declare const decode: (base64: string, options?: EncoderOptions) => Schema;

package/private/monkeypatches/index.d.ts

@@ -1,2 +0,0 @@
-import type { SchemaTypeDefinititionMiddlewareFn } from '../root';
-export declare const monkeyPatches: SchemaTypeDefinititionMiddlewareFn;

package/private/monkeypatches/validate_async.d.ts

@@ -1,23 +0,0 @@
-import type { Schema } from '../';
-import type { AsyncValidationOptions, ValidationWarning, Context } from 'joi';
-export declare const doValidation: (value: any, schema: any, state: any, prefs: any, overrides?: any) => Promise<any>;
-export declare const validateAsync: <TOpts extends AsyncValidationOptions, TSchema = any>(this: Schema, value: any, options?: TOpts) => Promise<TOpts extends {
-    artifacts: true;
-} | {
-    warnings: true;
-} ? {
-    value: TSchema;
-} & (TOpts extends {
-    artifacts: true;
-} ? {
-    artifacts: Map<any, string[][]>;
-} : {}) & (TOpts extends {
-    warnings: true;
-} ? {
-    warning: ValidationWarning;
-} : {}) : TSchema>;
-export declare const doAsyncValidateForKeysSchema: (value: any, { schema, error, state, prefs }: Context) => Promise<{
-    value: any;
-    errors: any;
-} | undefined>;
-export declare const doAsyncValidationForAlternativesSchema: (value: any, helpers: Context) => Promise<any>;

package/private/root.d.ts

@@ -1,17 +0,0 @@
-/**
- * In order to create a better DX, and to allow for deeper
- * patching of root instances of Joi, we are going to completely
- * recreate the Joi default export here based on:
- * https://github.com/hapijs/joi/blob/master/lib/index.js
- * Due to the lack of type definitions for the internal parts of Joi,
- * this file will be mainly untyped.
- */
-import type { Schema } from '../index';
-export type SchemaTypeDefinition = Schema;
-export type SchemaTypeDefinititionMiddlewareFn = (ctx: SchemaTypeDefinition) => SchemaTypeDefinition;
-export type ShortcutsMiddlewareFn = (ctx: string[]) => string[];
-export type RootFactoryOptions = {
-    schemaTypeModifiers?: SchemaTypeDefinititionMiddlewareFn[];
-    shortcutsModifiers?: ShortcutsMiddlewareFn[];
-};
-export declare const internals: any;

package/private/schemas/knex.d.ts

@@ -1,32 +0,0 @@
-import type { Knex } from 'knex';
-import type { AnySchema } from '../../index';
-import type { QueryClientContract } from '@adonisjs/lucid/types/database';
-import type { ExtensionFactory, Reference } from 'joi';
-import type { DatabaseQueryBuilderContract } from '@adonisjs/lucid/types/querybuilder';
-export type QueryClient = Knex | Knex.Transaction | QueryClientContract;
-export type QueryBuilder = Knex.QueryBuilder | DatabaseQueryBuilderContract;
-export interface KnexConnectionConfigurations {
-    client: NonNullable<Knex.Config['client']>;
-    connection: NonNullable<Knex.Config['connection']>;
-    [key: string | number | symbol]: any;
-}
-export type KnexSchemaConnection = QueryClient | KnexConnectionConfigurations;
-export type KnexSchemaSearchRuleOptions = {
-    caseInsensitive: boolean;
-    filter: (queryBuilder: QueryBuilder, value: any, column: string) => void | Promise<void>;
-};
-export type KnexSchemaSearchRule<TSchema = any> = (table: string | Reference, column: string | Reference, options?: Partial<KnexSchemaSearchRuleOptions>) => KnexSchema<TSchema>;
-export interface KnexSchema<TSchema = any> extends Omit<AnySchema<TSchema>, 'cast'> {
-    unique: KnexSchemaSearchRule<TSchema>;
-    exists: KnexSchemaSearchRule<TSchema>;
-    db: (connection: KnexSchemaConnection) => KnexSchema<TSchema>;
-}
-export declare const messages: {
-    'knex.unique': string;
-    'knex.exists': string;
-    'knex.missingConnection': string;
-    'knex.invalidTable': string;
-    'knex.invalidColumn': string;
-    'knex.internal': string;
-};
-export declare const knex: ExtensionFactory;