elasticlink 0.5.0-beta → 0.7.0-beta

package/README.md

@@ -24,6 +24,9 @@ elasticlink simplifies building Elasticsearch queries and index management in Ty
 
 | elasticlink | Node.js     | Elasticsearch |
 |-------------|-------------|---------------|
+| 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)  |
@@ -183,7 +186,7 @@ Aggregations can be combined with queries or used standalone:
 
 - **Bucket**: `terms()`, `dateHistogram()`, `histogram()`, `range()`
 - **Metric**: `avg()`, `sum()`, `min()`, `max()`, `cardinality()`, `percentiles()`, `stats()`, `valueCount()`
-- **Composition**: `subAgg()` for nested aggregations
+- **Composition**: `subAgg()` for nested aggregations — attaches sub-aggregations to the **last** aggregation defined before the call; chain order matters
 
 ```typescript
 import { query, aggregations } from 'elasticlink';
@@ -284,12 +287,14 @@ const hybridSearch = query(productWithEmbeddingMappings)
 ```
 
 **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:**
+
 ```typescript
 import type { DenseVectorOptions } from 'elasticlink';
 
@@ -345,6 +350,7 @@ const customScored = query(scoredProductMappings)
 ```
 
 **Script Languages:**
+
 - **painless** (default): Elasticsearch's primary scripting language
 - **expression**: Fast, limited expression language
 - **mustache**: Template-based scripting
@@ -1089,9 +1095,10 @@ const result = query(restaurantMappings)
 
 elasticlink provides mapping-aware TypeScript safety:
 
