elasticlink 0.8.0-beta → 1.0.0-beta.1

package/README.md

@@ -1,7 +1,5 @@
 # elasticlink
 
-> **Beta**: elasticlink is in active beta. APIs may change before the first stable release.
-
 [![npm version](https://img.shields.io/npm/v/elasticlink.svg)](https://www.npmjs.com/package/elasticlink)
 [![Build Status](https://github.com/misterrodger/elasticlink/actions/workflows/ci.yml/badge.svg)](https://github.com/misterrodger/elasticlink/actions)
 [![codecov](https://codecov.io/gh/misterrodger/elasticlink/branch/main/graph/badge.svg)](https://codecov.io/gh/misterrodger/elasticlink)
@@ -9,31 +7,16 @@
 
 > **Type-safe, fluent API for Elasticsearch queries and index management**
 
-elasticlink simplifies building Elasticsearch queries and index management in TypeScript. Write type-checked queries that compile to valid Elasticsearch DSL with zero runtime overhead.
+Define your Elasticsearch mappings once, then build queries with full IntelliSense and compile-time safety. `match()` only accepts text fields, `term()` only keyword fields, etc. Compiles to standard Elasticsearch DSL with no runtime overhead.
 
 ## Features
 
-- **Mapping-Aware Type Safety**: Define ES field types once via `mappings()`, get compile-time constraints — `match()` only accepts text fields, `term()` only keyword fields, etc.
-- **Fluent API**: Chainable query builder with intuitive method names
-- **Zero Runtime Overhead**: Compiles directly to Elasticsearch DSL objects
-- **Well-Tested**: Comprehensive unit and integration test suite against live Elasticsearch
-- **Great DX**: Excellent IntelliSense and error messages
-- **Types from the source**: Types derived directly from `@elastic/elasticsearch` for accuracy and automatic alignment with Elasticsearch updates
-
-## Compatibility
-
-| elasticlink | Node.js     | Elasticsearch |
-|-------------|-------------|---------------|
-| 0.8.0-beta  | 20, 22, 24  | 9.x (≥9.0.0)  |
-| 0.7.0-beta  | 20, 22, 24  | 9.x (≥9.0.0)  |
-| 0.6.0-beta  | 20, 22, 24  | 9.x (≥9.0.0)  |
-| 0.5.0-beta  | 20, 22, 24  | 9.x (≥9.0.0)  |
-| 0.4.0-beta  | 20, 22, 24  | 9.x (≥9.0.0)  |
-| 0.3.0-beta  | 20, 22, 24  | 9.x (≥9.0.0)  |
-| 0.2.0-beta  | 20, 22      | 9.x (≥9.0.0)  |
-| 0.1.0-beta  | 20, 22      | 9.x (≥9.0.0)  |
-
-Tested against the versions listed. Peer dependency is `@elastic/elasticsearch >=9.0.0`.
+- **Mapping-Aware Type Safety**: define your ES mappings once with `mappings()`, and every query method constrains its field arguments to the correct type.
+- **Types from the source**: autocomplete for field names, query options, and aggregation methods. Structural types are hand-rolled, leaf option types are derived from `@elastic/elasticsearch` types, so they stay current.
+- **Fluent Chainable API**: readable query building with boolean logic, conditional branches (using `.when()`), aggregations, and pagination in a single chain.
+- **No Runtime Overhead or Lock-In**: builds plain Elasticsearch DSL objects. Pass them to the official `@elastic/elasticsearch` client or any HTTP client.
+- **Production-Ready Settings Presets**: helpers for production search, fast ingest, and index sort presets for common lifecycle stages, with full type support.
+- **40+ Field Helpers**: `text()`, `keyword()`, `denseVector()`, `nested()`, and more with options for IDE tooltips.
 
 ## Installation
 
@@ -48,516 +31,443 @@ Requires Node.js 20+ and `@elastic/elasticsearch` 9.x as a peer dependency.
 ## Quick Start
 
 ```typescript
-import { query, mappings, text, keyword, float, type Infer } from 'elasticlink';
+import { queryBuilder, mappings, text, keyword, float, type Infer } from 'elasticlink';
 
 // Define field types once — this is the single source of truth
 const productMappings = mappings({
   name: text(),
+  description: text(),
   price: float(),
-  category: keyword(),
+  category: keyword()
 });
 
-// Derive a TS type from mappings (optional, for use elsewhere)
+// Derive a TS type from mappings (optional, for use elsewhere in your application)
 type Product = Infer<typeof productMappings>;
 
 // Build a type-safe query — field constraints are enforced at compile time
-const q = query(productMappings)
-  .match('name', 'laptop')    // ✅ 'name' is a text field
+const elasticQuery = queryBuilder(productMappings)
+  .match('name', 'laptop') // ✅ 'name' is a text field
   .range('price', { gte: 500, lte: 2000 })
+  .sort('price', 'asc')
   .from(0)
   .size(20)
   .build();
 
 // Send to Elasticsearch
-const response = await client.search({ index: 'products', ...q });
+const response = await client.search({ index: 'products', ...elasticQuery });
 ```
 
-## API Overview
-
-### Core Query Methods
-
-#### Basic Queries
-
-- `match(field, value, options?)` - Full-text search
-- `multiMatch(fields, query, options?)` - Search multiple fields
-- `matchPhrase(field, query)` - Exact phrase matching
-- `matchPhrasePrefix(field, query, options?)` - Prefix phrase matching
-- `matchBoolPrefix(field, value, options?)` - Analyze and build a bool query from query terms, with the last term as a prefix (search-as-you-type)
-- `combinedFields(fields, query, options?)` - Search across multiple fields treating them as one combined field
-- `queryString(query, options?)` - Lucene query string syntax
-- `simpleQueryString(query, options?)` - Simplified query string syntax with limited operators
-- `moreLikeThis(fields, like, options?)` - Find documents similar to a given document or text
-- `term(field, value)` - Exact term matching
-- `terms(field, values)` - Multiple exact values
-- `range(field, conditions)` - Range queries (gte, lte, gt, lt)
-- `exists(field)` - Field existence check
-- `wildcard(field, pattern)` - Wildcard pattern matching
-- `prefix(field, value)` - Prefix matching
-- `fuzzy(field, value, options?)` - Typo tolerance
-- `ids(values)` - Match by document IDs
-- `matchAll()` - Match all documents
-
-#### Geo Queries
-
-- `geoDistance(field, center, options)` - Distance-based search
-- `geoBoundingBox(field, options)` - Bounding box search
-- `geoPolygon(field, options)` - Polygon search
-
-#### Vector Search (KNN)
-
-- `knn(field, queryVector, options)` - K-nearest neighbors semantic search
-
-#### Advanced Queries
-
-- `nested(path, fn, options?)` - Nested object queries
-- `regexp(field, pattern, options?)` - Regular expression matching
-- `constantScore(fn, options?)` - Constant scoring for filters
-- `script(options)` - Script-based filtering
-- `scriptScore(query, script, options?)` - Custom scoring with scripts
-- `percolate(options)` - Match documents against stored queries
-
-#### Suggestions & Autocomplete
-
-- `suggest(fn)` - Add query suggestions (term, phrase, completion)
-- `term(name, text, options)` - Term-level spell checking
-- `phrase(name, text, options)` - Phrase-level corrections
-- `completion(name, prefix, options)` - Fast autocomplete
-
-### Boolean Logic
+Boolean queries with aggregations:
 
 ```typescript
-query(productMappings)
+const facetedSearch = queryBuilder(productMappings)
   .bool()
-  .must(q => q.match('name', 'laptop'))      // AND
-  .filter(q => q.range('price', { gte: 500 }))
-  .should(q => q.term('category', 'featured'))  // OR
-  .mustNot(q => q.term('category', 'discontinued')) // NOT
-  .minimumShouldMatch(1)
+  .must((q) => q.match('name', 'gaming laptop', { operator: 'and' }))
+  .filter((q) => q.term('category', 'electronics'))
+  .filter((q) => q.range('price', { gte: 800, lte: 2000 }))
+  .aggs((agg) => agg.terms('by_category', 'category', { size: 10 }).avg('avg_price', 'price'))
+  .highlight(['name', 'description'])
+  .size(20)
   .build();
 ```
 
-### Conditional Building
-
-Build queries dynamically based on runtime values. `.when(condition, fn)` — the chain is never broken. When the condition is falsy, the builder is returned unchanged, so no extra clauses or arrays are added. If you already called `.bool()`, that empty wrapper is preserved.
-
-`condition` resolves as: functions are called, booleans are used as-is, and any other value uses a nullish check (`!= null`) — so numeric `0` and empty string `''` are treated as truthy.
+Type safety in action — wrong field types are caught at compile time:
 
 ```typescript
-const searchTerm: string | undefined = param.searchTerm;
-const minPrice: number | undefined = param.minPrice;
+queryBuilder(productMappings).match('category', 'electronics');
+//                           ^^^^^^^^^^
+// TypeScript error: 'category' is a keyword field — use term(), not match()
 
-query(productMappings)
-  .bool()
-  .when(searchTerm, q => q.must(q2 => q2.match('name', searchTerm!)))
-  .when(minPrice, q => q.filter(q2 => q2.range('price', { gte: minPrice! })))
-  .build();
+queryBuilder(productMappings).term('category', 'electronics'); // ✅ Correct
 ```
 
-> **Note:** TypeScript cannot narrow closure variables inside callbacks. Even though `.when(searchTerm, fn)` guarantees the value is defined inside `fn`, you still need a non-null assertion (`!`) to satisfy the type checker.
->
-> **Note:** When the condition is false, any already-introduced `.bool()` wrapper is preserved. A `.bool().when(false, fn)` chain produces `{ query: { bool: {} } }` — not an error, just an empty bool clause.
+## Examples
+
+More examples available in [src/\_\_tests\_\_/examples.test.ts](src/__tests__/examples.test.ts).
+
+### E-commerce Product Search
 
-### Query Parameters
+A complete search request: boolean query with must/filter/should, aggregations for facets and price ranges, highlights, `_source` filtering, and pagination.
 
 ```typescript
-query(productMappings)
-  .match('name', 'laptop')
-  .from(0)                          // Pagination offset
-  .size(20)                         // Results per page
-  .sort('price', 'asc')             // Sort by field
-  ._source(['name', 'price'])       // Which fields to return
-  .timeout('5s')                    // Query timeout
-  .trackScores(true)                // Enable scoring in filter context
-  .trackTotalHits(true)             // Track total hit count (or pass a number threshold)
-  .explain(true)                    // Return scoring explanation
-  .minScore(10)                     // Minimum relevance score
-  .version(true)                    // Include document version in results
-  .seqNoPrimaryTerm(true)           // Include seq_no and primary_term for optimistic concurrency
+const ecommerceMappings = mappings({
+  name: text(),
+  description: text(),
+  category: keyword(),
+  price: float(),
+  tags: keyword(),
+  in_stock: boolean()
+});
+
+const searchTerm = 'gaming laptop';
+const category = 'electronics';
+const minPrice = 800;
+const maxPrice = 2000;
+
+const result = queryBuilder(ecommerceMappings)
+  .bool()
+  .must((q) => q.match('name', searchTerm, { operator: 'and', boost: 2 }))
+  .should((q) => q.fuzzy('description', searchTerm, { fuzziness: 'AUTO' }))
+  .filter((q) => q.term('category', category))
+  .filter((q) => q.range('price', { gte: minPrice, lte: maxPrice }))
+  .filter((q) => q.term('in_stock', true))
+  .minimumShouldMatch(1)
+  .aggs((agg) =>
+    agg.terms('by_category', 'category', { size: 10 }).range('price_ranges', 'price', {
+      ranges: [{ to: 800 }, { from: 800, to: 1500 }, { from: 1500 }]
+    })
+  )
   .highlight(['name', 'description'], {
-    fragment_size: 150,             // Per-field options (fragment_size, number_of_fragments, etc.)
-    pre_tags: ['<mark>'],           // Top-level highlight options
+    fragment_size: 150,
+    pre_tags: ['<mark>'],
     post_tags: ['</mark>']
   })
+  ._source(['name', 'price', 'category', 'tags'])
+  .timeout('5s')
+  .from(0)
+  .size(20)
+  .sort('_score', 'desc')
   .build();
 ```
 
-### Aggregations
-
-Aggregations can be combined with queries or used standalone:
+<details>
+<summary><b>Produced DSL</b> (click to expand)</summary>
 
-- **Bucket**: `terms()`, `dateHistogram()`, `histogram()`, `range()`
-- **Metric**: `avg()`, `sum()`, `min()`, `max()`, `cardinality()`, `percentiles()`, `stats()`, `valueCount()`
-- **Composition**: `subAgg()` for nested aggregations — attaches sub-aggregations to the **last** aggregation defined before the call; chain order matters
+```json
+{
+  "query": {
+    "bool": {
+      "must": [{ "match": { "name": { "query": "gaming laptop", "operator": "and", "boost": 2 } } }],
+      "should": [{ "fuzzy": { "description": { "value": "gaming laptop", "fuzziness": "AUTO" } } }],
+      "filter": [
+        { "term": { "category": "electronics" } },
+        { "range": { "price": { "gte": 800, "lte": 2000 } } },
+        { "term": { "in_stock": true } }
+      ],
+      "minimum_should_match": 1
+    }
+  },
+  "aggs": {
+    "by_category": { "terms": { "field": "category", "size": 10 } },
+    "price_ranges": {
+      "range": {
+        "field": "price",
+        "ranges": [{ "to": 800 }, { "from": 800, "to": 1500 }, { "from": 1500 }]
+      }
+    }
+  },
+  "highlight": {
+    "fields": { "name": { "fragment_size": 150 }, "description": { "fragment_size": 150 } },
+    "pre_tags": ["<mark>"],
+    "post_tags": ["</mark>"]
+  },
+  "_source": ["name", "price", "category", "tags"],
+  "timeout": "5s",
+  "from": 0,
+  "size": 20,
+  "sort": [{ "_score": "desc" }]
+}
+```
 
-```typescript
-import { query, aggregations } from 'elasticlink';
+</details>
 
-// Combined query + aggregations (inline aggs auto-thread mappings)
-const result = query(productMappings)
-  .term('category', 'electronics')
-  .aggs(agg =>
-    agg
-      .terms('by_category', 'category', { size: 10 })
-      .avg('avg_price', 'price')
-  )
-  .size(20)
-  .build();
+### Dynamic Search with Conditional Filters
 
-// Standalone aggregations (no query) — use query(mappings, false)
-const aggsOnly = query(productMappings, false)
-  .aggs(agg =>
-    agg
-      .terms('by_category', 'category')
-      .subAgg(sub =>
-        sub.avg('avg_price', 'price').max('max_price', 'price')
-      )
-  )
-  .size(0)  // Common pattern: size=0 when only wanting agg results
-  .build();
+Build queries dynamically based on runtime values. `.when(condition, fn)` — when the condition is falsy, the builder is returned unchanged.
 
-// Standalone aggregation builder (for manual composition)
-const standaloneAgg = aggregations(productMappings)
-  .avg('avg_price', 'price')
-  .terms('by_category', 'category', { size: 10 })
-  .build();
+```typescript
+const buildDynamicQuery = (filters: SearchFilters) => {
+  return queryBuilder(productMappings)
+    .bool()
+    .when(filters.searchTerm, (q) => q.must((q2) => q2.match('name', filters.searchTerm!, { boost: 2 })))
+    .when(filters.category, (q) => q.filter((q2) => q2.term('category', filters.category!)))
+    .when(filters.minPrice != null && filters.maxPrice != null, (q) =>
+      q.filter((q2) => q2.range('price', { gte: filters.minPrice!, lte: filters.maxPrice! }))
+    )
+    .from(filters.offset || 0)
+    .size(filters.limit || 20)
+    .build();
+};
 ```
 
-### Vector Search & Semantic Search
+### Aggregations — Portfolio Analytics
 
-KNN (k-nearest neighbors) queries enable semantic search using vector embeddings from machine learning models.
+Terms + sub-aggregation + date histogram in one request.
 
 ```typescript
-import { query, mappings, text, keyword, float, denseVector } from 'elasticlink';
-
-const productWithEmbeddingMappings = mappings({
+const instrumentMappings = mappings({
   name: text(),
-  description: text(),
+  asset_class: keyword(),
+  sector: keyword(),
   price: float(),
-  category: keyword(),
-  embedding: denseVector({ dims: 384 }),
+  yield_rate: float(),
+  listed_date: date()
 });
 
-// Basic semantic search
-const searchEmbedding = [0.23, 0.45, 0.67, 0.12, 0.89]; // From your ML model
-
-const result = query(productWithEmbeddingMappings)
-  .knn('embedding', searchEmbedding, {
-    k: 10,              // Return top 10 nearest neighbors
-    num_candidates: 100 // Consider 100 candidates per shard
-  })
-  .size(10)
-  .build();
-
-// Semantic search with filters
-const filtered = query(productWithEmbeddingMappings)
-  .knn('embedding', searchEmbedding, {
-    k: 20,
-    num_candidates: 200,
-    filter: {
-      bool: {
-        must: [{ term: { category: 'electronics' } }],
-        filter: [{ range: { price: { gte: 100, lte: 1000 } } }]
-      }
-    },
-    boost: 1.2,       // Boost relevance scores
-    similarity: 0.7   // Minimum similarity threshold
-  })
-  .size(20)
-  .build();
-
-// Hybrid search with aggregations
-const hybridSearch = query(productWithEmbeddingMappings)
-  .knn('embedding', searchEmbedding, {
-    k: 100,
-    num_candidates: 1000,
-    filter: { term: { category: 'electronics' } }
-  })
-  .aggs(agg =>
+const result = queryBuilder(instrumentMappings)
+  .bool()
+  .filter((q) => q.term('asset_class', 'fixed-income'))
+  .filter((q) => q.range('yield_rate', { gte: 3.0 }))
+  .aggs((agg) =>
     agg
-      .terms('categories', 'category', { size: 10 })
-      .range('price_ranges', 'price', {
-        ranges: [
-          { to: 100 },
-          { from: 100, to: 500 },
-          { from: 500 }
-        ]
+      .terms('by_sector', 'sector', { size: 10 })
+      .subAgg((sub) => sub.avg('avg_yield', 'yield_rate').max('max_price', 'price'))
+      .dateHistogram('listings_over_time', 'listed_date', {
+        interval: 'quarter',
+        min_doc_count: 1
       })
+      .subAgg((sub) => sub.percentiles('yield_percentiles', 'yield_rate', { percents: [25, 50, 75, 95] }))
   )
-  .size(20)
+  .size(0)
   .build();
 ```
 
-**Common Vector Dimensions:**
-
-- **384-768**: Sentence transformers (all-MiniLM, all-mpnet)
-- **512**: Image embeddings (ResNet, ViT)
-- **1536**: OpenAI text-embedding-ada-002
-- **3072**: OpenAI text-embedding-3-large
-
-**Dense Vector Field Mapping Example:**
+<details>
+<summary><b>Produced DSL</b> (click to expand)</summary>
 
-```typescript
-import type { DenseVectorOptions } from 'elasticlink';
-
-const mapping: DenseVectorOptions = {
-  dims: 384,
-  index: true,
-  similarity: 'cosine', // 'l2_norm', 'dot_product', or 'cosine'
-  index_options: {
-    type: 'hnsw',
-    m: 16,
-    ef_construction: 100
-  }
-};
+```json
+{
+  "query": {
+    "bool": {
+      "filter": [{ "term": { "asset_class": "fixed-income" } }, { "range": { "yield_rate": { "gte": 3.0 } } }]
+    }
+  },
+  "aggs": {
+    "by_sector": {
+      "terms": { "field": "sector", "size": 10 },
+      "aggs": {
+        "avg_yield": { "avg": { "field": "yield_rate" } },
+        "max_price": { "max": { "field": "price" } }
+      }
+    },
+    "listings_over_time": {
+      "date_histogram": { "field": "listed_date", "interval": "quarter", "min_doc_count": 1 },
+      "aggs": {
+        "yield_percentiles": { "percentiles": { "field": "yield_rate", "percents": [25, 50, 75, 95] } }
+      }
+    }
+  },
+  "size": 0
+}
 ```
 
-### Script Queries & Custom Scoring
+</details>
 
-**Note:** Scripts must be enabled in Elasticsearch configuration. Use with caution as they can impact performance.
+### Geospatial Search
 
 ```typescript
-import { query, mappings, text, keyword, float, long } from 'elasticlink';
-
-const scoredProductMappings = mappings({
+const restaurantMappings = mappings({
   name: text(),
-  price: float(),
-  popularity: long(),
-  quality_score: float(),
+  cuisine: keyword(),
+  location: geoPoint(),
+  rating: float()
 });
 
-// Script-based filtering
-const filtered = query(scoredProductMappings)
+const result = queryBuilder(restaurantMappings)
   .bool()
-  .must((q) => q.match('name', 'laptop'))
-  .filter((q) =>
-    q.script({
-      source: "doc['price'].value > params.threshold",
-      params: { threshold: 500 }
-    })
-  )
-  .build();
-
-// Custom scoring with script_score
-const customScored = query(scoredProductMappings)
-  .scriptScore(
-    (q) => q.match('name', 'smartphone'),
-    {
-      source: "_score * Math.log(2 + doc['popularity'].value)",
-      lang: 'painless'
-    }
-  )
+  .filter((q) => q.term('cuisine', 'italian'))
+  .filter((q) => q.geoDistance('location', { lat: 40.7128, lon: -74.006 }, { distance: '5km' }))
+  .sort('rating', 'desc')
   .size(20)
   .build();
 ```
 
-**Script Languages:**
-
-- **painless** (default): Elasticsearch's primary scripting language
-- **expression**: Fast, limited expression language
-- **mustache**: Template-based scripting
+## TypeScript Support
 
-### Percolate Queries
+elasticlink provides mapping-aware TypeScript safety:
 
-Percolate queries enable reverse search - match documents against stored queries. Perfect for alerting, content classification, and saved searches.
+- **Field-Type Constraints**: enforced at compile time across all methods — `match()` only accepts text fields, `term()` only keyword/numeric fields, `sort()` only sortable fields (keyword, numeric, date, boolean, ip), `collapse()` only keyword/numeric fields, `highlight()` only text/keyword fields
+- **Field Autocomplete**: IntelliSense knows your field names and their types
+- **`Infer<S>`**: Derive TS document types from your mappings schema for use elsewhere in your application
+- **Exported Field Group Types**: `TextFields<M>`, `KeywordFields<M>`, `NumericFields<M>`, `DateFields<M>`, `BooleanFields<M>`, `GeoPointFields<M>`, `GeoShapeFields<M>`, `VectorFields<M>`, `DenseVectorFields<M>`, `SparseVectorFields<M>`, `RankFeatureFields<M>`, `CompletionFields<M>`, `IpFields<M>`, `FieldsOfType<M, T>`, and others are exported for use in your own typed utilities
+- **Exported Builder Types**: `QueryBuilder<M>`, `ClauseBuilder<M>`, `RootAggregationBuilder<M>`, `NestedAggregationBuilder<M>`, `NestedEntryBuilder<M>`, `MSearchBuilder<M>`, `BulkBuilder<T>`, `SuggesterBuilder<M>`, `IndexBuilder<M>`, `AnalysisConfig`, `IndexSortFieldSpec`, `MSearchHeader`, `MSearchRequestParams`
 
 ```typescript
-import { query, mappings, keyword, percolator } from 'elasticlink';
+import { queryBuilder, mappings, text, keyword, integer, type Infer } from 'elasticlink';
 
-const alertRuleMappings = mappings({
-  query: percolator(),
-  name: keyword(),
-  severity: keyword(),
+const userMappings = mappings({
+  name: text(),
+  email: keyword(),
+  age: integer()
 });
 
-// Match document against stored queries
-const alerts = query(alertRuleMappings)
-  .percolate({
-    field: 'query',
-    document: {
-      level: 'ERROR',
-      message: 'Database connection failed',
-      timestamp: '2024-01-15T10:30:00Z'
-    }
-  })
-  .size(100)
-  .build();
-```
+type User = Infer<typeof userMappings>;
+// => { name: string; email: string; age: number }
 
-**Common Use Cases:**
+// ✅ 'name' is a text field — match() accepts it
+const q1 = queryBuilder(userMappings).match('name', 'John').build();
+
+// ❌ TypeScript error: 'email' is keyword, not text — use term() instead
+const q2 = queryBuilder(userMappings).match('email', 'john@example.com').build();
 
-- **Alerting:** Match events against alert rules
-- **Content Classification:** Categorize documents in real-time
-- **Saved Searches:** Notify users when new content matches their searches
-- **Monitoring:** Trigger actions based on metric thresholds
+// ✅ Correct: use term() for keyword fields
+const q3 = queryBuilder(userMappings).term('email', 'john@example.com').build();
+```
 
-### Query Suggestions & Autocomplete
+## Settings Presets
 
-Elasticsearch Suggesters provide spell-checking, phrase correction, and autocomplete functionality. Perfect for search-as-you-type experiences and fixing user typos.
+Ready-made index settings for common lifecycle stages. Use with `.settings()` on `indexBuilder()` or pass directly to the ES `_settings` API.
 
 ```typescript
-import { query, suggest, mappings, text, keyword, completion } from 'elasticlink';
+import { indexBuilder, productionSearchSettings, indexSortSettings, fastIngestSettings } from 'elasticlink';
 
-const searchableMappings = mappings({
-  name: text(),
-  description: text(),
-  suggest_field: completion(), // Must be type: completion
-});
+// Create index with production settings
+const indexConfig = indexBuilder().mappings(myMappings).settings(productionSearchSettings()).build();
 
-// Term suggester - Fix typos in individual terms
-const termSuggestions = suggest(searchableMappings)
-  .term('name-suggestions', 'laptpo', {
-    field: 'name',
-    size: 5,
-    suggest_mode: 'popular', // 'missing' | 'popular' | 'always'
-    string_distance: 'levenshtein',
-    max_edits: 2
+// Index-time sort for compression and early termination
+const sortedConfig = indexBuilder()
+  .mappings(myMappings)
+  .settings({
+    ...productionSearchSettings(),
+    index: indexSortSettings({ timestamp: 'desc', status: 'asc' })
   })
   .build();
 
-// Completion suggester - Fast autocomplete
-const autocomplete = suggest(searchableMappings)
-  .completion('autocomplete', 'lap', {
-    field: 'suggest_field',
-    size: 10,
-    skip_duplicates: true,
-    fuzzy: {
-      fuzziness: 'AUTO',
-      transpositions: true,
-      min_length: 3,
-      prefix_length: 1
-    }
-  })
-  .build();
+// Before bulk ingest — disables refresh, removes replicas, async translog
+await client.indices.putSettings({ index: 'my-index', body: fastIngestSettings() });
 
-// Combine with query - Search with autocomplete
-const searchWithSuggestions = query(searchableMappings)
-  .match('name', 'laptpo')
-  .suggest((s) =>
-    s.term('spelling-correction', 'laptpo', {
-      field: 'name',
-      size: 3,
-      suggest_mode: 'popular'
-    })
-  )
-  .size(20)
-  .build();
+// Perform bulk ingest...
+
+// Restore production settings afterward
+await client.indices.putSettings({ index: 'my-index', body: productionSearchSettings() });
+await client.indices.refresh({ index: 'my-index' });
 ```
 
-**Suggester Types:**
+| Preset                                 | Purpose                                                                     |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| `productionSearchSettings(overrides?)` | Balanced production defaults — 1 replica, 5s refresh                        |
+| `indexSortSettings(fields)`            | Configure index-time sort order for disk compression and early termination  |
+| `fastIngestSettings(overrides?)`       | Maximum indexing throughput — async translog, no replicas, refresh disabled |
 
-- **Term:** Suggests corrections for individual terms based on edit distance
-- **Phrase:** Suggests corrections for entire phrases using n-gram language models
-- **Completion:** Fast prefix-based autocomplete (requires `completion` field type)
+All presets accept an optional `overrides` argument typed as `Partial<IndicesIndexSettings>`. `fastIngestSettings` deep-merges the `translog` key so individual translog overrides don't clobber the other defaults.
 
-### Multi-Search API
+## API Overview
 
-Batch multiple search requests in a single API call using the NDJSON format.
+### Query Builder
 
-```typescript
-import { query, msearch } from 'elasticlink';
+`queryBuilder(schema, includeQuery?)` creates a fluent, immutable query builder. Every chain method returns a new builder instance.
 
-const laptopQuery = query(productMappings)
-  .match('name', 'laptop')
-  .range('price', { gte: 500, lte: 2000 })
+```typescript
+queryBuilder(productMappings)
+  .bool()
+  .must((q) => q.match('name', 'laptop'))
+  .filter((q) => q.range('price', { gte: 500 }))
+  .should((q) => q.term('category', 'featured'))
+  .mustNot((q) => q.term('category', 'discontinued'))
+  .minimumShouldMatch(1)
   .build();
+```
 
-const phoneQuery = query(productMappings)
-  .match('name', 'smartphone')
-  .range('price', { gte: 300, lte: 1000 })
-  .build();
+#### Query Methods
 
-// Build as NDJSON string for Elasticsearch API
-const ndjson = msearch(productMappings)
-  .addQuery(laptopQuery, { index: 'products', preference: '_local' })
-  .addQuery(phoneQuery, { index: 'products', preference: '_local' })
-  .build();
+| Category                   | Methods                                                                                           | Description                                                                      |
+| -------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| **Full-text**              | `match`, `multiMatch`, `matchPhrase`, `matchPhrasePrefix`, `matchBoolPrefix`, `combinedFields`    | Analyzed text search — field must be a text field                                |
+| **Term-level**             | `term`, `terms`, `prefix`, `wildcard`, `exists`, `ids`, `matchAll`, `matchNone`                   | Exact value matching — field must be keyword, numeric, date, boolean, or ip      |
+| **Range**                  | `range`                                                                                           | Range queries (`gte`, `lte`, `gt`, `lt`) on numeric, date, keyword, or ip fields |
+| **Fuzzy & Pattern**        | `fuzzy`, `regexp`, `queryString`, `simpleQueryString`, `moreLikeThis`                             | Typo tolerance, regex, Lucene syntax, and similarity search                      |
+| **Boolean**                | `bool` → `must`, `mustNot`, `should`, `filter`, `minimumShouldMatch`                              | Combine clauses with AND/OR/NOT/filter logic                                     |
+| **Conditional**            | `when(condition, fn)`                                                                             | Dynamic query building — skips the branch when condition is falsy                |
+| **Geo**                    | `geoDistance`, `geoBoundingBox`, `geoPolygon`, `geoShape`                                         | Spatial queries — field must be geo_point or geo_shape                           |
+| **Vector & Relevance**     | `knn`, `sparseVector`, `rankFeature`, `distanceFeature`                                           | Semantic/vector search, rank features, and decay functions                       |
+| **Nested & Structure**     | `nested`, `constantScore`, `hasChild`, `hasParent`, `parentId`                                    | Query nested objects, parent/child joins, or wrap in constant-score filter       |
+| **Sorting & Pagination**   | `from`, `size`, `sort`, `searchAfter`, `collapse`                                                 | Result ordering, pagination, and field collapsing                                |
+| **Source & Fields**        | `_source`, `sourceIncludes`, `sourceExcludes`, `fields`, `docValueFields`, `storedFields`         | Control which fields are returned                                                |
+| **Highlighting & Scoring** | `highlight`, `rescore`, `indicesBoost`, `minScore`, `trackScores`, `explain`                      | Result highlighting, rescoring, and relevance tuning                             |
+| **Positional**             | `intervals`, `spanTerm`, `spanNear`, `spanOr`, `spanNot`, `spanFirst`, `spanContaining`, `spanWithin`, `spanMultiTerm`, `spanFieldMasking` | Term proximity and ordering queries |
+| **Advanced**               | `postFilter`, `scriptFields`, `runtimeMappings`, `script`, `scriptScore`, `functionScore`, `percolate` | Post-query filtering, computed fields, and custom scoring                   |
+| **Configuration**          | `timeout`, `preference`, `pit`, `terminateAfter`, `version`, `seqNoPrimaryTerm`, `trackTotalHits` | Search execution options                                                         |
+| **Inline builders**        | `aggs(fn)`, `suggest(fn)`                                                                         | Attach aggregations or suggesters to the query                                   |
+| **Output**                 | `build()`                                                                                         | Returns the final Elasticsearch DSL object                                       |
 
-// Or build as array of objects
-const array = msearch(productMappings)
-  .addQuery(laptopQuery, { index: 'products' })
-  .addQuery(phoneQuery, { index: 'products' })
-  .buildArray();
-```
+All query methods accept options from their corresponding `@elastic/elasticsearch` type. See [`query.types.ts`](src/query.types.ts) for complete signatures.
 
-**NDJSON Format (for Elasticsearch `_msearch` endpoint):**
+#### Conditional Building
 
-```ndjson
-{"index":"products","preference":"_local"}
-{"query":{"bool":{"must":[{"match":{"name":"laptop"}},{"range":{"price":{"gte":500,"lte":2000}}}]}}}
-{"index":"products","preference":"_local"}
-{"query":{"bool":{"must":[{"match":{"name":"smartphone"}},{"range":{"price":{"gte":300,"lte":1000}}}]}}}
+`.when(condition, fn)` — the chain is never broken. When the condition is falsy, the builder is returned unchanged. `condition` resolves as: functions are called, booleans are used as-is, and any other value uses a nullish check (`!= null`) — so numeric `0` and empty string `''` are treated as truthy.
 
+```typescript
+const searchTerm: string | undefined = param.searchTerm;
+const minPrice: number | undefined = param.minPrice;
+
+queryBuilder(productMappings)
+  .bool()
+  .when(searchTerm, (q) => q.must((q2) => q2.match('name', searchTerm!)))
+  .when(minPrice, (q) => q.filter((q2) => q2.range('price', { gte: minPrice! })))
+  .build();
 ```
 
-**Header Options:**
+> **Note:** TypeScript cannot narrow closure variables inside callbacks. Even though `.when(searchTerm, fn)` guarantees the value is defined inside `fn`, you still need a non-null assertion (`!`).
 
-- `index`: Target index/indices (string or array)
-- `routing`: Routing value for sharding
-- `preference`: Node preference (\_local, \_primary, etc.)
-- `search_type`: Search type (dfs_query_then_fetch, etc.)
+#### Query Parameters
 
-### Bulk Operations
+```typescript
+queryBuilder(productMappings)
+  .match('name', 'laptop')
+  .from(0) // Pagination offset
+  .size(20) // Results per page
+  .sort('price', 'asc') // Sort by field
+  ._source(['name', 'price']) // Which fields to return
+  .timeout('5s') // Query timeout
+  .trackScores(true) // Enable scoring in filter context
+  .trackTotalHits(true) // Track total hit count (or pass a number threshold)
+  .explain(true) // Return scoring explanation
+  .minScore(10) // Minimum relevance score
+  .version(true) // Include document version in results
+  .seqNoPrimaryTerm(true) // Include seq_no and primary_term for optimistic concurrency
+  .highlight(['name', 'description'], {
+    fragment_size: 150,
+    pre_tags: ['<mark>'],
+    post_tags: ['</mark>']
+  })
+  .build();
+```
 
-Batch create, index, update, and delete operations efficiently.
+### Aggregations
 
-```typescript
-import { bulk, mappings, keyword, text, float } from 'elasticlink';
+Aggregations can be combined with queries via `.aggs()` or used standalone with the `aggregations()` builder.
 
-const productMappings = mappings({
-  id: keyword(),
-  name: text(),
-  price: float(),
-  category: keyword(),
-});
+```typescript
+import { queryBuilder, aggregations } from 'elasticlink';
 
-const bulkOp = bulk(productMappings)
-  // Index (create or replace)
-  .index(
-    { id: '1', name: 'Laptop Pro', price: 1299, category: 'electronics' },
-    { _index: 'products', _id: '1' }
-  )
-  // Create (fail if exists)
-  .create(
-    { id: '2', name: 'Wireless Mouse', price: 29, category: 'accessories' },
-    { _index: 'products', _id: '2' }
+// Inline aggregations (most common)
+const result = queryBuilder(productMappings)
+  .term('category', 'electronics')
+  .aggs((agg) =>
+    agg
+      .terms('by_category', 'category', { size: 10 })
+      .subAgg((sub) => sub.avg('avg_price', 'price').max('max_price', 'price'))
   )
-  // Update (partial document)
-  .update({
-    _index: 'products',
-    _id: '3',
-    doc: { price: 999 }
-  })
-  // Delete
-  .delete({ _index: 'products', _id: '4' })
+  .size(20)
   .build();
 
-// POST /_bulk with Content-Type: application/x-ndjson
-```
-
-**NDJSON Format:**
-
-```ndjson
-{"index":{"_index":"products","_id":"1"}}
-{"id":"1","name":"Laptop Pro","price":1299,"category":"electronics"}
-{"create":{"_index":"products","_id":"2"}}
-{"id":"2","name":"Wireless Mouse","price":29,"category":"accessories"}
-{"update":{"_index":"products","_id":"3"}}
-{"doc":{"price":999}}
-{"delete":{"_index":"products","_id":"4"}}
+// Aggregations-only (no query) — use queryBuilder(mappings, false)
+const aggsOnly = queryBuilder(productMappings, false)
+  .aggs((agg) => agg.terms('by_category', 'category'))
+  .size(0)
+  .build();
 
+// Standalone aggregation builder (for manual composition)
+const standaloneAgg = aggregations(productMappings)
+  .avg('avg_price', 'price')
+  .terms('by_category', 'category', { size: 10 })
+  .build();
 ```
 
-**Update Options:**
+#### Aggregation Methods
+
+| Category      | Methods                                                                                                                                                                    | Description                                                          |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Bucket**    | `terms`, `dateHistogram`, `histogram`, `range`, `dateRange`, `filters`, `significantTerms`, `rareTerms`, `multiTerms`, `autoDateHistogram`, `composite`, `filter`, `missing`, `geoDistance`, `geohashGrid`, `geotileGrid` | Group documents into buckets |
+| **Metric**    | `avg`, `sum`, `min`, `max`, `cardinality`, `percentiles`, `stats`, `valueCount`, `extendedStats`, `topHits`, `topMetrics`, `weightedAvg`, `geoBounds`, `geoCentroid`       | Compute metrics over documents                                       |
+| **Pipeline**  | `derivative`, `cumulativeSum`, `bucketScript`, `bucketSelector`                                                                                                            | Compute over other aggregation results                               |
+| **Structure** | `subAgg`, `nested`, `reverseNested`, `global`                                                                                                                              | Nest aggregations, navigate nested fields, or escape to global scope |
 
-- `doc`: Partial document merge
-- `script`: Script-based update (Painless)
-- `upsert`: Document to insert if not exists
-- `doc_as_upsert`: Use doc as upsert document
-- `retry_on_conflict`: Retry count for version conflicts
+`subAgg()` attaches sub-aggregations to the **last** aggregation defined before the call — chain order matters. See [`aggregation.types.ts`](src/aggregation.types.ts) for complete option types.
 
 ### Index Management
 
-Configure index mappings, settings, and aliases declaratively.
+Configure index mappings, settings, and aliases declaratively with `indexBuilder()`.
 
 ```typescript
 import { indexBuilder, mappings, keyword, integer, float, date, text } from 'elasticlink';
@@ -567,7 +477,7 @@ const matterMappings = mappings({
   practice_area: keyword(),
   billing_rate: integer(),
   risk_score: float(),
-  opened_at: date(),
+  opened_at: date()
 });
 
 const indexConfig = indexBuilder()
@@ -582,11 +492,11 @@ const indexConfig = indexBuilder()
   .build();
 
 // PUT /matters-v1
-// Content-Type: application/json
-// Body: JSON.stringify(indexConfig)
+await client.indices.create({ index: 'matters-v1', ...indexConfig });
 ```
 
-Produces:
+<details>
+<summary><b>Produced DSL</b> (click to expand)</summary>
 
 ```json
 {
@@ -611,9 +521,21 @@ Produces:
 }
 ```
 
+</details>
+
+#### IndexBuilder Methods
+
+| Method                               | Description                                                                    |
+| ------------------------------------ | ------------------------------------------------------------------------------ |
+| `mappings(schemaOrFields, options?)` | Set index mappings from a `MappingsSchema` or raw field definitions            |
+| `settings(settings)`                 | Set index settings (`IndicesIndexSettings` from `@elastic/elasticsearch`)      |
+| `analysis(config)`                   | Configure custom analyzers, tokenizers, filters, char filters, and normalizers |
+| `alias(name, options?)`              | Add an index alias with optional filter, routing, and write index settings     |
+| `build()`                            | Returns the final `CreateIndexOptions` object                                  |
+
 #### Object and Nested Fields
 
-Use `object()` for structured sub-documents queried with dot-notation — the common case for addresses, names, and similar JSON-like objects. Use `nested()` for arrays of objects where cross-field queries within the same element must be accurate.
+Use `object()` for structured sub-documents queried with dot-notation. Use `nested()` for arrays of objects where cross-field queries within the same element must be accurate.
 
 ```typescript
 import { mappings, text, keyword, float, integer, boolean, object, nested, type Infer } from 'elasticlink';
@@ -621,111 +543,85 @@ import { mappings, text, keyword, float, integer, boolean, object, nested, type
 const productMappings = mappings({
   name: text(),
   in_stock: boolean(),
-
-  // object() — single structured value, queried with dot-notation (no wrapper needed)
   address: object({
+    // Single structured value — queried with dot-notation
     street: text(),
     city: keyword(),
-    country: keyword(),
+    country: keyword()
   }),
-
-  // nested() — array of objects; cross-field queries require the .nested() wrapper
   variants: nested({
+    // Array of objects — cross-field accuracy preserved
     sku: keyword(),
     color: keyword(),
     price: float(),
-    stock: integer(),
-  }),
+    stock: integer()
+  })
 });
 
-// Infer<> produces the correct nested TypeScript types:
 type Product = Infer<typeof productMappings>;
-// {
-//   name: string;
-//   in_stock: boolean;
+// { name: string; in_stock: boolean;
 //   address: { street: string; city: string; country: string };
-//   variants: Array<{ sku: string; color: string; price: number; stock: number }>;
-// }
+//   variants: Array<{ sku: string; color: string; price: number; stock: number }> }
 
 // object sub-fields — query with dot-notation directly
-query(productMappings)
+queryBuilder(productMappings)
   .bool()
-  .filter(q => q.term('address.country', 'US'))   // ✅ 'address.country' is a keyword field
-  .filter(q => q.match('address.street', 'Main'))  // ✅ 'address.street' is a text field
+  .filter((q) => q.term('address.country', 'US'))
+  .filter((q) => q.match('address.street', 'Main'))
   .build();
 
-// nested sub-fields — must use .nested() wrapper; inner builder is fully typed
-query(productMappings)
-  .nested('variants', q => q.term('color', 'black'))  // ✅ 'color' is typed as keyword
+// nested sub-fields — must use .nested() wrapper; field names are relative
+queryBuilder(productMappings)
+  .nested('variants', (q) => q.term('color', 'black'))
   .build();
 
-query(productMappings)
-  .nested('variants', q => q.range('price', { lte: 150 }), { score_mode: 'min' })
+queryBuilder(productMappings)
+  .nested('variants', (q) => q.range('price', { lte: 150 }), { score_mode: 'min' })
   .build();
 ```
 
-> **Inner field names are relative.** Inside a `.nested()` callback, you write field names relative to the nested path (e.g. `'color'`, not `'variants.color'`). The library automatically qualifies them to the correct full path in the generated DSL.
-
-Object and nested fields can be composed to any depth. A 2-level deep mapping works the same way:
-
-```typescript
-const orderMappings = mappings({
-  title: text(),
-  shipments: nested({
-    tracking: keyword(),
-    address: object({     // object() inside nested()
-      city: keyword(),
-      country: keyword(),
-    }),
-  }),
-});
-
-// Root-level fields are queried directly
-query(orderMappings)
-  .term('title', 'urgent')
-  .build();
-
-// Nested sub-fields use .nested(); dot-notation inside is relative to the nested path
-query(orderMappings)
-  .nested('shipments', q => q.term('address.city', 'London'))  // ✅ 'address.city' relative to 'shipments'
-  .build();
-```
+> **Inner field names are relative.** Inside a `.nested()` callback, you write field names relative to the nested path (e.g. `'color'`, not `'variants.color'`). The library automatically qualifies them in the generated DSL.
 
-> **Why the difference?**
-> `object` fields are stored inline in the parent document — Elasticsearch flattens their sub-fields and you query them directly. `nested` fields are stored as separate hidden documents to preserve the relationship between sub-fields within each array element. Without the `.nested()` wrapper, a query like `color=black AND price<50` could incorrectly match a product where different variants have those values.
+#### Field Helpers
 
-**Field Helpers** (shorthand for common field types):
+| Category   | Helpers                                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------------- |
+| Text       | `text`, `keyword`, `constantKeyword`, `matchOnlyText`, `searchAsYouType`, `wildcardField`         |
+| Numeric    | `long`, `integer`, `short`, `byte`, `double`, `float`, `halfFloat`, `scaledFloat`, `unsignedLong` |
+| Date       | `date`, `dateNanos`                                                                               |
+| Boolean    | `boolean`                                                                                         |
+| Binary     | `binary`                                                                                          |
+| IP         | `ip`                                                                                              |
+| Range      | `integerRange`, `floatRange`, `longRange`, `doubleRange`, `dateRange`, `ipRange`                  |
+| Objects    | `object`, `nested`, `flattened`                                                                   |
+| Spatial    | `geoPoint`, `geoShape`                                                                            |
+| Vector     | `denseVector`, `quantizedDenseVector`, `sparseVector`                                             |
+| Rank       | `rankFeature`, `rankFeatures`                                                                     |
+| Semantic   | `semanticText`                                                                                    |
+| Completion | `completion`                                                                                      |
+| Special    | `percolator`, `alias`, `tokenCount`, `murmur3Hash`, `join`                                        |
 
 ```typescript
-import { text, keyword, integer, float, double, date, boolean, denseVector, scaledFloat, halfFloat } from 'elasticlink';
-
 // Shorthand — pass options or use defaults
-keyword()                        // { type: 'keyword' }
-integer()                        // { type: 'integer' }
-float()                          // { type: 'float' }
-date()                           // { type: 'date' }
-text({ analyzer: 'english' })    // { type: 'text', analyzer: 'english' }
-denseVector({ dims: 384, index: true, similarity: 'cosine' })
+keyword(); // { type: 'keyword' }
+integer(); // { type: 'integer' }
+text({ analyzer: 'english' }); // { type: 'text', analyzer: 'english' }
+denseVector({ dims: 384, index: true, similarity: 'cosine' });
+
+// Multi-fields carry type info — dot-notation paths work in queries
+const m = mappings({
+  name: text({ fields: { raw: keyword() } }),
+  price: float({ fields: { string: keyword() } }),
+});
+const qb = queryBuilder(m);
+qb.term('name.raw', 'exact match'); // ✓ name.raw is a KeywordFields<M> path
+qb.match('name', 'full text');      // ✓ name is a TextFields<M> path
 ```
 
-#### Field Types (25+ supported)
-
-| Category    | Helpers                                                                                                                       |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Text        | `text`, `keyword`, `constantKeyword`, `matchOnlyText`, `searchAsYouType`, `wildcardField`                                     |
-| Numeric     | `long`, `integer`, `short`, `byte`, `double`, `float`, `halfFloat`, `scaledFloat`                                             |
-| Date        | `date`                                                                                                                        |
-| Boolean     | `boolean`                                                                                                                     |
-| Range       | `integerRange`, `floatRange`, `longRange`, `doubleRange`, `dateRange`                                                         |
-| Objects     | `object`, `nested`, `flattened`                                                                                               |
-| Spatial     | `geoPoint`, `geoShape`                                                                                                        |
-| Vector      | `denseVector`, `quantizedDenseVector`                                                                                         |
-| Specialized | `ip`, `binary`, `completion`, `percolator`                                                                                    |
-| Alias       | `alias`                                                                                                                       |
-
-#### Mapping Properties
+See [`field.types.ts`](src/field.types.ts) for all field helper option types.
 
-All field helpers accept an optional options object. Common options across types:
+<details>
+<summary><b>Mapping Properties Reference</b> (click to expand)</summary>
 
 | Option                         | Types                  | Description                                                                          |
 | ------------------------------ | ---------------------- | ------------------------------------------------------------------------------------ |
@@ -742,7 +638,7 @@ All field helpers accept an optional options object. Common options across types
 | `dims`                         | `denseVector`          | Number of dimensions (required for KNN indexing)                                     |
 | `similarity`                   | `denseVector`          | Similarity function: `'cosine'`, `'dot_product'`, `'l2_norm'`, `'max_inner_product'` |
 | `element_type`                 | `denseVector`          | Element type: `'float'` (default), `'byte'`, `'bit'`                                 |
-| `fields`                       | text, keyword          | Multi-fields for indexing the same value in multiple ways                            |
+| `fields`                       | text, keyword, numeric, date | Multi-fields — type-safe dot-notation paths (e.g. `name.raw`) in query constraints |
 | `properties`                   | object, nested         | Sub-field mappings                                                                   |
 | `enabled`                      | `object`               | Disable indexing of object fields                                                    |
 | `path`                         | `alias`                | Path to the target field                                                             |
@@ -751,423 +647,269 @@ All field helpers accept an optional options object. Common options across types
 | `preserve_position_increments` | `completion`           | Preserve position increments                                                         |
 | `orientation`                  | `geoShape`             | Default orientation for polygons                                                     |
 
-#### Index Settings
+</details>
+
+<details>
+<summary><b>Index Settings Reference</b> (click to expand)</summary>
 
 The `.settings()` method accepts the full `IndicesIndexSettings` type from `@elastic/elasticsearch`. Common options:
 
-| Setting              | Type     | Description                                        |
-| -------------------- | -------- | -------------------------------------------------- |
-| `number_of_shards`   | `number` | Primary shard count (set at creation, immutable)   |
-| `number_of_replicas` | `number` | Replica count (can be changed after creation)      |
-| `refresh_interval`   | `string` | How often to refresh (`'1s'`, `'-1s'` to disable)  |
-| `max_result_window`  | `number` | Max `from + size` (default: 10000)                 |
-| `analysis`           | `object` | Custom analyzers, tokenizers, filters              |
-| `codec`              | `string` | Compression codec (`'best_compression'`)           |
+| Setting              | Type     | Description                                       |
+| -------------------- | -------- | ------------------------------------------------- |
+| `number_of_shards`   | `number` | Primary shard count (set at creation, immutable)  |
+| `number_of_replicas` | `number` | Replica count (can be changed after creation)     |
+| `refresh_interval`   | `string` | How often to refresh (`'1s'`, `'-1s'` to disable) |
+| `max_result_window`  | `number` | Max `from + size` (default: 10000)                |
+| `analysis`           | `object` | Custom analyzers, tokenizers, filters             |
+| `codec`              | `string` | Compression codec (`'best_compression'`)          |
+
+</details>
 
-#### Alias Options
+<details>
+<summary><b>Alias Options Reference</b> (click to expand)</summary>
 
 The `.alias()` method accepts an optional `IndicesAlias` object:
 
-| Option            | Type      | Description                                                       |
-| ----------------- | --------- | ----------------------------------------------------------------- |
-| `filter`          | `object`  | Query filter — only matching documents visible through alias      |
-| `is_write_index`  | `boolean` | Designate this index as the write target for the alias            |
-| `routing`         | `string`  | Custom routing value for alias operations                         |
-| `index_routing`   | `string`  | Routing value for index operations only                           |
-| `search_routing`  | `string`  | Routing value for search operations only                          |
-| `is_hidden`       | `boolean` | Hide alias from wildcard expressions                              |
+| Option           | Type      | Description                                                  |
+| ---------------- | --------- | ------------------------------------------------------------ |
+| `filter`         | `object`  | Query filter — only matching documents visible through alias |
+| `is_write_index` | `boolean` | Designate this index as the write target for the alias       |
+| `routing`        | `string`  | Custom routing value for alias operations                    |
+| `index_routing`  | `string`  | Routing value for index operations only                      |
+| `search_routing` | `string`  | Routing value for search operations only                     |
+| `is_hidden`      | `boolean` | Hide alias from wildcard expressions                         |
 
-### Settings Presets
+</details>
 
-Ready-made index settings for common lifecycle stages. Use with `.settings()` on `indexBuilder()` or pass directly to the ES `_settings` API.
+### Suggesters & Autocomplete
+
+`suggest(schema)` creates a standalone suggester builder. Suggesters can also be attached inline via `queryBuilder().suggest(fn)`.
 
 ```typescript
-import { productionSearchSettings, indexSortSettings, fastIngestSettings } from 'elasticlink';
+import { queryBuilder, suggest, mappings, text, keyword, completion } from 'elasticlink';
 
-// Create index with production settings
-const indexConfig = indexBuilder()
-  .mappings(myMappings)
-  .settings(productionSearchSettings())
-  .build();
+const searchableMappings = mappings({
+  name: text(),
+  description: text(),
+  suggest_field: completion()
+});
 
-// Index-time sort for compression and early termination
-const sortedConfig = indexBuilder()
-  .mappings(myMappings)
-  .settings({
-    ...productionSearchSettings(),
-    index: indexSortSettings({ timestamp: 'desc', status: 'asc' })
+// Standalone suggest
+const autocomplete = suggest(searchableMappings)
+  .completion('autocomplete', 'lap', {
+    field: 'suggest_field',
+    size: 10,
+    skip_duplicates: true,
+    fuzzy: { fuzziness: 'AUTO', min_length: 3, prefix_length: 1 }
   })
   .build();
 
-// Before bulk ingest — disables refresh, removes replicas, async translog
-await client.indices.putSettings({ index: 'my-index', body: fastIngestSettings() });
-
-// Perform bulk ingest...
-
-// Restore production settings afterward
-await client.indices.putSettings({ index: 'my-index', body: productionSearchSettings() });
-await client.indices.refresh({ index: 'my-index' });
+// Inline with query — search + spell-check in one request
+const searchWithSuggestions = queryBuilder(searchableMappings)
+  .match('name', 'laptpo')
+  .suggest((s) =>
+    s
+      .completion('autocomplete', 'lap', { field: 'suggest_field', size: 5 })
+      .term('spelling', 'laptpo', { field: 'name', size: 3, suggest_mode: 'popular' })
+  )
+  .size(20)
+  .build();
 ```
 
-| Preset | Purpose |
-| ------ | ------- |
-| `productionSearchSettings(overrides?)` | Balanced production defaults — 1 replica, 5s refresh |
-| `indexSortSettings(fields)` | Configure index-time sort order for disk compression and early termination |
-| `fastIngestSettings(overrides?)` | Maximum indexing throughput — async translog, no replicas, refresh disabled |
-
-`fastIngestSettings` deep-merges the `translog` key so individual translog overrides don't clobber the other defaults. All presets accept an optional `overrides` argument typed as `Partial<IndicesIndexSettings>`.
+| Method                              | Description                                                         |
+| ----------------------------------- | ------------------------------------------------------------------- |
+| `term(name, text, options)`         | Suggest corrections for individual terms based on edit distance     |
+| `phrase(name, text, options)`       | Suggest corrections for entire phrases using n-gram language models |
+| `completion(name, prefix, options)` | Fast prefix-based autocomplete (requires `completion` field type)   |
+| `build()`                           | Returns `{ suggest: ... }` object                                   |
 
-## Examples
-
-More examples available in [src/\_\_tests\_\_/examples.test.ts](src/__tests__/examples.test.ts).
+See [`suggester.types.ts`](src/suggester.types.ts) for complete option types (`TermSuggesterOptions`, `PhraseSuggesterOptions`, `CompletionSuggesterOptions`).
 
-### E-commerce Product Search
+### Multi-Search
 
-A complete search request: boolean query with must/filter/should, aggregations for facets and price ranges, highlights, `_source` filtering, and pagination.
+`msearch(schema)` batches multiple search requests into a single API call using NDJSON format.
 
 ```typescript
-const ecommerceMappings = mappings({
-  name: text(),
-  description: text(),
-  category: keyword(),
-  price: float(),
-  tags: keyword(),
-  in_stock: boolean(),
-});
+import { queryBuilder, msearch } from 'elasticlink';
 
-const searchTerm = 'gaming laptop';
-const category = 'electronics';
-const minPrice = 800;
-const maxPrice = 2000;
+const laptopQuery = queryBuilder(productMappings).match('name', 'laptop').range('price', { gte: 500, lte: 2000 }).build();
 
-const result = query(ecommerceMappings)
-  .bool()
-  .must(q => q.match('name', searchTerm, { operator: 'and', boost: 2 }))
-  .should(q => q.fuzzy('description', searchTerm, { fuzziness: 'AUTO' }))
-  .filter(q => q.term('category', category))
-  .filter(q => q.range('price', { gte: minPrice, lte: maxPrice }))
-  .filter(q => q.term('in_stock', true))
-  .minimumShouldMatch(1)
-  .aggs(agg =>
-    agg
-      .terms('by_category', 'category', { size: 10 })
-      .range('price_ranges', 'price', {
-        ranges: [
-          { to: 800 },
-          { from: 800, to: 1500 },
-          { from: 1500 }
-        ]
-      })
-  )
-  .highlight(['name', 'description'], {
-    fragment_size: 150,
-    pre_tags: ['<mark>'],
-    post_tags: ['</mark>']
-  })
-  ._source(['name', 'price', 'category', 'tags'])
-  .timeout('5s')
-  .from(0)
-  .size(20)
-  .sort('_score', 'desc')
+const phoneQuery = queryBuilder(productMappings).match('name', 'smartphone').range('price', { gte: 300, lte: 1000 }).build();
+
+// NDJSON string for Elasticsearch _msearch endpoint
+const ndjson = msearch(productMappings)
+  .addQuery(laptopQuery, { index: 'products', preference: '_local' })
+  .addQuery(phoneQuery, { index: 'products', preference: '_local' })
   .build();
+
+// Or as an array of objects
+const array = msearch(productMappings)
+  .addQuery(laptopQuery, { index: 'products' })
+  .addQuery(phoneQuery, { index: 'products' })
+  .buildArray();
 ```
 
-Produces:
+| Method                         | Description                            |
+| ------------------------------ | -------------------------------------- |
+| `add(request)`                 | Add a raw request (header + body)      |
+| `addQuery(body, header?)`      | Add a built query with optional header |
+| `addQueryBuilder(qb, header?)` | Add a QueryBuilder instance directly   |
+| `withParams(params)`           | Set shared request parameters          |
+| `build()`                      | Returns NDJSON string                  |
+| `buildArray()`                 | Returns array of header/body pairs     |
+| `buildParams()`                | Returns shared request parameters      |
 
-```json
-{
-  "query": {
-    "bool": {
-      "must": [{ "match": { "name": { "query": "gaming laptop", "operator": "and", "boost": 2 } } }],
-      "should": [{ "fuzzy": { "description": { "value": "gaming laptop", "fuzziness": "AUTO" } } }],
-      "filter": [
-        { "term": { "category": "electronics" } },
-        { "range": { "price": { "gte": 800, "lte": 2000 } } },
-        { "term": { "in_stock": true } }
-      ],
-      "minimum_should_match": 1
-    }
-  },
-  "aggs": {
-    "by_category": { "terms": { "field": "category", "size": 10 } },
-    "price_ranges": {
-      "range": {
-        "field": "price",
-        "ranges": [{ "to": 800 }, { "from": 800, "to": 1500 }, { "from": 1500 }]
-      }
-    }
-  },
-  "highlight": {
-    "fields": { "name": { "fragment_size": 150 }, "description": { "fragment_size": 150 } },
-    "pre_tags": ["<mark>"],
-    "post_tags": ["</mark>"]
-  },
-  "_source": ["name", "price", "category", "tags"],
-  "timeout": "5s",
-  "from": 0,
-  "size": 20,
-  "sort": [{ "_score": "desc" }]
-}
-```
+Header options: `index`, `routing`, `preference`, `search_type`. See [`multi-search.types.ts`](src/multi-search.types.ts) for full types.
 
-### Aggregations — Portfolio Analytics
+### Bulk Operations
 
-Terms + sub-aggregation + date histogram in one request.
+`bulk(schema)` batches create, index, update, and delete operations efficiently.
 
 ```typescript
-const instrumentMappings = mappings({
+import { bulk, mappings, keyword, text, float } from 'elasticlink';
+
+const productMappings = mappings({
+  id: keyword(),
   name: text(),
-  asset_class: keyword(),
-  sector: keyword(),
   price: float(),
-  yield_rate: float(),
-  listed_date: date(),
+  category: keyword()
 });
 
-const result = query(instrumentMappings)
-  .bool()
-  .filter(q => q.term('asset_class', 'fixed-income'))
-  .filter(q => q.range('yield_rate', { gte: 3.0 }))
-  .aggs(agg =>
-    agg
-      .terms('by_sector', 'sector', { size: 10 })
-      .subAgg(sub => sub.avg('avg_yield', 'yield_rate').max('max_price', 'price'))
-      .dateHistogram('listings_over_time', 'listed_date', {
-        interval: 'quarter',
-        min_doc_count: 1
-      })
-      .subAgg(sub => sub.percentiles('yield_percentiles', 'yield_rate', { percents: [25, 50, 75, 95] }))
-  )
-  .size(0)
+const bulkOp = bulk(productMappings)
+  .index({ id: '1', name: 'Laptop Pro', price: 1299, category: 'electronics' }, { _index: 'products', _id: '1' })
+  .create({ id: '2', name: 'Wireless Mouse', price: 29, category: 'accessories' }, { _index: 'products', _id: '2' })
+  .update({ _index: 'products', _id: '3', doc: { price: 999 } })
+  .delete({ _index: 'products', _id: '4' })
   .build();
-```
 
-Produces:
-
-```json
-{
-  "query": {
-    "bool": {
-      "filter": [
-        { "term": { "asset_class": "fixed-income" } },
-        { "range": { "yield_rate": { "gte": 3.0 } } }
-      ]
-    }
-  },
-  "aggs": {
-    "by_sector": {
-      "terms": { "field": "sector", "size": 10 },
-      "aggs": {
-        "avg_yield": { "avg": { "field": "yield_rate" } },
-        "max_price": { "max": { "field": "price" } }
-      }
-    },
-    "listings_over_time": {
-      "date_histogram": { "field": "listed_date", "interval": "quarter", "min_doc_count": 1 },
-      "aggs": {
-        "yield_percentiles": { "percentiles": { "field": "yield_rate", "percents": [25, 50, 75, 95] } }
-      }
-    }
-  },
-  "size": 0
-}
+// POST /_bulk with Content-Type: application/x-ndjson
 ```
 
-### Multi-Search — Parallel Queries
+| Method               | Description                                                                    |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `index(doc, meta?)`  | Index a document (create or replace)                                           |
+| `create(doc, meta?)` | Create a document (fail if exists)                                             |
+| `update(meta)`       | Update with `doc`, `script`, `upsert`, `doc_as_upsert`, or `retry_on_conflict` |
+| `delete(meta)`       | Delete a document                                                              |
+| `build()`            | Returns NDJSON string                                                          |
+| `buildArray()`       | Returns array of action/document pairs                                         |
+
+### Vector Search & Semantic Search
 
-Batch multiple independent searches into a single HTTP request.
+KNN (k-nearest neighbors) queries enable semantic search using vector embeddings.
 
 ```typescript
-const listingMappings = mappings({
-  address: text(),
-  property_class: keyword(),
-  list_price: long(),
+import { queryBuilder, mappings, text, keyword, float, denseVector } from 'elasticlink';
+
+const productWithEmbeddingMappings = mappings({
+  name: text(),
+  description: text(),
+  price: float(),
+  category: keyword(),
+  embedding: denseVector({ dims: 384 })
 });
 
-const condoSearch = query(listingMappings)
-  .bool()
-  .filter(q => q.term('property_class', 'condo'))
-  .filter(q => q.range('list_price', { lte: 2_000_000 }))
-  .aggs(agg => agg.avg('avg_price', 'list_price'))
-  .size(0)
-  .build();
+const searchEmbedding = [0.23, 0.45, 0.67, 0.12, 0.89]; // From your ML model
 
-const townhouseSearch = query(listingMappings)
-  .bool()
-  .filter(q => q.term('property_class', 'townhouse'))
-  .aggs(agg => agg.avg('avg_price', 'list_price').min('min_price', 'list_price'))
-  .size(0)
+// Basic semantic search
+const result = queryBuilder(productWithEmbeddingMappings)
+  .knn('embedding', searchEmbedding, {
+    k: 10,
+    num_candidates: 100
+  })
+  .size(10)
   .build();
 
-const ndjson = msearch(listingMappings)
-  .addQuery(condoSearch, { index: 'listings' })
-  .addQuery(townhouseSearch, { index: 'listings' })
+// Hybrid search — KNN + filters + aggregations
+const hybridSearch = queryBuilder(productWithEmbeddingMappings)
+  .knn('embedding', searchEmbedding, {
+    k: 100,
+    num_candidates: 1000,
+    filter: { term: { category: 'electronics' } },
+    boost: 1.2,
+    similarity: 0.7
+  })
+  .aggs((agg) => agg.terms('categories', 'category', { size: 10 }))
+  .size(20)
   .build();
 ```
 
-Produces:
-
-```ndjson
-{"index":"listings"}
-{"query":{"bool":{"filter":[{"term":{"property_class":"condo"}},{"range":{"list_price":{"lte":2000000}}}]}},"aggs":{"avg_price":{"avg":{"field":"list_price"}}},"size":0}
-{"index":"listings"}
-{"query":{"bool":{"filter":[{"term":{"property_class":"townhouse"}}]}},"aggs":{"avg_price":{"avg":{"field":"list_price"}},"min_price":{"min":{"field":"list_price"}}},"size":0}
+Additional vector and relevance methods: `sparseVector(field, options)` for learned sparse retrieval, `rankFeature(field, options?)` for rank feature scoring, and `distanceFeature(field, options)` for recency/proximity decay functions.
 
-```
+### Script Queries & Custom Scoring
 
-### Suggesters — Autocomplete & Spell Check
+Script-based filtering and custom scoring for advanced relevance tuning.
 
 ```typescript
-const attorneyMappings = mappings({
+import { queryBuilder, mappings, text, float, long } from 'elasticlink';
+
+const scoredProductMappings = mappings({
   name: text(),
-  practice_area: keyword(),
-  name_suggest: completion(),
+  price: float(),
+  popularity: long()
 });
 
-// Standalone suggest request
-const suggestions = query(attorneyMappings)
-  .suggest(s =>
-    s
-      .completion('autocomplete', 'kap', { field: 'name_suggest', size: 5 })
-      .term('spelling', 'wiliams', { field: 'name', size: 3 })
+// Script-based filtering
+const filtered = queryBuilder(scoredProductMappings)
+  .bool()
+  .must((q) => q.match('name', 'laptop'))
+  .filter((q) =>
+    q.script({
+      source: "doc['price'].value > params.threshold",
+      params: { threshold: 500 }
+    })
   )
-  .size(0)
   .build();
-```
-
-Produces:
-
-```json
-{
-  "suggest": {
-    "autocomplete": {
-      "prefix": "kap",
-      "completion": { "field": "name_suggest", "size": 5 }
-    },
-    "spelling": {
-      "text": "wiliams",
-      "term": { "field": "name", "size": 3 }
-    }
-  },
-  "size": 0
-}
-```
-
-### Dynamic Search with Conditional Filters
-
-```typescript
-const buildDynamicQuery = (filters: SearchFilters) => {
-  return query(productMappings)
-    .bool()
-    .when(filters.searchTerm, q => q.must(q2 => q2.match('name', filters.searchTerm!, { boost: 2 })))
-    .when(filters.category,   q => q.filter(q2 => q2.term('category', filters.category!)))
-    .when(filters.minPrice != null && filters.maxPrice != null,
-      q => q.filter(q2 => q2.range('price', { gte: filters.minPrice!, lte: filters.maxPrice! }))
-    )
-    .from(filters.offset || 0)
-    .size(filters.limit || 20)
-    .build();
-};
-```
-
-### Geospatial Search
 
-```typescript
-const restaurantMappings = mappings({
-  name: text(),
-  cuisine: keyword(),
-  location: geoPoint(),
-  rating: float(),
-});
-
-const result = query(restaurantMappings)
-  .term('cuisine', 'italian')
-  .geoDistance(
-    'location',
-    { lat: 40.7128, lon: -74.006 },
-    { distance: '5km' }
-  )
-  .from(0)
+// Custom scoring with script_score
+const customScored = queryBuilder(scoredProductMappings)
+  .scriptScore((q) => q.match('name', 'smartphone'), {
+    source: "_score * Math.log(2 + doc['popularity'].value)",
+    lang: 'painless'
+  })
   .size(20)
   .build();
 ```
 
-## TypeScript Support
-
-elasticlink provides mapping-aware TypeScript safety:
+### Percolate Queries
 
-- **Field-Type Constraints**: enforced at compile time across all methods — `match()` only accepts text fields, `term()` only keyword/numeric fields, `sort()` only sortable fields (keyword, numeric, date, boolean, ip), `collapse()` only keyword/numeric fields, `highlight()` only text/keyword fields
-- **Field Autocomplete**: IntelliSense knows your field names and their types
-- **`Infer<S>`**: Derive TS document types from your mappings schema
-- **Exported Field Group Types**: `SortableFields<M>`, `CollapsibleFields<M>`, `HighlightableFields<M>`, `TextFields<M>`, `KeywordFields<M>`, and others are exported for use in your own typed utilities
+Percolate queries enable reverse search — match documents against stored queries.
 
 ```typescript
-import { query, mappings, text, keyword, integer, type Infer } from 'elasticlink';
+import { queryBuilder, mappings, keyword, percolator } from 'elasticlink';
 
-const userMappings = mappings({
-  name: text(),
-  email: keyword(),
-  age: integer(),
+const alertRuleMappings = mappings({
+  query: percolator(),
+  name: keyword(),
+  severity: keyword()
 });
 
-type User = Infer<typeof userMappings>;
-// => { name: string; email: string; age: number }
-
-// ✅ 'name' is a text field — match() accepts it
-const q1 = query(userMappings).match('name', 'John').build();
-
-// ❌ TypeScript error: 'email' is keyword, not text — use term() instead
-const q2 = query(userMappings).match('email', 'john@example.com').build();
-
-// ✅ Correct: use term() for keyword fields
-const q3 = query(userMappings).term('email', 'john@example.com').build();
+const alerts = queryBuilder(alertRuleMappings)
+  .percolate({
+    field: 'query',
+    document: {
+      level: 'ERROR',
+      message: 'Database connection failed',
+      timestamp: '2024-01-15T10:30:00Z'
+    }
+  })
+  .size(100)
+  .build();
 ```
 
-## Testing
+**Common use cases:** alerting (match events against rules), content classification, saved search notifications, and metric threshold monitoring.
 
-```bash
-# Run tests
-npm test
-
-# Watch mode
-npm test:watch
+## Compatibility
 
-# Coverage report
-npm test:coverage
+| elasticlink  | Node.js    | Elasticsearch |
+| ------------ | ---------- | ------------- |
+| 1.0.0-beta.1 | 20, 22, 24 | 9.x (≥9.0.0) |
 
-# Type check
-npm run type-check
-```
-
-## Roadmap
-
-### Current Release ✅
-
-- [x] Core query types (match, term, range, bool, etc.)
-- [x] Fuzzy queries for typo tolerance
-- [x] Query parameters (from, size, sort, timeout, etc.)
-- [x] Conditional query building
-- [x] Highlight support
-- [x] Aggregations (bucket and metric)
-- [x] Geo queries (distance, bounding box, polygon)
-- [x] Advanced patterns (regexp, constant_score)
-- [x] Sub-aggregation support
-- [x] Query + aggregations integration
-- [x] KNN (k-nearest neighbors) queries for vector search
-- [x] Semantic search with vector embeddings
-- [x] Dense vector field support
-- [x] Script queries and custom scoring
-- [x] Percolate queries for reverse search
-- [x] Multi-search API (NDJSON batched queries)
-- [x] Bulk operations (create, index, update, delete)
-- [x] Index management (mappings, settings, aliases)
-- [x] Query suggestions/completions (term, phrase, completion)
-- [x] Integration test suite against live Elasticsearch 9.x
-- [x] Types derived from official `@elastic/elasticsearch` for accuracy and completeness
+Tested against the versions listed. Peer dependency is `@elastic/elasticsearch >=9.0.0`.
 
 ## Development
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and code style.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, design principles, and code style.
 
 ## License