elasticlink 0.8.0-beta → 1.0.0-beta.2

package/dist/index.d.cts

@@ -0,0 +1,1890 @@
+import { AggregationsAutoDateHistogramAggregation, AggregationsAverageAggregation, AggregationsBucketScriptAggregation, AggregationsBucketSelectorAggregation, AggregationsCardinalityAggregation, AggregationsCompositeAggregation, AggregationsCompositeAggregationSource, AggregationsCumulativeSumAggregation, AggregationsDateHistogramAggregation, AggregationsDateRangeAggregation, AggregationsDerivativeAggregation, AggregationsExtendedStatsAggregation, AggregationsFiltersAggregation, AggregationsGeoBoundsAggregation, AggregationsGeoCentroidAggregation, AggregationsGeoDistanceAggregation, AggregationsGeoHashGridAggregation, AggregationsGeoTileGridAggregation, AggregationsHistogramAggregation, AggregationsMaxAggregation, AggregationsMinAggregation, AggregationsMissingAggregation, AggregationsMultiTermsAggregation, AggregationsPercentilesAggregation, AggregationsRangeAggregation, AggregationsRareTermsAggregation, AggregationsSignificantTermsAggregation, AggregationsStatsAggregation, AggregationsSumAggregation, AggregationsTermsAggregation, AggregationsTopHitsAggregation, AggregationsTopMetricsAggregation, AggregationsValueCountAggregation, AggregationsWeightedAverageAggregation, AnalysisAnalyzer, AnalysisCharFilter, AnalysisNormalizer, AnalysisTokenFilter, AnalysisTokenizer, BulkCreateOperation, BulkDeleteOperation, BulkIndexOperation, BulkOperationContainer, BulkOperationContainer as BulkOperationContainer$1, BulkUpdateAction, BulkUpdateOperation, IndicesAlias, IndicesIndexSegmentSort, IndicesIndexSettings, IndicesIndexSettingsAnalysis, IndicesSegmentSortMissing, IndicesSegmentSortMode, KnnSearch, MappingDenseVectorIndexOptions, MappingDynamicTemplate, MappingIndexOptions, MappingRuntimeField, MappingSuggestContext, MsearchMultisearchHeader, MsearchRequest, QueryDslCombinedFieldsQuery, QueryDslConstantScoreQuery, QueryDslDistanceFeatureQuery, QueryDslFieldAndFormat, QueryDslFunctionScoreQuery, QueryDslFuzzyQuery, QueryDslHasChildQuery, QueryDslHasParentQuery, QueryDslIntervalsQuery, QueryDslMatchBoolPrefixQuery, QueryDslMatchPhrasePrefixQuery, QueryDslMatchQuery, QueryDslMoreLikeThisQuery, QueryDslMultiMatchQuery, QueryDslNestedQuery, QueryDslParentIdQuery, QueryDslPercolateQuery, QueryDslQueryContainer, QueryDslQueryStringQuery, QueryDslRankFeatureQuery, QueryDslRegexpQuery, QueryDslScriptQuery, QueryDslScriptScoreQuery, QueryDslSimpleQueryStringQuery, QueryDslSpanNearQuery, QueryDslSpanNotQuery, QueryDslSpanQuery, QueryDslSparseVectorQuery, QueryVectorBuilder, RescoreVector, Script, ScriptField, ScriptSource, SearchCompletionContext, SearchCompletionSuggester, SearchDirectGenerator, SearchHighlightBase, SearchInnerHits, SearchPhraseSuggestCollate, SearchPhraseSuggester, SearchSmoothingModelContainer, SearchTermSuggester, SortResults } from "@elastic/elasticsearch/lib/api/types";
+
+//#region src/field.types.d.ts
+/** Options for text fields */
+type TextFieldOptions<MF extends Record<string, FieldMappingWithLiteralType> = Record<string, FieldMappingWithLiteralType>> = {
+  analyzer?: string;
+  search_analyzer?: string;
+  search_quote_analyzer?: string;
+  boost?: number;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  similarity?: string;
+  fields?: MF;
+  copy_to?: string | string[];
+  index_options?: MappingIndexOptions;
+  index_prefixes?: {
+    min_chars?: number;
+    max_chars?: number;
+  };
+  index_phrases?: boolean;
+  eager_global_ordinals?: boolean;
+  position_increment_gap?: number;
+  norms?: boolean;
+  term_vector?: 'no' | 'yes' | 'with_positions' | 'with_offsets' | 'with_positions_offsets' | 'with_positions_payloads' | 'with_positions_offsets_payloads';
+};
+/** Options for keyword fields */
+type KeywordFieldOptions<MF extends Record<string, FieldMappingWithLiteralType> = Record<string, FieldMappingWithLiteralType>> = {
+  boost?: number;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  similarity?: string;
+  normalizer?: string;
+  fields?: MF;
+  copy_to?: string | string[];
+  null_value?: string;
+  eager_global_ordinals?: boolean;
+  ignore_above?: number;
+  split_queries_on_whitespace?: boolean;
+  script?: Script | ScriptSource;
+  on_script_error?: 'fail' | 'continue';
+};
+/** Options shared by numeric field types (long, integer, short, byte, double, float, half_float) */
+type NumericFieldOptions<MF extends Record<string, FieldMappingWithLiteralType> = Record<string, FieldMappingWithLiteralType>> = {
+  boost?: number;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  coerce?: boolean;
+  fields?: MF;
+  copy_to?: string | string[];
+  null_value?: number;
+  ignore_malformed?: boolean;
+};
+/** Options for scaled_float (extends numeric with scaling_factor) */
+type ScaledFloatFieldOptions<MF extends Record<string, FieldMappingWithLiteralType> = Record<string, FieldMappingWithLiteralType>> = NumericFieldOptions<MF> & {
+  scaling_factor?: number;
+};
+/** Options for unsigned_long fields — null_value accepts string or number for >MAX_SAFE_INTEGER precision */
+type UnsignedLongFieldOptions<MF extends Record<string, FieldMappingWithLiteralType> = Record<string, FieldMappingWithLiteralType>> = Omit<NumericFieldOptions<MF>, 'null_value'> & {
+  null_value?: string | number;
+};
+/** Options for date fields */
+type DateFieldOptions<MF extends Record<string, FieldMappingWithLiteralType> = Record<string, FieldMappingWithLiteralType>> = {
+  boost?: number;
+  format?: string;
+  locale?: string;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  fields?: MF;
+  copy_to?: string | string[];
+  null_value?: string;
+  ignore_malformed?: boolean;
+  script?: Script | ScriptSource;
+  on_script_error?: 'fail' | 'continue';
+};
+/**
+ * Options for date_nanos fields — same API as `date` but stores timestamps at nanosecond precision.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/date_nanos.html
+ */
+type DateNanosFieldOptions<MF extends Record<string, FieldMappingWithLiteralType> = Record<string, FieldMappingWithLiteralType>> = DateFieldOptions<MF>;
+/** Options for boolean fields */
+type BooleanFieldOptions = {
+  boost?: number;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  null_value?: boolean;
+};
+/** Options for dense_vector fields */
+type DenseVectorFieldOptions = {
+  dims?: number;
+  element_type?: 'float' | 'byte' | 'bit';
+  index?: boolean;
+  index_options?: MappingDenseVectorIndexOptions;
+  similarity?: 'cosine' | 'dot_product' | 'l2_norm' | 'max_inner_product';
+};
+/**
+ * Options for `rank_feature` fields — a single-value numeric feature used to boost relevance.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/rank-feature.html
+ */
+type RankFeatureFieldOptions = {
+  positive_score_impact?: boolean;
+};
+/**
+ * Options for `rank_features` fields — a sparse map of numeric features used to boost relevance.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/rank-features.html
+ */
+type RankFeaturesFieldOptions = {
+  positive_score_impact?: boolean;
+};
+/**
+ * Options for semantic_text fields (ES 9.x — ML-powered text field for semantic/hybrid search).
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/semantic-text.html
+ */
+type SemanticTextFieldOptions = {
+  inference_id?: string;
+  search_inference_id?: string;
+  model_settings?: {
+    task_type?: string;
+    [key: string]: unknown;
+  };
+};
+/** Options for object fields (sub-fields are the first argument) */
+type ObjectFieldOptions = {
+  enabled?: boolean;
+  dynamic?: boolean | 'strict' | 'runtime';
+};
+/** Options for nested fields (sub-fields are the first argument) */
+type NestedFieldOptions = {
+  enabled?: boolean;
+  dynamic?: boolean | 'strict' | 'runtime';
+  include_in_parent?: boolean;
+  include_in_root?: boolean;
+};
+/** Options for completion fields */
+type CompletionFieldOptions = {
+  analyzer?: string;
+  search_analyzer?: string;
+  max_input_length?: number;
+  preserve_separators?: boolean;
+  preserve_position_increments?: boolean;
+  contexts?: MappingSuggestContext[];
+};
+/** Options for geo_point fields */
+type GeoPointFieldOptions = {
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  ignore_malformed?: boolean;
+  ignore_z_value?: boolean;
+  null_value?: string | {
+    lat: number;
+    lon: number;
+  };
+  copy_to?: string | string[];
+  script?: Script | ScriptSource;
+  on_script_error?: 'fail' | 'continue';
+};
+/** Options for geo_shape fields */
+type GeoShapeFieldOptions = {
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  orientation?: string;
+  ignore_malformed?: boolean;
+};
+/** Options for alias fields */
+type AliasFieldOptions = {
+  path: string;
+};
+/** Options for ip fields */
+type IpFieldOptions = {
+  boost?: number;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  null_value?: string;
+  ignore_malformed?: boolean;
+};
+/**
+ * Options for `ip_range` fields — range of IPv4 or IPv6 addresses.
+ * Mirrors numeric `RangeFieldOptions` but conceptually scoped to IP ranges.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/range.html
+ */
+type IpRangeFieldOptions = {
+  boost?: number;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  coerce?: boolean;
+};
+/** Options for range fields (integer_range, float_range, long_range, double_range, date_range) */
+type RangeFieldOptions = {
+  boost?: number;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  coerce?: boolean;
+};
+/**
+ * Options for match_only_text fields.
+ * Use when you only need filter/match but not relevance scoring — faster and uses less disk.
+ */
+type MatchOnlyTextFieldOptions<MF extends Record<string, FieldMappingWithLiteralType> = Record<string, FieldMappingWithLiteralType>> = {
+  fields?: MF;
+  copy_to?: string | string[];
+  meta?: Record<string, string>;
+};
+/**
+ * Options for search_as_you_type fields.
+ * Provides out-of-the-box autocomplete / typeahead capabilities.
+ */
+type SearchAsYouTypeFieldOptions = {
+  analyzer?: string;
+  search_analyzer?: string;
+  search_quote_analyzer?: string;
+  max_shingle_size?: 2 | 3 | 4;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  similarity?: string;
+  norms?: boolean;
+  term_vector?: 'no' | 'yes' | 'with_positions' | 'with_offsets' | 'with_positions_offsets' | 'with_positions_payloads' | 'with_positions_offsets_payloads';
+};
+/**
+ * Options for constant_keyword fields.
+ * Every document in the index has the same value for this field.
+ * Useful for multi-index queries to identify the index type.
+ */
+type ConstantKeywordFieldOptions = {
+  value?: string;
+};
+/**
+ * Options for wildcard fields.
+ * Optimized for grep-like wildcard/regexp queries on high-cardinality or large fields.
+ * Use instead of keyword when leading wildcards (`*foo`) are needed.
+ */
+type WildcardFieldOptions = {
+  null_value?: string;
+  ignore_above?: number;
+};
+/**
+ * Options for flattened fields.
+ * Flattens complex/dynamic objects into a single field. Faster than nested,
+ * but only supports keyword-level queries on inner values.
+ */
+type FlattenedFieldOptions = {
+  depth_limit?: number;
+  doc_values?: boolean;
+  index?: boolean;
+  null_value?: string;
+  similarity?: string;
+  eager_global_ordinals?: boolean;
+};
+/**
+ * Options for token_count fields — counts the number of tokens in a string.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/token-count.html
+ */
+type TokenCountFieldOptions = {
+  analyzer?: string;
+  boost?: number;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  null_value?: number;
+  enable_position_increments?: boolean;
+};
+/**
+ * Options for join fields — defines parent/child relationships within a single index.
+ * `relations` is required and maps parent names to child names.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/parent-join.html
+ */
+type JoinFieldOptions = {
+  relations: Record<string, string | string[]>;
+  eager_global_ordinals?: boolean;
+};
+type TypedFieldMapping<T extends string> = Omit<FieldMapping, 'type'> & {
+  type: T;
+};
+type FieldMappingWithLiteralType = FieldMapping & {
+  type: FieldTypeString;
+};
+/**
+ * Typed variant of `NestedFieldMapping` carrying sub-field type info at compile time.
+ * Produced when `nested()` is called with a typed field map.
+ */
+type TypedNestedFieldMapping<F extends Record<string, FieldMappingWithLiteralType>> = NestedFieldMapping & Readonly<{
+  _subFields: F;
+}>;
+/**
+ * Typed variant of `ObjectFieldMapping` carrying sub-field type info at compile time.
+ * Produced when `object()` is called with a typed field map.
+ */
+type TypedObjectFieldMapping<F extends Record<string, FieldMappingWithLiteralType>> = ObjectFieldMapping & Readonly<{
+  _subFields: F;
+}>;
+type TextFieldMapping = TypedFieldMapping<'text'>;
+type KeywordFieldMapping = TypedFieldMapping<'keyword'>;
+type LongFieldMapping = TypedFieldMapping<'long'>;
+type IntegerFieldMapping = TypedFieldMapping<'integer'>;
+type ShortFieldMapping = TypedFieldMapping<'short'>;
+type ByteFieldMapping = TypedFieldMapping<'byte'>;
+type DoubleFieldMapping = TypedFieldMapping<'double'>;
+type FloatFieldMapping = TypedFieldMapping<'float'>;
+type HalfFloatFieldMapping = TypedFieldMapping<'half_float'>;
+type ScaledFloatFieldMapping = TypedFieldMapping<'scaled_float'>;
+type DateFieldMapping = TypedFieldMapping<'date'>;
+type BooleanFieldMapping = TypedFieldMapping<'boolean'>;
+type BinaryFieldMapping = TypedFieldMapping<'binary'>;
+type IpFieldMapping = TypedFieldMapping<'ip'>;
+type DenseVectorFieldMapping = TypedFieldMapping<'dense_vector'>;
+type SparseVectorFieldMapping = TypedFieldMapping<'sparse_vector'>;
+type RankFeatureFieldMapping = TypedFieldMapping<'rank_feature'>;
+type RankFeaturesFieldMapping = TypedFieldMapping<'rank_features'>;
+type SemanticTextFieldMapping = TypedFieldMapping<'semantic_text'>;
+type UnsignedLongFieldMapping = TypedFieldMapping<'unsigned_long'>;
+type GeoPointFieldMapping = TypedFieldMapping<'geo_point'>;
+type GeoShapeFieldMapping = TypedFieldMapping<'geo_shape'>;
+type CompletionFieldMapping = TypedFieldMapping<'completion'>;
+type NestedFieldMapping = TypedFieldMapping<'nested'>;
+type ObjectFieldMapping = TypedFieldMapping<'object'>;
+type AliasFieldMapping = TypedFieldMapping<'alias'>;
+type PercolatorFieldMapping = TypedFieldMapping<'percolator'>;
+type IntegerRangeFieldMapping = TypedFieldMapping<'integer_range'>;
+type FloatRangeFieldMapping = TypedFieldMapping<'float_range'>;
+type LongRangeFieldMapping = TypedFieldMapping<'long_range'>;
+type DoubleRangeFieldMapping = TypedFieldMapping<'double_range'>;
+type DateRangeFieldMapping = TypedFieldMapping<'date_range'>;
+type IpRangeFieldMapping = TypedFieldMapping<'ip_range'>;
+type DateNanosFieldMapping = TypedFieldMapping<'date_nanos'>;
+type MatchOnlyTextFieldMapping = TypedFieldMapping<'match_only_text'>;
+type SearchAsYouTypeFieldMapping = TypedFieldMapping<'search_as_you_type'>;
+type ConstantKeywordFieldMapping = TypedFieldMapping<'constant_keyword'>;
+type WildcardFieldMapping = TypedFieldMapping<'wildcard'>;
+type FlattenedFieldMapping = TypedFieldMapping<'flattened'>;
+type TokenCountFieldMapping = TypedFieldMapping<'token_count'>;
+type Murmur3FieldMapping = TypedFieldMapping<'murmur3'>;
+type JoinFieldMapping = TypedFieldMapping<'join'>;
+//#endregion
+//#region src/mapping.types.d.ts
+/**
+ * Options for `mappings()`.
+ *
+ * @param dynamic - Controls how unmapped fields are handled. Defaults to `'strict'`
+ *   to prevent unmapped fields from being silently indexed. Set to `true` to allow
+ *   dynamic mapping, or `'runtime'` for runtime fields.
+ * @param _source - Configure which fields are stored in `_source`.
+ *   Use `{ excludes: ['embedding'] }` to prune large dense_vector fields from
+ *   returned `_source` — they remain searchable via kNN but won't bloat query responses.
+ * @param _meta - Custom metadata to attach to the mapping.
+ */
+type MappingOptions = {
+  dynamic?: boolean | 'strict' | 'runtime';
+  _source?: SourceConfig;
+  _meta?: Record<string, unknown>;
+};
+type MappingsSchema<M extends Record<string, FieldTypeString>, F extends Record<string, FieldMappingWithLiteralType> = Record<string, FieldMappingWithLiteralType>> = Readonly<{
+  _fieldTypes: M;
+  _fields?: F;
+  properties: Record<string, FieldMapping>;
+  _mappingOptions?: MappingOptions;
+}>;
+type ESTypeToTS = {
+  text: string;
+  match_only_text: string;
+  keyword: string;
+  constant_keyword: string;
+  wildcard: string;
+  long: number;
+  integer: number;
+  short: number;
+  byte: number;
+  float: number;
+  double: number;
+  half_float: number;
+  scaled_float: number;
+  date: string;
+  date_nanos: string;
+  boolean: boolean;
+  binary: string;
+  ip: string;
+  geo_point: {
+    lat: number;
+    lon: number;
+  };
+  geo_shape: Record<string, unknown>;
+  dense_vector: number[];
+  sparse_vector: Record<string, number>;
+  semantic_text: string;
+  unsigned_long: number | string;
+  completion: string | {
+    input: string[];
+    weight?: number;
+  };
+  search_as_you_type: string;
+  nested: unknown;
+  object: unknown;
+  flattened: Record<string, unknown>;
+  alias: unknown;
+  percolator: unknown;
+  integer_range: {
+    gte?: number;
+    lte?: number;
+    gt?: number;
+    lt?: number;
+  };
+  float_range: {
+    gte?: number;
+    lte?: number;
+    gt?: number;
+    lt?: number;
+  };
+  long_range: {
+    gte?: number;
+    lte?: number;
+    gt?: number;
+    lt?: number;
+  };
+  double_range: {
+    gte?: number;
+    lte?: number;
+    gt?: number;
+    lt?: number;
+  };
+  date_range: {
+    gte?: string;
+    lte?: string;
+    gt?: string;
+    lt?: string;
+  };
+  ip_range: {
+    gte?: string;
+    lte?: string;
+    gt?: string;
+    lt?: string;
+  } | string;
+  token_count: string | number;
+  murmur3: string;
+  join: string | {
+    name: string;
+    parent?: string;
+  };
+  rank_feature: number;
+  rank_features: Record<string, number>;
+};
+type InferSubFields<F extends Record<string, FieldMappingWithLiteralType>> = { [K in keyof F]: F[K] extends {
+  _subFields: infer Sub extends Record<string, FieldMappingWithLiteralType>;
+} ? F[K] extends {
+  type: 'nested';
+} ? Array<InferSubFields<Sub>> : InferSubFields<Sub> : F[K]['type'] extends keyof ESTypeToTS ? ESTypeToTS[F[K]['type']] : unknown };
+type Infer<S> = S extends MappingsSchema<infer _M, infer F> ? InferSubFields<F> : never;
+type FieldsOfType<M extends Record<string, FieldTypeString>, Types extends FieldTypeString> = { [K in keyof M]: M[K] extends Types ? K : never }[keyof M];
+/**
+ * Removes keys from M that are sub-fields of a `nested` parent.
+ * For example, if `variants` is a nested field, `variants.color` is excluded.
+ * Used to prevent root-level query methods from accepting nested descendants —
+ * those fields must be queried inside a `.nested()` callback instead.
+ */
+type ExcludeNestedDescendants<M extends Record<string, FieldTypeString>> = { [K in keyof M as K extends `${FieldsOfType<M, 'nested'> & string}.${string}` ? never : K]: M[K] };
+type TextFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'text' | 'match_only_text' | 'search_as_you_type'>;
+type KeywordFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'keyword' | 'constant_keyword' | 'wildcard'>;
+type NumericFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'long' | 'integer' | 'short' | 'byte' | 'double' | 'float' | 'half_float' | 'scaled_float' | 'unsigned_long'>;
+type DateFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'date' | 'date_nanos'>;
+type BooleanFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'boolean'>;
+type GeoPointFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'geo_point'>;
+type GeoShapeFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'geo_shape'>;
+/**
+ * Projection covering `rank_feature` and `rank_features` fields — valid targets for
+ * the `rank_feature` query and `distance_feature` (when using the rank_feature origin).
+ */
+type RankFeatureFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'rank_feature' | 'rank_features'>;
+/**
+ * Umbrella projection covering all vector-shaped field types (dense + sparse).
+ * Use the narrower `DenseVectorFields<M>` or `SparseVectorFields<M>` when a
+ * specific vector variant is required (e.g. `.knn()` dense-only, `.sparseVector()` sparse-only).
+ */
+type VectorFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'dense_vector' | 'sparse_vector'>;
+/**
+ * Fields valid as the target of a `.knn()` query — dense vector fields only.
+ * Kept as a dedicated alias so the `.knn()` constraint is explicit and so the broader
+ * `VectorFields<M>` umbrella can grow without loosening `.knn()`.
+ */
+type DenseVectorFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'dense_vector'>;
+/**
+ * Fields valid as the target of a `.sparseVector()` query — sparse vector fields only.
+ * Used by ELSER and other learned-sparse retrieval models.
+ */
+type SparseVectorFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'sparse_vector'>;
+/**
+ * Fields valid as the target of a completion suggester.
+ */
+type CompletionFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'completion'>;
+type IpFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'ip'>;
+/**
+ * Fields valid for sorting in Elasticsearch.
+ * Excludes `object`, `nested`, `dense_vector`, `binary`, `geo_shape`, `geo_point`, and other non-sortable types.
+ * Note: `geo_point` fields require the special `_geo_distance` sort syntax, not a plain field sort.
+ */
+type SortableFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'keyword' | 'constant_keyword' | 'long' | 'integer' | 'short' | 'byte' | 'double' | 'float' | 'half_float' | 'scaled_float' | 'date' | 'boolean' | 'ip'>;
+/**
+ * Fields valid for field collapsing in Elasticsearch.
+ * Collapse requires a keyword or numeric field.
+ */
+type CollapsibleFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'keyword' | 'constant_keyword' | 'long' | 'integer' | 'short' | 'byte' | 'double' | 'float' | 'half_float' | 'scaled_float'>;
+/**
+ * Fields valid for highlighting in Elasticsearch.
+ * Highlighting applies to text-like and keyword fields only.
+ */
+type HighlightableFields<M extends Record<string, FieldTypeString>> = FieldsOfType<ExcludeNestedDescendants<M>, 'text' | 'match_only_text' | 'search_as_you_type' | 'keyword' | 'constant_keyword' | 'wildcard'>;
+/** Maps a single FieldTypeString to its TypeScript value type. Used by Val<M,K> in query constraints. */
+type FieldValueType<T extends FieldTypeString> = T extends keyof ESTypeToTS ? ESTypeToTS[T] : unknown;
+/**
+ * Extracts field names from M that have type `'nested'`.
+ * Used to constrain the `path` argument of `.nested()` to valid nested field names.
+ */
+type NestedPathFields<M extends Record<string, FieldTypeString>> = FieldsOfType<M, 'nested'>;
+/**
+ * Given a parent field path (e.g. `'tags'`), extracts the sub-fields of that path
+ * from the flat expanded M map. Keys like `'tags.label'` become `'label'` in the result.
+ *
+ * Used to provide a typed `ClauseBuilder` for the inner callback of `.nested()`.
+ */
+type SubFieldsOf<M extends Record<string, FieldTypeString>, Path extends string> = { [K in keyof M as K extends `${Path}.${infer Rest}` ? Rest : never]: M[K] & FieldTypeString };
+//#endregion
+//#region src/index-management.types.d.ts
+/**
+ * All supported Elasticsearch field type strings.
+ */
+type FieldTypeString = 'text' | 'match_only_text' | 'keyword' | 'constant_keyword' | 'wildcard' | 'long' | 'integer' | 'short' | 'byte' | 'double' | 'float' | 'half_float' | 'scaled_float' | 'date' | 'date_nanos' | 'boolean' | 'binary' | 'integer_range' | 'float_range' | 'long_range' | 'double_range' | 'date_range' | 'ip_range' | 'ip' | 'alias' | 'object' | 'nested' | 'flattened' | 'geo_point' | 'geo_shape' | 'completion' | 'search_as_you_type' | 'dense_vector' | 'sparse_vector' | 'rank_feature' | 'rank_features' | 'semantic_text' | 'unsigned_long' | 'percolator' | 'token_count' | 'murmur3' | 'join';
+/**
+ * Field mapping definition.
+ */
+type FieldMapping = {
+  type: FieldTypeString;
+  fields?: Record<string, FieldMapping>;
+  analyzer?: string;
+  search_analyzer?: string;
+  boost?: number;
+  index?: boolean;
+  store?: boolean;
+  doc_values?: boolean;
+  similarity?: string;
+  dims?: number;
+  index_options?: any;
+  scaling_factor?: number;
+  properties?: Record<string, FieldMapping>;
+  normalizer?: string;
+  format?: string;
+  coerce?: boolean;
+  enabled?: boolean;
+  element_type?: string;
+  path?: string;
+  max_input_length?: number;
+  preserve_separators?: boolean;
+  preserve_position_increments?: boolean;
+  orientation?: string;
+  copy_to?: string | string[];
+  index_prefixes?: {
+    min_chars?: number;
+    max_chars?: number;
+  };
+  index_phrases?: boolean;
+  ignore_malformed?: boolean;
+  null_value?: string | number | boolean | {
+    lat: number;
+    lon: number;
+  };
+  eager_global_ordinals?: boolean;
+  term_vector?: string;
+  ignore_above?: number;
+  max_shingle_size?: number;
+  value?: string;
+  depth_limit?: number;
+  inference_id?: string;
+  search_inference_id?: string;
+};
+/**
+ * _source field configuration for index mappings.
+ */
+type SourceConfig = {
+  enabled?: boolean;
+  includes?: string[];
+  excludes?: string[];
+};
+/**
+ * Index mappings configuration.
+ */
+type IndexMappings = {
+  properties: Record<string, FieldMapping>;
+  dynamic?: boolean | 'strict' | 'runtime';
+  dynamic_templates?: Partial<Record<string, MappingDynamicTemplate>>[];
+  _source?: SourceConfig;
+  _meta?: Record<string, unknown>;
+};
+/**
+ * Index settings configuration — re-exported from official @elastic/elasticsearch types
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html
+ */
+type IndexSettings = IndicesIndexSettings;
+/**
+ * Create index options
+ */
+type CreateIndexOptions = {
+  mappings?: IndexMappings;
+  settings?: IndexSettings;
+  aliases?: Record<string, IndicesAlias>;
+};
+/**
+ * Custom analyzer definition — passthrough to `AnalysisAnalyzer` from `@elastic/elasticsearch`.
+ * Covers every built-in analyzer (standard, pattern, keyword, language analyzers, ICU, Kuromoji, etc.).
+ */
+type AnalysisAnalyzerConfig = AnalysisAnalyzer;
+/**
+ * Tokenizer passthrough — accepts either a built-in tokenizer name string or a
+ * full `AnalysisTokenizerDefinition`.
+ */
+type AnalysisTokenizerConfig = AnalysisTokenizer;
+/**
+ * Token filter passthrough — accepts either a built-in token filter name string or a
+ * full `AnalysisTokenFilterDefinition`.
+ */
+type AnalysisTokenFilterConfig = AnalysisTokenFilter;
+/**
+ * Char filter passthrough — accepts either a built-in char filter name string or a
+ * full `AnalysisCharFilterDefinition`.
+ */
+type AnalysisCharFilterConfig = AnalysisCharFilter;
+/**
+ * Normalizer passthrough.
+ */
+type AnalysisNormalizerConfig = AnalysisNormalizer;
+/**
+ * Analysis settings for an index — configures custom analyzers, tokenizers, token filters, and char filters.
+ * Passes through `IndicesIndexSettingsAnalysis` from `@elastic/elasticsearch`, unlocking every
+ * built-in and plugin analyzer/tokenizer/filter for free as the Elastic types evolve.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis.html
+ */
+type AnalysisConfig = IndicesIndexSettingsAnalysis;
+/**
+ * Index builder interface.
+ *
+ * The optional generic `M` carries the field-type map of the attached mapping schema,
+ * enabling other builders (or downstream type helpers) to reference the same field
+ * constraints that were used to build the index.
+ */
+type IndexBuilder<M extends Record<string, FieldTypeString> = Record<string, FieldTypeString>> = {
+  mappings: <NewM extends Record<string, FieldTypeString>>(schemaOrFields: MappingsSchema<NewM> | Record<string, FieldMapping>, options?: MappingOptions) => IndexBuilder<NewM>;
+  settings: (settings: IndexSettings) => IndexBuilder<M>; /** Configure custom analyzers, tokenizers, token filters, and char filters for this index. */
+  analysis: (config: AnalysisConfig) => IndexBuilder<M>;
+  alias: (name: string, options?: IndicesAlias) => IndexBuilder<M>;
+  build: () => CreateIndexOptions;
+};
+//#endregion
+//#region src/aggregation.types.d.ts
+/**
+ * Options for terms aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html
+ */
+type TermsAggOptions = Omit<AggregationsTermsAggregation, 'field'>;
+/**
+ * Options for date_histogram aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html
+ */
+type DateHistogramAggOptions = Omit<AggregationsDateHistogramAggregation, 'field'>;
+/**
+ * Options for range aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-range-aggregation.html
+ */
+type RangeAggOptions = Omit<AggregationsRangeAggregation, 'field'>;
+/**
+ * Options for histogram aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-histogram-aggregation.html
+ */
+type HistogramAggOptions = Omit<AggregationsHistogramAggregation, 'field'>;
+/**
+ * Options for avg aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-avg-aggregation.html
+ */
+type AvgAggOptions = Omit<AggregationsAverageAggregation, 'field'>;
+/**
+ * Options for sum aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-sum-aggregation.html
+ */
+type SumAggOptions = Omit<AggregationsSumAggregation, 'field'>;
+/**
+ * Options for min aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-min-aggregation.html
+ */
+type MinAggOptions = Omit<AggregationsMinAggregation, 'field'>;
+/**
+ * Options for max aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-max-aggregation.html
+ */
+type MaxAggOptions = Omit<AggregationsMaxAggregation, 'field'>;
+/**
+ * Options for cardinality aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-cardinality-aggregation.html
+ */
+type CardinalityAggOptions = Omit<AggregationsCardinalityAggregation, 'field'>;
+/**
+ * Options for percentiles aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-percentile-aggregation.html
+ */
+type PercentilesAggOptions = Omit<AggregationsPercentilesAggregation, 'field'>;
+/**
+ * Options for stats aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-stats-aggregation.html
+ */
+type StatsAggOptions = Omit<AggregationsStatsAggregation, 'field'>;
+/**
+ * Options for value_count aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-valuecount-aggregation.html
+ */
+type ValueCountAggOptions = Omit<AggregationsValueCountAggregation, 'field'>;
+/**
+ * Options for extended_stats aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-extendedstats-aggregation.html
+ */
+type ExtendedStatsAggOptions = Omit<AggregationsExtendedStatsAggregation, 'field'>;
+/**
+ * Options for top_hits aggregation
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-top-hits-aggregation.html
+ */
+type TopHitsAggOptions = AggregationsTopHitsAggregation;
+/**
+ * Options for auto_date_histogram aggregation (excludes 'field' which is handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-autodatehistogram-aggregation.html
+ */
+type AutoDateHistogramAggOptions = Omit<AggregationsAutoDateHistogramAggregation, 'field'>;
+/**
+ * Options for date_range aggregation (excludes 'field' which is handled by the builder).
+ * Complement to `range` for date-typed fields; supports date-math expressions in `ranges[].from`/`to`.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-daterange-aggregation.html
+ */
+type DateRangeAggOptions = Omit<AggregationsDateRangeAggregation, 'field'>;
+/**
+ * Options for filters aggregation — multi-filter buckets. Distinct from the single-query
+ * `.filter(name, query)` metric-wrapping aggregation. `filters` creates one named bucket per
+ * supplied query, plus an optional `other_bucket` for non-matches.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-filters-aggregation.html
+ */
+type FiltersAggOptions = Omit<AggregationsFiltersAggregation, 'filters'>;
+/**
+ * Options for significant_terms aggregation (excludes 'field' which is handled by the builder).
+ * Text-analytics staple — returns terms that are statistically significant in the foreground
+ * set relative to the background set.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-significantterms-aggregation.html
+ */
+type SignificantTermsAggOptions = Omit<AggregationsSignificantTermsAggregation, 'field'>;
+/** Options for rare_terms aggregation (excludes 'field' which is handled by the builder) */
+type RareTermsAggOptions = Omit<AggregationsRareTermsAggregation, 'field'>;
+/** Options for multi_terms aggregation — full passthrough (field is inside `terms` array) */
+type MultiTermsAggOptions = AggregationsMultiTermsAggregation;
+/** Options for geo_distance aggregation (excludes 'field' which is handled by the builder) */
+type GeoDistanceAggOptions = Omit<AggregationsGeoDistanceAggregation, 'field'>;
+/** Options for geohash_grid aggregation (excludes 'field' which is handled by the builder) */
+type GeohashGridAggOptions = Omit<AggregationsGeoHashGridAggregation, 'field'>;
+/** Options for geotile_grid aggregation (excludes 'field' which is handled by the builder) */
+type GeotileGridAggOptions = Omit<AggregationsGeoTileGridAggregation, 'field'>;
+/** Options for geo_bounds aggregation (excludes 'field' which is handled by the builder) */
+type GeoBoundsAggOptions = Omit<AggregationsGeoBoundsAggregation, 'field'>;
+/** Options for geo_centroid aggregation (excludes 'field' which is handled by the builder) */
+type GeoCentroidAggOptions = Omit<AggregationsGeoCentroidAggregation, 'field'>;
+/** Options for missing aggregation (excludes 'field' which is handled by the builder) */
+type MissingAggOptions = Omit<AggregationsMissingAggregation, 'field'>;
+/** Options for top_metrics aggregation — full passthrough (metrics and sort in options) */
+type TopMetricsAggOptions = AggregationsTopMetricsAggregation;
+/** Options for weighted_avg aggregation — full passthrough (value and weight in options) */
+type WeightedAvgAggOptions = AggregationsWeightedAverageAggregation;
+/** Options for bucket_script pipeline aggregation — full passthrough */
+type BucketScriptAggOptions = AggregationsBucketScriptAggregation;
+/** Options for bucket_selector pipeline aggregation — full passthrough */
+type BucketSelectorAggOptions = AggregationsBucketSelectorAggregation;
+/** Options for derivative pipeline aggregation — full passthrough */
+type DerivativeAggOptions = AggregationsDerivativeAggregation;
+/** Options for cumulative_sum pipeline aggregation — full passthrough */
+type CumulativeSumAggOptions = AggregationsCumulativeSumAggregation;
+/**
+ * Source entry for composite aggregation — a named single-value source definition
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-composite-aggregation.html
+ */
+type CompositeAggSource = Record<string, AggregationsCompositeAggregationSource>;
+/**
+ * Options for composite aggregation (excludes 'sources' which is handled by the builder)
+ */
+type CompositeAggOptions = Omit<AggregationsCompositeAggregation, 'sources'>;
+/**
+ * Aggregation state for build output
+ */
+type AggregationState = {
+  [key: string]: any;
+};
+/**
+ * Shared metric and bucket aggregation methods.
+ * `Self` is the return type for each method — varies by context (root vs nested).
+ */
+type BaseAggMethods<M extends Record<string, FieldTypeString>, Self> = {
+  terms: <K extends (KeywordFields<M> | NumericFields<M> | BooleanFields<M> | IpFields<M>) & string>(name: string, field: K, options?: TermsAggOptions) => Self;
+  dateHistogram: <K extends DateFields<M> & string>(name: string, field: K, options?: DateHistogramAggOptions) => Self;
+  range: <K extends (NumericFields<M> | DateFields<M>) & string>(name: string, field: K, options?: RangeAggOptions) => Self; /** Date-range aggregation — complement to `range` for date-typed fields. Supports date-math in range bounds. */
+  dateRange: <K extends DateFields<M> & string>(name: string, field: K, options?: DateRangeAggOptions) => Self;
+  /**
+   * Multi-filter aggregation — creates one named bucket per supplied query, plus an optional
+   * `other_bucket` for non-matches. Distinct from the single-query `.filter(name, query)`.
+   */
+  filters: (name: string, filters: Record<string, QueryDslQueryContainer>, options?: FiltersAggOptions) => Self; /** Significant-terms aggregation — statistically significant terms relative to the background set. */
+  significantTerms: <K extends (KeywordFields<M> | TextFields<M>) & string>(name: string, field: K, options?: SignificantTermsAggOptions) => Self;
+  histogram: <K extends NumericFields<M> & string>(name: string, field: K, options?: HistogramAggOptions) => Self;
+  avg: <K extends NumericFields<M> & string>(name: string, field: K, options?: AvgAggOptions) => Self;
+  sum: <K extends NumericFields<M> & string>(name: string, field: K, options?: SumAggOptions) => Self;
+  min: <K extends NumericFields<M> & string>(name: string, field: K, options?: MinAggOptions) => Self;
+  max: <K extends NumericFields<M> & string>(name: string, field: K, options?: MaxAggOptions) => Self;
+  cardinality: <K extends (KeywordFields<M> | TextFields<M> | NumericFields<M> | DateFields<M> | BooleanFields<M> | IpFields<M>) & string>(name: string, field: K, options?: CardinalityAggOptions) => Self;
+  percentiles: <K extends NumericFields<M> & string>(name: string, field: K, options?: PercentilesAggOptions) => Self;
+  stats: <K extends NumericFields<M> & string>(name: string, field: K, options?: StatsAggOptions) => Self;
+  valueCount: <K extends (KeywordFields<M> | TextFields<M> | NumericFields<M> | DateFields<M> | BooleanFields<M> | IpFields<M>) & string>(name: string, field: K, options?: ValueCountAggOptions) => Self;
+  extendedStats: <K extends NumericFields<M> & string>(name: string, field: K, options?: ExtendedStatsAggOptions) => Self;
+  topHits: (name: string, options?: TopHitsAggOptions) => Self;
+  autoDateHistogram: <K extends DateFields<M> & string>(name: string, field: K, options?: AutoDateHistogramAggOptions) => Self;
+  composite: (name: string, sources: CompositeAggSource[], options?: CompositeAggOptions) => Self;
+  filter: (name: string, query: QueryDslQueryContainer) => Self; /** Rare-terms aggregation — returns terms that are rare in the index (inverse of terms). */
+  rareTerms: <K extends (KeywordFields<M> | NumericFields<M> | IpFields<M>) & string>(name: string, field: K, options?: RareTermsAggOptions) => Self; /** Multi-terms aggregation — creates buckets from combinations of multiple field values. */
+  multiTerms: (name: string, options: MultiTermsAggOptions) => Self; /** Geo-distance aggregation — buckets documents by distance from an origin point. */
+  geoDistance: <K extends GeoPointFields<M> & string>(name: string, field: K, options: GeoDistanceAggOptions) => Self; /** Geohash-grid aggregation — groups geo_point values into grid cells. */
+  geohashGrid: <K extends GeoPointFields<M> & string>(name: string, field: K, options?: GeohashGridAggOptions) => Self; /** Geotile-grid aggregation — groups geo_point values into map tile cells. */
+  geotileGrid: <K extends GeoPointFields<M> & string>(name: string, field: K, options?: GeotileGridAggOptions) => Self; /** Geo-bounds aggregation — computes the bounding box containing all geo_point values. */
+  geoBounds: <K extends GeoPointFields<M> & string>(name: string, field: K, options?: GeoBoundsAggOptions) => Self; /** Geo-centroid aggregation — computes the weighted centroid of all geo_point values. */
+  geoCentroid: <K extends GeoPointFields<M> & string>(name: string, field: K, options?: GeoCentroidAggOptions) => Self; /** Missing aggregation — counts documents with missing or null values for a field. */
+  missing: <K extends (KeywordFields<M> | TextFields<M> | NumericFields<M> | DateFields<M> | BooleanFields<M> | IpFields<M>) & string>(name: string, field: K, options?: MissingAggOptions) => Self; /** Top-metrics aggregation — returns the top document's metrics sorted by a given criterion. */
+  topMetrics: (name: string, options: TopMetricsAggOptions) => Self; /** Weighted-average aggregation — computes a weighted average of numeric values. */
+  weightedAvg: (name: string, options: WeightedAvgAggOptions) => Self; /** Bucket-script pipeline aggregation — executes a script on bucket values from other aggs. */
+  bucketScript: (name: string, options: BucketScriptAggOptions) => Self; /** Bucket-selector pipeline aggregation — filters buckets based on a script predicate. */
+  bucketSelector: (name: string, options: BucketSelectorAggOptions) => Self; /** Derivative pipeline aggregation — calculates the derivative of a metric in a parent histogram/date_histogram. */
+  derivative: (name: string, options: DerivativeAggOptions) => Self; /** Cumulative-sum pipeline aggregation — calculates the cumulative sum of a metric in a parent histogram/date_histogram. */
+  cumulativeSum: (name: string, options: CumulativeSumAggOptions) => Self;
+  build: () => AggregationState;
+};
+/**
+ * Root-level aggregation builder. Supports `global` and `nested`; does not expose `reverseNested`.
+ *
+ * Declared as an `interface` (not a `type` alias) so that TypeScript's lazy interface resolution
+ * handles the 3-way mutual recursion between `RootAggregationBuilder`, `NestedEntryBuilder`,
+ * and `NestedAggregationBuilder` without triggering TS2456 (circular type alias).
+ */
+interface RootAggregationBuilder<M extends Record<string, FieldTypeString>> extends BaseAggMethods<M, RootAggregationBuilder<M>> {
+  /** Global aggregation — escapes the current filter context to aggregate across all documents.
+   * @remarks Only valid at the root aggregation level, not inside a nested context. */
+  global: (name: string) => RootAggregationBuilder<M>;
+  /** Nested aggregation — enters a nested document context for aggregating nested fields.
+   * Returns a `NestedEntryBuilder` whose `subAgg` callback receives the nested sub-field types. */
+  nested: <K extends NestedPathFields<M> & string>(name: string, path: K) => NestedEntryBuilder<M, SubFieldsOf<M, K>, RootAggregationBuilder<M>, M>;
+  /** Add sub-aggregation to the last bucket aggregation */
+  subAgg: (fn: (agg: RootAggregationBuilder<M>) => RootAggregationBuilder<M>) => RootAggregationBuilder<M>;
+}
+/**
+ * Returned by `.nested()` on a root or nested builder.
+ *
+ * Dual-context design: metric/bucket helpers inherited from `BaseAggMethods<M, R>` operate
+ * on the parent field map `M` (sibling aggregations), while the `subAgg` callback is typed
+ * to `NestedAggregationBuilder<N>`, giving it access only to the nested sub-fields `N`.
+ *
+ * `R` is the parent context — `RootAggregationBuilder<M>` when called from root,
+ * `NestedAggregationBuilder<M>` when called from inside a nested context.
+ */
+interface NestedEntryBuilder<M extends Record<string, FieldTypeString>, N extends Record<string, FieldTypeString>, R = RootAggregationBuilder<M>, Root extends Record<string, FieldTypeString> = M> extends BaseAggMethods<M, R> {
+  global: (name: string) => RootAggregationBuilder<M>;
+  nested: <K extends NestedPathFields<M> & string>(name: string, path: K) => NestedEntryBuilder<M, SubFieldsOf<M, K>, R, Root>;
+  subAgg: (fn: (agg: NestedAggregationBuilder<N, Root>) => NestedAggregationBuilder<N, Root>) => R;
+}
+/**
+ * Nested-context aggregation builder. Supports `reverseNested` and nested-level `nested`;
+ * does not expose `global`.
+ */
+interface NestedAggregationBuilder<N extends Record<string, FieldTypeString>, Root extends Record<string, FieldTypeString> = N> extends BaseAggMethods<N, NestedAggregationBuilder<N, Root>> {
+  /** Nested aggregation within a nested context — supports multi-level nesting */
+  nested: <K extends NestedPathFields<N> & string>(name: string, path: K) => NestedEntryBuilder<N, SubFieldsOf<N, K>, NestedAggregationBuilder<N, Root>, Root>;
+  /** Reverse nested aggregation — returns from a nested context back to the root document.
+   * @remarks Only valid inside a nested aggregation context. */
+  reverseNested: (name: string, path?: string) => NestedAggregationBuilder<Root, Root>;
+  /** Add sub-aggregation to the last bucket aggregation */
+  subAgg: (fn: (agg: NestedAggregationBuilder<N, Root>) => NestedAggregationBuilder<N, Root>) => NestedAggregationBuilder<N, Root>;
+}
+//#endregion
+//#region src/vector.types.d.ts
+/**
+ * Options for KNN (k-nearest neighbors) query (excludes 'field' and 'query_vector' which are handled by the builder)
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/knn-search.html
+ */
+type KnnOptions = Omit<KnnSearch, 'field' | 'query_vector'>;
+//#endregion
+//#region src/suggester.types.d.ts
+/**
+ * Phrase suggester direct-generator config — re-exported from official @elastic/elasticsearch types.
+ * Used in `PhraseSuggesterOptions.direct_generator`.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html#phrase-suggester
+ */
+type PhraseSuggestDirectGenerator = SearchDirectGenerator;
+/**
+ * Phrase suggester collate config — re-exported from official @elastic/elasticsearch types.
+ * Used in `PhraseSuggesterOptions.collate` to run a query against each candidate phrase.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html#_collate
+ */
+type PhraseSuggestCollate = SearchPhraseSuggestCollate;
+/**
+ * Phrase suggester smoothing-model container — re-exported from official @elastic/elasticsearch types.
+ * Used in `PhraseSuggesterOptions.smoothing`.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html#_smoothing_models
+ */
+type PhraseSuggestSmoothingModel = SearchSmoothingModelContainer;
+/**
+ * Completion suggester context — re-exported from official @elastic/elasticsearch types.
+ * Used in `CompletionSuggesterOptions.contexts`.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/suggester-context.html
+ */
+type CompletionSuggestContext = SearchCompletionContext;
+/**
+ * Options for term suggester — mirrors the official `SearchTermSuggester` type.
+ * `field`, `text`, and `prefix` are omitted because they are supplied by the builder
+ * as explicit arguments (`field` is re-added below, narrowed to the mapping schema).
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html#term-suggester
+ */
+type TermSuggesterOptions<M extends Record<string, FieldTypeString>> = Omit<SearchTermSuggester, 'field' | 'text' | 'prefix'> & {
+  field: (TextFields<M> | KeywordFields<M>) & string;
+};
+/**
+ * Options for phrase suggester — mirrors the official `SearchPhraseSuggester` type
+ * with `field`, `text`, and `prefix` removed (builder-owned).
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html#phrase-suggester
+ */
+type PhraseSuggesterOptions<M extends Record<string, FieldTypeString>> = Omit<SearchPhraseSuggester, 'field' | 'text' | 'prefix'> & {
+  field: (TextFields<M> | KeywordFields<M>) & string;
+};
+/**
+ * Options for completion suggester — mirrors the official `SearchCompletionSuggester` type
+ * with `field`, `text`, and `prefix` removed (builder-owned).
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html#completion-suggester
+ */
+type CompletionSuggesterOptions<M extends Record<string, FieldTypeString>> = Omit<SearchCompletionSuggester, 'field' | 'text' | 'prefix'> & {
+  field: CompletionFields<M> & string;
+};
+/**
+ * Suggester state for build output.
+ *
+ * The state carries the suggester DSL as Elasticsearch accepts it — options still
+ * embed `field` internally after the builder writes them, since that is how the
+ * underlying wire format works. The type-safety benefit lives at the method
+ * boundary: callers cannot pass a non-existent field to `.term()`/`.phrase()`/`.completion()`.
+ */
+type SuggesterState = {
+  [suggesterName: string]: {
+    text?: string;
+    prefix?: string;
+    term?: Omit<SearchTermSuggester, 'text' | 'prefix'>;
+    phrase?: Omit<SearchPhraseSuggester, 'text' | 'prefix'>;
+    completion?: Omit<SearchCompletionSuggester, 'text' | 'prefix'>;
+  };
+};
+/**
+ * Suggester builder interface
+ */
+type SuggesterBuilder<M extends Record<string, FieldTypeString>> = {
+  /** Term suggester - suggests corrections for individual terms */term: (name: string, text: string, options: TermSuggesterOptions<M>) => SuggesterBuilder<M>; /** Phrase suggester - suggests corrections for entire phrases */
+  phrase: (name: string, text: string, options: PhraseSuggesterOptions<M>) => SuggesterBuilder<M>; /** Completion suggester - autocomplete functionality */
+  completion: (name: string, prefix: string, options: CompletionSuggesterOptions<M>) => SuggesterBuilder<M>; /** Build suggester DSL */
+  build: () => {
+    suggest: SuggesterState;
+  };
+};
+//#endregion
+//#region src/query.types.d.ts
+type MatchOptions = Omit<QueryDslMatchQuery, 'query'>;
+type MultiMatchOptions = Omit<QueryDslMultiMatchQuery, 'query' | 'fields'>;
+type FuzzyOptions = Omit<QueryDslFuzzyQuery, 'value'>;
+type HighlightOptions = SearchHighlightBase;
+type RegexpOptions = Omit<QueryDslRegexpQuery, 'value'>;
+type ConstantScoreOptions = Omit<QueryDslConstantScoreQuery, 'filter'>;
+type MatchPhrasePrefixOptions = Omit<QueryDslMatchPhrasePrefixQuery, 'query'>;
+type GeoDistanceOptions = {
+  distance: string | number;
+  unit?: 'mi' | 'km' | 'mm' | 'cm' | 'm' | 'yd' | 'ft' | 'in' | 'nmi';
+  distance_type?: 'arc' | 'plane';
+};
+type GeoBoundingBoxOptions = {
+  top_left?: {
+    lat: number;
+    lon: number;
+  };
+  bottom_right?: {
+    lat: number;
+    lon: number;
+  };
+  top?: number;
+  left?: number;
+  bottom?: number;
+  right?: number;
+};
+type GeoPolygonOptions = {
+  points: Array<{
+    lat: number;
+    lon: number;
+  }>;
+};
+type GeoShapeQueryOptions = {
+  relation?: 'intersects' | 'disjoint' | 'within' | 'contains';
+  boost?: number;
+  ignore_unmapped?: boolean;
+};
+type ScriptOptions = Script;
+type ScriptQueryOptions = Script & Omit<QueryDslScriptQuery, 'script'>;
+type ScriptScoreOptions = Omit<QueryDslScriptScoreQuery, 'query' | 'script'>;
+type PercolateOptions = QueryDslPercolateQuery;
+type CombinedFieldsOptions = Omit<QueryDslCombinedFieldsQuery, 'query' | 'fields'>;
+type QueryStringOptions = Omit<QueryDslQueryStringQuery, 'query'>;
+type SimpleQueryStringOptions = Omit<QueryDslSimpleQueryStringQuery, 'query'>;
+type MoreLikeThisOptions = Omit<QueryDslMoreLikeThisQuery, 'fields' | 'like'>;
+type MatchBoolPrefixOptions = Omit<QueryDslMatchBoolPrefixQuery, 'query'>;
+type NestedOptions = Omit<QueryDslNestedQuery, 'path' | 'query'>;
+type FunctionScoreOptions = Omit<QueryDslFunctionScoreQuery, 'query'>;
+type HasChildOptions = Omit<QueryDslHasChildQuery, 'query' | 'type'>;
+type HasParentOptions = Omit<QueryDslHasParentQuery, 'query' | 'parent_type'>;
+type ParentIdOptions = Omit<QueryDslParentIdQuery, 'id' | 'type'>;
+/**
+ * Options for the `intervals` query — the field is supplied as the first argument.
+ * The value is the full `QueryDslIntervalsQuery` rule (match, prefix, wildcard, fuzzy, all_of, any_of, etc.).
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-intervals-query.html
+ */
+type IntervalsOptions = QueryDslIntervalsQuery;
+/**
+ * Options for `spanNear` — `clauses` is supplied as the first argument.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-span-near-query.html
+ */
+type SpanNearOptions = Omit<QueryDslSpanNearQuery, 'clauses'>;
+/**
+ * Options for `spanNot` — `include` and `exclude` are supplied as the first two arguments.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-span-not-query.html
+ */
+type SpanNotOptions = Omit<QueryDslSpanNotQuery, 'include' | 'exclude'>;
+/** Re-export the Elastic span query container for composing span clauses. */
+type SpanQuery = QueryDslSpanQuery;
+/**
+ * Options for the `distance_feature` query — boosts documents by proximity of a
+ * `date`, `date_nanos`, or `geo_point` field to a given origin. The builder
+ * supplies `field` as an explicit argument and constrains it to date/geo fields.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-distance-feature-query.html
+ */
+type DistanceFeatureOptions = Omit<QueryDslDistanceFeatureQuery, 'field'>;
+/**
+ * Options for the `rank_feature` query — boosts relevance using a numeric feature
+ * stored in a `rank_feature` or `rank_features` field. The builder supplies
+ * `field` as an explicit argument.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-rank-feature-query.html
+ */
+type RankFeatureQueryOptions = Omit<QueryDslRankFeatureQuery, 'field'>;
+/**
+ * Options for the `sparse_vector` query — scores documents using token-weight
+ * vectors produced by a learned sparse model (e.g. ELSER). The builder supplies
+ * `field` as an explicit argument.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-sparse-vector-query.html
+ */
+type SparseVectorQueryOptions = Omit<QueryDslSparseVectorQuery, 'field'>;
+type TermableFields<M extends Record<string, FieldTypeString>> = KeywordFields<M> | NumericFields<M> | DateFields<M> | BooleanFields<M> | IpFields<M>;
+type RangeableFields<M extends Record<string, FieldTypeString>> = NumericFields<M> | DateFields<M> | KeywordFields<M> | IpFields<M>;
+type FuzzyableFields<M extends Record<string, FieldTypeString>> = TextFields<M> | KeywordFields<M>;
+type Val<M extends Record<string, FieldTypeString>, K extends keyof M> = FieldValueType<M[K]>;
+type QueryState<M extends Record<string, FieldTypeString>> = {
+  _includeQuery?: boolean;
+  query?: QueryDslQueryContainer;
+  knn?: {
+    field: string;
+    query_vector?: number[];
+    query_vector_builder?: QueryVectorBuilder;
+    k?: number;
+    num_candidates?: number;
+    filter?: QueryDslQueryContainer | QueryDslQueryContainer[];
+    boost?: number;
+    similarity?: number;
+    inner_hits?: SearchInnerHits;
+    rescore_vector?: RescoreVector;
+    visit_percentage?: number;
+  };
+  aggs?: AggregationState;
+  suggest?: SuggesterState;
+  from?: number;
+  size?: number;
+  sort?: Array<Record<string, 'asc' | 'desc'>>;
+  _source?: Array<string & keyof M>;
+  timeout?: string;
+  track_scores?: boolean;
+  explain?: boolean;
+  min_score?: number;
+  version?: boolean;
+  seq_no_primary_term?: boolean;
+  track_total_hits?: boolean | number;
+  highlight?: {
+    fields: Record<string, HighlightOptions>;
+    pre_tags?: string[];
+    post_tags?: string[];
+  };
+  search_after?: SortResults;
+  preference?: string;
+  collapse?: {
+    field: string;
+    inner_hits?: SearchInnerHits;
+    max_concurrent_group_searches?: number;
+  };
+  rescore?: {
+    window_size: number;
+    query: {
+      rescore_query: QueryDslQueryContainer;
+      query_weight?: number;
+      rescore_query_weight?: number;
+      score_mode?: 'total' | 'multiply' | 'avg' | 'max' | 'min';
+    };
+  };
+  stored_fields?: Array<string>;
+  terminate_after?: number;
+  pit?: {
+    id: string;
+    keep_alive: string;
+  };
+  indices_boost?: Array<Record<string, number>>;
+  runtime_mappings?: Record<string, MappingRuntimeField>;
+  docvalue_fields?: Array<QueryDslFieldAndFormat | string>;
+  fields?: Array<QueryDslFieldAndFormat | string>;
+  post_filter?: QueryDslQueryContainer;
+  script_fields?: Record<string, ScriptField>;
+  _source_includes?: string[];
+  _source_excludes?: string[];
+};
+type ClauseBuilder<M extends Record<string, FieldTypeString>> = {
+  matchAll: () => any;
+  matchNone: () => any;
+  match: <K extends TextFields<M> & string>(field: K, value: string, options?: MatchOptions) => any;
+  multiMatch: <K extends TextFields<M> & string>(fields: K[], value: string, options?: MultiMatchOptions) => any;
+  matchPhrase: <K extends TextFields<M> & string>(field: K, value: string) => any;
+  matchPhrasePrefix: <K extends TextFields<M> & string>(field: K, value: string, options?: MatchPhrasePrefixOptions) => any;
+  term: <K extends TermableFields<M> & string>(field: K, value: Val<M, K>) => any;
+  terms: <K extends TermableFields<M> & string>(field: K, value: Array<Val<M, K>>) => any;
+  range: <K extends RangeableFields<M> & string>(field: K, conditions: {
+    gte?: Val<M, K>;
+    lte?: Val<M, K>;
+    gt?: Val<M, K>;
+    lt?: Val<M, K>;
+  }) => any;
+  exists: <K extends string & keyof M>(field: K) => any;
+  prefix: <K extends KeywordFields<M> & string>(field: K, value: string) => any;
+  wildcard: <K extends KeywordFields<M> & string>(field: K, value: string) => any;
+  fuzzy: <K extends FuzzyableFields<M> & string>(field: K, value: string, options?: FuzzyOptions) => any;
+  ids: (values: string[]) => any;
+  knn: <K extends DenseVectorFields<M> & string>(field: K, queryVector: number[], options: KnnOptions) => any;
+  regexp: <K extends KeywordFields<M> & string>(field: K, value: string, options?: RegexpOptions) => any;
+  geoDistance: <K extends GeoPointFields<M> & string>(field: K, center: {
+    lat: number;
+    lon: number;
+  }, options: GeoDistanceOptions) => any;
+  geoBoundingBox: <K extends GeoPointFields<M> & string>(field: K, options: GeoBoundingBoxOptions) => any;
+  geoPolygon: <K extends GeoPointFields<M> & string>(field: K, options: GeoPolygonOptions) => any;
+  geoShape: <K extends GeoShapeFields<M> & string>(field: K, shape: Record<string, unknown>, options?: GeoShapeQueryOptions) => any; /** Distance-feature query — boost relevance by proximity of a date or geo_point field to an origin. */
+  distanceFeature: <K extends (DateFields<M> | GeoPointFields<M>) & string>(field: K, options: DistanceFeatureOptions) => any; /** Rank-feature query — boost relevance using a numeric feature in a `rank_feature`/`rank_features` field. */
+  rankFeature: <K extends RankFeatureFields<M> & string>(field: K, options?: RankFeatureQueryOptions) => any; /** Sparse-vector query — score with token-weight pairs from a learned sparse model (e.g. ELSER). */
+  sparseVector: <K extends SparseVectorFields<M> & string>(field: K, options: SparseVectorQueryOptions) => any;
+  /**
+   * Script query — executes a Painless script to filter documents.
+   *
+   * **Security:** the `source` string is executed as Painless on the Elasticsearch cluster.
+   * Never derive `source` from untrusted user input — use `params` to pass runtime values safely instead.
+   */
+  script: (options: ScriptQueryOptions) => any;
+  combinedFields: <K extends TextFields<M> & string>(fields: K[], query: string, options?: CombinedFieldsOptions) => any;
+  /**
+   * Query string query — parses a Lucene query syntax string.
+   *
+   * **Security:** if `query` is derived from untrusted user input, field-level access control and
+   * syntax errors may expose internal field names or cause unexpected query behaviour.
+   * Prefer `simpleQueryString` for user-facing search boxes — it silently ignores invalid syntax.
+   */
+  queryString: (query: string, options?: QueryStringOptions) => any;
+  /**
+   * Simple query string query — a safer Lucene subset for user-facing search.
+   *
+   * **Security:** invalid syntax is silently ignored rather than returning an error.
+   * Still constrain which fields are searched via `options.fields` to avoid exposing sensitive fields.
+   */
+  simpleQueryString: (query: string, options?: SimpleQueryStringOptions) => any;
+  moreLikeThis: (fields: Array<(TextFields<M> | KeywordFields<M>) & string>, like: string | Array<string | {
+    _index: string;
+    _id: string;
+  }>, options?: MoreLikeThisOptions) => any;
+  matchBoolPrefix: <K extends TextFields<M> & string>(field: K, value: string, options?: MatchBoolPrefixOptions) => any;
+  /**
+   * Conditionally execute a clause. Returns the clause DSL when `condition` is truthy, `undefined` otherwise.
+   * The parent bool method (`must`, `filter`, etc.) treats `undefined` as a no-op — no empty arrays are emitted.
+   *
+   * `condition` is resolved as follows: functions are called, booleans are used as-is,
+   * and any other value is checked for nullishness (`!= null`) — so `0` and `''` are truthy.
+   *
+   * **Note:** TypeScript cannot narrow closure variables inside callbacks, so values typed as `T | undefined`
+   * still require a non-null assertion (`!`) inside the callback even when `condition` guarantees they are defined:
+   * ```ts
+   * .must(q => q.when(searchTerm, q => q.match('name', searchTerm!)))
+   * ```
+   */
+  /**
+   * Nested query inside a clause context — use inside `must`, `filter`, `should`, or `mustNot`.
+   *
+   * ```ts
+   * queryBuilder(m).bool().filter(q => q.nested('variants', qn => qn.term('color', 'red')))
+   * ```
+   */
+  nested: <K extends NestedPathFields<M> & string>(path: K, fn: (q: ClauseBuilder<SubFieldsOf<M, K>>) => any, options?: NestedOptions) => any; /** Function score query — wraps an inner query and applies scoring functions (field_value_factor, decay, script_score, etc.). */
+  functionScore: (query: (q: ClauseBuilder<M>) => any, options?: FunctionScoreOptions) => any; /** Has-child query — returns parent documents whose child documents match the inner query. */
+  hasChild: (type: string, query: (q: ClauseBuilder<M>) => any, options?: HasChildOptions) => any; /** Has-parent query — returns child documents whose parent document matches the inner query. */
+  hasParent: (type: string, query: (q: ClauseBuilder<M>) => any, options?: HasParentOptions) => any; /** Parent-ID query — returns child documents joined to a specific parent document. */
+  parentId: (type: string, id: string, options?: ParentIdOptions) => any; /** Intervals query — returns documents based on the order and proximity of matching terms. */
+  intervals: <K extends TextFields<M> & string>(field: K, options: IntervalsOptions) => any; /** Span term — matches a single term; the building block for other span queries. */
+  spanTerm: <K extends TextFields<M> & string>(field: K, value: string) => any; /** Span near — matches spans that are near one another. */
+  spanNear: (clauses: ReadonlyArray<SpanQuery>, options?: SpanNearOptions) => any; /** Span or — matches the union of its span clauses. */
+  spanOr: (clauses: ReadonlyArray<SpanQuery>) => any; /** Span not — removes matches that overlap with another span query. */
+  spanNot: (include: SpanQuery, exclude: SpanQuery, options?: SpanNotOptions) => any; /** Span first — matches spans near the beginning of a field. */
+  spanFirst: (match: SpanQuery, end: number) => any; /** Span containing — returns matches from `big` that contain a match from `little`. */
+  spanContaining: (big: SpanQuery, little: SpanQuery) => any; /** Span within — returns matches from `little` that fall within `big`. */
+  spanWithin: (big: SpanQuery, little: SpanQuery) => any; /** Span multi-term — wraps a multi-term query (wildcard, fuzzy, prefix, range, or regexp) as a span query. */
+  spanMultiTerm: (query: Record<string, unknown>) => any; /** Span field masking — allows queries on different fields to be combined. */
+  spanFieldMasking: (field: string, query: SpanQuery) => any;
+  when: (condition: unknown, thenFn: (q: ClauseBuilder<M>) => any) => any | undefined;
+};
+type QueryBuilder<M extends Record<string, FieldTypeString>> = {
+  bool: () => QueryBuilder<M>;
+  must: (fn: (q: ClauseBuilder<M>) => any) => QueryBuilder<M>;
+  mustNot: (fn: (q: ClauseBuilder<M>) => any) => QueryBuilder<M>;
+  should: (fn: (q: ClauseBuilder<M>) => any) => QueryBuilder<M>;
+  filter: (fn: (q: ClauseBuilder<M>) => any) => QueryBuilder<M>;
+  minimumShouldMatch: (n: number) => QueryBuilder<M>;
+  matchAll: () => QueryBuilder<M>;
+  matchNone: () => QueryBuilder<M>;
+  match: <K extends TextFields<M> & string>(field: K, value: string, options?: MatchOptions) => QueryBuilder<M>;
+  multiMatch: <K extends TextFields<M> & string>(fields: K[], value: string, options?: MultiMatchOptions) => QueryBuilder<M>;
+  matchPhrase: <K extends TextFields<M> & string>(field: K, value: string) => QueryBuilder<M>;
+  matchPhrasePrefix: <K extends TextFields<M> & string>(field: K, value: string, options?: MatchPhrasePrefixOptions) => QueryBuilder<M>;
+  term: <K extends TermableFields<M> & string>(field: K, value: Val<M, K>) => QueryBuilder<M>;
+  terms: <K extends TermableFields<M> & string>(field: K, values: Array<Val<M, K>>) => QueryBuilder<M>;
+  range: <K extends RangeableFields<M> & string>(field: K, conditions: {
+    gte?: Val<M, K>;
+    lte?: Val<M, K>;
+    gt?: Val<M, K>;
+    lt?: Val<M, K>;
+  }) => QueryBuilder<M>;
+  exists: (field: string & keyof M) => QueryBuilder<M>;
+  prefix: <K extends KeywordFields<M> & string>(field: K, value: string) => QueryBuilder<M>;
+  wildcard: <K extends KeywordFields<M> & string>(field: K, value: string) => QueryBuilder<M>;
+  fuzzy: <K extends FuzzyableFields<M> & string>(field: K, value: string, options?: FuzzyOptions) => QueryBuilder<M>;
+  ids: (values: string[]) => QueryBuilder<M>;
+  /**
+   * Nested query — for querying fields mapped as `nested()`.
+   *
+   * Each nested object is stored as a separate hidden document. The `.nested()` wrapper
+   * is required for Elasticsearch to search those hidden documents correctly. Without it,
+   * queries against nested sub-fields will return no results.
+   *
+   * The inner callback receives a typed `ClauseBuilder` constrained to the sub-fields of
+   * `path`, so field names and value types are checked at compile time.
+   *
+   * For `object()` fields, no wrapper is needed — query sub-fields directly with dot-notation
+   * (e.g. `.term('address.city', 'NYC')`).
+   */
+  nested: <K extends NestedPathFields<M> & string>(path: K, fn: (q: ClauseBuilder<SubFieldsOf<M, K>>) => any, options?: NestedOptions) => QueryBuilder<M>;
+  knn: <K extends DenseVectorFields<M> & string>(field: K, queryVector: number[], options: KnnOptions) => QueryBuilder<M>;
+  /**
+   * Script query — executes a Painless script to filter documents.
+   *
+   * **Security:** the `source` string is executed as Painless on the Elasticsearch cluster.
+   * Never derive `source` from untrusted user input — use `params` to pass runtime values safely instead.
+   */
+  script: (options: ScriptQueryOptions) => QueryBuilder<M>;
+  /**
+   * Script score query — wraps an inner query and rescores results using a Painless script.
+   *
+   * **Security:** the `source` string is executed as Painless on the Elasticsearch cluster.
+   * Never derive `source` from untrusted user input — use `params` to pass runtime values safely instead.
+   */
+  scriptScore: (query: (q: ClauseBuilder<M>) => any, script: ScriptOptions, options?: ScriptScoreOptions) => QueryBuilder<M>;
+  percolate: (options: PercolateOptions) => QueryBuilder<M>; /** Function score query — wraps an inner query and applies scoring functions (field_value_factor, decay, script_score, etc.). */
+  functionScore: (query: (q: ClauseBuilder<M>) => any, options?: FunctionScoreOptions) => QueryBuilder<M>; /** Has-child query — returns parent documents whose child documents match the inner query. */
+  hasChild: (type: string, query: (q: ClauseBuilder<M>) => any, options?: HasChildOptions) => QueryBuilder<M>; /** Has-parent query — returns child documents whose parent document matches the inner query. */
+  hasParent: (type: string, query: (q: ClauseBuilder<M>) => any, options?: HasParentOptions) => QueryBuilder<M>; /** Parent-ID query — returns child documents joined to a specific parent document. */
+  parentId: (type: string, id: string, options?: ParentIdOptions) => QueryBuilder<M>; /** Intervals query — returns documents based on the order and proximity of matching terms. */
+  intervals: <K extends TextFields<M> & string>(field: K, options: IntervalsOptions) => QueryBuilder<M>; /** Span term — matches a single term; the building block for other span queries. */
+  spanTerm: <K extends TextFields<M> & string>(field: K, value: string) => QueryBuilder<M>; /** Span near — matches spans that are near one another. */
+  spanNear: (clauses: ReadonlyArray<SpanQuery>, options?: SpanNearOptions) => QueryBuilder<M>; /** Span or — matches the union of its span clauses. */
+  spanOr: (clauses: ReadonlyArray<SpanQuery>) => QueryBuilder<M>; /** Span not — removes matches that overlap with another span query. */
+  spanNot: (include: SpanQuery, exclude: SpanQuery, options?: SpanNotOptions) => QueryBuilder<M>; /** Span first — matches spans near the beginning of a field. */
+  spanFirst: (match: SpanQuery, end: number) => QueryBuilder<M>; /** Span containing — returns matches from `big` that contain a match from `little`. */
+  spanContaining: (big: SpanQuery, little: SpanQuery) => QueryBuilder<M>; /** Span within — returns matches from `little` that fall within `big`. */
+  spanWithin: (big: SpanQuery, little: SpanQuery) => QueryBuilder<M>; /** Span multi-term — wraps a multi-term query (wildcard, fuzzy, prefix, range, or regexp) as a span query. */
+  spanMultiTerm: (query: Record<string, unknown>) => QueryBuilder<M>; /** Span field masking — allows queries on different fields to be combined. */
+  spanFieldMasking: (field: string, query: SpanQuery) => QueryBuilder<M>;
+  /**
+   * Conditionally apply a branch to the query chain. Returns the result of `thenFn` when `condition` is truthy,
+   * otherwise returns the current builder unchanged — the chain is never broken.
+   *
+   * `condition` is resolved as follows: functions are called, booleans are used as-is,
+   * and any other value is checked for nullishness (`!= null`) — so `0` and `''` are truthy.
+   *
+   * **Note:** TypeScript cannot narrow closure variables inside callbacks, so values typed as `T | undefined`
+   * still require a non-null assertion (`!`) inside the callback even when `condition` guarantees they are defined:
+   * ```ts
+   * queryBuilder(m).bool()
+   *   .when(searchTerm, q => q.must(q2 => q2.match('name', searchTerm!)))
+   *   .when(minPrice, q => q.filter(q2 => q2.range('price', { gte: minPrice! })))
+   *   .build()
+   * ```
+   */
+  when: (condition: unknown, thenFn: (q: QueryBuilder<M>) => QueryBuilder<M>) => QueryBuilder<M>;
+  aggs: (fn: (agg: RootAggregationBuilder<M>) => RootAggregationBuilder<M>) => QueryBuilder<M>;
+  suggest: (fn: (s: SuggesterBuilder<M>) => SuggesterBuilder<M>) => QueryBuilder<M>;
+  sort: (field: (SortableFields<M> & string) | '_score' | '_doc', direction: 'asc' | 'desc') => QueryBuilder<M>;
+  from: (from: number) => QueryBuilder<M>;
+  size: (size: number) => QueryBuilder<M>;
+  _source: (fields: Array<string & keyof M>) => QueryBuilder<M>; /** Include-only subset for `_source` filtering (paths may use wildcards). */
+  sourceIncludes: (paths: string[]) => QueryBuilder<M>; /** Exclude subset for `_source` filtering (paths may use wildcards). */
+  sourceExcludes: (paths: string[]) => QueryBuilder<M>; /** Runtime mappings — define script-computed fields available to the query, sorts, and aggs. */
+  runtimeMappings: (mappings: Record<string, MappingRuntimeField>) => QueryBuilder<M>; /** Retrieve doc-values for the specified fields in the hit response. */
+  docValueFields: (fields: Array<QueryDslFieldAndFormat | string>) => QueryBuilder<M>; /** Retrieve values via the fields API (supports runtime + standard fields with format). */
+  fields: (fields: Array<QueryDslFieldAndFormat | string>) => QueryBuilder<M>; /** Post-filter — applied after aggregations, so aggs see the unfiltered result set. */
+  postFilter: (fn: (q: ClauseBuilder<M>) => any) => QueryBuilder<M>; /** Script fields — compute per-hit values via Painless scripts. */
+  scriptFields: (fields: Record<string, ScriptField>) => QueryBuilder<M>;
+  timeout: (timeout: string) => QueryBuilder<M>;
+  trackScores: (track: boolean) => QueryBuilder<M>;
+  explain: (explain: boolean) => QueryBuilder<M>;
+  minScore: (score: number) => QueryBuilder<M>;
+  version: (version: boolean) => QueryBuilder<M>;
+  seqNoPrimaryTerm: (enabled: boolean) => QueryBuilder<M>;
+  trackTotalHits: (value: boolean | number) => QueryBuilder<M>;
+  highlight: (fields: Array<HighlightableFields<M> & string>, options?: HighlightOptions) => QueryBuilder<M>;
+  geoDistance: <K extends GeoPointFields<M> & string>(field: K, center: {
+    lat: number;
+    lon: number;
+  }, options: GeoDistanceOptions) => QueryBuilder<M>;
+  geoBoundingBox: <K extends GeoPointFields<M> & string>(field: K, options: GeoBoundingBoxOptions) => QueryBuilder<M>;
+  geoPolygon: <K extends GeoPointFields<M> & string>(field: K, options: GeoPolygonOptions) => QueryBuilder<M>;
+  geoShape: <K extends GeoShapeFields<M> & string>(field: K, shape: Record<string, unknown>, options?: GeoShapeQueryOptions) => QueryBuilder<M>; /** Distance-feature query — boost relevance by proximity of a date or geo_point field to an origin. */
+  distanceFeature: <K extends (DateFields<M> | GeoPointFields<M>) & string>(field: K, options: DistanceFeatureOptions) => QueryBuilder<M>; /** Rank-feature query — boost relevance using a numeric feature in a `rank_feature`/`rank_features` field. */
+  rankFeature: <K extends RankFeatureFields<M> & string>(field: K, options?: RankFeatureQueryOptions) => QueryBuilder<M>; /** Sparse-vector query — score with token-weight pairs from a learned sparse model (e.g. ELSER). */
+  sparseVector: <K extends SparseVectorFields<M> & string>(field: K, options: SparseVectorQueryOptions) => QueryBuilder<M>;
+  regexp: <K extends KeywordFields<M> & string>(field: K, value: string, options?: RegexpOptions) => QueryBuilder<M>;
+  constantScore: (fn: (q: ClauseBuilder<M>) => any, options?: ConstantScoreOptions) => QueryBuilder<M>;
+  combinedFields: <K extends TextFields<M> & string>(fields: K[], query: string, options?: CombinedFieldsOptions) => QueryBuilder<M>;
+  /**
+   * Query string query — parses a Lucene query syntax string.
+   *
+   * **Security:** if `query` is derived from untrusted user input, field-level access control and
+   * syntax errors may expose internal field names or cause unexpected query behaviour.
+   * Prefer `simpleQueryString` for user-facing search boxes — it silently ignores invalid syntax.
+   */
+  queryString: (query: string, options?: QueryStringOptions) => QueryBuilder<M>;
+  /**
+   * Simple query string query — a safer Lucene subset for user-facing search.
+   *
+   * **Security:** invalid syntax is silently ignored rather than returning an error.
+   * Still constrain which fields are searched via `options.fields` to avoid exposing sensitive fields.
+   */
+  simpleQueryString: (query: string, options?: SimpleQueryStringOptions) => QueryBuilder<M>;
+  moreLikeThis: (fields: Array<(TextFields<M> | KeywordFields<M>) & string>, like: string | Array<string | {
+    _index: string;
+    _id: string;
+  }>, options?: MoreLikeThisOptions) => QueryBuilder<M>;
+  matchBoolPrefix: <K extends TextFields<M> & string>(field: K, value: string, options?: MatchBoolPrefixOptions) => QueryBuilder<M>;
+  searchAfter: (values: SortResults) => QueryBuilder<M>;
+  preference: (value: string) => QueryBuilder<M>;
+  collapse: (field: CollapsibleFields<M> & string, options?: {
+    inner_hits?: SearchInnerHits;
+    max_concurrent_group_searches?: number;
+  }) => QueryBuilder<M>;
+  rescore: (queryFn: (q: ClauseBuilder<M>) => any, windowSize: number, options?: {
+    query_weight?: number;
+    rescore_query_weight?: number;
+    score_mode?: 'total' | 'multiply' | 'avg' | 'max' | 'min';
+  }) => QueryBuilder<M>;
+  storedFields: (fields: Array<string>) => QueryBuilder<M>;
+  terminateAfter: (count: number) => QueryBuilder<M>;
+  pit: (id: string, keepAlive: string) => QueryBuilder<M>;
+  indicesBoost: (boosts: Array<Record<string, number>>) => QueryBuilder<M>;
+  build: () => QueryState<M>;
+};
+//#endregion
+//#region src/aggregation.builder.d.ts
+declare const aggregations: <M extends Record<string, FieldTypeString>>(_schema: MappingsSchema<M>) => RootAggregationBuilder<M>;
+//#endregion
+//#region src/mapping.builder.d.ts
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => never : never) extends ((x: infer I) => never) ? I : never;
+type FlattenSubFields<Prefix extends string, F extends Record<string, FieldMappingWithLiteralType>> = UnionToIntersection<{ [K in keyof F & string]: { [Key in `${Prefix}.${K}`]: F[K]['type'] } & (F[K] extends {
+  _subFields: infer Sub extends Record<string, FieldMappingWithLiteralType>;
+} ? FlattenSubFields<`${Prefix}.${K}`, Sub> : Record<never, never>) }[keyof F & string]>;
+type FlattenMultiFields<Prefix extends string, MF extends Record<string, FieldMappingWithLiteralType>> = UnionToIntersection<{ [K in keyof MF & string]: { [Key in `${Prefix}.${K}`]: MF[K]['type'] } }[keyof MF & string]>;
+type ExtractFieldTypes<F extends Record<string, FieldMappingWithLiteralType>> = { [K in keyof F]: F[K]['type'] } & UnionToIntersection<{ [K in keyof F & string]: (F[K] extends {
+  _subFields: infer Sub extends Record<string, FieldMappingWithLiteralType>;
+} ? FlattenSubFields<K, Sub> : Record<never, never>) & (F[K] extends {
+  _multiFields: infer MF extends Record<string, FieldMappingWithLiteralType>;
+} ? FlattenMultiFields<K, MF> : Record<never, never>) }[keyof F & string]>;
+declare const mappings: <F extends Record<string, FieldMappingWithLiteralType>>(fields: F, options?: MappingOptions) => MappingsSchema<ExtractFieldTypes<F>, F>;
+//#endregion
+//#region src/field.helpers.d.ts
+declare const text: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: TextFieldOptions<MF>) => TextFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const keyword: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: KeywordFieldOptions<MF>) => KeywordFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const long: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: NumericFieldOptions<MF>) => LongFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const integer: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: NumericFieldOptions<MF>) => IntegerFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const short: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: NumericFieldOptions<MF>) => ShortFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const byte: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: NumericFieldOptions<MF>) => ByteFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const double: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: NumericFieldOptions<MF>) => DoubleFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const float: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: NumericFieldOptions<MF>) => FloatFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const halfFloat: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: NumericFieldOptions<MF>) => HalfFloatFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const scaledFloat: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: ScaledFloatFieldOptions<MF>) => ScaledFloatFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const date: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: DateFieldOptions<MF>) => DateFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+/**
+ * Date field stored with nanosecond precision. Same API as `date()` but supports sub-millisecond timestamps.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/date_nanos.html
+ */
+declare const dateNanos: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: DateNanosFieldOptions<MF>) => DateNanosFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const boolean: (options?: BooleanFieldOptions) => BooleanFieldMapping;
+declare const binary: () => BinaryFieldMapping;
+declare const ip: (options?: IpFieldOptions) => IpFieldMapping;
+declare const denseVector: (options?: DenseVectorFieldOptions) => DenseVectorFieldMapping;
+/**
+ * Quantized dense vector field — wraps `denseVector()` with `int8_hnsw` index type.
+ *
+ * Quantizes float32 vectors to int8 at index time, saving ~75% memory.
+ * Recommended for vectors with dims >= 384. Original float vectors are retained
+ * in the index, enabling a two-phase search pattern:
+ *
+ * 1. Fast approximate search using quantized int8 vectors
+ * 2. Precise rescore of top-k results using retained float vectors
+ *
+ * @example
+ * // Index mapping
+ * const schema = mappings({
+ *   title: text(),
+ *   embedding: quantizedDenseVector({ dims: 768, similarity: 'cosine' }),
+ * }, {
+ *   _source: { excludes: ['embedding'] },
+ * });
+ *
+ * // Two-phase search: fast kNN + precise rescore
+ * const result = queryBuilder(schema)
+ *   .knn('embedding', queryVector, { k: 100, num_candidates: 200 })
+ *   .rescore(
+ *     (q) => q.scriptScore(
+ *       (inner) => inner.matchAll(),
+ *       { source: "cosineSimilarity(params.v, 'embedding') + 1.0", params: { v: queryVector } }
+ *     ),
+ *     100
+ *   )
+ *   .build();
+ */
+declare const quantizedDenseVector: (options?: DenseVectorFieldOptions) => DenseVectorFieldMapping;
+/**
+ * Sparse vector field — stores token-weight pairs for sparse retrieval (e.g. ELSER/BM25-style models).
+ * Complement to `denseVector()`. Query with the `sparse_vector` query.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/sparse-vector.html
+ */
+declare const sparseVector: () => SparseVectorFieldMapping;
+/**
+ * Rank feature field — a single numeric feature used by the `rank_feature` query to boost relevance.
+ * Use when each document has one named signal (e.g. `pagerank`, `popularity_score`).
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/rank-feature.html
+ */
+declare const rankFeature: (options?: RankFeatureFieldOptions) => RankFeatureFieldMapping;
+/**
+ * Rank features field — a sparse map of numeric features used by the `rank_feature` query.
+ * Use when each document has many named signals (e.g. topic scores).
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/rank-features.html
+ */
+declare const rankFeatures: (options?: RankFeaturesFieldOptions) => RankFeaturesFieldMapping;
+/**
+ * Semantic text field (ES 9.x) — ML-powered text field for semantic and hybrid search.
+ * Automatically generates and stores embeddings at index time using the configured inference endpoint.
+ *
+ * @example
+ * const schema = mappings({
+ *   title: text(),
+ *   body: semanticText({ inference_id: 'my-elser-endpoint' }),
+ * });
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/semantic-text.html
+ */
+declare const semanticText: (options?: SemanticTextFieldOptions) => SemanticTextFieldMapping;
+/**
+ * Unsigned long field (ES 9.0+) — stores unsigned 64-bit integer values (0 to 2^64-1).
+ * Use when values exceed the `long` range.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/number.html
+ */
+declare const unsignedLong: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: UnsignedLongFieldOptions<MF>) => UnsignedLongFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+declare const geoPoint: (options?: GeoPointFieldOptions) => GeoPointFieldMapping;
+declare const geoShape: (options?: GeoShapeFieldOptions) => GeoShapeFieldMapping;
+declare const completion: (options?: CompletionFieldOptions) => CompletionFieldMapping;
+/**
+ * Object field — for JSON-like structured documents where sub-fields are queried with dot-notation.
+ *
+ * The most common way to model structured data (e.g. `{ address: { city, zip } }`).
+ * Sub-fields are indexed inline within the parent document — no special query wrapper needed.
+ * Query sub-fields directly using dot-notation: `.term('address.city', 'NYC')`.
+ *
+ * Use `nested()` instead when you have **arrays of objects** and need cross-field queries
+ * within each element to be accurate (e.g. tags with both a label and weight).
+ *
+ * @example
+ * const m = mappings({
+ *   address: object({
+ *     street: text(),
+ *     city: keyword(),
+ *     zip: keyword(),
+ *   }),
+ * });
+ * queryBuilder(m).term('address.city', 'NYC').build();
+ */
+declare function object<F extends Record<string, FieldMappingWithLiteralType>>(fields: F, options?: ObjectFieldOptions): TypedObjectFieldMapping<F>;
+/**
+ * Nested field — for **arrays of objects** where cross-field queries within each element must be accurate.
+ *
+ * Each nested object is stored as a separate hidden Elasticsearch document, preserving the
+ * relationship between sub-fields within each element. Without `nested`, Elasticsearch flattens
+ * array sub-fields and loses which values belong to the same element.
+ *
+ * Queries on nested fields **must** use the `.nested()` query builder method — direct dot-notation
+ * queries will not find nested documents.
+ *
+ * Use `object()` instead for single structured objects (addresses, names, etc.) — it is simpler,
+ * more efficient, and does not require a query wrapper.
+ *
+ * @example
+ * const m = mappings({
+ *   tags: nested({
+ *     label: keyword(),
+ *     weight: float(),
+ *   }),
+ * });
+ * queryBuilder(m).nested('tags', q => q.term('label', 'sale')).build();
+ */
+declare function nested<F extends Record<string, FieldMappingWithLiteralType>>(fields: F, options?: NestedFieldOptions): TypedNestedFieldMapping<F>;
+declare const alias: (options: AliasFieldOptions) => AliasFieldMapping;
+declare const percolator: () => PercolatorFieldMapping;
+declare const integerRange: (options?: RangeFieldOptions) => IntegerRangeFieldMapping;
+declare const floatRange: (options?: RangeFieldOptions) => FloatRangeFieldMapping;
+declare const longRange: (options?: RangeFieldOptions) => LongRangeFieldMapping;
+declare const doubleRange: (options?: RangeFieldOptions) => DoubleRangeFieldMapping;
+declare const dateRange: (options?: RangeFieldOptions) => DateRangeFieldMapping;
+/**
+ * IP range field — stores a range of IPv4/IPv6 addresses.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/range.html
+ */
+declare const ipRange: (options?: IpRangeFieldOptions) => IpRangeFieldMapping;
+/**
+ * No-score text field — faster and uses less disk than `text()`.
+ * Use when you only need filter/match but not relevance scoring (e.g., logs, simple field matches).
+ */
+declare const matchOnlyText: <MF extends Record<string, FieldMappingWithLiteralType>>(options?: MatchOnlyTextFieldOptions<MF>) => MatchOnlyTextFieldMapping & Readonly<{
+  _multiFields: MF;
+}>;
+/**
+ * Autocomplete / typeahead field. Creates sub-fields for edge n-gram matching
+ * out of the box. Query with `multi_match` targeting the generated sub-fields.
+ */
+declare const searchAsYouType: (options?: SearchAsYouTypeFieldOptions) => SearchAsYouTypeFieldMapping;
+/**
+ * Field where every document has the same value. Useful for multi-index queries
+ * to identify the index type (e.g., `constantKeyword({ value: 'product' })`).
+ */
+declare const constantKeyword: (options?: ConstantKeywordFieldOptions) => ConstantKeywordFieldMapping;
+/**
+ * Optimized for grep-like wildcard/regexp queries on high-cardinality or large fields.
+ * Use instead of `keyword()` when leading wildcards (`*foo`) are needed.
+ */
+declare const wildcardField: (options?: WildcardFieldOptions) => WildcardFieldMapping;
+/**
+ * Flattens complex/dynamic objects into a single field. Faster than `nested()`,
+ * but only supports keyword-level queries on inner values.
+ */
+declare const flattened: (options?: FlattenedFieldOptions) => FlattenedFieldMapping;
+/**
+ * Token count field — stores the number of tokens produced by an analyzer.
+ * Useful for enforcing minimum/maximum field lengths via queries or aggregations.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/token-count.html
+ */
+declare const tokenCount: (options?: TokenCountFieldOptions) => TokenCountFieldMapping;
+/**
+ * Murmur3 hash field — computes and stores a murmur3 hash of field values at index time.
+ * Requires the `mapper-murmur3` plugin.
+ * @see https://www.elastic.co/guide/en/elasticsearch/plugins/current/mapper-murmur3.html
+ */
+declare const murmur3Hash: () => Murmur3FieldMapping;
+/**
+ * Join field — defines parent/child relationships within a single index.
+ * `relations` is required: maps parent names to one or more child names.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/parent-join.html
+ *
+ * @example
+ * const m = mappings({
+ *   title: text(),
+ *   relation: join({ relations: { question: 'answer' } }),
+ * });
+ */
+declare const join: (options: JoinFieldOptions) => JoinFieldMapping;
+//#endregion
+//#region src/multi-search.types.d.ts
+/**
+ * Request-level parameters for a multi-search request — mirrors the subset of
+ * the official `MsearchRequest` type that is set at the top of the request
+ * (rather than per-sub-search). The builder applies these via
+ * `.withParams({...})` and exposes them on `.buildParams()` so callers can
+ * spread them into `client.msearch({...params, body: ndjson})`.
+ */
+type MSearchRequestParams = Pick<MsearchRequest, 'max_concurrent_searches' | 'max_concurrent_shard_requests' | 'pre_filter_shard_size' | 'rest_total_hits_as_int' | 'typed_keys' | 'ccs_minimize_roundtrips' | 'search_type' | 'routing'>;
+/**
+ * Header options for each search in a multi-search request — re-exported from official @elastic/elasticsearch types
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html
+ */
+type MSearchHeader = MsearchMultisearchHeader;
+/**
+ * A single search request in a multi-search operation
+ */
+type MSearchRequest<M extends Record<string, FieldTypeString>> = {
+  /** Optional header for this search */header?: MSearchHeader; /** The query body */
+  body: QueryState<M>;
+};
+/**
+ * Multi-search builder interface
+ */
+type MSearchBuilder<M extends Record<string, FieldTypeString>> = {
+  /** Add a search request with header and body */add: (request: MSearchRequest<M>) => MSearchBuilder<M>; /** Add a search using a pre-built query state */
+  addQuery: (body: QueryState<M>, header?: MSearchHeader) => MSearchBuilder<M>; /** Add a search using a QueryBuilder directly — convenience over `.addQuery(qb.build(), header)` */
+  addQueryBuilder: (qb: QueryBuilder<M>, header?: MSearchHeader) => MSearchBuilder<M>; /** Set request-level params (e.g. `max_concurrent_searches`, `typed_keys`). Merges with any previously set params. */
+  withParams: (params: MSearchRequestParams) => MSearchBuilder<M>; /** Build as NDJSON string format for Elasticsearch */
+  build: () => string; /** Build as array of objects (header, body pairs) */
+  buildArray: () => Array<MSearchHeader | QueryState<M>>; /** Return the request-level params set via `.withParams()`, for spreading into `client.msearch()`. */
+  buildParams: () => MSearchRequestParams;
+};
+//#endregion
+//#region src/multi-search.builder.d.ts
+/**
+ * Create a new multi-search builder
+ * @example
+ * const ms = msearch(productMappings)
+ *   .addQueryBuilder(queryBuilder(productMappings).match('name', 'shoe'), { index: 'products' })
+ *   .addQueryBuilder(queryBuilder(productMappings).match('name', 'shirt'), { index: 'products' })
+ *   .withParams({ max_concurrent_searches: 5, typed_keys: true })
+ *   .build();
+ */
+declare const msearch: <M extends Record<string, FieldTypeString>>(_schema: MappingsSchema<M>) => MSearchBuilder<M>;
+//#endregion
+//#region src/bulk.types.d.ts
+/**
+ * Metadata for bulk index operation — re-exported from official @elastic/elasticsearch types
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html
+ */
+type BulkIndexMeta = BulkIndexOperation;
+/**
+ * Metadata for bulk create operation — re-exported from official @elastic/elasticsearch types
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html
+ */
+type BulkCreateMeta = BulkCreateOperation;
+/**
+ * Metadata for bulk update operation.
+ * Combines official BulkUpdateOperation (header) with BulkUpdateAction (body) for ergonomic API.
+ * The builder splits these into separate header and body when building the bulk request.
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html
+ */
+type BulkUpdateMeta<T> = BulkUpdateOperation & BulkUpdateAction<T, Partial<T>>;
+/**
+ * Metadata for bulk delete operation — re-exported from official @elastic/elasticsearch types
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html
+ */
+type BulkDeleteMeta = BulkDeleteOperation;
+/**
+ * Bulk operations builder interface
+ */
+type BulkBuilder<T> = {
+  /** Index a document (create or replace) */index: (doc: T, meta?: BulkIndexMeta) => BulkBuilder<T>; /** Create a new document (fails if already exists) */
+  create: (doc: T, meta?: BulkCreateMeta) => BulkBuilder<T>; /** Update an existing document */
+  update: (meta: BulkUpdateMeta<T>) => BulkBuilder<T>; /** Delete a document */
+  delete: (meta: BulkDeleteMeta) => BulkBuilder<T>; /** Build as NDJSON string format for Elasticsearch */
+  build: () => string; /** Build as array of operation headers and document bodies. Alternating operation/document pairs (except `delete` which is header-only). */
+  buildArray: () => Array<BulkOperationContainer$1 | T | Partial<T> | BulkUpdateAction<T, Partial<T>>>;
+};
+//#endregion
+//#region src/bulk.builder.d.ts
+/**
+ * Create a new bulk operations builder.
+ * `.build()` returns an NDJSON string (newline-delimited JSON) ready to POST to `/_bulk`.
+ * `.buildArray()` returns the raw operation objects if you need to inspect or transform them.
+ * @example
+ * const ndjson = bulk(productMappings)
+ *   .index({ id: '1', name: 'Product 1' }, { _index: 'products', _id: '1' })
+ *   .create({ id: '2', name: 'Product 2' }, { _index: 'products', _id: '2' })
+ *   .update({ _index: 'products', _id: '3', doc: { name: 'Updated' } })
+ *   .delete({ _index: 'products', _id: '4' })
+ *   .build(); // POST to /_bulk with Content-Type: application/x-ndjson
+ */
+declare const bulk: <M extends Record<string, FieldTypeString>>(_schema: MappingsSchema<M>) => BulkBuilder<{
+  [x: string]: unknown;
+}>;
+//#endregion
+//#region src/index-management.builder.d.ts
+/**
+ * Create a new index builder for Elasticsearch index configuration.
+ *
+ * Typical lifecycle:
+ * 1. **Create index:** `indexBuilder().mappings(schema).settings(productionSearchSettings()).build()`
+ * 2. **Bulk ingest:** Apply `fastIngestSettings()` via ES `_settings` API → bulk index →
+ *    apply `productionSearchSettings()` → `POST /index/_refresh`
+ * 3. **Normal operations:** Query, update individual docs via `_update` API
+ * 4. **Migration with mapping changes:** Create new index with new mappings → `POST _reindex`
+ *    from old → atomically swap alias via `POST _aliases` → delete old index
+ *
+ * After bulk loading, remember to refresh the index with `POST /index/_refresh`
+ * to make all documents searchable.
+ *
+ * @example
+ * const indexConfig = indexBuilder()
+ *   .mappings(productMappings)
+ *   .settings(productionSearchSettings())
+ *   .alias('products')
+ *   .build();
+ */
+declare const indexBuilder: () => IndexBuilder;
+//#endregion
+//#region src/suggester.builder.d.ts
+/**
+ * Factory function to create a new suggester builder
+ * @example
+ * ```typescript
+ * const suggestions = suggest(productMappings)
+ *   .term('name-suggestions', 'laptop', { field: 'name', size: 5 })
+ *   .build();
+ * ```
+ */
+declare const suggest: <M extends Record<string, FieldTypeString>>(_schema: MappingsSchema<M>) => SuggesterBuilder<M>;
+//#endregion
+//#region src/settings.presets.d.ts
+/**
+ * Balanced production settings for search workloads.
+ *
+ * Defaults:
+ * - `number_of_replicas: 1` — one replica for redundancy
+ * - `refresh_interval: '5s'` — near-real-time search without excessive refresh overhead
+ *
+ * @param overrides - Override or extend any setting. Applied after defaults.
+ *
+ * @example
+ * const index = indexBuilder()
+ *   .mappings(schema)
+ *   .settings(productionSearchSettings())
+ *   .build();
+ *
+ * @example
+ * // With best_compression for disk savings
+ * productionSearchSettings({ codec: 'best_compression' })
+ *
+ * @example
+ * // Restore production settings after bulk ingest
+ * await client.indices.putSettings({
+ *   index: 'my-index',
+ *   body: productionSearchSettings(),
+ * });
+ * await client.indices.refresh({ index: 'my-index' });
+ */
+declare const productionSearchSettings: (overrides?: Partial<IndicesIndexSettings>) => IndicesIndexSettings;
+/**
+ * Per-field sort configuration for `indexSortSettings()`.
+ * Either a bare direction, or a full spec with `mode`/`missing`.
+ */
+type IndexSortFieldSpec = 'asc' | 'desc' | {
+  order: 'asc' | 'desc';
+  mode?: IndicesSegmentSortMode;
+  missing?: IndicesSegmentSortMissing;
+};
+/**
+ * Generate index sort settings from a field→direction (or full spec) map.
+ *
+ * Index-time sorting improves compression (similar values stored together) and
+ * enables early termination when query sort matches index sort. Combine with
+ * `trackTotalHits(false)` for fastest sorted queries.
+ *
+ * The returned object lives at the top level of `IndicesIndexSettings` — spread it
+ * directly into a settings object (do NOT wrap it under an `index` key, the
+ * `@elastic/elasticsearch` client normalises that form).
+ *
+ * Pass a bare `'asc' | 'desc'` for simple cases; pass `{ order, mode?, missing? }`
+ * when you need `mode` (`min`/`max`/`median`/`avg`) or `missing` (`_first`/`_last`).
+ *
+ * @param fields - Map of field names to sort direction or full spec.
+ * @returns A `{ sort: IndicesIndexSegmentSort }` fragment to spread into your settings.
+ *
+ * @example
+ * const index = indexBuilder()
+ *   .mappings(schema)
+ *   .settings({
+ *     ...productionSearchSettings(),
+ *     ...indexSortSettings({ timestamp: 'desc', status: 'asc' }),
+ *   })
+ *   .build();
+ *
+ * @example
+ * indexSortSettings({
+ *   price: { order: 'asc', mode: 'min', missing: '_last' },
+ *   created_at: 'desc'
+ * })
+ */
+declare const indexSortSettings: (fields: Record<string, IndexSortFieldSpec>) => {
+  sort: IndicesIndexSegmentSort;
+};
+/**
+ * Settings optimized for maximum indexing speed during bulk operations.
+ *
+ * Apply via the ES `_settings` API before starting bulk ingest, then revert
+ * with `productionSearchSettings()` afterward. Do not use these as permanent
+ * index settings — they trade durability and search availability for speed.
+ *
+ * Defaults:
+ * - `refresh_interval: '-1'` — disables refresh (can improve reindex time by 70%+)
+ * - `number_of_replicas: 0` — no replication overhead during ingest
+ * - `translog.durability: 'async'` — async translog for faster writes
+ * - `translog.sync_interval: '30s'` — less frequent translog sync
+ *
+ * @param overrides - Override or extend any setting. Applied after defaults.
+ * `translog` overrides are deep-merged so individual translog keys can be
+ * changed without clobbering the other defaults.
+ *
+ * @example
+ * // Apply before bulk ingest via ES client
+ * await client.indices.putSettings({
+ *   index: 'my-index',
+ *   body: fastIngestSettings(),
+ * });
+ *
+ * @example
+ * // With custom overrides
+ * fastIngestSettings({ number_of_shards: 3 })
+ */
+declare const fastIngestSettings: (overrides?: Partial<IndicesIndexSettings>) => IndicesIndexSettings;
+//#endregion
+//#region src/index.d.ts
+declare const queryBuilder: <M extends Record<string, FieldTypeString>>(_schema: MappingsSchema<M>, includeQuery?: boolean) => QueryBuilder<M>;
+/**
+ * Type inference helper for vanilla JavaScript.
+ *
+ * **Type-only — do not use the returned value at runtime.** This function always returns
+ * `undefined`; its declared return type is a lie used to carry `Infer<typeof schema>` into
+ * JSDoc `@type` annotations. Accessing properties on the return value (e.g. `inferType(s).name`)
+ * will throw `TypeError`.
+ *
+ * @example
+ * const schema = mappings({ name: text() });
+ * const _Product = inferType(schema); // undefined at runtime; type-only
+ *
+ * /** @type {typeof _Product} *\/
+ * const doc = { name: 'Laptop' };
+ *
+ * In TypeScript, prefer `type Product = Infer<typeof schema>` directly.
+ */
+declare const inferType: <M extends Record<string, FieldTypeString>, F extends Record<string, FieldMappingWithLiteralType>>(_schema: MappingsSchema<M, F>) => Infer<MappingsSchema<M, F>>;
+//#endregion
+export { type AnalysisAnalyzerConfig, type AnalysisCharFilterConfig, type AnalysisConfig, type AnalysisNormalizerConfig, type AnalysisTokenFilterConfig, type AnalysisTokenizerConfig, type BooleanFields, type BulkBuilder, type BulkOperationContainer, type ClauseBuilder, type CompletionFields, type CompletionSuggestContext, type CompletionSuggesterOptions, type DateFields, type DateNanosFieldOptions, type DenseVectorFields, type FieldMappingWithLiteralType, type FieldsOfType, type FunctionScoreOptions, type GeoPointFields, type GeoShapeFields, type HasChildOptions, type HasParentOptions, type IndexBuilder, type IndexSortFieldSpec, type Infer, type IntervalsOptions, type IpFields, type IpRangeFieldOptions, type JoinFieldOptions, type KeywordFields, type MSearchBuilder, type MSearchHeader, type MSearchRequestParams, type MappingsSchema, type NestedAggregationBuilder, type NestedEntryBuilder, type NestedFieldOptions, type NumericFields, type ObjectFieldOptions, type ParentIdOptions, type PhraseSuggestCollate, type PhraseSuggestDirectGenerator, type PhraseSuggestSmoothingModel, type PhraseSuggesterOptions, type QueryBuilder, type RankFeatureFields, type RootAggregationBuilder, type SpanNearOptions, type SpanNotOptions, type SpanQuery, type SparseVectorFields, type SuggesterBuilder, type TermSuggesterOptions, type TextFields, type TokenCountFieldOptions, type TypedNestedFieldMapping, type TypedObjectFieldMapping, type UnsignedLongFieldOptions, type VectorFields, aggregations, alias, binary, boolean, bulk, byte, completion, constantKeyword, date, dateNanos, dateRange, denseVector, double, doubleRange, fastIngestSettings, flattened, float, floatRange, geoPoint, geoShape, halfFloat, indexBuilder, indexSortSettings, inferType, integer, integerRange, ip, ipRange, join, keyword, long, longRange, mappings, matchOnlyText, msearch, murmur3Hash, nested, object, percolator, productionSearchSettings, quantizedDenseVector, queryBuilder, rankFeature, rankFeatures, scaledFloat, searchAsYouType, semanticText, short, sparseVector, suggest, text, tokenCount, unsignedLong, wildcardField };
+//# sourceMappingURL=index.d.cts.map