-- **Field-Type Constraints**: `match()` only accepts text fields, `term()` only keyword fields — enforced at compile time
+- **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
 
 ```typescript
 import { query, mappings, text, keyword, integer, type Infer } from 'elasticlink';

package/dist/aggregation.builder.d.ts

@@ -1,6 +1,6 @@
 import type { FieldTypeString } from './index-management.types.js';
 import type { MappingsSchema } from './mapping.types.js';
-import { AggregationBuilder, AggregationState } from './aggregation.types.js';
-export declare const createAggregationBuilder: <M extends Record<string, FieldTypeString>>(state?: AggregationState) => AggregationBuilder<M>;
-export declare const aggregations: <M extends Record<string, FieldTypeString>>(_schema: MappingsSchema<M>) => AggregationBuilder<M>;
+import type { RootAggregationBuilder, AggregationState } from './aggregation.types.js';
+export declare function createAggregationBuilder<M extends Record<string, FieldTypeString>>(state?: AggregationState): RootAggregationBuilder<M>;
+export declare const aggregations: <M extends Record<string, FieldTypeString>>(_schema: MappingsSchema<M>) => RootAggregationBuilder<M>;
 //# sourceMappingURL=aggregation.builder.d.ts.map

package/dist/aggregation.builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregation.builder.d.ts","sourceRoot":"","sources":["../src/aggregation.builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAajB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,wBAAwB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAChF,QAAO,gBAAqB,KAC3B,kBAAkB,CAAC,CAAC,CAsKrB,CAAC;AAGH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,SAAS,cAAc,CAAC,CAAC,CAAC,0BACnE,CAAC"}
+{"version":3,"file":"aggregation.builder.d.ts","sourceRoot":"","sources":["../src/aggregation.builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAiC,MAAM,oBAAoB,CAAC;AACxF,OAAO,KAAK,EACV,sBAAsB,EAGtB,gBAAgB,EAkBjB,MAAM,wBAAwB,CAAC;AAuHhC,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAChF,KAAK,GAAE,gBAAqB,GAC3B,sBAAsB,CAAC,CAAC,CAAC,CAgB3B;AAED,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,SAAS,cAAc,CAAC,CAAC,CAAC,8BACnE,CAAC"}

package/dist/aggregation.builder.js

@@ -1,155 +1,65 @@
-export const createAggregationBuilder = (state = {}) => ({
-    // Bucket aggregations
-    terms: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                terms: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    dateHistogram: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                date_histogram: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    range: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                range: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    histogram: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                histogram: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    // Metric aggregations
-    avg: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                avg: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    sum: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                sum: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    min: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                min: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    max: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                max: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    cardinality: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                cardinality: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    percentiles: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                percentiles: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    stats: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                stats: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    valueCount: (name, field, options) => {
-        return createAggregationBuilder({
-            ...state,
-            [name]: {
-                value_count: {
-                    field,
-                    ...(options && options)
-                }
-            }
-        });
-    },
-    // Sub-aggregations
-    subAgg: (fn) => {
-        const keys = Object.keys(state);
-        const lastKey = keys.at(-1);
-        const { [lastKey]: lastAgg } = state;
-        const subAggs = fn(createAggregationBuilder({})).build();
-        return createAggregationBuilder({
-            ...state,
-            [lastKey]: {
-                ...lastAgg,
-                aggs: subAggs
-            }
-        });
-    },
-    // Build
+// Shared metric/bucket method implementations — return type is `any` so the same code
+// can be spread into RootAggregationBuilder, NestedEntryBuilder, and NestedAggregationBuilder.
+// The actual return-type contracts are enforced by the public factory return-type annotations.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const sharedAggMethods = (state, rebuild) => ({
+    terms: (name, field, options) => rebuild({ ...state, [name]: { terms: { field, ...(options ?? {}) } } }),
+    dateHistogram: (name, field, options) => rebuild({ ...state, [name]: { date_histogram: { field, ...(options ?? {}) } } }),
+    range: (name, field, options) => rebuild({ ...state, [name]: { range: { field, ...(options ?? {}) } } }),
+    histogram: (name, field, options) => rebuild({ ...state, [name]: { histogram: { field, ...(options ?? {}) } } }),
+    avg: (name, field, options) => rebuild({ ...state, [name]: { avg: { field, ...(options ?? {}) } } }),
+    sum: (name, field, options) => rebuild({ ...state, [name]: { sum: { field, ...(options ?? {}) } } }),
+    min: (name, field, options) => rebuild({ ...state, [name]: { min: { field, ...(options ?? {}) } } }),
+    max: (name, field, options) => rebuild({ ...state, [name]: { max: { field, ...(options ?? {}) } } }),
+    cardinality: (name, field, options) => rebuild({ ...state, [name]: { cardinality: { field, ...(options ?? {}) } } }),
+    percentiles: (name, field, options) => rebuild({ ...state, [name]: { percentiles: { field, ...(options ?? {}) } } }),
+    stats: (name, field, options) => rebuild({ ...state, [name]: { stats: { field, ...(options ?? {}) } } }),
+    valueCount: (name, field, options) => rebuild({ ...state, [name]: { value_count: { field, ...(options ?? {}) } } }),
+    extendedStats: (name, field, options) => rebuild({ ...state, [name]: { extended_stats: { field, ...(options ?? {}) } } }),
+    topHits: (name, options) => rebuild({ ...state, [name]: { top_hits: { ...(options ?? {}) } } }),
+    autoDateHistogram: (name, field, options) => rebuild({ ...state, [name]: { auto_date_histogram: { field, ...(options ?? {}) } } }),
+    composite: (name, sources, options) => rebuild({ ...state, [name]: { composite: { sources, ...(options ?? {}) } } }),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    filter: (name, query) => rebuild({ ...state, [name]: { filter: query } }),
     // eslint-disable-next-line functional/functional-parameters
     build: () => state
 });
-// Helper function to create aggregations without needing to import the builder
+const attachSubAgg = (state, subAggState) => {
+    const lastKey = Object.keys(state).at(-1);
+    const existing = state[lastKey].aggs ?? {};
+    return { ...state, [lastKey]: { ...state[lastKey], aggs: { ...existing, ...subAggState } } };
+};
+// Function declarations are used for the internal factories (vs const arrows) so that mutual
+// recursion between createNestedEntryBuilder and createNestedAggregationBuilder is hoisted.
+function createNestedEntryBuilder(state, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+rebuild
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+) {
+    return {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ...sharedAggMethods(state, rebuild),
+        global: (name) => createAggregationBuilder({ ...state, [name]: { global: {} } }),
+        nested: (name, path) => createNestedEntryBuilder({ ...state, [name]: { nested: { path } } }, rebuild),
+        subAgg: (fn) => rebuild(attachSubAgg(state, fn(createNestedAggregationBuilder()).build()))
+    };
+}
+function createNestedAggregationBuilder(state = {}) {
+    return {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ...sharedAggMethods(state, (createNestedAggregationBuilder)),
+        nested: (name, path) => createNestedEntryBuilder({ ...state, [name]: { nested: { path } } }, (createNestedAggregationBuilder)),
+        reverseNested: (name, path) => createNestedAggregationBuilder({ ...state, [name]: { reverse_nested: path ? { path } : {} } }),
+        subAgg: (fn) => createNestedAggregationBuilder(attachSubAgg(state, fn(createNestedAggregationBuilder()).build()))
+    };
+}
+export function createAggregationBuilder(state = {}) {
+    return {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ...sharedAggMethods(state, (createAggregationBuilder)),
+        global: (name) => createAggregationBuilder({ ...state, [name]: { global: {} } }),
+        nested: (name, path) => createNestedEntryBuilder({ ...state, [name]: { nested: { path } } }, (createAggregationBuilder)),
+        subAgg: (fn) => createAggregationBuilder(attachSubAgg(state, fn(createAggregationBuilder()).build()))
+    };
+}
 export const aggregations = (_schema) => createAggregationBuilder();

package/dist/aggregation.types.d.ts

@@ -3,9 +3,9 @@
  * Derived from official @elastic/elasticsearch types for accuracy and completeness.
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html
  */
-import type { AggregationsTermsAggregation, AggregationsDateHistogramAggregation, AggregationsRangeAggregation, AggregationsHistogramAggregation, AggregationsAverageAggregation, AggregationsSumAggregation, AggregationsMinAggregation, AggregationsMaxAggregation, AggregationsCardinalityAggregation, AggregationsPercentilesAggregation, AggregationsStatsAggregation, AggregationsValueCountAggregation, AggregationsCalendarInterval } from '@elastic/elasticsearch/lib/api/types';
+import type { AggregationsTermsAggregation, AggregationsDateHistogramAggregation, AggregationsRangeAggregation, AggregationsHistogramAggregation, AggregationsAverageAggregation, AggregationsSumAggregation, AggregationsMinAggregation, AggregationsMaxAggregation, AggregationsCardinalityAggregation, AggregationsPercentilesAggregation, AggregationsStatsAggregation, AggregationsValueCountAggregation, AggregationsCalendarInterval, AggregationsExtendedStatsAggregation, AggregationsTopHitsAggregation, AggregationsAutoDateHistogramAggregation, AggregationsCompositeAggregation, AggregationsCompositeAggregationSource } from '@elastic/elasticsearch/lib/api/types';
 import type { FieldTypeString } from './index-management.types.js';
-import type { DateFields, NumericFields } from './mapping.types.js';
+import type { DateFields, NumericFields, KeywordFields, BooleanFields, IpFields, NestedPathFields, SubFieldsOf } from './mapping.types.js';
 /**
  * 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
@@ -71,6 +71,30 @@ export type StatsAggOptions = Omit<AggregationsStatsAggregation, 'field'>;
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-valuecount-aggregation.html
  */
 export 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
+ */
+export 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
+ */
+export 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
+ */
+export type AutoDateHistogramAggOptions = Omit<AggregationsAutoDateHistogramAggregation, 'field'>;
+/**
+ * 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
+ */
+export type CompositeAggSource = Record<string, AggregationsCompositeAggregationSource>;
+/**
+ * Options for composite aggregation (excludes 'sources' which is handled by the builder)
+ */
+export type CompositeAggOptions = Omit<AggregationsCompositeAggregation, 'sources'>;
 /**
  * Aggregation state for build output
  */
@@ -78,36 +102,72 @@ export type AggregationState = {
     [key: string]: any;
 };
 /**
- * Aggregation builder interface
- */
-export type AggregationBuilder<M extends Record<string, FieldTypeString>> = {
-    /** Terms aggregation - group by field values */
-    terms: <K extends string & keyof M>(name: string, field: K, options?: TermsAggOptions) => AggregationBuilder<M>;
-    /** Date histogram aggregation - group by time intervals */
-    dateHistogram: <K extends DateFields<M> & string>(name: string, field: K, options?: DateHistogramAggOptions) => AggregationBuilder<M>;
-    /** Range aggregation - group by numeric/date ranges */
-    range: <K extends string & keyof M>(name: string, field: K, options?: RangeAggOptions) => AggregationBuilder<M>;
-    /** Histogram aggregation - group by numeric intervals */
-    histogram: <K extends NumericFields<M> & string>(name: string, field: K, options?: HistogramAggOptions) => AggregationBuilder<M>;
-    /** Average aggregation */
-    avg: <K extends NumericFields<M> & string>(name: string, field: K, options?: AvgAggOptions) => AggregationBuilder<M>;
-    /** Sum aggregation */
-    sum: <K extends NumericFields<M> & string>(name: string, field: K, options?: SumAggOptions) => AggregationBuilder<M>;
-    /** Minimum value aggregation */
-    min: <K extends NumericFields<M> & string>(name: string, field: K, options?: MinAggOptions) => AggregationBuilder<M>;
-    /** Maximum value aggregation */
-    max: <K extends NumericFields<M> & string>(name: string, field: K, options?: MaxAggOptions) => AggregationBuilder<M>;
-    /** Cardinality aggregation - count unique values */
-    cardinality: <K extends string & keyof M>(name: string, field: K, options?: CardinalityAggOptions) => AggregationBuilder<M>;
-    /** Percentiles aggregation */
-    percentiles: <K extends NumericFields<M> & string>(name: string, field: K, options?: PercentilesAggOptions) => AggregationBuilder<M>;
-    /** Statistics aggregation (count, min, max, avg, sum) */
-    stats: <K extends NumericFields<M> & string>(name: string, field: K, options?: StatsAggOptions) => AggregationBuilder<M>;
-    /** Value count aggregation */
-    valueCount: <K extends string & keyof M>(name: string, field: K, options?: ValueCountAggOptions) => AggregationBuilder<M>;
-    /** Add sub-aggregation to parent bucket aggregation */
-    subAgg: (fn: (agg: AggregationBuilder<M>) => AggregationBuilder<M>) => AggregationBuilder<M>;
-    /** Build aggregation DSL */
+ * Shared metric and bucket aggregation methods.
+ * `Self` is the return type for each method — varies by context (root vs nested).
+ */
+export 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;
+    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 string & keyof M>(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 string & keyof M>(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: Record<string, any>) => 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).
+ */
+export 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.
+ */
+export 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`.
+ */
+export 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>;
+}
 //# sourceMappingURL=aggregation.types.d.ts.map

