Add detailed benchmark docs and facet-heavy search benchmark

Author: cigolpl

README.md

@@ -290,13 +290,5 @@ APIs:
 
 Snapshots are optional; if you don’t provide them, itemsjs rebuilds indexes as before.
 
-Benchmark (Node):
-- Run `npm run benchmark:snapshot` to compare fresh build vs snapshot load (defaults to 1k, 10k and 30k items). Override sizes with `SIZES=5000,20000 npm run benchmark:snapshot`.
-- Output includes cold-start speedup ratio (build/load). Note: real-world cost in browser also includes `fetch` + `JSON.parse` time if you download the snapshot.
-
-Search benchmark (Node):
-- Run `npm run benchmark:search` to measure build/search/facets timings across scenarios (empty, query-only, filters-only, query+filters, boolean filter). Defaults to sizes 1k/10k/30k; override with `SIZES=5000,20000` and repeats with `REPEAT=10`.
-
-Browser smoke test (manual/optional):
-- Build the bundle: `npm run build`.
-- EITHER open `benchmarks/browser-snapshot.html` directly in a browser, OR run `npm run serve:benchmark` and open `http://localhost:4173/` (auto-loads the snapshot page). It builds once, saves a snapshot to `localStorage`, and on refresh loads from it and logs a sample search.
+Benchmarks and browser smoke test:
+- See `docs/benchmarks.md` for snapshot/search benchmarks and the optional browser smoke test.

benchmarks/search.js

@@ -7,6 +7,8 @@ const sizes = process.env.SIZES
   : defaultSizes;
 
 const repeats = parseInt(process.env.REPEAT || '5', 10);
+const extraFacetsCount = parseInt(process.env.EXTRA_FACETS || '0', 10);
+const extraFacetValues = ['a', 'b', 'c'];
 
 const tagsPool = Array.from({ length: 40 }, (_, i) => `tag${i}`);
 const actorsPool = Array.from({ length: 30 }, (_, i) => `actor${i}`);
@@ -28,10 +30,20 @@ function makeItems(count) {
       actors: [actor],
       category,
       popular,
+      ...makeExtraFacets(i),
     };
   });
 }
 
+function makeExtraFacets(index) {
+  const result = {};
+  for (let j = 0; j < extraFacetsCount; j++) {
+    const val = extraFacetValues[(index + j) % extraFacetValues.length];
+    result[`facet_${j}`] = val;
+  }
+  return result;
+}
+
 function average(arr) {
   if (!arr.length) return 0;
   return arr.reduce((a, b) => a + b, 0) / arr.length;
@@ -64,6 +76,15 @@ function runScenario(engine, input) {
 
 function logResult(size, buildMs, results) {
   console.log(`items: ${size}`);
+  console.log(
+    `  facets: tags(${tagsPool.length}), actors(${actorsPool.length}), category(${categories.length}), popular(boolean)`,
+  );
+  if (extraFacetsCount > 0) {
+    console.log(`  extra facets: ${extraFacetsCount} (3 values each)`);
+  }
+  console.log(
+    '  fields: name (boosted), tags, actors; each item has 3 tags, 1 actor, 1 category, boolean popular',
+  );
   console.log(`  build (ms): ${buildMs.toFixed(1)}`);
   Object.entries(results).forEach(([name, data]) => {
     console.log(
@@ -98,6 +119,12 @@ function main() {
       },
     };
 
+    if (extraFacetsCount > 0) {
+      for (let i = 0; i < extraFacetsCount; i++) {
+        config.aggregations[`facet_${i}`] = { title: `Facet ${i}` };
+      }
+    }
+
     const buildStart = performance.now();
     const engine = itemsjs(data, config);
     const buildEnd = performance.now();

docs/benchmarks.md

@@ -0,0 +1,28 @@
+# Benchmarks
+
+This folder contains small, reproducible benchmarks for ItemsJS. They are optional and not part of the published package.
+
+## Snapshot benchmark
+
+Script: `npm run benchmark:snapshot`
+
+- Compares fresh index build vs loading from snapshot.
+- Defaults: sizes `1000,10000,30000`. Override with `SIZES=5000,20000 npm run benchmark:snapshot`.
+- Output includes cold-start speedup (build/load) and snapshot size.
+- Note: In the browser, total cost also includes `fetch + JSON.parse` if you download the snapshot.
+
+## Search benchmark
+
+Script: `npm run benchmark:search`
+
+- Measures build/search/facets timings across scenarios: empty, query-only, filters-only, query+filters, boolean filter.
+- Defaults: sizes `1000,10000,30000`, repeats per scenario `5`.
+- Override: `SIZES=5000,20000`, `REPEAT=10`.
+- Dataset per size: 40 tags, 30 actors, 4 categories, boolean `popular`; each item has 3 tags, 1 actor, 1 category. Facets: tags, actors, category, popular. Searchable fields: name (boosted), tags, actors.
+- Stress facet-heavy setups with `EXTRA_FACETS=1000` (each with 3 values) to see scaling for many facets.
+
+## Browser smoke test
+
+- Build: `npm run build`.
+- Run: `npm run serve:benchmark` and open `http://localhost:4173/` (serves `benchmarks/browser-snapshot.html`), or open the HTML directly.
+- First load builds and stores a snapshot in `localStorage`; subsequent loads use the snapshot and log a sample search. Green message = OK; red/error or stuck on “Loading…” → check console.