/**
 * db4ai Query Builder
 *
 * Provides a fluent API for building type-safe queries with excellent
 * TypeScript inference and ergonomic convenience methods.
 *
 * @packageDocumentation
 */
/**
 * Query operators for filtering documents.
 *
 * @typeParam V - The value type for the field being filtered
 *
 * @example
 * ```typescript
 * const filter: QueryOperators<number> = {
 *   $gte: 18,
 *   $lt: 65
 * };
 * ```
 */
export interface QueryOperators<V> {
    /** Equal to */
    $eq?: V;
    /** Not equal to */
    $ne?: V;
    /** Greater than */
    $gt?: V;
    /** Greater than or equal to */
    $gte?: V;
    /** Less than */
    $lt?: V;
    /** Less than or equal to */
    $lte?: V;
    /** Value is in array */
    $in?: V[];
    /** Value is not in array */
    $nin?: V[];
    /** String contains substring (case-sensitive) */
    $contains?: string;
    /** String starts with prefix */
    $startsWith?: string;
    /** String ends with suffix */
    $endsWith?: string;
    /** Field exists */
    $exists?: boolean;
    /** Matches regular expression */
    $regex?: string;
    /** Case-insensitive regex match */
    $iregex?: string;
}
/**
 * Where clause for filtering documents.
 *
 * @typeParam T - The document type
 *
 * @example
 * ```typescript
 * const where: WhereClause<User> = {
 *   status: { $eq: 'active' },
 *   age: { $gte: 18 },
 *   $or: [
 *     { role: 'admin' },
 *     { permissions: { $contains: 'write' } }
 *   ]
 * };
 * ```
 */
export type WhereClause<T> = {
    [K in keyof T]?: T[K] | QueryOperators<T[K]>;
} & {
    /** Nested field path access (e.g., 'profile.settings.theme') */
    [path: string]: unknown | QueryOperators<unknown>;
} & {
    /** All conditions must match */
    $and?: WhereClause<T>[];
    /** Any condition must match */
    $or?: WhereClause<T>[];
    /** Condition must not match */
    $not?: WhereClause<T>;
};
/**
 * Select clause for field projection.
 *
 * @typeParam T - The document type
 *
 * @example
 * ```typescript
 * const select: SelectClause<User> = {
 *   id: true,
 *   name: true,
 *   email: true
 * };
 * ```
 */
export type SelectClause<T> = {
    [K in keyof T]?: boolean;
};
/**
 * Include clause for related documents.
 *
 * @example
 * ```typescript
 * const include: IncludeClause = {
 *   posts: true,
 *   comments: {
 *     include: { author: true },
 *     limit: 10
 *   }
 * };
 * ```
 */
export interface IncludeClause {
    [relation: string]: boolean | IncludeOptions;
}
/**
 * Options for including related documents.
 */
export interface IncludeOptions {
    /** Nested includes */
    include?: IncludeClause;
    /** Filter related documents */
    where?: Record<string, unknown>;
    /** Sort related documents */
    orderBy?: Record<string, 'asc' | 'desc'>;
    /** Limit number of related documents */
    limit?: number;
    /** Skip related documents */
    offset?: number;
}
/**
 * Order by clause for sorting.
 *
 * @typeParam T - The document type
 *
 * @example
 * ```typescript
 * const orderBy: OrderByClause<User> = {
 *   createdAt: 'desc',
 *   name: 'asc'
 * };
 * ```
 */
export type OrderByClause<T> = {
    [K in keyof T]?: 'asc' | 'desc';
};
/**
 * Built query object.
 *
 * @typeParam T - The document type
 */
export interface Query<T> {
    /** Filter conditions */
    where?: WhereClause<T>;
    /** Field selection */
    select?: SelectClause<T>;
    /** Related documents to include */
    include?: IncludeClause;
    /** Sort order */
    orderBy?: OrderByClause<T>;
    /** Maximum number of results */
    limit?: number;
    /** Number of results to skip */
    offset?: number;
}
/**
 * Query builder interface for fluent query construction.
 *
 * @typeParam T - The document type
 *
 * @example
 * ```typescript
 * const query = createQueryBuilder<User>()
 *   .where({ status: 'active' })
 *   .where({ age: { $gte: 18 } })
 *   .orderBy({ createdAt: 'desc' })
 *   .limit(10)
 *   .build();
 * ```
 */