package/dist/aggregation.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregation.types.d.ts","sourceRoot":"","sources":["../src/aggregation.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"aggregation.types.d.ts","sourceRoot":"","sources":["../src/aggregation.types.ts"],"names":[],"mappings":"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"}

package/dist/field.helpers.d.ts

@@ -13,7 +13,7 @@
  *   embedding: denseVector({ dims: 384 }),
  * });
  */
-import type { TextFieldOptions, KeywordFieldOptions, NumericFieldOptions, ScaledFloatFieldOptions, DateFieldOptions, BooleanFieldOptions, DenseVectorFieldOptions, ObjectFieldOptions, CompletionFieldOptions, GeoPointFieldOptions, GeoShapeFieldOptions, AliasFieldOptions, IpFieldOptions, RangeFieldOptions, MatchOnlyTextFieldOptions, SearchAsYouTypeFieldOptions, ConstantKeywordFieldOptions, WildcardFieldOptions, FlattenedFieldOptions, FieldMappingWithLiteralType, TextFieldMapping, KeywordFieldMapping, LongFieldMapping, IntegerFieldMapping, ShortFieldMapping, ByteFieldMapping, DoubleFieldMapping, FloatFieldMapping, HalfFloatFieldMapping, ScaledFloatFieldMapping, DateFieldMapping, BooleanFieldMapping, BinaryFieldMapping, IpFieldMapping, DenseVectorFieldMapping, GeoPointFieldMapping, GeoShapeFieldMapping, CompletionFieldMapping, TypedNestedFieldMapping, TypedObjectFieldMapping, AliasFieldMapping, PercolatorFieldMapping, IntegerRangeFieldMapping, FloatRangeFieldMapping, LongRangeFieldMapping, DoubleRangeFieldMapping, DateRangeFieldMapping, MatchOnlyTextFieldMapping, SearchAsYouTypeFieldMapping, ConstantKeywordFieldMapping, WildcardFieldMapping, FlattenedFieldMapping } from './field.types.js';
+import type { TextFieldOptions, KeywordFieldOptions, NumericFieldOptions, UnsignedLongFieldOptions, ScaledFloatFieldOptions, DateFieldOptions, BooleanFieldOptions, DenseVectorFieldOptions, SemanticTextFieldOptions, ObjectFieldOptions, CompletionFieldOptions, GeoPointFieldOptions, GeoShapeFieldOptions, AliasFieldOptions, IpFieldOptions, RangeFieldOptions, MatchOnlyTextFieldOptions, SearchAsYouTypeFieldOptions, ConstantKeywordFieldOptions, WildcardFieldOptions, FlattenedFieldOptions, FieldMappingWithLiteralType, TextFieldMapping, KeywordFieldMapping, LongFieldMapping, IntegerFieldMapping, ShortFieldMapping, ByteFieldMapping, DoubleFieldMapping, FloatFieldMapping, HalfFloatFieldMapping, ScaledFloatFieldMapping, DateFieldMapping, BooleanFieldMapping, BinaryFieldMapping, IpFieldMapping, DenseVectorFieldMapping, SparseVectorFieldMapping, SemanticTextFieldMapping, UnsignedLongFieldMapping, GeoPointFieldMapping, GeoShapeFieldMapping, CompletionFieldMapping, TypedNestedFieldMapping, TypedObjectFieldMapping, AliasFieldMapping, PercolatorFieldMapping, IntegerRangeFieldMapping, FloatRangeFieldMapping, LongRangeFieldMapping, DoubleRangeFieldMapping, DateRangeFieldMapping, MatchOnlyTextFieldMapping, SearchAsYouTypeFieldMapping, ConstantKeywordFieldMapping, WildcardFieldMapping, FlattenedFieldMapping } from './field.types.js';
 export declare const text: (options?: TextFieldOptions) => TextFieldMapping;
 export declare const keyword: (options?: KeywordFieldOptions) => KeywordFieldMapping;
 export declare const long: (options?: NumericFieldOptions) => LongFieldMapping;
