Add configurable refresh per operation

- Add refresh parameter to ElasticsearchServiceParams
- Create mergeESParamsWithRefresh utility function
- Allow per-operation override of global refresh setting
- Support false, true, and 'wait_for' refresh modes
- Update all write methods to use refresh override

Author: marshallswain

src/methods/create.ts

@@ -1,9 +1,13 @@
 import { getDocDescriptor } from '../utils/index'
-import { prepareGetParams } from '../utils/params'
+import { prepareGetParams, mergeESParamsWithRefresh } from '../utils/params'
 import { ElasticsearchServiceParams, ElasticAdapterInterface, DocDescriptor, IndexRequest } from '../types'
 import { get } from './get'
 
-function getCreateParams(service: ElasticAdapterInterface, docDescriptor: DocDescriptor): IndexRequest {
+function getCreateParams(
+  service: ElasticAdapterInterface,
+  docDescriptor: DocDescriptor,
+  requestParams: ElasticsearchServiceParams = {}
+): IndexRequest {
   let { id, parent, routing, join, doc } = docDescriptor
 
   if (join) {
@@ -19,25 +23,25 @@ function getCreateParams(service: ElasticAdapterInterface, docDescriptor: DocDes
   }
 
   // Build params with required fields
-  const params: IndexRequest = {
+  const indexParams: IndexRequest = {
     index: service.index || '',
     document: doc
   }
 
   // Only add id if it's defined
   if (id !== undefined) {
-    params.id = id
+    indexParams.id = id
   }
 
   // Only add routing if it's defined
   if (routing !== undefined) {
-    params.routing = routing
+    indexParams.routing = routing
   }
 
-  // Merge esParams but exclude index if it's already set
-  const cleanEsParams = service.esParams ? { ...service.esParams } : {}
-  delete (cleanEsParams as Record<string, unknown>).index
-  return Object.assign(params, cleanEsParams)
+  // PERFORMANCE: Merge esParams with per-operation refresh override
+  const cleanEsParams = mergeESParamsWithRefresh(service.esParams, requestParams)
+  delete cleanEsParams.index
+  return Object.assign(indexParams, cleanEsParams)
 }
 
 export function create(
@@ -47,7 +51,7 @@ export function create(
 ) {
   const docDescriptor = getDocDescriptor(service, data)
   const { id, routing } = docDescriptor
-  const createParams = getCreateParams(service, docDescriptor)
+  const createParams = getCreateParams(service, docDescriptor, params)
   const getParams = prepareGetParams(params, 'upsert')
 
   // If we have routing (parent document), pass it in the query for the get operation

src/methods/patch.ts

@@ -1,6 +1,7 @@
 'use strict'
 
 import { getDocDescriptor, getQueryLength, mapPatch } from '../utils/index'
+import { mergeESParamsWithRefresh } from '../utils/params'
 import { ElasticsearchServiceParams, ElasticAdapterInterface } from '../types'
 
 export function patch(
@@ -13,12 +14,13 @@ export function patch(
   const { routing } = getDocDescriptor(service, query)
   const { doc } = getDocDescriptor(service, data)
 
+  // PERFORMANCE: Merge esParams with per-operation refresh override
   const updateParams: Record<string, unknown> = {
     index: filters.$index || service.index,
     id: String(id),
     body: { doc },
     _source: filters.$select || true,
-    ...service.esParams
+    ...mergeESParamsWithRefresh(service.esParams, params)
   }
 
   // Add routing if specified

src/methods/remove.ts

@@ -1,6 +1,7 @@
 'use strict'
 
 import { getDocDescriptor } from '../utils/index'
+import { mergeESParamsWithRefresh } from '../utils/params'
 import { ElasticsearchServiceParams, ElasticAdapterInterface } from '../types'
 
 export function remove(
@@ -10,12 +11,14 @@ export function remove(
 ) {
   const { filters, query } = service.filterQuery(params)
   const { routing } = getDocDescriptor(service, query)
+
+  // PERFORMANCE: Merge esParams with per-operation refresh override
   const removeParams = Object.assign(
     {
       index: filters.$index || service.index,
       id: String(id)
     },
-    service.esParams
+    mergeESParamsWithRefresh(service.esParams, params)
   )
 
   if (routing !== undefined) {

src/methods/update.ts

@@ -1,28 +1,29 @@
 import { removeProps, getDocDescriptor } from '../utils/index'
-import { prepareGetParams } from '../utils/params'
+import { prepareGetParams, mergeESParamsWithRefresh } from '../utils/params'
 import { ElasticsearchServiceParams, ElasticAdapterInterface, DocDescriptor } from '../types'
 
 function getUpdateParams(
   service: ElasticAdapterInterface,
   docDescriptor: DocDescriptor,
-  filters: Record<string, unknown>
+  filters: Record<string, unknown>,
+  params: ElasticsearchServiceParams = {}
 ) {
   const { id, routing, doc } = docDescriptor
 
-  const params: Record<string, unknown> = {
+  const updateParams: Record<string, unknown> = {
     index: filters.$index || service.index,
     id: String(id),
     body: doc
   }
 
   if (routing !== undefined) {
-    params.routing = routing
+    updateParams.routing = routing
   }
 
-  // Merge esParams but exclude index if it's already set
-  const cleanEsParams = service.esParams ? { ...service.esParams } : {}
+  // PERFORMANCE: Merge esParams with per-operation refresh override
+  const cleanEsParams = mergeESParamsWithRefresh(service.esParams, params)
   delete cleanEsParams.index
-  return Object.assign(params, cleanEsParams)
+  return Object.assign(updateParams, cleanEsParams)
 }
 
 export function update(
@@ -35,7 +36,7 @@ export function update(
   const docDescriptor = getDocDescriptor(service, data, query, {
     [service.id]: id
   })
-  const updateParams = getUpdateParams(service, docDescriptor, filters)
+  const updateParams = getUpdateParams(service, docDescriptor, filters, params)
 
   if (params.upsert) {
     return service.Model.index(updateParams as never).then((result: unknown) =>

src/utils/params.ts

@@ -58,3 +58,24 @@ export function prepareRoutingParams(
   }
   return params
 }
+
+/**
+ * Merges ES params with per-operation overrides for refresh control
+ * PERFORMANCE: Allows configurable refresh per operation instead of global setting
+ * @param serviceEsParams - Service-level ES parameters
+ * @param operationParams - Operation-specific parameters from request
+ * @returns Merged parameters with refresh override if specified
+ */
+export function mergeESParamsWithRefresh(
+  serviceEsParams: Record<string, unknown> = {},
+  operationParams: ElasticsearchServiceParams = {}
+): Record<string, unknown> {
+  const merged = { ...serviceEsParams }
+
+  // Allow per-operation refresh override
+  if (operationParams.refresh !== undefined) {
+    merged.refresh = operationParams.refresh
+  }
+
+  return merged
+}