export interface QueryBuilder<T> {
    /**
     * Add a where condition. Multiple calls are combined with AND.
     *
     * @param condition - The filter condition
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.where({ status: 'active' })
     * builder.where({ age: { $gte: 18 } })
     * ```
     */
    where(condition: WhereClause<T>): QueryBuilder<T>;
    /**
     * Add an AND condition explicitly.
     *
     * @param conditions - Array of conditions that must all match
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.and([
     *   { status: 'active' },
     *   { role: 'admin' }
     * ])
     * ```
     */
    and(conditions: WhereClause<T>[]): QueryBuilder<T>;
    /**
     * Add an OR condition.
     *
     * @param conditions - Array of conditions where at least one must match
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.or([
     *   { role: 'admin' },
     *   { permissions: { $contains: 'write' } }
     * ])
     * ```
     */
    or(conditions: WhereClause<T>[]): QueryBuilder<T>;
    /**
     * Filter by exact field equality.
     * Convenience method for simple equality checks.
     *
     * @param field - The field name
     * @param value - The value to match
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.eq('status', 'active')
     * ```
     */
    eq<K extends keyof T>(field: K, value: T[K]): QueryBuilder<T>;
    /**
     * Filter by field not equal to value.
     *
     * @param field - The field name
     * @param value - The value that must not match
     * @returns The builder for chaining
     */
    ne<K extends keyof T>(field: K, value: T[K]): QueryBuilder<T>;
    /**
     * Filter by field greater than value.
     *
     * @param field - The field name
     * @param value - The minimum value (exclusive)
     * @returns The builder for chaining
     */
    gt<K extends keyof T>(field: K, value: T[K]): QueryBuilder<T>;
    /**
     * Filter by field greater than or equal to value.
     *
     * @param field - The field name
     * @param value - The minimum value (inclusive)
     * @returns The builder for chaining
     */
    gte<K extends keyof T>(field: K, value: T[K]): QueryBuilder<T>;
    /**
     * Filter by field less than value.
     *
     * @param field - The field name
     * @param value - The maximum value (exclusive)
     * @returns The builder for chaining
     */
    lt<K extends keyof T>(field: K, value: T[K]): QueryBuilder<T>;
    /**
     * Filter by field less than or equal to value.
     *
     * @param field - The field name
     * @param value - The maximum value (inclusive)
     * @returns The builder for chaining
     */
    lte<K extends keyof T>(field: K, value: T[K]): QueryBuilder<T>;
    /**
     * Filter by field value in array.
     *
     * @param field - The field name
     * @param values - The allowed values
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.in('status', ['active', 'pending'])
     * ```
     */
    in<K extends keyof T>(field: K, values: T[K][]): QueryBuilder<T>;
    /**
     * Filter by field value not in array.
     *
     * @param field - The field name
     * @param values - The disallowed values
     * @returns The builder for chaining
     */
    notIn<K extends keyof T>(field: K, values: T[K][]): QueryBuilder<T>;
    /**
     * Filter by string field containing substring.
     *
     * @param field - The field name
     * @param substring - The substring to search for
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.contains('name', 'john')
     * ```
     */
    contains<K extends keyof T>(field: K, substring: string): QueryBuilder<T>;
    /**
     * Filter by string field starting with prefix.
     *
     * @param field - The field name
     * @param prefix - The prefix to match
     * @returns The builder for chaining
     */
    startsWith<K extends keyof T>(field: K, prefix: string): QueryBuilder<T>;
    /**
     * Filter by string field ending with suffix.
     *
     * @param field - The field name
     * @param suffix - The suffix to match
     * @returns The builder for chaining
     */
    endsWith<K extends keyof T>(field: K, suffix: string): QueryBuilder<T>;
    /**
     * Filter by field between two values (inclusive).
     *
     * @param field - The field name
     * @param min - The minimum value
     * @param max - The maximum value
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.between('age', 18, 65)
     * ```
     */
    between<K extends keyof T>(field: K, min: T[K], max: T[K]): QueryBuilder<T>;
    /**
     * Select specific fields to include in results.
     *
     * @param fields - Field selection object
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.select({ id: true, name: true, email: true })
     * ```
     */
    select(fields: SelectClause<T>): QueryBuilder<T>;
    /**
     * Select only specified field names.
     * Convenience method for positive selection.
     *
     * @param fields - Field names to include
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.only('id', 'name', 'email')
     * ```
     */
    only<K extends keyof T>(...fields: K[]): QueryBuilder<T>;
    /**
     * Exclude specified fields from results.
     *
     * @param fields - Field names to exclude
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.omit('password', 'secret')
     * ```
     */
    omit<K extends keyof T>(...fields: K[]): QueryBuilder<T>;
    /**
     * Include related documents.
     *
     * @param relations - Relations to include
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.include({
     *   posts: true,
     *   comments: { limit: 10 }
     * })
     * ```
     */
    include(relations: IncludeClause): QueryBuilder<T>;
    /**
     * Include a single relation.
     * Convenience method for simple includes.
     *
     * @param relation - The relation name
     * @param options - Optional include options
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.with('posts')
     * builder.with('comments', { limit: 10 })
     * ```
     */
    with(relation: string, options?: IncludeOptions | boolean): QueryBuilder<T>;
    /**
     * Set the sort order.
     *
     * @param order - Sort specification
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.orderBy({ createdAt: 'desc', name: 'asc' })
     * ```
     */
    orderBy(order: OrderByClause<T>): QueryBuilder<T>;
    /**
     * Sort by a single field ascending.
     *
     * @param field - The field to sort by
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.asc('name')
     * ```
     */
    asc<K extends keyof T>(field: K): QueryBuilder<T>;
    /**
     * Sort by a single field descending.
     *
     * @param field - The field to sort by
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.desc('createdAt')
     * ```
     */
    desc<K extends keyof T>(field: K): QueryBuilder<T>;
    /**
     * Limit the number of results.
     *
     * @param count - Maximum number of results
     * @returns The builder for chaining
     */
    limit(count: number): QueryBuilder<T>;
    /**
     * Skip a number of results.
     *
     * @param count - Number of results to skip
     * @returns The builder for chaining
     */
    offset(count: number): QueryBuilder<T>;
    /**
     * Alias for offset.
     *
     * @param count - Number of results to skip
     * @returns The builder for chaining
     */
    skip(count: number): QueryBuilder<T>;
    /**
     * Set pagination with page number and size.
     *
     * @param page - Page number (1-based)
     * @param pageSize - Number of items per page
     * @returns The builder for chaining
     *
     * @example
     * ```typescript
     * builder.page(1, 20) // First 20 items
     * builder.page(2, 20) // Items 21-40
     * ```
     */
    page(page: number, pageSize: number): QueryBuilder<T>;
    /**
     * Get the first N results.
     * Convenience method for limit(n).
     *
     * @param count - Number of results
     * @returns The builder for chaining
     */
    first(count: number): QueryBuilder<T>;
    /**
     * Get a single result.
     * Equivalent to limit(1).
     *
     * @returns The builder for chaining
     */
    one(): QueryBuilder<T>;
    /**
     * Build and return the query object.
     *
     * @returns The built query
     *
     * @example
     * ```typescript
     * const query = builder.build();
     * const results = await collection.find(query.where);
     * ```
     */
    build(): Query<T>;
    /**
     * Clone the current builder state.
     *
     * @returns A new builder with the same state
     *
     * @example
     * ```typescript
     * const base = query().where({ status: 'active' });
     * const admins = base.clone().where({ role: 'admin' });
     * const users = base.clone().where({ role: 'user' });
     * ```
     */
    clone(): QueryBuilder<T>;
    /**
     * Reset the builder to initial state.
     *
     * @returns The builder for chaining
     */
    reset(): QueryBuilder<T>;
}
/**
 * Creates a new query builder instance.
 *
 * @typeParam T - The document type
 * @returns A new query builder
 *
 * @example Basic usage
 * ```typescript
 * const query = createQueryBuilder<User>()
 *   .where({ status: 'active' })
 *   .orderBy({ createdAt: 'desc' })
 *   .limit(10)
 *   .build();
 * ```
 *
 * @example Convenience methods
 * ```typescript
 * const query = createQueryBuilder<User>()
 *   .eq('status', 'active')
 *   .gte('age', 18)
 *   .only('id', 'name', 'email')
 *   .desc('createdAt')
 *   .page(1, 20)
 *   .build();
 * ```
 *
 * @example Complex filtering
 * ```typescript
 * const query = createQueryBuilder<User>()
 *   .where({ status: 'active' })
 *   .or([
 *     { role: 'admin' },
 *     { permissions: { $contains: 'write' } }
 *   ])
 *   .between('age', 18, 65)
 *   .build();
 * ```
 */