@@ -61,6 +61,30 @@ export declare const denseVector: (options?: DenseVectorFieldOptions) => DenseVe
  *   .build();
  */
 export 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
+ */
+export declare const sparseVector: () => SparseVectorFieldMapping;
+/**
+ * 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
+ */
+export 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
+ */
+export declare const unsignedLong: (options?: UnsignedLongFieldOptions) => UnsignedLongFieldMapping;
 export declare const geoPoint: (options?: GeoPointFieldOptions) => GeoPointFieldMapping;
 export declare const geoShape: (options?: GeoShapeFieldOptions) => GeoShapeFieldMapping;
 export declare const completion: (options?: CompletionFieldOptions) => CompletionFieldMapping;

package/dist/field.helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field.helpers.d.ts","sourceRoot":"","sources":["../src/field.helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"field.helpers.d.ts","sourceRoot":"","sources":["../src/field.helpers.ts"],"names":[],"mappings":"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"}

package/dist/field.helpers.js

@@ -113,6 +113,37 @@ export const quantizedDenseVector = (options) => ({
     ...options,
     index_options: { type: 'int8_hnsw', ...options?.index_options }
 });
+/**
+ * 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
+ */
+// eslint-disable-next-line functional/functional-parameters
+export const sparseVector = () => ({ type: 'sparse_vector' });
+/**
+ * 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
+ */
+export const semanticText = (options) => ({
+    type: 'semantic_text',
+    ...options
+});
+/**
+ * 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
+ */
+export const unsignedLong = (options) => ({
+    type: 'unsigned_long',
+    ...options
+});
 // Geo
 export const geoPoint = (options) => ({
     type: 'geo_point',

package/dist/field.types.d.ts

@@ -53,6 +53,10 @@ export type NumericFieldOptions = {
 export type ScaledFloatFieldOptions = NumericFieldOptions & {
     scaling_factor?: number;
 };
+/** Options for unsigned_long fields — null_value accepts string or number for >MAX_SAFE_INTEGER precision */
+export type UnsignedLongFieldOptions = Omit<NumericFieldOptions, 'null_value'> & {
+    null_value?: string | number;
+};
 /** Options for date fields */
 export type DateFieldOptions = {
     boost?: number;
@@ -81,6 +85,18 @@ export type DenseVectorFieldOptions = {
     index_options?: any;
     similarity?: 'cosine' | 'dot_product' | 'l2_norm' | 'max_inner_product';
 };
+/**
+ * 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
+ */
+export type SemanticTextFieldOptions = {
+    inference_id?: string;
+    search_inference_id?: string;
+    model_settings?: {
+        task_type?: string;
+        [key: string]: unknown;
+    };
+};
 /** Sub-fields for nested and object field types */
 export type NestedFields = Record<string, FieldMapping>;
 /** Options for object fields (enabled flag only — sub-fields are the first argument) */
@@ -216,6 +232,9 @@ export type BooleanFieldMapping = TypedFieldMapping<'boolean'>;
 export type BinaryFieldMapping = TypedFieldMapping<'binary'>;
 export type IpFieldMapping = TypedFieldMapping<'ip'>;
 export type DenseVectorFieldMapping = TypedFieldMapping<'dense_vector'>;
+export type SparseVectorFieldMapping = TypedFieldMapping<'sparse_vector'>;
+export type SemanticTextFieldMapping = TypedFieldMapping<'semantic_text'>;
+export type UnsignedLongFieldMapping = TypedFieldMapping<'unsigned_long'>;
 export type GeoPointFieldMapping = TypedFieldMapping<'geo_point'>;
 export type GeoShapeFieldMapping = TypedFieldMapping<'geo_shape'>;
 export type CompletionFieldMapping = TypedFieldMapping<'completion'>;