feat(elasticsearch-plugin): avoid redundant reindex on stock movements

Adds two opt-in options that stop stock movements from needlessly re-indexing a
product. Both default to the current behavior, so existing installs are unaffected.

reindexOnStockMovement: 'always' | 'onStockStatusChange' (default 'always').
In 'onStockStatusChange' the StockMovementEvent subscriber only enqueues an update
when the movement flips a variant's inStock or its product's productInStock, so a
50 to 49 change never creates a job. It inspects only the built-in stock booleans,
so it is meant for setups without a stock-derived custom mapping.

skipUnchangedIndexUpdates: boolean (default false). Before the delete-then-recreate,
the indexer builds the product's documents, compares them against what is currently
indexed, and skips the write when they are identical. It compares the whole document
so it stays correct for any mapping configuration, and it removes the delete-then-
recreate window during which a product drops out of search. A full reindex is never
skipped.

The document comparison reads through the existing SearchClientAdapter.search and the
stock check uses ProductVariantService.getSaleableStockLevel, so both features behave
the same on Elasticsearch and OpenSearch. No adapter interface or index mapping change.

Refs #50.

Author: LeftoversTodayAppAdmin

packages/elasticsearch-plugin/e2e/skip-unchanged-reindex.e2e-spec.ts

@@ -0,0 +1,130 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { GlobalFlag } from '@vendure/common/lib/generated-types';
+import { DefaultJobQueuePlugin, mergeConfig } from '@vendure/core';
+import { createTestEnvironment } from '@vendure/testing';
+import path from 'path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { initialData } from '../../../e2e-common/e2e-initial-data';
+import { TEST_SETUP_TIMEOUT_MS, testConfig } from '../../../e2e-common/test-config';
+import { ElasticsearchPlugin } from '../src/plugin';
+
+import { awaitRunningJobs } from './await-running-jobs';
+import { buildAdapterForBackend } from './build-adapter-for-backend';
+import { dropElasticIndices } from './e2e-helpers';
+import { graphql } from './graphql/graphql-admin';
+import { updateProductVariantsDocument } from './graphql/shared-definitions';
+import { searchProductsShopDocument } from './graphql/shop-definitions';
+
+const { searchBackend } = require('./constants');
+
+const INDEX_PREFIX = `e2e-skip-unchanged-${searchBackend as string}-`;
+
+const reindexDocument = graphql(`
+    mutation Reindex {
+        reindex {
+            id
+        }
+    }
+`);
+
+describe(`Elasticsearch plugin skip-unchanged reindex [${searchBackend as string}]`, () => {
+    const { server, adminClient, shopClient } = createTestEnvironment(
+        mergeConfig(testConfig(), {
+            plugins: [
+                ElasticsearchPlugin.init({
+                    indexPrefix: INDEX_PREFIX,
+                    adapter: buildAdapterForBackend(),
+                    // The two guards under test.
+                    reindexOnStockMovement: 'onStockStatusChange',
+                    skipUnchangedIndexUpdates: true,
+                }),
+                DefaultJobQueuePlugin,
+            ],
+        }),
+    );
+
+    beforeAll(async () => {
+        await dropElasticIndices(INDEX_PREFIX);
+        await server.init({
+            initialData,
+            productsCsvPath: path.join(__dirname, 'fixtures/e2e-products-full.csv'),
+            customerCount: 1,
+        });
+        await adminClient.asSuperAdmin();
+        await awaitRunningJobs(adminClient, 20_000, 1000);
+        await adminClient.query(reindexDocument);
+        await awaitRunningJobs(adminClient);
+    }, TEST_SETUP_TIMEOUT_MS);
+
+    afterAll(async () => {
+        await awaitRunningJobs(adminClient);
+        await server.destroy();
+    }, TEST_SETUP_TIMEOUT_MS);
+
+    async function inStockVariantIds(inStock: boolean): Promise<string[]> {
+        const result = await shopClient.query(searchProductsShopDocument, {
+            input: { groupByProduct: false, inStock, take: 200 },
+        });
+        return result.search.items.map(i => i.productVariantId);
+    }
+
+    async function setStock(id: string, stockOnHand: number): Promise<void> {
+        await adminClient.query(updateProductVariantsDocument, {
+            input: [{ id, trackInventory: GlobalFlag.TRUE, stockOnHand }],
+        });
+        await awaitRunningJobs(adminClient);
+    }
+
+    // A variant that is in stock in the seeded data; captured in the first test.
+    let variantId: string;
+
+    it('has in-stock variants after reindex', async () => {
+        const inStock = await inStockVariantIds(true);
+        expect(inStock.length).toBeGreaterThan(0);
+        variantId = inStock[0];
+    });
+
+    it('reflects a stock movement that flips the variant out of stock', async () => {
+        await setStock(variantId, 0);
+        expect(await inStockVariantIds(true)).not.toContain(variantId);
+        expect(await inStockVariantIds(false)).toContain(variantId);
+    });
+
+    it('reflects a stock movement that flips the variant back in stock', async () => {
+        await setStock(variantId, 100);
+        expect(await inStockVariantIds(true)).toContain(variantId);
+        expect(await inStockVariantIds(false)).not.toContain(variantId);
+    });
+
+    it('keeps search correct after a non-boundary stock movement (still in stock)', async () => {
+        await setStock(variantId, 99);
+        expect(await inStockVariantIds(true)).toContain(variantId);
+        expect(await inStockVariantIds(false)).not.toContain(variantId);
+    });
+
+    it('still applies an ordinary variant edit (disabling removes it from search)', async () => {
+        await adminClient.query(updateProductVariantsDocument, {
+            input: [{ id: variantId, enabled: false }],
+        });
+        await awaitRunningJobs(adminClient);
+        const allVariantIds = (
+            await shopClient.query(searchProductsShopDocument, {
+                input: { groupByProduct: false, take: 200 },
+            })
+        ).search.items.map(i => i.productVariantId);
+        expect(allVariantIds).not.toContain(variantId);
+
+        // Re-enable so the state is restored for any following assertions.
+        await adminClient.query(updateProductVariantsDocument, {
+            input: [{ id: variantId, enabled: true }],
+        });
+        await awaitRunningJobs(adminClient);
+    });
+
+    it('rebuilds the whole index on a full reindex (guard is exempt)', async () => {
+        await adminClient.query(reindexDocument);
+        await awaitRunningJobs(adminClient);
+        expect(await inStockVariantIds(true)).toContain(variantId);
+    });
+});

