/**
 * Relation builders for entity definitions
 * @module relations
 */
import type { FieldBuilder, FieldConfig } from './fields';
export type RelationType = 'hasOne' | 'hasMany' | 'belongsToMany';
/**
 * Pivot table configuration for belongsToMany relations
 */
export interface PivotConfig {
    /** Custom name for the junction/pivot table */
    table?: string;
    /** Additional fields on the pivot table */
    fields?: Record<string, FieldConfig>;
}
export interface RelationConfig {
    type: RelationType;
    entity: string;
    /** Optional custom foreign key field name */
    field?: string;
    /** Whether the relation is optional (for hasOne relations) */
    optional?: boolean;
    /** Pivot table configuration for belongsToMany */
    pivot?: PivotConfig;
}
export interface RelationBuilder {
    readonly _config: RelationConfig;
    /** Override the default foreign key field name */
    field(name: string): RelationBuilder;
    /** Mark this relation as optional (foreign key can be null) */
    optional(): RelationBuilder;
}
export interface BelongsToManyBuilder extends RelationBuilder {
    /** Configure pivot table with additional fields */
    through(options: {
        table?: string;
        fields: Record<string, FieldBuilder>;
    }): BelongsToManyBuilder;
}
/**
 * Create a one-to-one relation (adds foreign key to this entity)
 *
 * @param entity - Target entity name
 * @returns RelationBuilder
 *
 * @example
 * ```typescript
 * relations: {
 *   author: hasOne('User'),
 *   category: hasOne('Category').field('categoryId'),
 * }
 * ```
 */
export declare function hasOne(entity: string): RelationBuilder;
/**
 * Create a one-to-many relation (target entity has FK to this entity)
 *
 * @param entity - Target entity name
 * @returns RelationBuilder
 *
 * @example
 * ```typescript
 * relations: {
 *   posts: hasMany('Post'),
 *   comments: hasMany('Comment'),
 * }
 * ```
 */
export declare function hasMany(entity: string): RelationBuilder;
/**
 * Create a many-to-many relation (creates junction table)
 *
 * @param entity - Target entity name
 * @returns BelongsToManyBuilder
 *
 * @example
 * ```typescript
 * // Simple many-to-many
 * relations: {
 *   tags: belongsToMany('Tag'),
 * }
 *
 * // With pivot data (e.g., OrderItem with quantity)
 * relations: {
 *   products: belongsToMany('Product').through({
 *     table: 'order_items',
 *     fields: {
 *       quantity: number().required().min(1),
 *       unitPrice: number().required(),
 *     }
 *   }),
 * }
 * ```
 */
export declare function belongsToMany(entity: string): BelongsToManyBuilder;
//# sourceMappingURL=relations.d.ts.map