export declare function createQueryBuilder<T>(): QueryBuilder<T>;
/**
 * Shorthand for createQueryBuilder.
 *
 * @typeParam T - The document type
 * @returns A new query builder
 *
 * @example
 * ```typescript
 * import { query } from '@db4/db4ai';
 *
 * const q = query<User>()
 *   .eq('status', 'active')
 *   .limit(10)
 *   .build();
 * ```
 */
export declare function query<T>(): QueryBuilder<T>;
/**
 * Static query helper functions for common query patterns.
 */
export declare const Q: {
    /**
     * Create an equality condition.
     *
     * @example
     * ```typescript
     * Q.eq('status', 'active')
     * // { status: { $eq: 'active' } }
     * ```
     */
    eq: <T, K extends keyof T>(field: K, value: T[K]) => WhereClause<T>;
    /**
     * Create a not-equal condition.
     */
    ne: <T, K extends keyof T>(field: K, value: T[K]) => WhereClause<T>;
    /**
     * Create a greater-than condition.
     */
    gt: <T, K extends keyof T>(field: K, value: T[K]) => WhereClause<T>;
    /**
     * Create a greater-than-or-equal condition.
     */
    gte: <T, K extends keyof T>(field: K, value: T[K]) => WhereClause<T>;
    /**
     * Create a less-than condition.
     */
    lt: <T, K extends keyof T>(field: K, value: T[K]) => WhereClause<T>;
    /**
     * Create a less-than-or-equal condition.
     */
    lte: <T, K extends keyof T>(field: K, value: T[K]) => WhereClause<T>;
    /**
     * Create an in-array condition.
     */
    in: <T, K extends keyof T>(field: K, values: T[K][]) => WhereClause<T>;
    /**
     * Create a not-in-array condition.
     */
    nin: <T, K extends keyof T>(field: K, values: T[K][]) => WhereClause<T>;
    /**
     * Create a contains condition.
     */
    contains: <T, K extends keyof T>(field: K, value: string) => WhereClause<T>;
    /**
     * Create a starts-with condition.
     */
    startsWith: <T, K extends keyof T>(field: K, value: string) => WhereClause<T>;
    /**
     * Create an ends-with condition.
     */
    endsWith: <T, K extends keyof T>(field: K, value: string) => WhereClause<T>;
    /**
     * Create a between condition (inclusive).
     */
    between: <T, K extends keyof T>(field: K, min: T[K], max: T[K]) => WhereClause<T>;
    /**
     * Create an AND condition.
     */
    and: <T>(...conditions: WhereClause<T>[]) => WhereClause<T>;
    /**
     * Create an OR condition.
     */
    or: <T>(...conditions: WhereClause<T>[]) => WhereClause<T>;
    /**
     * Create a NOT condition.
     */
    not: <T>(condition: WhereClause<T>) => WhereClause<T>;
    /**
     * Check if a field exists.
     */
    exists: <T, K extends keyof T>(field: K) => WhereClause<T>;
    /**
     * Check if a field does not exist.
     */
    notExists: <T, K extends keyof T>(field: K) => WhereClause<T>;
};
//# sourceMappingURL=query.d.ts.map