packages/elasticsearch-plugin/src/indexing/elasticsearch-index.service.ts

@@ -84,6 +84,17 @@ export class ElasticsearchIndexService implements OnApplicationBootstrap {
         return this.updateIndexQueue.add({ type: 'update-variants', ctx: ctx.serialize(), variantIds }, { ctx });
     }
 
+    async updateVariantsForStockMovement(ctx: RequestContext, variants: ProductVariant[]) {
+        if (await this.indexerController.stockMovementWouldChangeIndex(ctx, variants)) {
+            return this.updateVariants(ctx, variants);
+        }
+        Logger.debug(
+            'Skipping index update for stock movement: indexed stock status unchanged',
+            loggerCtx,
+        );
+        return undefined;
+    }
+
     deleteProduct(ctx: RequestContext, product: Product) {
         return this.updateIndexQueue.add({
             type: 'delete-product',

packages/elasticsearch-plugin/src/indexing/index-diff.spec.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+
+import { indexedDocumentsMatch, stableStringify } from './index-diff';
+
+describe('stableStringify', () => {
+    it('is independent of object key order', () => {
+        expect(stableStringify({ a: 1, b: 2 })).toBe(stableStringify({ b: 2, a: 1 }));
+    });
+
+    it('is independent of key order in nested objects', () => {
+        const x = { outer: { a: 1, b: { c: 3, d: 4 } } };
+        const y = { outer: { b: { d: 4, c: 3 }, a: 1 } };
+        expect(stableStringify(x)).toBe(stableStringify(y));
+    });
+
+    it('preserves array order (arrays are position-sensitive)', () => {
+        expect(stableStringify([1, 2, 3])).not.toBe(stableStringify([3, 2, 1]));
+        expect(stableStringify(['a', 'b'])).toBe(stableStringify(['a', 'b']));
+    });
+
+    it('omits undefined values so they equal an absent key', () => {
+        expect(stableStringify({ a: 1, b: undefined })).toBe(stableStringify({ a: 1 }));
+    });
+
+    it('distinguishes null from absent/undefined', () => {
+        expect(stableStringify({ a: null })).not.toBe(stableStringify({}));
+        expect(stableStringify(null)).toBe('null');
+    });
+
+    it('serializes primitives', () => {
+        expect(stableStringify('x')).toBe('"x"');
+        expect(stableStringify(42)).toBe('42');
+        expect(stableStringify(true)).toBe('true');
+    });
+
+    it('distinguishes number from numeric string', () => {
+        expect(stableStringify({ n: 2 })).not.toBe(stableStringify({ n: '2' }));
+    });
+});
+
+describe('indexedDocumentsMatch', () => {
+    const target = new Map<string, unknown>([
+        ['1_10_en', { inStock: true, productInStock: true, sku: 'A', facetIds: ['1', '2'] }],
+        ['1_11_en', { inStock: false, productInStock: true, sku: 'B', facetIds: [] }],
+    ]);
+
+    it('returns true when ids and content match (ignoring key order)', () => {
+        const hits = [
+            // deliberately reordered keys in _source
+            { _id: '1_11_en', _source: { facetIds: [], sku: 'B', productInStock: true, inStock: false } },
+            { _id: '1_10_en', _source: { facetIds: ['1', '2'], sku: 'A', inStock: true, productInStock: true } },
+        ];
+        expect(indexedDocumentsMatch(target, hits)).toBe(true);
+    });
+
+    it('returns false when a document field differs (e.g. inStock flipped)', () => {
+        const hits = [
+            { _id: '1_10_en', _source: { inStock: false, productInStock: true, sku: 'A', facetIds: ['1', '2'] } },
+            { _id: '1_11_en', _source: { inStock: false, productInStock: true, sku: 'B', facetIds: [] } },
+        ];
+        expect(indexedDocumentsMatch(target, hits)).toBe(false);
+    });
+
+    it('returns false when a stock-derived custom field differs (guards the onStockStatusChange caveat)', () => {
+        const targetWithCustom = new Map<string, unknown>([
+            ['1_10_en', { inStock: true, 'product-stockCount': 5 }],
+        ]);
+        const hits = [{ _id: '1_10_en', _source: { inStock: true, 'product-stockCount': 4 } }];
+        expect(indexedDocumentsMatch(targetWithCustom, hits)).toBe(false);
+    });
+
+    it('returns false when the index has an extra document (removal needed)', () => {
+        const hits = [
+            { _id: '1_10_en', _source: { inStock: true, productInStock: true, sku: 'A', facetIds: ['1', '2'] } },
+            { _id: '1_11_en', _source: { inStock: false, productInStock: true, sku: 'B', facetIds: [] } },
+            { _id: '1_12_en', _source: { inStock: true, productInStock: true, sku: 'C', facetIds: [] } },
+        ];
+        expect(indexedDocumentsMatch(target, hits)).toBe(false);
+    });
+
+    it('returns false when a target document is missing from the index (needs creating)', () => {
+        const hits = [
+            { _id: '1_10_en', _source: { inStock: true, productInStock: true, sku: 'A', facetIds: ['1', '2'] } },
+        ];
+        expect(indexedDocumentsMatch(target, hits)).toBe(false);
+    });
+
+    it('returns false when an indexed id is not in the target set', () => {
+        const hits = [
+            { _id: '1_10_en', _source: { inStock: true, productInStock: true, sku: 'A', facetIds: ['1', '2'] } },
+            { _id: '9_99_en', _source: { inStock: false, productInStock: true, sku: 'B', facetIds: [] } },
+        ];
+        expect(indexedDocumentsMatch(target, hits)).toBe(false);
+    });
+});

packages/elasticsearch-plugin/src/indexing/index-diff.ts

@@ -0,0 +1,37 @@
+/**
+ * Deterministic JSON serialization (keys sorted, `undefined` omitted, array order preserved).
+ */
+export function stableStringify(value: any): string {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(v => stableStringify(v)).join(',')}]`;
+    }
+    const keys = Object.keys(value)
+        .filter(k => value[k] !== undefined)
+        .sort();
+    return `{${keys.map(k => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+}
+
+/**
+ * True when the freshly-built documents (keyed by `_id`) match what is currently indexed, both in
+ * the set of ids and in content.
+ */
+export function indexedDocumentsMatch(
+    targetById: Map<string, unknown>,
+    currentHits: Array<{ _id: string; _source: unknown }>,
+): boolean {
+    if (currentHits.length !== targetById.size) {
+        return false;
+    }
+    for (const hit of currentHits) {
+        if (!targetById.has(hit._id)) {
+            return false;
+        }
+        if (stableStringify(targetById.get(hit._id)) !== stableStringify(hit._source)) {
+            return false;
+        }
+    }
+    return true;
+}