elasticlink 1.0.0-beta.1 → 1.0.0

package/README.md

@@ -71,15 +71,7 @@ const facetedSearch = queryBuilder(productMappings)
   .build();
 ```
 
-Type safety in action — wrong field types are caught at compile time:
-
-```typescript
-queryBuilder(productMappings).match('category', 'electronics');
-//                           ^^^^^^^^^^
-// TypeScript error: 'category' is a keyword field — use term(), not match()
-
-queryBuilder(productMappings).term('category', 'electronics'); // ✅ Correct
-```
+Wrong field types are caught at compile time — `.match()` on a keyword field is a TypeScript error, use `.term()`. See [TypeScript Support](#typescript-support) for a worked example.
 
 ## Examples
 
@@ -171,25 +163,6 @@ const result = queryBuilder(ecommerceMappings)
 
 </details>
 
-### Dynamic Search with Conditional Filters
-
-Build queries dynamically based on runtime values. `.when(condition, fn)` — when the condition is falsy, the builder is returned unchanged.
-
-```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();
-};
-```
-
 ### Aggregations — Portfolio Analytics
 
 Terms + sub-aggregation + date histogram in one request.
@@ -304,6 +277,76 @@ const q2 = queryBuilder(userMappings).match('email', 'john@example.com').build()
 const q3 = queryBuilder(userMappings).term('email', 'john@example.com').build();
 ```
 
+## Vanilla JavaScript
+
+elasticlink works in vanilla JavaScript with full IntelliSense — no TypeScript required. The library ships both ESM and CommonJS builds, so `import` and `require()` both work.
+
+### Setup
+
+For project-wide type checking, add a `jsconfig.json` to your project root:
+
+```json
+{
+  "compilerOptions": {
+    "checkJs": true,
+    "strict": true,
+    "module": "commonjs",
+    "moduleResolution": "node10",
+    "target": "ES2022"
+  }
+}
+```
+
+Or enable per-file with `// @ts-check` at the top of any `.js` file.
+
+### Usage
+
+Query builder methods provide field-name autocomplete and type constraints in VS Code even without any configuration:
+
+```js
+const { mappings, text, keyword, float, queryBuilder } = require('elasticlink');
+
+const productSchema = mappings({
+  name: text(),
+  price: float(),
+  category: keyword()
+});
+
+// Field names autocomplete, and are constrained by type:
+const query = queryBuilder(productSchema)
+  .match('name', 'laptop')           // 'name' is text — allowed in match()
+  .range('price', { gte: 500 })      // 'price' is numeric — allowed in range()
+  .term('category', 'electronics')   // 'category' is keyword — allowed in term()
+  .build();
+```
+
+### Deriving Document Types
+
+In TypeScript you'd use `type Product = Infer<typeof schema>`. In JavaScript, use the `inferType()` helper:
+
+> ⚠️ **Type-only helper.** `inferType()` always returns `undefined`. It exists so you can write `typeof _Product` in a JSDoc `@type` annotation. Never use the returned value at runtime — accessing a property on it (e.g. `_Product.name`) will throw `TypeError`.
+
+```js
+const { mappings, text, keyword, float, inferType } = require('elasticlink');
+
+const schema = mappings({ name: text(), price: float(), category: keyword() });
+
+const _Product = inferType(schema); // undefined at runtime; only the type matters
+
+/** @type {typeof _Product} */
+const doc = { name: 'Laptop', price: 999, category: 'electronics' };
+// ^ full autocomplete on all properties
+```
+
+Alternatively, use the JSDoc import syntax directly:
+
+```js
+/** @type {import('elasticlink').Infer<typeof schema>} */
+const doc = { name: 'Laptop', price: 999, category: 'electronics' };
+```
+
+See [`examples/vanilla-js/`](examples/vanilla-js/) for a complete working example.
+
 ## Settings Presets
 
 Ready-made index settings for common lifecycle stages. Use with `.settings()` on `indexBuilder()` or pass directly to the ES `_settings` API.
@@ -901,9 +944,9 @@ const alerts = queryBuilder(alertRuleMappings)
 
 ## Compatibility
 
-| elasticlink  | Node.js    | Elasticsearch |
-| ------------ | ---------- | ------------- |
-| 1.0.0-beta.1 | 20, 22, 24 | 9.x (≥9.0.0) |
+| elasticlink | Node.js    | Elasticsearch          |
+| ----------- | ---------- | ---------------------- |
+| 1.0.0       | 20, 22, 24 | 9.x (≥9.0.0), tested against 9.4.2 |
 
 Tested against the versions listed. Peer dependency is `@elastic/elasticsearch >=9.0.0`.